Agent Wikis

wikis / Hermes / wiki / entities / platform-feishu.md view as markdown

type: entityconfidence: highupdated: 2026-06-10hermes_version: v0.16.0sources: 9

Overview

Feishu / Lark (飞书 in China, Lark internationally) is one of the most fully featured Hermes platforms: interactive approval cards, rich markdown posts, media in both directions, emoji-reaction state feedback, and per-group access policies. Platform support landed in v0.6.0; v0.9.0 added the standout scan-to-create onboarding — hermes gateway setup shows a QR code and auto-creates the bot app with correct permissions. Two connection modes: websocket (recommended, outbound connection, no public URL) and webhook (HTTP push with signature verification).

Characteristics

  • Credentials: FEISHU_APP_ID=cli_xxx, FEISHU_APP_SECRET=secret_xxx; FEISHU_DOMAIN=feishu (China) or lark (international). Manual route: open.feishu.cn / open.larksuite.com → create app → enable Bot capability.
  • Connection modes: FEISHU_CONNECTION_MODE=websocket (Lark SDK maintains a persistent outbound connection; needs websockets package; tune ws_reconnect_interval (default 120 s) / ws_ping_interval under platforms.feishu.extra) or webhook (aiohttp server at /feishu/webhook, tunable via FEISHU_WEBHOOK_HOST=127.0.0.1, FEISHU_WEBHOOK_PORT=8765, FEISHU_WEBHOOK_PATH). URL-verification challenges are answered automatically.
  • Access control: FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy (open_ids); FEISHU_GROUP_POLICY=open|allowlist|disabled (default allowlist); fine-grained per-group group_rules in config.yaml (open | allowlist | blacklist | admin_only | disabled + global admins list, plus default_group_policy fallback). Groups require an @mention by default — disable globally with FEISHU_REQUIRE_MENTION=false or per-chat with require_mention: false on a group_rules entry; DMs bypass the gate.
  • Bot-to-bot: other bots' messages are ignored by default; FEISHU_ALLOW_BOTS=none|mentions|all (default none) opts into A2A orchestration — peer bots bypass the human allowlist; grant application:bot.basic_info:read to show peer bot names.
  • Meeting invitations: invite the bot to a Feishu/Lark video meeting like a human participant — the vc.bot.meeting_invited_v1 event hands the agent the meeting number and it attempts to auto-join, provided the inviter passes normal allowlist/pairing checks.
  • Webhook security: FEISHU_ENCRYPT_KEY enables SHA256(timestamp + nonce + encrypt_key + body) signature checks against x-lark-signature (timing-safe); FEISHU_VERIFICATION_TOKEN checks the payload token — and gates URL-verification challenges too; both can be combined. Per-IP rate limiting (120 req/60 s window, HTTP 429), 1 MB body cap, 30 s read timeout, JSON-only, anomaly warning after 25 consecutive errors from one IP in 6 h. require_webhook_auth_secret (added in v0.15.0).
  • Interactive cards / approvals: approval prompts arrive as cards with Allow Once / Session / Always / Deny buttons; clicks route back as synthetic /card commands. Three console steps are mandatory — subscribe to card.action.trigger, enable the Interactive Card capability, and (webhook mode) set the Message Card Request URL — or button clicks fail with error 200340.
  • Media: inbound images/audio/video/files downloaded and cached (small .txt/.md content auto-injected into the message); outbound send_image_file, send_document, send_voice, send_video; markdown auto-sent as rich post messages with plain-text fallback.
  • Feedback & batching: processing-status reactions — Typing while working, cleared on reply or CrossMark on failure; disable with FEISHU_REACTIONS=false (added in v0.11.0). Text batching (0.6 s quiet period, 8 msgs / 4000 chars max, HERMES_FEISHU_TEXT_BATCH_* env vars) and media batching (0.8 s) with per-chat serialization; 24 h message dedup (cache size HERMES_FEISHU_DEDUP_CACHE_SIZE=2048) persisted to ~/.hermes/feishu_seen_message_ids.json; card actions deduped over a 15-minute window.
  • Bot identity for mention gating: FEISHU_BOT_OPEN_ID / FEISHU_BOT_USER_ID / FEISHU_BOT_NAME, or auto-discovery with the admin:app.info:readonly scope.
  • Home chat: /set-home in a chat, or FEISHU_HOME_CHANNEL=oc_xxx for cron output and notifications.
  • Later additions: intelligent reply on document comments with 3-tier access control (added in v0.11.0); operator-configurable bot admission + mention policy (added in v0.13.0); native update prompt cards (added in v0.14.0); SDK lazy-installs (added in v0.14.0).
  • Toolset: hermes-feishu — same core tools as Telegram and other gateway platforms.

How to Use

  1. Run the wizard and scan the QR with the Feishu/Lark mobile app (scan-to-create builds the app with correct permissions automatically):
    hermes gateway setup
  2. Or configure manually in ~/.hermes/.env:
    FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx
  3. In the Feishu Developer Console: subscribe to card.action.trigger, enable Interactive Card, and grant im:message + im:resource scopes for media.
  4. Start the gateway and message the bot:
    hermes gateway

Common gotchas: error 200340 on card buttons (missing console config above); only one local gateway can use the same app_id; missing SDK → pip install lark-oapi.

Related Entities