@dingxiang-me/openclaw-wechat 1.7.1 → 2.0.0

package/README.en.md

@@ -6,23 +6,64 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 
 - `Agent mode`: WeCom custom app callback (XML)
 - `Bot mode`: WeCom intelligent bot API callback (JSON + native stream)
+- `Webhook outbound targets`: push messages to group webhooks or named webhook endpoints
 
 ## Table of Contents
 
+- [Major Update (v2.0.0)](#major-update-v200)
 - [Highlights](#highlights)
 - [Mode Comparison](#mode-comparison)
 - [5-Minute Quick Start](#5-minute-quick-start)
 - [Requirements](#requirements)
 - [Install and Load](#install-and-load)
+- [Config Paths and Ownership](#config-paths-and-ownership)
 - [Configuration Reference](#configuration-reference)
 - [Capability Matrix](#capability-matrix)
 - [Commands and Session Policy](#commands-and-session-policy)
 - [Environment Variables](#environment-variables)
+- [Public Callbacks and Gateway Auth](#public-callbacks-and-gateway-auth)
+- [Webhook and Heartbeat Ops](#webhook-and-heartbeat-ops)
 - [Coexistence with Other Channels](#coexistence-with-other-channels)
 - [Troubleshooting](#troubleshooting)
 - [Development](#development)
 - [FAQ](#faq)
 
+## Major Update (v2.0.0)
+
+This is a real capability update, not a minor patch.  
+`OpenClaw-Wechat` now has **working WeCom Bot long-connection support** in real gateway runtime.
+
+### WeCom Bot long connection
+
+| Item | Result |
+|---|---|
+| Official endpoint | `wss://openws.work.weixin.qq.com` |
+| Inbound commands | `aibot_msg_callback` / `aibot_event_callback` |
+| Outbound command | `aibot_respond_msg` |
+| Runtime | switched to `ws`, no longer blocked by built-in Node WebSocket `1006` failures |
+| Public Bot callback required | no, not in long-connection mode |
+| Verification command | `npm run wecom:bot:longconn:probe -- --json` |
+
+### Control UI and operations
+
+This release also keeps the earlier operations improvements: **WeCom supports visual configuration in Control UI**, so you no longer need to rely on manual JSON edits only.
+
+### Visual config in Control UI
+
+| Item | Status | Notes |
+|---|---|---|
+| WeCom config form | ✅ | `channels.wecom` can be edited/saved directly from UI |
+| Localized labels | ✅ | Common fields are now clearly labeled in Chinese for ops teams |
+| Sensitive-field hints | ✅ | secret/token/aesKey fields are marked as sensitive |
+| Runtime status clarity | ✅ | `Connected` is no longer stuck at `n/a`; default account display name is localized |
+| Inbound activity tracking | ✅ | `Last inbound` is updated after webhook callbacks (`n/a` before first inbound after restart is expected) |
+
+### Practical impact
+
+- Configure WeCom directly in `Channels -> WeCom` without hand-editing large config files.
+- Better readability for day-to-day ops and handover.
+- More accurate runtime status display reduces false alarm on “plugin not working”.
+
 ## Highlights
 
 | Feature | Status | Notes |
@@ -30,6 +71,7 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 | WeCom inbound message handling | ✅ | text/image/voice/link/file/video (Agent + Bot) |
 | AI auto-reply via OpenClaw runtime | ✅ | routed by session key |
 | Native WeCom Bot stream protocol | ✅ | `msgtype=stream` refresh flow |
+| Bot thinking display | ✅ | parses `<think>/<thinking>/<thought>` into native `thinking_content` |
 | Bot card replies | ✅ | `markdown/template_card` with automatic text fallback |
 | Multi-account support | ✅ | `channels.wecom.accounts.<id>` |
 | Sender allowlist and admin bypass | ✅ | `allowFrom` + `adminUsers` |
@@ -50,21 +92,46 @@ OpenClaw-Wechat is an OpenClaw channel plugin for Enterprise WeChat (WeCom), wit
 | Default callback path | `/wecom/callback` | `/wecom/bot/callback` |
 | Reply mechanism | WeCom send APIs | stream response + refresh polling |
 | Streaming UX | simulated via multiple messages | native stream protocol |
+| Thinking display | not applicable | native `thinking_content` from `<think>` tags |
 | Outbound media | full support (image/voice/video/file) | image/file supported (`active_stream msg_item(image)` first, then `response_url` mixed / webhook fallback) |
 
 ## 5-Minute Quick Start
 
 ### 1) Install plugin
 
+```bash
+openclaw plugins install @dingxiang-me/openclaw-wechat
+```
+
+Recommended minimum package version: `2.0.0`. If `plugins.installs.openclaw-wechat` in `openclaw.json` still reports `1.7.x`, upgrade or reinstall first; those older npm packages do not expose the current WeCom channel metadata.
+
+For local development or direct source-path loading, use:
+
 ```bash
 git clone https://github.com/dingxiang-me/OpenClaw-Wechat.git
 cd OpenClaw-Wechat
 npm install
 ```
 
-### 2) Load plugin in OpenClaw
+### 2) Enable plugin in OpenClaw
 
-Add to `~/.openclaw/openclaw.json`:
+If you installed via `openclaw plugins install`, add this to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "enabled": true,
+    "allow": ["openclaw-wechat"],
+    "entries": {
+      "openclaw-wechat": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+If you are loading from source path instead, use the version below with `load.paths`:
 
 ```json
 {
@@ -90,14 +157,16 @@ Add to `~/.openclaw/openclaw.json`:
 | Agent | `corpId`, `corpSecret`, `agentId`, `callbackToken`, `callbackAesKey` |
 | Bot | `bot.enabled=true`, `bot.token`, `bot.encodingAesKey` |
 
+> Agent-mode note (important): configure **Trusted IP** in the WeCom self-built app settings and include the real egress IP of your OpenClaw gateway. Otherwise you may see "messages received but no reply".
+
 ### 4) Restart and verify
 
 ```bash
 openclaw gateway restart
 openclaw gateway status
 npm run wecom:selfcheck -- --all-accounts
-npm run wecom:agent:selfcheck -- --account default
-npm run wecom:bot:selfcheck -- --account default
+npm run wecom:agent:selfcheck -- --all-accounts
+npm run wecom:bot:selfcheck -- --all-accounts
 ```
 
 ## Requirements
@@ -113,7 +182,17 @@ npm run wecom:bot:selfcheck -- --account default
 
 ## Install and Load
 
-### Local path loading (recommended)
+### OpenClaw-managed installation (recommended)
+
+```bash
+openclaw plugins install @dingxiang-me/openclaw-wechat
+```
+
+If your installed runtime still shows `1.7.x`, reinstall before debugging config; old packages can fail with `unknown channel id: wecom`.
+
+This installs the package under `~/.openclaw/extensions/openclaw-wechat/`. Treat that directory as installed runtime package content, not as your primary business configuration surface.
+
+### Local path loading (development mode)
 
 ```bash
 git clone https://github.com/dingxiang-me/OpenClaw-Wechat.git
@@ -123,11 +202,36 @@ npm install
 
 Configure plugin load path in `~/.openclaw/openclaw.json`.
 
-### npm installation
+## Config Paths and Ownership
 
-```bash
-openclaw plugins install @dingxiang-me/openclaw-wechat
-```
+The paths raised in issue #25 serve different purposes:
+
+| Path | Edit manually? | Purpose |
+|---|---|---|
+| `~/.openclaw/openclaw.json` | **Yes** | Main OpenClaw config. Put `plugins.*`, `channels.wecom.*`, `bindings`, and `env.vars` here |
+| `~/.openclaw/extensions/openclaw-wechat/package.json` | Usually no | Installed package metadata |
+| `~/.openclaw/extensions/openclaw-wechat/openclaw.plugin.json` | Usually no | Plugin manifest/schema used by OpenClaw |
+| `~/.openclaw/extensions/openclaw-wechat/package-lock.json` | No | Dependency lockfile |
+| `~/.openclaw/agents/<id>/sessions/sessions.json` | No | Runtime session index |
+| `~/.openclaw/agents/<id>/sessions/*.jsonl` | No | Runtime transcripts/state |
+
+Windows example mapping:
+
+| Windows path | Meaning |
+|---|---|
+| `D:\\Win\\AppData\\LocalLow\\.openclaw\\openclaw.json` | Main config file; this is where parameters belong |
+| `D:\\Win\\AppData\\LocalLow\\.openclaw\\extensions\\openclaw-wechat\\openclaw.plugin.json` | Plugin schema; not a business config file |
+| `D:\\Win\\AppData\\LocalLow\\.openclaw\\agents\\main\\sessions\\sessions.json` | Runtime state; do not use it as config |
+
+Recommended placement:
+
+| Parameter type | Where to put it |
+|---|---|
+| Plugin load / enable flags | `plugins.*` in `openclaw.json` |
+| WeCom business config | `channels.wecom.*` |
+| Multi-account settings | `channels.wecom.accounts.<id>.*` |
+| Account-to-agent routing | OpenClaw root `bindings` |
+| Secrets / environment-specific overrides | `env.vars.*` or system environment variables |
 
 ## Configuration Reference
 
@@ -144,6 +248,7 @@ openclaw plugins install @dingxiang-me/openclaw-wechat
 | `webhookPath` | string | `/wecom/callback` | Agent callback path (auto `/wecom/<accountId>/callback` when non-default account leaves it empty) |
 | `agent` | object | - | legacy layout: `agent.corpId/corpSecret/agentId` (equivalent to top-level Agent fields) |
 | `outboundProxy` | string | - | WeCom API proxy |
+| `defaultAccount` | string | - | preferred default account for tool usage and runtime fallback |
 | `webhooks` | object | - | named webhook target map (`{ "ops": "https://...key=xxx" }`) |
 | `accounts` | object | - | multi-account map (supports `accounts.<id>.bot` overrides) |
 
@@ -213,6 +318,31 @@ When multi-account is enabled, each account can override Bot callback credential
 | Agent streaming | `streaming.enabled`, `streaming.minChars`, `streaming.minIntervalMs` |
 | Observability | `observability.enabled`, `observability.logPayloadMeta` |
 
+### OpenClaw bindings for account-level routing
+
+Use OpenClaw core `bindings` for stable account-to-agent routing. The plugin exposes `channel=wecom` and `accountId=<id>` to the core router.
+
+```json
+{
+  "bindings": [
+    {
+      "match": {
+        "channel": "wecom",
+        "accountId": "sales"
+      },
+      "agentId": "sales"
+    },
+    {
+      "match": {
+        "channel": "wecom",
+        "accountId": "support"
+      },
+      "agentId": "support"
+    }
+  ]
+}
+```
+
 ## Capability Matrix
 
 ### Agent mode
@@ -250,7 +380,9 @@ Quoted reply context in Bot mode is also supported (`quote` is prepended into cu
 | `/reset` | reset conversation |
 | `/compact` | compact session (runtime-supported) |
 
-Session key policy: default is one-user-one-session (`wecom:<userid>`).
+Session key policy:
+- default account: `wecom:<userid>`
+- non-default accounts: `wecom:<accountId>:<userid>`
 
 Outbound target formats:
 - `user`: `wecom:alice` / `user:alice`
@@ -316,6 +448,201 @@ Outbound target formats:
 |---|---|
 | `WECOM_VOICE_TRANSCRIBE_*` | local whisper/whisper-cli settings |
 
+## Public Callbacks and Gateway Auth
+
+### Goal
+
+WeCom must reach the OpenClaw webhook route directly.  
+The callback path must not be intercepted by:
+
+- Gateway auth / token walls
+- SSO or login redirects
+- frontend/WebUI routing
+- the wrong upstream service
+
+### Recommended layout
+
+| Scenario | Recommendation |
+|---|---|
+| Single domain | Route `/wecom/*`, legacy `/webhooks/app*`, and `/webhooks/wecom*` directly to the OpenClaw gateway port |
+| Gateway Auth / Zero Trust enabled | Exempt those webhook paths from auth; no Authorization/Cookie/login should be required |
+| Shared frontend + gateway domain | Keep frontend routes separate; do not let `/wecom/*` fall into the SPA |
+| Most stable setup | Use a dedicated subdomain for WeCom callbacks |
+
+### Minimum checks
+
+| Probe | Expected result |
+|---|---|
+| `curl -i http://127.0.0.1:8885/wecom/callback` | `200` + `wecom webhook ok` |
+| `curl -i http://127.0.0.1:8885/wecom/bot/callback` | `200` + `wecom bot webhook ok` |
+| `curl -i https://your-domain/wecom/callback` | same as local; no HTML, no `401/403`, no redirect |
+| `curl -i https://your-domain/wecom/bot/callback` | same as local; no HTML, no `401/403`, no redirect |
+
+### What common responses mean
+
+| Response | Meaning | Fix |
+|---|---|---|
+| `200` + `wecom webhook ok` / `wecom bot webhook ok` | webhook route is healthy | continue with URL verification and WeCom-side setup |
+| `200` + HTML | request hit frontend/WebUI | proxy `/wecom/*` directly to the gateway |
+| `401/403` | callback path is auth-gated | bypass auth for webhook paths |
+| `301/302/307/308` | callback path is redirected to login/SSO/frontend | remove redirect and proxy directly to OpenClaw |
+| `502/503/504` | gateway upstream is down/unreachable | fix gateway health/upstream first |
+| `404` | wrong path or webhook route not registered | verify `webhookPath`, plugin load state, and legacy aliases |
+
+### Nginx example
+
+```nginx
+server {
+  listen 443 ssl http2;
+  server_name wecom.example.com;
+
+  location /wecom/ {
+    proxy_pass http://127.0.0.1:8885;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+  }
+
+  location /webhooks/app {
+    proxy_pass http://127.0.0.1:8885;
+  }
+
+  location /webhooks/wecom {
+    proxy_pass http://127.0.0.1:8885;
+  }
+}
+```
+
+### Cloudflare Tunnel example
+
+```yaml
+ingress:
+  - hostname: wecom.example.com
+    service: http://127.0.0.1:8885
+  - service: http_status:404
+```
+
+### Self-check
+
+```bash
+npm run wecom:selfcheck -- --all-accounts
+npm run wecom:agent:selfcheck -- --all-accounts
+npm run wecom:bot:selfcheck -- --all-accounts
+```
+
+Self-check now distinguishes:
+
+- `route-not-found`
+- `html-fallback`
+- `gateway-auth`
+- `redirect-auth`
+- `gateway-unreachable`
+
+## Webhook and Heartbeat Ops
+
+### Typical use cases
+
+| Need | Recommended path |
+|---|---|
+| Send a one-off group notice | `openclaw message send --channel wecom --target webhook:<name>` |
+| Deliver an agent result into a WeCom group | `openclaw agent --deliver --reply-channel wecom --reply-to webhook:<name>` |
+| Send periodic summaries/checks | OpenClaw `agents.defaults.heartbeat` with `target: "wecom"` and `to: "webhook:<name>"` |
+
+### Configure named webhook targets
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "webhooks": {
+        "ops": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx",
+        "dev": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=yyy"
+      }
+    }
+  }
+}
+```
+
+For multi-account setups you can also place them under `channels.wecom.accounts.<id>.webhooks`.
+
+### Direct send
+
+```bash
+openclaw message send --channel wecom --target webhook:ops --message "Service has recovered"
+```
+
+### Deliver an agent turn into the group
+
+```bash
+openclaw agent \
+  --message "Summarize today's alerts" \
+  --deliver \
+  --reply-channel wecom \
+  --reply-to webhook:ops
+```
+
+### Heartbeat delivery to WeCom webhook
+
+On this machine, OpenClaw `2026.3.2` supports heartbeat delivery by channel and target.  
+For a WeCom webhook target:
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "webhooks": {
+        "ops": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "heartbeat": {
+        "every": "30m",
+        "target": "wecom",
+        "to": "webhook:ops",
+        "prompt": "Check gateway health, recent alerts, and WeCom channel status; if all is healthy, reply in three lines or less.",
+        "ackMaxChars": 300
+      }
+    }
+  }
+}
+```
+
+Multi-account webhook delivery can add:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "heartbeat": {
+        "target": "wecom",
+        "to": "webhook:ops",
+        "accountId": "sales"
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- `target: "wecom"` selects the WeCom channel.
+- `to: "webhook:ops"` selects the named webhook target inside that channel.
+- `accountId` is only needed for multi-account routing.
+- If `target` is omitted, heartbeat still runs but does not deliver externally.
+
+Useful ops commands:
+
+```bash
+openclaw system heartbeat last
+openclaw config get agents.defaults.heartbeat
+openclaw status --deep
+openclaw logs --follow
+openclaw system event --mode now --text "Run the next ops heartbeat now"
+```
+
 ## Coexistence with Other Channels
 
 Recommended hardening for Telegram/Feishu/WeCom together:
@@ -331,11 +658,15 @@ See [`docs/troubleshooting/coexistence.md`](./docs/troubleshooting/coexistence.m
 | Symptom | Check first | Typical root cause |
 |---|---|---|
 | Callback verification failed | callback URL reachability | URL/Token/AES mismatch |
+| Public `curl` returns `200`, but WeCom admin still says callback verification failed | WeCom console validation | temporary tunnel domain, untrusted public domain, or enterprise-side validation rejects the callback chain | use a stable public domain; do not use temporary domains such as `trycloudflare.com` as the formal Agent callback |
 | `curl /wecom/callback` returns WebUI page | reverse-proxy path routing | `/wecom/*` path is forwarded to frontend/static site instead of OpenClaw gateway |
+| `curl https://your-domain/wecom/callback` returns `401/403` | gateway auth / zero-trust auth | webhook path requires login or token |
+| `curl https://your-domain/wecom/callback` returns `301/302/307/308` | login redirect / SSO / frontend route | webhook path is redirected away from OpenClaw |
 | Inbound received but no reply | gateway logs + dispatch status | timeout, queueing, policy block |
 | Bot image parse failed | `wecom(bot): failed to fetch image url` | expired URL/non-image stream |
 | Voice transcription failed | local command/model path | whisper/ffmpeg environment issue |
 | Startup logs show `wecom: account diagnosis ...` | diagnosis code + account list | multi-account token/agent/path conflict risk |
+| `wecom:selfcheck -- --all-accounts` reports `account '<id>' not found or incomplete` | account layout | older selfcheck logic did not fully recognize nested `agent` blocks or legacy inline accounts, or the account is actually incomplete |
 | gettoken failed | WeCom API result | wrong credentials or network/proxy |
 
 Useful commands:
@@ -345,6 +676,7 @@ openclaw gateway status
 openclaw status --deep
 openclaw logs --follow
 npm run wecom:selfcheck -- --all-accounts
+npm run wecom:agent:selfcheck -- --all-accounts
 npm run wecom:bot:selfcheck -- --all-accounts
 ```
 
@@ -358,12 +690,15 @@ npm run wecom:bot:selfcheck -- --all-accounts
 | `npm run test:e2e:prepare-browser` | check remote browser sandbox readiness (optional Chromium auto-install) |
 | `npm run test:e2e:collect-pdf` | collect browser-generated PDFs from remote sandbox to local artifacts |
 | `npm run wecom:selfcheck -- --all-accounts` | config/network self-check |
-| `npm run wecom:agent:selfcheck -- --account <id>` | Agent E2E self-check (URL verify + encrypted POST) |
+| `npm run wecom:agent:selfcheck -- --account <id>` | single-account Agent E2E self-check (URL verify + encrypted POST) |
+| `npm run wecom:agent:selfcheck -- --all-accounts` | multi-account Agent E2E self-check (runs URL verify + encrypted POST per account) |
 | `npm run wecom:bot:selfcheck -- --account <id>` | Bot E2E self-check (URL verify/signature/encryption/stream-refresh, supports multi-account) |
+| `npm run wecom:callback:matrix -- --agent-url <public-agent-callback> --bot-url <public-bot-callback>` | public callback matrix probe (optionally include legacy alias URLs) |
 | `npm run wecom:remote:e2e -- --mode all --agent-url <public-agent-callback> --bot-url <public-bot-callback>` | remote matrix verification (Agent + Bot) |
 | `npm run wecom:remote:e2e -- --mode all --agent-url <public-agent-callback> --bot-url <public-bot-callback> --prepare-browser --collect-pdf` | remote matrix with browser sandbox prepare + PDF artifact collection |
 | `WECOM_E2E_BOT_URL=<...> WECOM_E2E_AGENT_URL=<...> npm run wecom:remote:e2e -- --mode all` | env-driven remote E2E (also compatible with legacy `E2E_WECOM_*`) |
 | `npm run wecom:e2e:scenario -- --scenario full-smoke --agent-url <public-agent-callback> --bot-url <public-bot-callback>` | scenario-based E2E (preset smoke/queue workflows) |
+| `npm run wecom:e2e:scenario -- --scenario callback-matrix --agent-url <public-agent-callback> --bot-url <public-bot-callback>` | callback-health-only scenario |
 | `npm run wecom:e2e:scenario -- --scenario compat-smoke --agent-url <new-agent-url> --agent-legacy-url <legacy-agent-url> --bot-url <new-bot-url> --bot-legacy-url <legacy-bot-url>` | compatibility matrix run across new + legacy webhook endpoints |
 | `npm run wecom:e2e:scenario -- --scenario matrix-smoke --bot-url <public-bot-callback>` | bot protocol matrix checks (signature/negative requests/stream-refresh/dedupe; requires `WECOM_BOT_TOKEN/WECOM_BOT_ENCODING_AES_KEY`) |
 | `npm run wecom:e2e:compat -- --agent-url <new-agent-url> --agent-legacy-url <legacy-agent-url> --bot-url <new-bot-url> --bot-legacy-url <legacy-bot-url>` | compatibility matrix shortcut command (same as `--scenario compat-smoke`) |
@@ -381,6 +716,12 @@ Most likely the bot was created in non-API mode. Re-create as **API mode**.
 ### Why can image recognition fail intermittently?
 WeCom image URLs can return non-standard content type or encrypted media stream. The plugin now includes content sniffing and decrypt fallback.
 
+### The app can receive messages but never replies (logs look normal). Why?
+Check whether **Trusted IP** is configured for the WeCom self-built app.
+If trusted IP is missing, WeCom may silently block part of the send/callback chain and it looks like “received but no reply”.
+
+Fix: add the actual egress IP of your OpenClaw gateway to the app's Trusted IP list, then retry.
+
 ### Can Telegram and WeCom affect each other?
 They are logically independent, but can conflict via shared webhook paths, multi-process gateway races, or loose plugin loading policy.
 
@@ -403,6 +744,33 @@ Quick checks:
 2. Public: `curl -i https://<domain>/wecom/callback`
 3. Proxy rules: route `/wecom/*` to OpenClaw gateway port, not WebUI.
 
+### Why does WeCom admin still say `openapi callback verification failed` even though both local and public `curl` return `200 wecom webhook ok`?
+That only proves your route is reachable. It does **not** prove the WeCom admin console will accept the callback URL.
+
+Common causes:
+1. You are using a temporary public tunnel domain such as `trycloudflare.com`
+2. The tenant requires a more stable/trusted public domain
+3. Your callback chain still gets rewritten by auth, redirects, frontend fallback, or edge middleware during the real WeCom-side check
+
+Recommended action:
+1. Use your own stable public domain for the self-built app callback
+2. Do not use `trycloudflare.com` as the formal Agent callback URL
+3. Re-check that `/wecom/callback` is free from auth, redirects, frontend fallback, and caching layers
+
+### Why do two WeCom accounts seem to share one agent/session?
+This is a multi-account routing problem, not expected channel interference.
+
+Current behavior:
+1. Agent session keys are account-aware.
+2. `npm run wecom:selfcheck -- --all-accounts` recognizes `accounts.<id>`, nested `agent` blocks, and legacy inline accounts.
+3. Stable account-to-agent mapping should be expressed with OpenClaw `bindings`.
+
+Recommended verification order:
+1. Run `npm run wecom:selfcheck -- --all-accounts`
+2. Ensure every account shows `config.account :: OK`
+3. Add explicit `bindings` for each WeCom `accountId`
+4. Verify session keys are `wecom:<userid>` for default account and `wecom:<accountId>:<userid>` for non-default accounts
+
 ### How to enable self-built app group chat without requiring `@`?
 First, separate the two WeCom integration types:
 1. **Webhook Bot**: can be added into normal WeCom groups directly (best for group chat).