@dingxiang-me/openclaw-wechat 1.4.1 → 1.7.2

package/CHANGELOG.md

@@ -4,6 +4,125 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+- 新增 Bot 卡片回包能力：`channels.wecom.bot.card`（支持 `markdown` / `template_card`）
+- 新增卡片回包分层开关：`bot.card.responseUrlEnabled`、`bot.card.webhookBotEnabled`
+- 新增 `outbound-bot-card` 模块与回归测试，统一卡片 payload 构建与长度截断
+- 新增多账号冲突诊断：启动时输出 `wecom: account diagnosis ...`（重复 callbackToken / bot token、共享路径等）
+- 新增场景化远端 E2E 脚本：`npm run wecom:e2e:scenario -- --scenario <bot-smoke|agent-smoke|full-smoke|bot-queue>`
+- 新增账号路径诊断单测与默认路径单测（Agent/Bot）
+- 新增 sunnoy 风格配置兼容层：支持 `agent.*`、`dynamicAgents.*`、`dm.createAgentOnFirstMessage`
+- 新增 legacy inline account 兼容解析（`channels.wecom.<accountId>`）及对应回归测试
+- 新增 legacy 指令配置兼容：`commandAllowlist`、`commandBlockMessage`
+- 新增 legacy 动态路由模板兼容：顶层 `workspaceTemplate` 自动映射到 `dynamicAgent.workspaceTemplate`
+- 新增 legacy 兼容：`dm.allowFrom` 与 `commands.blockMessage`
+- 新增 legacy `name` 字段兼容（渠道与账户级）
+- 改进命令策略：当配置了 `commands.allowlist`（或 `commandAllowlist`）且未显式关闭时，自动启用命令白名单
+- 修复账户级 `dm.allowFrom` 兼容：`accounts.<id>.dm.allowFrom` 在归一化后保持生效
+- 调整 manifest：`accounts.<id>` 不再强制 `corpId/corpSecret/agentId`，支持 Bot-only 账号配置
+- 新增 Bot 路由兼容：默认新路径会自动注册 legacy alias（`/webhooks/wecom` / `/webhooks/wecom/<id>`），并在与 Agent 路径冲突时自动跳过
+- 新增 Agent 路由兼容：默认新路径会自动注册 legacy alias（`/webhooks/app` / `/webhooks/app/<id>`），并在与 Bot 路径冲突时自动跳过
+- 新增 Agent 自检增强：`wecom:agent:selfcheck` 在默认新路径场景下会额外探测 legacy alias（`/webhooks/app`）
+- 新增远端浏览器 E2E 辅助脚本：`test:e2e:prepare-browser`（沙箱就绪检查）与 `test:e2e:collect-pdf`（回收 PDF 产物）
+- 新增远端 E2E 联动参数：`wecom:remote:e2e` / `wecom:e2e:scenario` 支持 `--prepare-browser`、`--collect-pdf`、`--browser-prepare-mode`、`--browser-require-ready`
+- 新增一键命令：`npm run wecom:e2e:full`（full-smoke + 浏览器准备检查 + PDF 回收）
+- 新增远端 E2E 环境变量兼容：`wecom:remote:e2e` / `wecom:e2e:scenario` 支持 `WECOM_E2E_*` 与 legacy `E2E_WECOM_*` 默认参数注入
+- 新增场景化兼容矩阵：`wecom:e2e:scenario --scenario compat-smoke` 支持新旧回调 URL 双链路验证（Agent/Bot）
+- 新增兼容矩阵快捷命令：`npm run wecom:e2e:compat`（等价 `wecom:e2e:scenario --scenario compat-smoke`）
+- CI 远端联调增强：`workflow_dispatch` 支持选择 `e2e_scenario`、浏览器准备模式与 PDF 回收参数
+- FAQ 补充：明确 Bot 模式在“微信插件入口”可见性的产品限制，并给出 Agent/Bot 并行方案建议
+- 新增远端矩阵 E2E：`test:e2e:matrix`，覆盖 Bot 回调验签、异常请求、stream-refresh 与重复消息去重链路
+- 新增 `matrix-smoke` 场景：`wecom:e2e:scenario --scenario matrix-smoke` 可直接触发 Bot 协议矩阵回归
+- 新增 Bot 可见性诊断：`/status` 与 `wecom:bot:selfcheck` 输出“微信插件入口联系人”提示，避免将产品形态差异误判为插件故障
+- 新增 Bot 自检多账户参数：`npm run wecom:bot:selfcheck -- --account <id>` 与 `--all-accounts`（支持 scoped `WECOM_<ACCOUNT>_BOT_*` 环境变量）
+- 新增安装元数据：`package.json` 增加 `openclaw.install`（`defaultChoice=npm` + `npmSpec=@dingxiang-me/openclaw-wechat`）
+- 新增命令兼容映射：`/new` 与 `/clear` 一样会转换为 `/reset`（Agent/Bot 双模式，支持 `/new` 白名单兼容）
+- 新增 Bot 自检插件加载诊断：输出 `plugins.enabled / plugins.entry.openclaw-wechat / plugins.allow` 三项结果
+- 新增 Bot 自检 URL 验证检查：`e2e.url.verify` 覆盖 `GET echostr` 验签 + 解密回显
+- 新增 Bot 自检本地回调健康诊断：可识别 `html-fallback/route-not-found/gateway-unreachable` 并输出修复提示
+
+### Changed
+- Bot 回包链路增强：当无媒体且卡片开启时，`response_url` / `webhook_bot` 优先发送卡片并自动降级文本
+- 多账号默认回调路径自动分配：
+  - Agent：非 default 账户缺省为 `/wecom/<accountId>/callback`
+  - Bot：非 default 账户缺省为 `/wecom/<accountId>/bot/callback`
+- `openclaw.plugin.json` 与 README（中英文）补充自动路径与账号体检说明
+- Bot 配置解析增强：在 legacy `agent` 配置块存在时，自动将顶层 `token/encodingAesKey/webhookPath` 识别为 Bot 配置
+- 动态路由增强：支持私聊/群聊维度开关（`dmCreateAgentOnFirstMessage`、`groupEnabled`）
+- 远端 E2E 兼容增强：`test:e2e:remote` 支持 `WECOM_E2E_*` 与 legacy `E2E_WECOM_*` 两套环境变量
+- 语法检查范围增强：`test:syntax` 从仅 `src` 扩展到 `src + scripts + tests`，降低脚本/测试回归漏检风险
+
+## [1.7.2] - 2026-03-05
+
+### Changed
+- Bot 群聊触发策略收紧：在企业微信官方 Bot 模式下，`groupChat.triggerMode=direct/keyword` 会自动规范为 `mention` 并输出告警，避免“配置可写但平台不回调”的误导
+- Bot `/status` 与 `/help` 文案增强：明确“群聊通常仅 @ 机器人消息触发（平台限制）”
+- 文档更新：README 与 `docs/channels/wecom.md` 明确 Bot 群聊触发限制与配置降级行为
+
+### Added
+- 新增回归测试 `tests/wecom-bot-inbound-executor-helpers.test.mjs`，覆盖 Bot 群聊策略规范化
+- 更新命令处理测试，覆盖 Bot 状态文案中的平台限制提示
+
+## [1.7.1] - 2026-03-05
+
+### Added
+- 新增事件策略 `events.*`：支持处理 `MsgType=event`，并支持 `enter_agent` 自动欢迎语
+- 新增事件策略环境变量：`WECOM_EVENTS_*` 与 `WECOM_<ACCOUNT>_EVENTS_*`
+- 新增事件链路测试：覆盖 XML 事件字段解析、事件调度与 `enter_agent` 欢迎语发送
+
+### Changed
+- `/status` 增加事件策略状态展示（是否启用事件处理与欢迎语）
+- 文档更新：README（中英文）与渠道文档新增事件策略配置说明
+
+## [1.7.0] - 2026-03-05
+
+### Added
+- 新增私聊策略 `dm.mode`：支持 `open` / `allowlist` / `deny`，并支持账户级覆盖（`accounts.<id>.dm`）
+- 新增私聊策略环境变量：`WECOM_DM_POLICY|MODE`、`WECOM_DM_ALLOW_FROM`、`WECOM_DM_REJECT_MESSAGE`，并支持 `WECOM_<ACCOUNT>_DM_*` scoped 覆盖
+- 新增 WeCom 可观测指标存储：入站量、回包成功/失败、错误计数与最近失败样本
+- 新增 `/status` 观测输出：展示入站/回包统计、成功率和最近一次失败原因
+- 新增 Bot mixed 入站增强：支持 `file/link/location/voice` 子项解析与文件/语音链路接入
+- 新增测试覆盖：DM 策略解析/拦截、可观测统计、mixed 文件与语音解析、回包指标记录
+
+### Changed
+- Agent/Bot 入站守卫统一接入 DM 策略，按配置执行放行/拒绝
+- 回包编排链路统一埋点（active_stream / response_url / webhook_bot / agent_push）并上报最终状态
+- Bot 入站内容构建从“单类型”提升为“mixed 聚合”流程，支持同一条 mixed 消息中组合文件与语音内容
+
+### Fixed
+- 修复 Bot 入站执行流在新增 DM 策略依赖后的测试注入缺失问题（`resolveWecomDmPolicy is required`）
+
+## [1.6.1] - 2026-03-04
+
+### Added
+- Bot 可见性诊断补齐：`/status` 与 `wecom:bot:selfcheck` 新增“微信插件入口联系人”提示，避免将产品形态差异误判为故障
+- Bot 体检支持账户维度：`npm run wecom:bot:selfcheck -- --account <id>` 与 `--all-accounts`
+- Bot 体检新增插件加载诊断：`plugins.enabled / plugins.entry.openclaw-wechat / plugins.allow`
+- 新增脚本级回归测试：覆盖 Bot 体检多账户发现与参数冲突（`--all-accounts` + `--url`）
+
+### Changed
+- 命令兼容增强：`/new` 与 `/clear` 在 Agent/Bot 双模式统一映射到 `/reset`，并兼容白名单
+- 插件安装元数据完善：`package.json` 增加 `openclaw.install`（`defaultChoice=npm` + `npmSpec=@dingxiang-me/openclaw-wechat`）
+
+## [1.5.0] - 2026-03-04
+
+### Added
+- Bot 模式补齐语音 URL 下载 + 本地转写链路：支持从 `voice.url/media_url/download_url/file_url` 拉取音频并接入本地转写
+- Bot 多账号能力增强：支持 `channels.wecom.accounts.<id>.bot` 独立配置与 `WECOM_<ACCOUNT>_BOT_*` 环境变量覆盖
+- Bot 路由增强：同一路径支持多账户签名匹配并按账户分组注册 webhook
+- Bot 回包增强：支持从回复文本中提取 `/workspace/...` 本地图片并自动打包为 `active_stream msg_item(image)`
+- 新增/扩展回归测试，覆盖 Bot 多账号、语音转写、workspace 图片打包等关键路径（总测试数提升到 264）
+
+### Changed
+- `register-runtime` 启动日志升级：支持展示 Bot 多账户加载状态与 webhook 聚合信息
+- `openclaw.plugin.json` 新增 `accounts.<id>.bot` schema 与敏感字段标记
+- README（中英文）补充多账户 Bot 覆盖配置与环境变量说明
+
+### Fixed
+- 修复 Bot 入站内容构建依赖注入缺失导致的运行时异常（`resolveWecomVoiceTranscriptionConfig is required`）
+- 修复 Bot dispatcher 在多账号场景下因未携带匹配账户配置导致的 401 响应问题
+- 修复路由注册与依赖工厂在多账号 Bot resolver 接入后的兼容性回归
+
 ## [1.4.1] - 2026-03-03
 
 ### Added

package/README.en.md

@@ -30,11 +30,15 @@ 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 card replies | ✅ | `markdown/template_card` with automatic text fallback |
 | Multi-account support | ✅ | `channels.wecom.accounts.<id>` |
 | Sender allowlist and admin bypass | ✅ | `allowFrom` + `adminUsers` |
-| Command allowlist | ✅ | `/help`, `/status`, `/clear`, etc. |
+| Direct-message policy | ✅ | `dm.mode=open/allowlist/deny` + account overrides |
+| Event welcome reply (`enter_agent`) | ✅ | configurable via `events.enterAgentWelcome*` |
+| Command allowlist | ✅ | `/help`, `/status`, `/clear`, `/new`, etc. |
 | Group trigger policy | ✅ | mention-required or direct-trigger |
 | Debounce and late-reply fallback | ✅ | better stability under queue/timeout |
+| Observability metrics | ✅ | inbound/delivery/error counters + recent failures |
 | Outbound proxy for WeCom APIs | ✅ | `outboundProxy` / `WECOM_PROXY` |
 
 ## Mode Comparison
@@ -93,7 +97,7 @@ openclaw gateway restart
 openclaw gateway status
 npm run wecom:selfcheck -- --all-accounts
 npm run wecom:agent:selfcheck -- --account default
-npm run wecom:bot:selfcheck
+npm run wecom:bot:selfcheck -- --account default
 ```
 
 ## Requirements
@@ -137,12 +141,16 @@ openclaw plugins install @dingxiang-me/openclaw-wechat
 | `agentId` | number/string | - | Agent mode |
 | `callbackToken` | string | - | sensitive |
 | `callbackAesKey` | string | - | sensitive |
-| `webhookPath` | string | `/wecom/callback` | Agent callback path |
+| `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 |
 | `webhooks` | object | - | named webhook target map (`{ "ops": "https://...key=xxx" }`) |
-| `accounts` | object | - | multi-account map |
+| `accounts` | object | - | multi-account map (supports `accounts.<id>.bot` overrides) |
 
-Compatibility note: legacy Agent keys `token` / `encodingAesKey` are still accepted (mapped to `callbackToken` / `callbackAesKey`). Prefer the new names for new configs.
+Compatibility note: legacy keys/layouts are supported: `name`, `token` / `encodingAesKey`, `agent.*`, `dynamicAgents.*`, `dm.createAgentOnFirstMessage`, `dm.allowFrom`, `workspaceTemplate`, `commandAllowlist/commandBlockMessage`, `commands.blockMessage`, and inline account blocks (`channels.wecom.<accountId>`). New configs should prefer `accounts.<id>`, `callbackToken/callbackAesKey`, `commands.*`, and `dynamicAgent.*`.
+
+Note: `accounts.<id>` now supports Bot-only accounts (`bot.*` only) and no longer requires `corpId/corpSecret/agentId`.
+Compat note: when default new paths are used, legacy aliases are auto-registered for smoother migration. Agent default paths also add `/webhooks/app` aliases (`/webhooks/app/<id>` for multi-account), and Bot default paths add `/webhooks/wecom` aliases (`/webhooks/wecom/<id>`). Conflicting aliases are skipped with warnings.
 
 ### Bot config (`channels.wecom.bot`)
 
@@ -151,12 +159,44 @@ Compatibility note: legacy Agent keys `token` / `encodingAesKey` are still accep
 | `enabled` | boolean | `false` | enable Bot mode |
 | `token` | string | - | sensitive |
 | `encodingAesKey` | string | - | sensitive, 43 chars |
-| `webhookPath` | string | `/wecom/bot/callback` | Bot callback path |
+| `webhookPath` | string | `/wecom/bot/callback` | Bot callback path (auto `/wecom/<accountId>/bot/callback` when non-default account leaves it empty) |
 | `placeholderText` | string | processing text | stream initial placeholder |
 | `streamExpireMs` | integer | `600000` | 30s ~ 1h |
 | `replyTimeoutMs` | integer | `90000` | Bot reply timeout (15s ~ 10m) |
 | `lateReplyWatchMs` | integer | `180000` | async late-reply watch window |
 | `lateReplyPollMs` | integer | `2000` | async late-reply poll interval |
+| `card` | object | see below | Bot card reply policy (`response_url` / `webhook_bot`) |
+
+#### Bot card config (`channels.wecom.bot.card`)
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `enabled` | boolean | `false` | enable card replies |
+| `mode` | string | `markdown` | `markdown` (compat-first) or `template_card` |
+| `title` | string | `OpenClaw-Wechat` | card title |
+| `subtitle` | string | - | card subtitle |
+| `footer` | string | - | card footer text |
+| `maxContentLength` | integer | `1400` | max card body length (auto-truncated) |
+| `responseUrlEnabled` | boolean | `true` | enable card sending at `response_url` layer |
+| `webhookBotEnabled` | boolean | `true` | enable card sending at `webhook_bot` layer |
+
+### Account-level Bot overrides (`channels.wecom.accounts.<id>.bot`)
+
+When multi-account is enabled, each account can override Bot callback credentials/path/timeout/proxy. If omitted, it falls back to `channels.wecom.bot`.
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `enabled` | boolean | `false` | enable Bot mode for this account |
+| `token` / `callbackToken` | string | - | callback token (legacy alias supported) |
+| `encodingAesKey` / `callbackAesKey` | string | - | callback AES key (legacy alias supported) |
+| `webhookPath` | string | `/wecom/bot/callback` | Bot callback path |
+| `placeholderText` | string | processing text | stream placeholder |
+| `streamExpireMs` | integer | `600000` | stream TTL |
+| `replyTimeoutMs` | integer | `90000` | model reply timeout |
+| `lateReplyWatchMs` | integer | `180000` | late-reply watch window |
+| `lateReplyPollMs` | integer | `2000` | late-reply poll interval |
+| `card` | object | - | account-level card policy (overrides global `bot.card`) |
+| `outboundProxy` / `proxyUrl` / `proxy` | string | - | account-level Bot proxy |
 
 ### Policy config
 
@@ -165,10 +205,13 @@ Compatibility note: legacy Agent keys `token` / `encodingAesKey` are still accep
 | Sender ACL | `allowFrom`, `allowFromRejectMessage` |
 | Command ACL | `commands.enabled`, `commands.allowlist`, `commands.rejectMessage` |
 | Admin bypass | `adminUsers` |
+| Direct-message policy | `dm.mode`, `dm.allowFrom`, `dm.rejectMessage` |
+| Event policy | `events.enabled`, `events.enterAgentWelcomeEnabled`, `events.enterAgentWelcomeText` |
 | Group trigger | `groupChat.enabled`, `groupChat.triggerMode`, `groupChat.mentionPatterns`, `groupChat.triggerKeywords` |
-| Dynamic route | `dynamicAgent.*` (with `workspaceTemplate` bootstrap seeding) |
+| Dynamic route | `dynamicAgent.*` (compatible with `dynamicAgents.*`, `dm.createAgentOnFirstMessage`) |
 | Debounce | `debounce.enabled`, `debounce.windowMs`, `debounce.maxBatch` |
 | Agent streaming | `streaming.enabled`, `streaming.minChars`, `streaming.minIntervalMs` |
+| Observability | `observability.enabled`, `observability.logPayloadMeta` |
 
 ## Capability Matrix
 
@@ -203,8 +246,8 @@ Quoted reply context in Bot mode is also supported (`quote` is prepended into cu
 | `/help` | show help |
 | `/status` | show runtime status |
 | `/clear` | clear session (mapped to `/reset`) |
+| `/new` | new session (mapped to `/reset`) |
 | `/reset` | reset conversation |
-| `/new` | new session (runtime-supported) |
 | `/compact` | compact session (runtime-supported) |
 
 Session key policy: default is one-user-one-session (`wecom:<userid>`).
@@ -241,6 +284,16 @@ Outbound target formats:
 | `WECOM_BOT_REPLY_TIMEOUT_MS` | Bot reply timeout |
 | `WECOM_BOT_LATE_REPLY_WATCH_MS` | Bot late-reply watch window |
 | `WECOM_BOT_LATE_REPLY_POLL_MS` | Bot late-reply poll interval |
+| `WECOM_BOT_CARD_ENABLED` | enable Bot card replies |
+| `WECOM_BOT_CARD_MODE` | card mode: `markdown` / `template_card` |
+| `WECOM_BOT_CARD_TITLE` | card title |
+| `WECOM_BOT_CARD_SUBTITLE` | card subtitle |
+| `WECOM_BOT_CARD_FOOTER` | card footer text |
+| `WECOM_BOT_CARD_MAX_CONTENT_LENGTH` | max card body length |
+| `WECOM_BOT_CARD_RESPONSE_URL_ENABLED` | card switch for response_url layer |
+| `WECOM_BOT_CARD_WEBHOOK_BOT_ENABLED` | card switch for webhook_bot layer |
+| `WECOM_<ACCOUNT>_BOT_*` | account-level Bot override (e.g. `WECOM_SALES_BOT_TOKEN`) |
+| `WECOM_<ACCOUNT>_BOT_PROXY` | account-level Bot proxy for media/download/reply |
 
 ### Stability and policy
 
@@ -248,10 +301,13 @@ Outbound target formats:
 |---|---|
 | `WECOM_ALLOW_FROM*` | sender authorization |
 | `WECOM_COMMANDS_*` | command ACL |
+| `WECOM_DM_*`, `WECOM_<ACCOUNT>_DM_*` | DM policy + allowlist |
+| `WECOM_EVENTS_*`, `WECOM_<ACCOUNT>_EVENTS_*` | event handling + enter_agent welcome text |
 | `WECOM_GROUP_CHAT_*` | group trigger policy |
 | `WECOM_DEBOUNCE_*` | text debounce |
 | `WECOM_STREAMING_*` | Agent incremental output |
 | `WECOM_LATE_REPLY_*` | async late reply fallback |
+| `WECOM_OBSERVABILITY_ENABLED`, `WECOM_OBSERVABILITY_PAYLOAD_META` | observability counters and payload-meta logging |
 | `WECOM_PROXY`, `WECOM_<ACCOUNT>_PROXY` | outbound proxy |
 
 ### Local voice transcription fallback
@@ -279,6 +335,7 @@ See [`docs/troubleshooting/coexistence.md`](./docs/troubleshooting/coexistence.m
 | 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 |
 | gettoken failed | WeCom API result | wrong credentials or network/proxy |
 
 Useful commands:
@@ -288,7 +345,7 @@ openclaw gateway status
 openclaw status --deep
 openclaw logs --follow
 npm run wecom:selfcheck -- --all-accounts
-npm run wecom:bot:selfcheck
+npm run wecom:bot:selfcheck -- --all-accounts
 ```
 
 ## Development
@@ -296,12 +353,22 @@ npm run wecom:bot:selfcheck
 | Command | Purpose |
 |---|---|
 | `npm test` | syntax + tests |
-| `WECOM_E2E_ENABLE=1 npm run test:e2e:remote` | run remote E2E tests (skipped by default; requires `WECOM_E2E_BOT_URL`/`WECOM_E2E_AGENT_URL`) |
+| `WECOM_E2E_ENABLE=1 npm run test:e2e:remote` | run remote E2E tests (skipped by default; supports both `WECOM_E2E_*` and legacy `E2E_WECOM_*` env sets) |
+| `WECOM_E2E_MATRIX_ENABLE=1 npm run test:e2e:matrix` | run remote matrix E2E (signature/negative requests/stream refresh/dedupe) |
+| `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:bot:selfcheck` | Bot E2E self-check (signature/encryption/stream-refresh) |
+| `npm run wecom:bot:selfcheck -- --account <id>` | Bot E2E self-check (URL verify/signature/encryption/stream-refresh, supports multi-account) |
 | `npm run wecom:remote:e2e -- --mode all --agent-url <public-agent-callback> --bot-url <public-bot-callback>` | remote matrix verification (Agent + Bot) |
-| `GitHub Actions -> CI -> Run workflow (run_remote_e2e=true)` | trigger remote E2E in CI (uses `WECOM_E2E_*` secrets) |
+| `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 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`) |
+| `npm run wecom:e2e:full -- --agent-url <public-agent-callback> --bot-url <public-bot-callback>` | one-shot full-smoke (pre-enabled `--prepare-browser --collect-pdf`) |
+| `GitHub Actions -> CI -> Run workflow` | trigger remote E2E in CI with `run_remote_e2e=true`; optionally pick `e2e_scenario` (including `compat-smoke`) and browser options |
 | `npm run wecom:smoke` | smoke test after upgrades (Agent path) |
 | `npm run wecom:smoke -- --with-bot-e2e` | smoke test after upgrades (with Bot E2E) |
 | `openclaw gateway restart` | restart runtime |
@@ -317,6 +384,16 @@ WeCom image URLs can return non-standard content type or encrypted media stream.
 ### 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.
 
+### Why is the Bot contact not visible in the WeChat plugin entry?
+This is usually a WeCom product behavior difference, not a plugin bug.  
+In many tenants, the WeChat plugin entry maps to **self-built app (Agent callback)** visibility, while Bot mode (intelligent bot API) is not exposed as a direct contact.
+
+Recommended setup:
+1. Need stable direct entry: prefer Agent mode.
+2. Need group notifications/conversation: prefer Webhook Bot / Bot mode.
+3. Need both: run Agent (entry) + Bot (group capability) together.
+4. Run `npm run wecom:bot:selfcheck -- --account <id>` (or `--all-accounts`) and check `bot.entry.visibility` to confirm this is expected product behavior rather than a plugin fault.
+
 ### Why does `curl https://<domain>/wecom/callback` return WebUI instead of webhook health text?
 That is a routing issue. `GET /wecom/callback` (without `echostr`) should return plain text `wecom webhook ok`.
 If you get WebUI HTML, your reverse proxy is sending `/wecom/*` to frontend/static service.

package/README.md

@@ -92,12 +92,16 @@ npm run wecom:selfcheck -- --all-accounts
 | 企业微信入站消息处理 | ✅ | 文本、图片、语音、链接、文件/视频（Agent + Bot） |
 | AI 自动回复 | ✅ | 接入 OpenClaw Runtime，自动路由 Agent |
 | Bot 原生 stream 协议 | ✅ | `msgtype=stream` 刷新与增量回包 |
+| Bot 卡片回包 | ✅ | 支持 `markdown/template_card`，失败自动降级文本 |
 | 多账户 | ✅ | `channels.wecom.accounts.<id>` |
 | 发送者授权控制 | ✅ | `allowFrom` + 账户级覆盖 |
-| 命令白名单 | ✅ | `/help` `/status` `/clear` 等 |
+| 私聊策略（DM） | ✅ | `dm.mode=open/allowlist/deny` + 账户级覆盖 |
+| 事件欢迎语（enter_agent） | ✅ | `events.enterAgentWelcome*` 可配置 |
+| 命令白名单 | ✅ | `/help` `/status` `/clear` `/new` 等 |
 | 群聊触发策略 | ✅ | 支持 `direct/mention/keyword` 三种模式 |
 | 文本防抖合并 | ✅ | 窗口期内多条消息合并投递 |
 | 异步补发（超时后） | ✅ | transcript 轮询补发最终回复 |
+| 观测统计 | ✅ | 入站/回包/错误计数 + 最近失败样本（`/status`） |
 | WeCom 出站代理 | ✅ | `outboundProxy` / `WECOM_PROXY` |
 
 ### 媒体能力
@@ -242,7 +246,7 @@ openclaw gateway restart
 openclaw gateway status
 openclaw plugins list
 npm run wecom:selfcheck -- --all-accounts
-npm run wecom:bot:selfcheck
+npm run wecom:bot:selfcheck -- --account default
 ```
 
 `wecom:selfcheck` 帮助：
@@ -269,12 +273,16 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | `agentId` | number/string | - | 应用 AgentId |
 | `callbackToken` | string | - | 回调 Token（敏感） |
 | `callbackAesKey` | string | - | 回调 AES Key（敏感） |
-| `webhookPath` | string | `/wecom/callback` | Agent 回调路径 |
+| `webhookPath` | string | `/wecom/callback` | Agent 回调路径（非 default 账户未配置时自动生成 `/wecom/<accountId>/callback`） |
+| `agent` | object | - | 兼容旧配置：`agent.corpId/corpSecret/agentId`（与顶层 Agent 字段等价） |
 | `outboundProxy` | string | - | WeCom 出站代理 |
 | `webhooks` | object | - | 命名 Webhook 目标映射（如 `{ "ops": "https://...key=xxx" }`） |
-| `accounts` | object | - | 多账户配置 |
+| `accounts` | object | - | 多账户配置（支持 `accounts.<id>.bot` 独立 Bot 配置） |
 
-兼容说明：旧字段 `token` / `encodingAesKey` 仍可用于 Agent 模式（分别等价于 `callbackToken` / `callbackAesKey`），建议逐步迁移到新字段名。
+兼容说明：支持旧字段与旧结构迁移：`name`、`token` / `encodingAesKey`、`agent.*`、`dynamicAgents.*`、`dm.createAgentOnFirstMessage`、`dm.allowFrom`、`workspaceTemplate`、`commandAllowlist/commandBlockMessage`、`commands.blockMessage`、以及 inline 账户写法 `channels.wecom.<accountId>`。新配置建议优先使用 `accounts.<id>`、`callbackToken/callbackAesKey`、`commands.*` 与 `dynamicAgent.*`。
+
+提示：`accounts.<id>` 现在支持 Bot-only 账号（仅配置 `bot.*`），不再强制要求 `corpId/corpSecret/agentId`。
+兼容提示：当使用默认新路径时会自动附加 legacy alias，便于旧回调地址平滑迁移：Agent 默认路径会附加 `/webhooks/app`（多账号为 `/webhooks/app/<id>`），Bot 默认路径会附加 `/webhooks/wecom`（多账号为 `/webhooks/wecom/<id>`）。若 alias 与另一类路由冲突会自动跳过并告警。
 
 ### Bot 配置（`channels.wecom.bot`）
 
@@ -283,12 +291,47 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | `enabled` | boolean | `false` | 启用 Bot 模式 |
 | `token` | string | - | Bot 回调 Token（敏感） |
 | `encodingAesKey` | string | - | Bot 回调 AESKey（43 位，敏感） |
-| `webhookPath` | string | `/wecom/bot/callback` | Bot 回调路径 |
+| `webhookPath` | string | `/wecom/bot/callback` | Bot 回调路径（非 default 账户未配置时自动生成 `/wecom/<accountId>/bot/callback`） |
 | `placeholderText` | string | `消息已收到...` | stream 初始占位文案（可设为空字符串） |
 | `streamExpireMs` | integer | `600000` | stream 状态保留时间（30s~1h） |
 | `replyTimeoutMs` | integer | `90000` | Bot 等待模型回包超时（15s~10m） |
 | `lateReplyWatchMs` | integer | `180000` | Bot 超时后异步补发观察窗口（30s~10m） |
 | `lateReplyPollMs` | integer | `2000` | Bot 异步补发轮询间隔（500ms~10s） |
+| `card` | object | 见下方 | Bot 卡片回包策略（`response_url` / `webhook_bot`） |
+
+> 重要限制：企业微信官方 Bot 在群聊里通常仅对 `@机器人` 消息触发回调。  
+> 因此 Bot 模式下即使配置 `groupChat.triggerMode=direct/keyword`，也会按 `mention` 处理（插件会输出告警）。
+
+#### Bot 卡片配置（`channels.wecom.bot.card`）
+
+| 键 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `enabled` | boolean | `false` | 启用卡片回包 |
+| `mode` | string | `markdown` | `markdown`（兼容优先）或 `template_card` |
+| `title` | string | `OpenClaw-Wechat` | 卡片标题 |
+| `subtitle` | string | - | 卡片副标题 |
+| `footer` | string | - | 卡片底部说明 |
+| `maxContentLength` | integer | `1400` | 卡片正文最大长度（自动截断） |
+| `responseUrlEnabled` | boolean | `true` | 是否在 `response_url` 层发送卡片 |
+| `webhookBotEnabled` | boolean | `true` | 是否在 `webhook_bot` 层发送卡片 |
+
+### 多账户 Bot 覆盖配置（`channels.wecom.accounts.<id>.bot`）
+
+当你启用了 `accounts` 多账户时，可以为每个账户单独配置 Bot 回调密钥、路径、超时和代理；若未配置，则回退到 `channels.wecom.bot`。
+
+| 键 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `enabled` | boolean | `false` | 是否启用该账户 Bot |
+| `token` / `callbackToken` | string | - | 该账户 Bot 回调 Token（兼容旧字段） |
+| `encodingAesKey` / `callbackAesKey` | string | - | 该账户 Bot 回调 AESKey（兼容旧字段） |
+| `webhookPath` | string | `/wecom/bot/callback` | 该账户 Bot 回调路径 |
+| `placeholderText` | string | `消息已收到...` | stream 初始占位文案 |
+| `streamExpireMs` | integer | `600000` | stream 状态保留时间 |
+| `replyTimeoutMs` | integer | `90000` | Bot 等待模型回包超时 |
+| `lateReplyWatchMs` | integer | `180000` | 超时后异步补发观察窗口 |
+| `lateReplyPollMs` | integer | `2000` | 异步补发轮询间隔 |
+| `card` | object | - | 该账户专用卡片回包配置（覆盖全局 `bot.card`） |
+| `outboundProxy` / `proxyUrl` / `proxy` | string | - | 该账户 Bot 专用代理（优先于全局） |
 
 ### 授权与指令策略
 
@@ -298,8 +341,10 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | 拒绝文案 | `allowFromRejectMessage` | 未授权提示 |
 | 管理员 | `adminUsers` | 绕过命令白名单 |
 | 命令白名单 | `commands.enabled` + `commands.allowlist` | 限制 `/` 指令 |
-| 群聊触发 | `groupChat.enabled` + `triggerMode` + `mentionPatterns` + `triggerKeywords` | 控制群消息触发条件 |
-| 动态路由 | `dynamicAgent.*`（含 `workspaceTemplate`） | 动态 Agent + workspace bootstrap 播种 |
+| 私聊策略 | `dm.mode` + `dm.allowFrom` + `dm.rejectMessage` | 控制私聊开放/白名单/拒绝 |
+| 事件策略 | `events.enabled` + `events.enterAgentWelcomeEnabled` + `events.enterAgentWelcomeText` | 控制事件处理与 enter_agent 欢迎语 |
+| 群聊触发 | `groupChat.enabled` + `triggerMode` + `mentionPatterns` + `triggerKeywords` | 控制群消息触发条件（自建应用支持 `direct/mention/keyword`；Bot 模式按平台限制固定 `mention`） |
+| 动态路由 | `dynamicAgent.*`（兼容 `dynamicAgents.*`、`dm.createAgentOnFirstMessage`） | 动态 Agent + workspace bootstrap 播种 |
 
 ### 吞吐与稳定性
 
@@ -308,6 +353,7 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | 文本防抖 | `debounce.enabled/windowMs/maxBatch` | 合并短时间多条文本 |
 | Agent 增量回包 | `streaming.enabled/minChars/minIntervalMs` | 多消息模拟流式 |
 | 异步补发 | `WECOM_LATE_REPLY_WATCH_MS/POLL_MS` | dispatch 超时后补发最终回复 |
+| 观测统计 | `observability.enabled/logPayloadMeta` | 记录入站/回包/错误并在 `/status` 展示 |
 
 ### 语音转写（本地）
 
@@ -350,6 +396,14 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
           "callbackAesKey": "aes-sales",
           "webhookPath": "/wecom/sales/callback",
           "outboundProxy": "http://10.0.0.5:8888",
+          "bot": {
+            "enabled": true,
+            "token": "sales-bot-token",
+            "encodingAesKey": "sales-bot-aes",
+            "webhookPath": "/wecom/sales/bot/callback",
+            "replyTimeoutMs": 120000,
+            "outboundProxy": "http://10.0.0.9:7890"
+          },
           "allowFrom": ["alice", "wecom:bob"],
           "allowFromRejectMessage": "销售助手未授权，请联系管理员。"
         }
@@ -392,8 +446,8 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | `/help` | 查看帮助 |
 | `/status` | 查看运行状态 |
 | `/clear` | 清理会话（兼容映射到 `/reset`） |
+| `/new` | 新建会话（兼容映射到 `/reset`） |
 | `/reset` | 重置会话 |
-| `/new` | 新建会话（由上层运行时支持） |
 | `/compact` | 压缩会话（由上层运行时支持） |
 
 ### 会话策略
@@ -437,6 +491,16 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | `WECOM_BOT_REPLY_TIMEOUT_MS` | 否 | Bot 等待模型回包超时 |
 | `WECOM_BOT_LATE_REPLY_WATCH_MS` | 否 | Bot 超时后补发观察窗口 |
 | `WECOM_BOT_LATE_REPLY_POLL_MS` | 否 | Bot 补发轮询间隔 |
+| `WECOM_BOT_CARD_ENABLED` | 否 | 是否启用 Bot 卡片回包 |
+| `WECOM_BOT_CARD_MODE` | 否 | 卡片模式：`markdown` / `template_card` |
+| `WECOM_BOT_CARD_TITLE` | 否 | 卡片标题 |
+| `WECOM_BOT_CARD_SUBTITLE` | 否 | 卡片副标题 |
+| `WECOM_BOT_CARD_FOOTER` | 否 | 卡片底部说明 |
+| `WECOM_BOT_CARD_MAX_CONTENT_LENGTH` | 否 | 卡片正文最大长度 |
+| `WECOM_BOT_CARD_RESPONSE_URL_ENABLED` | 否 | response_url 层卡片开关 |
+| `WECOM_BOT_CARD_WEBHOOK_BOT_ENABLED` | 否 | webhook_bot 层卡片开关 |
+| `WECOM_<ACCOUNT>_BOT_*` | 否 | 账户级 Bot 覆盖（如 `WECOM_SALES_BOT_TOKEN`） |
+| `WECOM_<ACCOUNT>_BOT_PROXY` | 否 | 账户级 Bot 媒体下载/回包代理 |
 
 ### 策略与流控
 
@@ -446,10 +510,13 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | `WECOM_ALLOW_FROM_REJECT_MESSAGE` / `WECOM_<ACCOUNT>_ALLOW_FROM_REJECT_MESSAGE` | 未授权提示 |
 | `WECOM_ADMIN_USERS` | 管理员用户列表 |
 | `WECOM_COMMANDS_ENABLED` / `WECOM_COMMANDS_ALLOWLIST` / `WECOM_COMMANDS_REJECT_MESSAGE` | 命令白名单策略 |
+| `WECOM_DM_POLICY` / `WECOM_DM_MODE` / `WECOM_DM_ALLOW_FROM` / `WECOM_DM_REJECT_MESSAGE` | 私聊策略（支持 `WECOM_<ACCOUNT>_DM_*` 覆盖） |
+| `WECOM_EVENTS_ENABLED` / `WECOM_EVENTS_ENTER_AGENT_WELCOME_ENABLED` / `WECOM_EVENTS_ENTER_AGENT_WELCOME_TEXT` | 事件处理与 enter_agent 欢迎语（支持 `WECOM_<ACCOUNT>_EVENTS_*`） |
 | `WECOM_GROUP_CHAT_ENABLED` / `WECOM_GROUP_CHAT_REQUIRE_MENTION` / `WECOM_GROUP_CHAT_MENTION_PATTERNS` | 群触发策略 |
 | `WECOM_DEBOUNCE_ENABLED` / `WECOM_DEBOUNCE_WINDOW_MS` / `WECOM_DEBOUNCE_MAX_BATCH` | 文本防抖 |
 | `WECOM_STREAMING_ENABLED` / `WECOM_STREAMING_MIN_CHARS` / `WECOM_STREAMING_MIN_INTERVAL_MS` | Agent 增量回包 |
 | `WECOM_LATE_REPLY_WATCH_MS` / `WECOM_LATE_REPLY_POLL_MS` | 异步补发窗口与轮询频率 |
+| `WECOM_OBSERVABILITY_ENABLED` / `WECOM_OBSERVABILITY_PAYLOAD_META` | 观测统计与载荷元信息日志开关 |
 
 ### 语音回退转写
 
@@ -486,6 +553,7 @@ node ./scripts/wecom-bot-selfcheck.mjs --help
 | 能收到消息但不回复 | `openclaw gateway status` + `openclaw logs --follow` | 模型超时、会话排队、权限策略拦截 | 查看 dispatch/allowFrom/commands 日志 |
 | Bot 图片识别失败 | `wecom(bot): failed to fetch image url` | URL 失效、返回非图像流 | 已支持 octet-stream+解密兜底，先升级到最新版本 |
 | 语音转写失败 | `wecom: voice transcription failed` | 本地命令或模型路径错误 | 检查 `command`、`modelPath`、`ffmpeg` |
+| 启动出现账号体检告警 | `wecom: account diagnosis ...` | 多账号 Token/Agent/路径存在冲突风险 | 按日志 `code` 与账户列表调整配置，优先处理 `warn` 级别 |
 | gettoken 失败 | 企业微信 API 返回码 | CorpId/Secret 错或网络受限 | 检查凭据/配置代理 |
 
 ### 推荐检查命令
@@ -496,7 +564,7 @@ openclaw status --deep
 openclaw logs --follow
 npm run wecom:selfcheck -- --all-accounts
 npm run wecom:agent:selfcheck -- --account default
-npm run wecom:bot:selfcheck
+npm run wecom:bot:selfcheck -- --all-accounts
 ```
 
 ## 开发与发布
@@ -506,12 +574,22 @@ npm run wecom:bot:selfcheck
 | 命令 | 作用 |
 |---|---|
 | `npm test` | 语法与单测 |
-| `WECOM_E2E_ENABLE=1 npm run test:e2e:remote` | 运行远程 E2E 测试（默认跳过，需配 `WECOM_E2E_BOT_URL`/`WECOM_E2E_AGENT_URL`） |
+| `WECOM_E2E_ENABLE=1 npm run test:e2e:remote` | 运行远程 E2E 测试（默认跳过；支持 `WECOM_E2E_*` 与兼容 `E2E_WECOM_*` 两套变量） |
+| `WECOM_E2E_MATRIX_ENABLE=1 npm run test:e2e:matrix` | 运行远程矩阵 E2E（签名验签/异常请求/stream refresh/去重链路） |
+| `npm run test:e2e:prepare-browser` | 远程浏览器沙箱就绪检查（可选自动安装 Chromium） |
+| `npm run test:e2e:collect-pdf` | 收集远端浏览器沙箱中的 PDF 产物到本地 |
 | `npm run wecom:selfcheck -- --all-accounts` | 配置+网络体检 |
 | `npm run wecom:agent:selfcheck -- --account <id>` | Agent 端到端链路体检（URL 验证 + 加密 POST） |
-| `npm run wecom:bot:selfcheck` | Bot 端到端链路体检（签名/加密/stream-refresh） |
+| `npm run wecom:bot:selfcheck -- --account <id>` | Bot 端到端链路体检（URL 验证/签名/加密/stream-refresh，支持多账户） |
 | `npm run wecom:remote:e2e -- --mode all --agent-url <公网Agent回调> --bot-url <公网Bot回调>` | 远端矩阵验证（Agent+Bot） |
-| `GitHub Actions -> CI -> Run workflow (run_remote_e2e=true)` | 在仓库 CI 手动触发远程 E2E（使用 `WECOM_E2E_*` secrets） |
+| `npm run wecom:remote:e2e -- --mode all --agent-url <公网Agent回调> --bot-url <公网Bot回调> --prepare-browser --collect-pdf` | 远端矩阵验证（含浏览器沙箱检查与 PDF 回收） |
+| `WECOM_E2E_BOT_URL=<...> WECOM_E2E_AGENT_URL=<...> npm run wecom:remote:e2e -- --mode all` | 用环境变量驱动远端 E2E（兼容旧 `E2E_WECOM_*`） |
+| `npm run wecom:e2e:scenario -- --scenario full-smoke --agent-url <公网Agent回调> --bot-url <公网Bot回调>` | 场景化 E2E（预置 smoke/queue 场景） |
+| `npm run wecom:e2e:scenario -- --scenario compat-smoke --agent-url <新Agent回调> --agent-legacy-url <旧Agent回调> --bot-url <新Bot回调> --bot-legacy-url <旧Bot回调>` | 兼容矩阵验证（新旧回调地址都跑一遍） |
+| `npm run wecom:e2e:scenario -- --scenario matrix-smoke --bot-url <公网Bot回调>` | Bot 协议矩阵验证（验签/异常请求/stream-refresh/去重；需 `WECOM_BOT_TOKEN/WECOM_BOT_ENCODING_AES_KEY`） |
+| `npm run wecom:e2e:compat -- --agent-url <新Agent回调> --agent-legacy-url <旧Agent回调> --bot-url <新Bot回调> --bot-legacy-url <旧Bot回调>` | 兼容矩阵快捷命令（等价 `--scenario compat-smoke`） |
+| `npm run wecom:e2e:full -- --agent-url <公网Agent回调> --bot-url <公网Bot回调>` | 一键 full-smoke（默认带 `--prepare-browser --collect-pdf`） |
+| `GitHub Actions -> CI -> Run workflow` | 在仓库 CI 手动触发远程 E2E：设置 `run_remote_e2e=true`，可选 `e2e_scenario`（含 `compat-smoke`）与浏览器参数 |
 | `npm run wecom:smoke` | 升级后快速回归（Agent 主链路） |
 | `npm run wecom:smoke -- --with-bot-e2e` | 升级后快速回归（含 Bot E2E） |
 | `openclaw gateway restart` | 重启网关 |
@@ -537,6 +615,16 @@ npm run wecom:bot:selfcheck
 ### Q4：支持个人微信吗？
 支持企业微信场景下的“微信插件入口”（个人微信扫码进入企业应用对话），不等同于“个人微信网页版协议”。
 
+### Q4.1：为什么 Bot 模式在“微信插件入口”里看不到机器人联系人？
+这是企业微信产品形态差异，不是插件故障。  
+在很多租户里，“微信插件入口”主要对应**自建应用（Agent 回调）**可见，Bot 模式（智能机器人 API）不会以可直接会话的联系人形态出现。
+
+建议：
+1. 需要稳定私聊入口：优先用自建应用（Agent 模式）
+2. 需要群聊通知/群内对话：优先用 Webhook Bot / Bot 模式
+3. 需要两者兼顾：并行启用 Agent（入口）+ Bot（群能力）
+4. 运行 `npm run wecom:bot:selfcheck -- --account <id>`（或 `--all-accounts`）可看到 `bot.entry.visibility` 提示，用于快速确认该行为属于产品形态差异而非插件故障
+
 ### Q5：为什么 `curl https://域名/wecom/callback` 返回的是 WebUI 页面？
 这是路由层问题，不是插件正常行为。`GET /wecom/callback`（无 `echostr`）应返回纯文本 `wecom webhook ok`。  
 若返回 WebUI，说明你的反向代理把该路径转发到了前端服务而不是 OpenClaw 网关。
@@ -548,10 +636,10 @@ npm run wecom:bot:selfcheck
 
 ### Q6：自建应用群聊怎么开？为什么群里不 @ 就不触发？
 先区分两种通道能力：
-1. **群机器人（Webhook Bot）**：可直接添加到企微群，天然适合群聊收发。
+1. **群机器人（Webhook Bot）**：可直接添加到企微群，天然适合群聊收发；但群聊通常仅 `@机器人` 时才会回调。
 2. **自建应用（Agent 回调）**：插件支持处理 `ChatId` 群消息；但是否能收到“普通群消息”取决于企业微信实际下发能力（很多租户里普通群只能加机器人，无法像成员一样加自建应用）。
 
-如果你的场景是“普通群里直接聊天并稳定触发”，优先用 **Webhook Bot 模式**。  
+如果你的场景是“普通群里稳定对话”，优先用 **Webhook Bot 模式**（注意通常仍需 `@机器人` 才触发）。  
 如果你确认企业微信会把群消息回调到自建应用（日志里有 `chatId=...`），再配置触发模式：
 
 ```json