ca4907dfbc
Adds Feishu (ByteDance's enterprise messaging platform) as a gateway platform adapter with full feature parity: WebSocket + webhook transports, message batching, dedup, rate limiting, rich post/card content parsing, media handling (images/audio/files/video), group @mention gating, reaction routing, and interactive card button support. Cherry-picked from PR #1793 by penwyp with: - Moved to current main (PR was 458 commits behind) - Fixed _send_with_retry shadowing BasePlatformAdapter method (renamed to _feishu_send_with_retry to avoid signature mismatch crash) - Fixed import structure: aiohttp/websockets imported independently of lark_oapi so they remain available when SDK is missing - Fixed get_hermes_home import (hermes_constants, not hermes_cli.config) - Added skip decorators for tests requiring lark_oapi SDK - All 16 integration points added surgically to current main New dependency: lark-oapi>=1.5.3,<2 (optional, pip install hermes-agent[feishu]) Fixes #1788 Co-authored-by: penwyp <penwyp@users.noreply.github.com>
3.2 KiB
sidebar_position, title, description
| sidebar_position | title | description |
|---|---|---|
| 11 | Feishu / Lark | Set up Hermes Agent as a Feishu or Lark bot |
Feishu / Lark Setup
Hermes Agent integrates with Feishu and Lark as a full-featured bot. Once connected, you can chat with the agent in direct messages or group chats, receive cron job results in a home chat, and send text, images, audio, and file attachments through the normal gateway flow.
The integration supports both connection modes:
websocket— recommended; Hermes opens the outbound connection and you do not need a public webhook endpointwebhook— useful when you want Feishu/Lark to push events into your gateway over HTTP
How Hermes Behaves
| Context | Behavior |
|---|---|
| Direct messages | Hermes responds to every message. |
| Group chats | Hermes responds when the bot is addressed in the chat. |
| Shared group chats | By default, session history is isolated per user inside a shared chat. |
This shared-chat behavior is controlled by config.yaml:
group_sessions_per_user: true
Set it to false only if you explicitly want one shared conversation per chat.
Step 1: Create a Feishu / Lark App
- Open the Feishu or Lark developer console:
- Feishu: https://open.feishu.cn/
- Lark: https://open.larksuite.com/
- Create a new app.
- In Credentials & Basic Info, copy the App ID and App Secret.
- Enable the Bot capability for the app.
:::warning Keep the App Secret private. Anyone with it can impersonate your app. :::
Step 2: Choose a Connection Mode
Recommended: WebSocket mode
Use WebSocket mode when Hermes runs on your laptop, workstation, or a private server. No public URL is required.
FEISHU_CONNECTION_MODE=websocket
Optional: Webhook mode
Use webhook mode only when you already run Hermes behind a reachable HTTP endpoint.
FEISHU_CONNECTION_MODE=webhook
In webhook mode, Hermes serves a Feishu endpoint at:
/feishu/webhook
Step 3: Configure Hermes
Option A: Interactive Setup
hermes gateway setup
Select Feishu / Lark and fill in the prompts.
Option B: Manual Configuration
Add the following to ~/.hermes/.env:
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
# Optional but strongly recommended
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx
FEISHU_DOMAIN accepts:
feishufor Feishu Chinalarkfor Lark international
Step 4: Start the Gateway
hermes gateway
Then message the bot from Feishu/Lark to confirm that the connection is live.
Home Chat
Use /set-home in a Feishu/Lark chat to mark it as the home channel for cron job results and cross-platform notifications.
You can also preconfigure it:
FEISHU_HOME_CHANNEL=oc_xxx
Security
For production use, set an allowlist:
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
If you leave the allowlist empty, anyone who can reach the bot may be able to use it.
Toolset
Feishu / Lark uses the hermes-feishu platform preset, which includes the same core tools as Telegram and other gateway-based messaging platforms.