How to Connect Hermes Agent to Feishu / Lark: The Complete Setup Guide

Want to reach your AI agent from the app your team already lives in? Hermes Agent ships a native Feishu (Lark) integration: once connected, you chat with your agent in direct messages or group chats, receive scheduled-job results in a home chat, and exchange text, images, audio and files through the normal gateway flow. This guide walks through the complete setup.

What you get once connected

• Direct messages: the bot replies to every private message.
• Group chats: it responds when @-mentioned, and by default keeps separate session history per user inside shared chats (group_sessions_per_user: true in config.yaml).
• Home chat delivery: cron job results land in a designated chat automatically.
• Document intelligence: @-mention the bot in a Feishu/Lark document comment and it reads the document plus the comment thread, then posts an inline reply on the thread.

Step 1: Create the Feishu/Lark app

In the Feishu/Lark developer console, create a custom app and grant the base permissions:

For full functionality add im:message.reactions:readonly (emoji reactions), admin:app.info:readonly (auto-detect the bot identity for @mention gating) and contact:user.id:readonly (resolve user IDs for allowlists). Subscribe to the required message events, and — if you want the document-comment feature — subscribe to drive.notice.comment_add_v1 and grant docs:doc:readonly plus drive:drive:readonly. Then publish the app.

Step 2: Choose a connection mode

WebSocket mode is recommended — the bot connects outward to Feishu, so you don’t need a public URL or TLS certificates on your server. Webhook mode is available if you prefer Feishu to push events to an HTTPS endpoint you expose.

Step 3: Configure Hermes

Add your Feishu credentials to Hermes’s .env file (interactive setup is available), then lock the door behind you with a user allowlist — production bots should only talk to known Open IDs:

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

If you run several Hermes profiles behind a multiplexed gateway, remember that each profile reads only its own .env — put FEISHU_GROUP_POLICY and FEISHU_ALLOWED_USERS in profiles/<name>/.env, or use group_rules in that profile’s config.yaml.

Step 4: Start the gateway and say hello

Start the gateway, then DM your bot or @-mention it in a group. The bot auto-detects its own open_id and display name at startup. From here, everything the agent can do on your machine — file work, web research, scheduled tasks — is one message away, including having it post daily digests into a team chat.

Security checklist

• Set FEISHU_ALLOWED_USERS before going live — never run an open bot on a corporate tenant.
• Keep group_sessions_per_user on unless you explicitly want one shared conversation per chat.
• Document-comment replies are explicit-grant only: configure the 3-tier access rules (exact doc / wildcard / workspace-wide) rather than assuming default access.

Official guide: Feishu / Lark — Hermes Agent docs. Images: CC-licensed with attribution in captions.