hermes-feishu-gateway-setup

name	hermes-feishu-gateway-setup
description	Set up Hermes Agent Feishu/Lark gateway from CLI, including dependency install, TERM=dumb interactive setup, QR/manual credential flow, gateway restart, and daily cron delivery verification. Use when configuring Hermes with Feishu/Lark or troubleshooting Feishu setup.
version	1.0.0

Hermes Feishu/Lark Gateway Setup

Use this when enabling Hermes Agent messaging through Feishu/Lark.

Steps

1. Verify Hermes source directory:

   • cd ~/.hermes/hermes-agent

2. Ensure the Hermes venv has pip. Some installs have a Python venv without pip:

   • ./venv/bin/python -m ensurepip --upgrade
   • ./venv/bin/python -m pip --version

3. Install Feishu extras:

   • ./venv/bin/python -m pip install -e ".[feishu]"

4. Verify imports:

   • ./venv/bin/python - <<'PY'
   • import lark_oapi, qrcode
   • print('lark_oapi ok')
   • print('qrcode ok')
   • PY

5. Start gateway setup in dumb terminal mode. This is easier to drive through a tool PTY because it prints numbered choices:

   • TERM=dumb hermes gateway setup

6. Select Feishu/Lark:

   • Platform choice is typically 11. Feishu / Lark.
   • Choose setup method 1 for QR auto-create when available.
   • If QR flow does not complete, use method 2 and enter App ID/App Secret manually.
   • During QR setup, the CLI may print a QR code plus a URL like https://open.feishu.cn/page/launcher?...; ask the user to scan/open it and approve bot creation.
   • After QR success (Bot created: ...), the prompt can visually jump back to the setup-method selector even though credentials were obtained. Press Enter to accept the shown default/continue, then accept recommended defaults for DM pairing, group @mention policy, and leave Home chat ID blank if unknown.
   • Do not display or save secrets in chat logs; write credentials only through the setup tool or environment file.

7. Recommended Feishu choices:

   • Domain: feishu for China, lark for international.
   • Connection mode: WebSocket, because it does not require a public HTTP endpoint.
   • DM access: pairing approval unless the user explicitly wants open DM access.
   • Group policy: respond only when @mentioned.
   • Home channel: leave blank during setup if unknown, then set it later from Feishu with /sethome.

8. Restart and verify:

   • hermes gateway restart
   • hermes status --all
   • Check that Feishu/Lark shows configured/running.
   • hermes gateway status and hermes logs --since 10m are useful follow-ups; a healthy Feishu WebSocket setup logs Connecting to feishu..., [Feishu] Connected in websocket mode, and ✓ feishu connected.
   • If multiple earlier hermes gateway setup PTY sessions were started, use process list and ignore or clean up exited residual sessions so they do not confuse the active QR setup.

9. For scheduled daily digest delivery:

   • First establish a Feishu home channel using /sethome from the target Feishu chat, or configure the home channel explicitly.
   • If DM pairing is enabled, the first DM may return a pairing code; approve it with hermes pairing approve feishu <code>, then have the user send /sethome again.
   • Verify only whether the Feishu home-channel setting is present; redact App ID, App Secret, token, and other credential values in any user-facing output.
   • Then update the cron job delivery target from local/origin to Feishu or the specific Feishu target supported by the local Hermes version.
   • Note: the in-chat send_message tool may report Platform 'feishu' is not configured or show no targets before a home channel/channel directory exists, even when hermes status --all says Feishu is configured and gateway logs show WebSocket connected. Use /sethome, gateway logs, and cron delivery verification as the source of truth.
   • Run the cron job manually once and verify the message arrives.

10. Creating Feishu docx reading documents from Hermes:

• Use the Hermes agent venv Python if needed: /Users/leiyuxuan/.hermes/hermes-agent/venv/bin/python.
• Load Feishu credentials from /Users/leiyuxuan/.hermes/.env but never print secrets.
• Get a tenant token with POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal.
• Create a docx document with POST https://open.feishu.cn/open-apis/docx/v1/documents, JSON body {"title": "..."}.
• Add content blocks with POST https://open.feishu.cn/open-apis/docx/v1/documents/:document_id/blocks/:document_id/children?document_revision_id=-1; use the document_id itself as the root block_id.
• Text-like block types: 2 text, 3 heading1, 4 heading2, 5 heading3, 12 bullet, 13 ordered, 14 code, 15 quote. The payload format is {"block_type": 2, "text": {"elements": [{"text_run": {"content": "...", "text_element_style": {}}}], "style": {}}}; replace text with heading1, heading2, bullet, etc. to match the block type.
• Batch content at roughly <=45 blocks/request and pause briefly between requests to avoid Feishu's document edit rate limits.
• Verify with GET /open-apis/docx/v1/documents/:document_id; the returned revision_id increasing confirms writes.
• User-facing URLs can usually be formed as https://www.feishu.cn/docx/<document_id> or the tenant host URL if known.
• On this machine, the app can create/edit docx but lacks Drive/permission scopes for listing files or changing sharing/collaborators (drive:drive, drive:drive:readonly, space:document:retrieve, docs:permission.setting:write_only, docs:permission.member:create). If these calls fail with 99991672, deliver the document link with a caveat rather than treating document creation as failed.

Reusable Feishu docx workflow notes

Use this when the user asks to turn an existing digest/wiki page into a Feishu document rather than only sending a Feishu message.

1. Verify Feishu app/gateway status without revealing credentials:

   • hermes status --all should show Feishu configured/running.
   • Use Hermes agent venv Python (~/.hermes/hermes-agent/venv/bin/python) because Feishu dependencies may exist there even if shell Python lacks them.
   • Load app credentials only inside the local script/process and never print credential values.

2. Create the docx document with tenant access token:

   • Get token: POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal using the configured app credentials.
   • Create document: POST https://open.feishu.cn/open-apis/docx/v1/documents with JSON {"title": "..."}.
   • This returns document.document_id; the root block id is the same as document_id.

3. Convert markdown into simple docx blocks:

   • Strip YAML frontmatter.
   • Map headings to block types: H1=3, H2=4, H3=5, H4+=6.
   • Map normal paragraphs to text block 2 and bullets to bullet block 12.
   • Text payload shape:

     {
       "block_type": 2,
       "text": {
         "elements": [{"text_run": {"content": "...", "text_element_style": {}}}],
         "style": {}
       }
     }
     

   • For headings use the corresponding field name (heading1, heading2, heading3, etc.) with the same elements/style shape.
   • Split very long paragraphs before sending; preserve source links as plain text if rich link conversion is not necessary.

4. Insert content blocks:

   • Endpoint: POST https://open.feishu.cn/open-apis/docx/v1/documents/{document_id}/blocks/{document_id}/children?document_revision_id=-1.
   • Body: {"index": <insert_index>, "children": [...]}.
   • Use chunks (for example 45 blocks/request) and sleep ~0.4–0.5s between requests to stay under docx edit frequency limits.
   • Verify with GET /open-apis/docx/v1/documents/{document_id} and GET /open-apis/docx/v1/documents/{document_id}/blocks?document_revision_id=-1&page_size=5.

5. Share/link handling:

   • A created doc URL can be formed as https://<tenant>.feishu.cn/docx/{document_id}; generic https://www.feishu.cn/docx/{document_id} may redirect to the tenant domain.
   • Creating/editing docx only requires docx scopes such as docx:document / docx:document:create, but changing link sharing requires permission scopes such as docs:permission.setting:write_only; adding a user/group collaborator requires docs:permission.member:create or broader Drive scopes.
   • If those scopes are missing, document creation can still succeed but automatic “organization link readable” or “add current chat as collaborator” will fail with code 99991672 and an auth URL. Report this limitation clearly and send the document link to Feishu, but warn that the user may need to grant access manually or enable those scopes.

Pitfalls

• Without TERM=dumb, the platform selector may render as an interactive TUI that is difficult to control through automated PTY input.
• If the venv lacks pip, ./venv/bin/python -m pip install ... fails with No module named pip; use ensurepip first.
• deliver=origin may fail in CLI sessions with no delivery target resolved for deliver=origin; use a configured messaging platform home channel for reliable cron delivery.
• On some macOS setups Feishu connectivity may depend on a local proxy/TUN (commonly system proxy 127.0.0.1:7890, routes through utun*, and open.feishu.cn resolving to 198.18.x). If cron delivery fails with Errno 49 Can't assign requested address or NameResolutionError, first verify whether this network layer was ready at run time before changing Hermes config:
  • curl -Iv --connect-timeout 8 --max-time 15 https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
  • python3 - <<'PY' with socket.getaddrinfo, TCP connect to open.feishu.cn:443, and TLS handshake for a non-secret check.
  • scutil --proxy, nc -vz 127.0.0.1 7890, route -n get <198.18.x address>, and ifconfig | grep -B2 -A2 '198\.18' to confirm proxy/TUN routing.
  • hermes logs --since 2h | grep -iE 'feishu|lark|open.feishu|delivery|error|connected' to distinguish transient DNS/proxy failures from credential/config errors.
  • Verify recovery with send_message to target feishu; cron last_delivery_error may still show the old failure even after connectivity is restored.
• Feishu messaging configured/running does not automatically mean the bot can create or edit Feishu Docs. When the user asks for a “飞书文档”, distinguish between: (1) sending a message/link to Feishu via the gateway, and (2) creating an online Feishu document via Docs/Drive APIs. Verify docs permissions/API support before promising automatic document creation. A quick non-secret check is hermes status --all for Feishu gateway health plus inspecting only the names of Feishu-related env vars (never values) to confirm whether only messaging credentials are present.
• Never paste App Secret, tokens, API keys, or environment file contents into the conversation.