289cc47631
Broad drift audit against origin/main (b52b63396). Reference pages (most user-visible drift): - slash-commands: add /busy, /curator, /footer, /indicator, /redraw, /steer that were missing; drop non-existent /terminal-setup; fix /q footnote (resolves to /queue, not /quit); extend CLI-only list with all 24 CLI-only commands in the registry - cli-commands: add dedicated sections for hermes curator / fallback / hooks (new subcommands not previously documented); remove stale hermes honcho standalone section (the plugin registers dynamically via hermes memory); list curator/fallback/hooks in top-level table; fix completion to include fish - toolsets-reference: document the real 52-toolset count; split browser vs browser-cdp; add discord / discord_admin / spotify / yuanbao; correct hermes-cli tool count from 36 to 38; fix misleading claim that hermes-homeassistant adds tools (it's identical to hermes-cli) - tools-reference: bump tool count 55 -> 68; add 7 Spotify, 5 Yuanbao, 2 Discord toolsets; move browser_cdp/browser_dialog to their own browser-cdp toolset section - environment-variables: add 40+ user-facing HERMES_* vars that were undocumented (--yolo, --accept-hooks, --ignore-*, inference model override, agent/stream/checkpoint timeouts, OAuth trace, per-platform batch tuning for Telegram/Discord/Matrix/Feishu/WeCom, cron knobs, gateway restart/connect timeouts); dedupe the Cron Scheduler section; replace stale QQ_SANDBOX with QQ_PORTAL_HOST User-guide (top level): - cli.md: compression preserves last 20 turns, not 4 (protect_last_n: 20) - configuration.md: display.platforms is the canonical per-platform override key; tool_progress_overrides is deprecated and auto-migrated - profiles.md: model.default is the config key, not model.model - sessions.md: CLI/TUI session IDs use 6-char hex, gateway uses 8 - checkpoints-and-rollback.md: destructive-command list now matches _DESTRUCTIVE_PATTERNS (adds rmdir, cp, install, dd) - docker.md: the container runs as non-root hermes (UID 10000) via gosu; fix install command (uv pip); add missing --insecure on the dashboard compose example (required for non-loopback bind) - security.md: systemctl danger pattern also matches 'restart' - index.md: built-in tool count 47 -> 68 - integrations/index.md: 6 STT providers, 8 memory providers - integrations/providers.md: drop fictional dashscope/qwen aliases Features: - overview.md: 9 image models (not 8), 9 TTS providers (not 5), 8 memory providers (Supermemory was missing) - tool-gateway.md: 9 image models - tools.md: extend common-toolsets list with search / messaging / spotify / discord / debugging / safe - fallback-providers.md: add 6 real providers from PROVIDER_REGISTRY (lmstudio, kimi-coding-cn, stepfun, alibaba-coding-plan, tencent-tokenhub, azure-foundry) - plugins.md: Available Hooks table now includes on_session_finalize, on_session_reset, subagent_stop - built-in-plugins.md: add the 7 bundled plugins the page didn't mention (spotify, google_meet, three image_gen providers, two dashboard examples) - web-dashboard.md: add --insecure and --tui flags - cron.md: hermes cron create takes positional schedule/prompt, not flags Messaging: - telegram.md: TELEGRAM_WEBHOOK_SECRET is now REQUIRED when TELEGRAM_WEBHOOK_URL is set (gateway refuses to start without it per GHSA-3vpc-7q5r-276h). Biggest user-visible drift in the batch. - discord.md: HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS default is 2.0, not 0.1 - dingtalk.md: document DINGTALK_REQUIRE_MENTION / FREE_RESPONSE_CHATS / MENTION_PATTERNS / HOME_CHANNEL / ALLOW_ALL_USERS that the adapter supports - bluebubbles.md: drop fictional BLUEBUBBLES_SEND_READ_RECEIPTS env var; the setting lives in platforms.bluebubbles.extra only - qqbot.md: drop dead QQ_SANDBOX; add real QQ_PORTAL_HOST and QQ_GROUP_ALLOWED_USERS - wecom-callback.md: replace 'hermes gateway start' (service-only) with 'hermes gateway' for first-time setup Developer-guide: - architecture.md: refresh tool/toolset counts (61/52), terminal backend count (7), line counts for run_agent.py (~13.7k), cli.py (~11.5k), main.py (~10.4k), setup.py (~3.5k), gateway/run.py (~12.2k), mcp_tool.py (~3.1k); add yuanbao adapter, bump platform adapter count 18 -> 20 - agent-loop.md: run_agent.py line count 10.7k -> 13.7k - tools-runtime.md: add vercel_sandbox backend - adding-tools.md: remove stale 'Discovery import added to model_tools.py' checklist item (registry auto-discovery) - adding-platform-adapters.md: mark send_typing / get_chat_info as concrete base methods; only connect/disconnect/send are abstract - acp-internals.md: ACP sessions now persist to SessionDB (~/.hermes/state.db); acp.run_agent call uses use_unstable_protocol=True - cron-internals.md: gateway runs scheduler in a dedicated background thread via _start_cron_ticker, not on a maintenance cycle; locking is cross-process via fcntl.flock (Unix) / msvcrt.locking (Windows) - gateway-internals.md: gateway/run.py ~12k lines - provider-runtime.md: cron DOES support fallback (run_job reads fallback_providers from config) - session-storage.md: SCHEMA_VERSION = 11 (not 9); add migrations 10 and 11 (trigram FTS, inline-mode FTS5 re-index); add api_call_count column to Sessions DDL; document messages_fts_trigram and state_meta in the architecture tree - context-compression-and-caching.md: remove the obsolete 'context pressure warnings' section (warnings were removed for causing models to give up early) - context-engine-plugin.md: compress() signature now includes focus_topic param - extending-the-cli.md: _build_tui_layout_children signature now includes model_picker_widget; add to default layout Also fixed three pre-existing broken links/anchors the build warned about (docker.md -> api-server.md, yuanbao.md -> cron-jobs.md and tips#background-tasks, nix-setup.md -> #container-aware-cli). Regenerated per-skill pages via website/scripts/generate-skill-docs.py so catalog tables and sidebar are consistent with current SKILL.md frontmatter. docusaurus build: clean, no broken links or anchors.
150 lines
5.3 KiB
Markdown
150 lines
5.3 KiB
Markdown
---
|
||
sidebar_position: 15
|
||
---
|
||
|
||
# WeCom Callback (Self-Built App)
|
||
|
||
Connect Hermes to WeCom (Enterprise WeChat) as a self-built enterprise application using the callback/webhook model.
|
||
|
||
:::info WeCom Bot vs WeCom Callback
|
||
Hermes supports two WeCom integration modes:
|
||
- **[WeCom Bot](wecom.md)** — bot-style, connects via WebSocket. Simpler setup, works in group chats.
|
||
- **WeCom Callback** (this page) — self-built app, receives encrypted XML callbacks. Shows as a first-class app in users' WeCom sidebar. Supports multi-corp routing.
|
||
:::
|
||
|
||
## How It Works
|
||
|
||
1. You register a self-built application in the WeCom Admin Console
|
||
2. WeCom pushes encrypted XML to your HTTP callback endpoint
|
||
3. Hermes decrypts the message, queues it for the agent
|
||
4. Immediately acknowledges (silent — nothing displayed to the user)
|
||
5. The agent processes the request (typically 3–30 minutes)
|
||
6. The reply is delivered proactively via the WeCom `message/send` API
|
||
|
||
## Prerequisites
|
||
|
||
- A WeCom enterprise account with admin access
|
||
- `aiohttp` and `httpx` Python packages (included in the default install)
|
||
- A publicly reachable server for the callback URL (or a tunnel like ngrok)
|
||
|
||
## Setup
|
||
|
||
### 1. Create a Self-Built App in WeCom
|
||
|
||
1. Go to [WeCom Admin Console](https://work.weixin.qq.com/) → **Applications** → **Create App**
|
||
2. Note your **Corp ID** (shown at the top of the admin console)
|
||
3. In the app settings, create a **Corp Secret**
|
||
4. Note the **Agent ID** from the app's overview page
|
||
5. Under **Receive Messages**, configure the callback URL:
|
||
- URL: `http://YOUR_PUBLIC_IP:8645/wecom/callback`
|
||
- Token: Generate a random token (WeCom provides one)
|
||
- EncodingAESKey: Generate a key (WeCom provides one)
|
||
|
||
### 2. Configure Environment Variables
|
||
|
||
Add to your `.env` file:
|
||
|
||
```bash
|
||
WECOM_CALLBACK_CORP_ID=your-corp-id
|
||
WECOM_CALLBACK_CORP_SECRET=your-corp-secret
|
||
WECOM_CALLBACK_AGENT_ID=1000002
|
||
WECOM_CALLBACK_TOKEN=your-callback-token
|
||
WECOM_CALLBACK_ENCODING_AES_KEY=your-43-char-aes-key
|
||
|
||
# Optional
|
||
WECOM_CALLBACK_HOST=0.0.0.0
|
||
WECOM_CALLBACK_PORT=8645
|
||
WECOM_CALLBACK_ALLOWED_USERS=user1,user2
|
||
```
|
||
|
||
### 3. Start the Gateway
|
||
|
||
```bash
|
||
hermes gateway
|
||
```
|
||
|
||
(Use `hermes gateway start` only after `hermes gateway install` has registered the systemd/launchd service.)
|
||
|
||
The callback adapter starts an HTTP server on the configured port. WeCom will verify the callback URL via a GET request, then begin sending messages via POST.
|
||
|
||
## Configuration Reference
|
||
|
||
Set these in `config.yaml` under `platforms.wecom_callback.extra`, or use environment variables:
|
||
|
||
| Setting | Default | Description |
|
||
|---------|---------|-------------|
|
||
| `corp_id` | — | WeCom enterprise Corp ID (required) |
|
||
| `corp_secret` | — | Corp secret for the self-built app (required) |
|
||
| `agent_id` | — | Agent ID of the self-built app (required) |
|
||
| `token` | — | Callback verification token (required) |
|
||
| `encoding_aes_key` | — | 43-character AES key for callback encryption (required) |
|
||
| `host` | `0.0.0.0` | Bind address for the HTTP callback server |
|
||
| `port` | `8645` | Port for the HTTP callback server |
|
||
| `path` | `/wecom/callback` | URL path for the callback endpoint |
|
||
|
||
## Multi-App Routing
|
||
|
||
For enterprises running multiple self-built apps (e.g., across different departments or subsidiaries), configure the `apps` list in `config.yaml`:
|
||
|
||
```yaml
|
||
platforms:
|
||
wecom_callback:
|
||
enabled: true
|
||
extra:
|
||
host: "0.0.0.0"
|
||
port: 8645
|
||
apps:
|
||
- name: "dept-a"
|
||
corp_id: "ww_corp_a"
|
||
corp_secret: "secret-a"
|
||
agent_id: "1000002"
|
||
token: "token-a"
|
||
encoding_aes_key: "key-a-43-chars..."
|
||
- name: "dept-b"
|
||
corp_id: "ww_corp_b"
|
||
corp_secret: "secret-b"
|
||
agent_id: "1000003"
|
||
token: "token-b"
|
||
encoding_aes_key: "key-b-43-chars..."
|
||
```
|
||
|
||
Users are scoped by `corp_id:user_id` to prevent cross-corp collisions. When a user sends a message, the adapter records which app (corp) they belong to and routes replies through the correct app's access token.
|
||
|
||
## Access Control
|
||
|
||
Restrict which users can interact with the app:
|
||
|
||
```bash
|
||
# Allowlist specific users
|
||
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu
|
||
|
||
# Or allow all users
|
||
WECOM_CALLBACK_ALLOW_ALL_USERS=true
|
||
```
|
||
|
||
## Endpoints
|
||
|
||
The adapter exposes:
|
||
|
||
| Method | Path | Purpose |
|
||
|--------|------|---------|
|
||
| GET | `/wecom/callback` | URL verification handshake (WeCom sends this during setup) |
|
||
| POST | `/wecom/callback` | Encrypted message callback (WeCom sends user messages here) |
|
||
| GET | `/health` | Health check — returns `{"status": "ok"}` |
|
||
|
||
## Encryption
|
||
|
||
All callback payloads are encrypted with AES-CBC using the EncodingAESKey. The adapter handles:
|
||
|
||
- **Inbound**: Decrypt XML payload, verify SHA1 signature
|
||
- **Outbound**: Replies sent via proactive API (not encrypted callback response)
|
||
|
||
The crypto implementation is compatible with Tencent's official WXBizMsgCrypt SDK.
|
||
|
||
## Limitations
|
||
|
||
- **No streaming** — replies arrive as complete messages after the agent finishes
|
||
- **No typing indicators** — the callback model doesn't support typing status
|
||
- **Text only** — currently supports text messages for input; image/file/voice input not yet implemented. The agent is aware of outbound media capabilities via the WeCom platform hint (images, documents, video, voice).
|
||
- **Response latency** — agent sessions take 3–30 minutes; users see the reply when processing completes
|