Setup and troubleshoot Hermes Feishu/Lark gateway integration
~/.hermes/.envFEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy # Comma-separated open_id list
Grant these in Feishu Open Platform (开放平台) → Your App → Permission Management:
| Permission | Purpose |
|---|
admin:app.info:readonly | Read app info for bot identity |
application:application:self_manage | Self-manage application |
im:message:readonly | Read messages |
im:message:send_as_bot | Send messages as bot |
im:chat:readonly | Get chat info |
im:message.react:readonly | Read message reactions |
im:message.react:write | Add ACK reactions |
hermes gateway restart
hermes gateway status
cat ~/.hermes/gateway_state.json
journalctl --user -u hermes-gateway.service):| Error | Cause | Fix |
|---|---|---|
Unauthorized user: ou_xxx (None) | User not in allowlist | Add to FEISHU_ALLOWED_USERS |
Unable to hydrate bot identity | Missing admin:app.info:readonly | Grant permission in open platform |
Failed to get chat info | Missing im:chat:readonly | Grant permission |
Failed to add ack reaction | Missing im:message.react:write | Grant permission |
Executor shutdown has been called | Often cascading from auth failure | Fix auth issues first |
| Error 200340 on card button click | Missing interactive card config | See Interactive Card Config below |
hermes logs gateway -n 100 | grep -i feishu
journalctl --user -u hermes-gateway.service -n 200 | grep -i feishu
Error 200340 occurs when users click buttons on interactive cards (e.g., Command Approval) but the Feishu app is missing required configuration. The card sends successfully (only needs im:message:send), but button clicks fail.
Three steps required in Feishu Developer Console:
Subscribe to card action event:
card.action.triggerEnable Interactive Card capability:
Configure Card Request URL (webhook mode only):
https://your-server:8765/feishu/webhook)After configuration, restart gateway: hermes gateway restart
FEISHU_APP_ID - App ID from open platformFEISHU_APP_SECRET - App secretFEISHU_DOMAIN - feishu or lark (default: feishu)FEISHU_CONNECTION_MODE - websocket or webhook (default: websocket)FEISHU_ALLOWED_USERS - Comma-separated open_id list (REQUIRED for DM)FEISHU_ENCRYPT_KEY - Encryption key (webhook mode)FEISHU_VERIFICATION_TOKEN - Verification token (webhook mode)FEISHU_GROUP_POLICY - open, allowlist, admin_only, or disabled (default: allowlist)
open - anyone can interact with the bot (recommended for group chats)allowlist - only users in FEISHU_ALLOWED_USERSadmin_only - only bot adminsdisabled - group chat disabledIf the bot cannot be added to group chats:
Set group policy to open:
echo 'FEISHU_GROUP_POLICY=open' >> ~/.hermes/.env
hermes gateway restart
Default allowlist restricts group interactions to whitelisted users only.
Ensure bot is published in Feishu Open Platform (发布上线).
In the group chat: Settings (···) → Group Robots → Search bot name → Add.
Verify in logs:
journalctl --user -u hermes-gateway.service -n 100 | grep -i "feishu.*group"
FEISHU_BOT_OPEN_ID - Bot's open_id (optional)