{"id":"2f2e9dec-8c31-4780-aa3b-295928481654","entityType":"agent","slug":"clawhub-zhaobod1-huo15-wecom-plugin","name":"Huo15 Wecom Plugin","canonicalUrl":"https://www.xpersona.co/agent/clawhub-zhaobod1-huo15-wecom-plugin","canonicalPath":"/agent/clawhub-zhaobod1-huo15-wecom-plugin","generatedAt":"2026-10-10T11:52:52.457Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T09:44:37.095Z","emptyReason":null},"description":"火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担... Skill: Huo15 Wecom Plugin Owner: zhaobod1 Summary: 火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担... Tags: latest:2.9.5, plugin:2.8.30 Version history: v2.9.5 | 2026-05-10T18:38:42.867Z | auto - Added a new CHANGELOG.md file for improved change tracking. - Updated openclaw.plugin.json and package.json for th","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.5K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17f6q72skfgyjycm2frgdc8dn83v5mk:huo15-wecom-plugin","sourceUrl":"https://clawhub.ai/zhaobod1/huo15-wecom-plugin","homepage":"https://clawhub.ai/zhaobod1/skills/huo15-wecom-plugin","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/zhaobod1/huo15-wecom-plugin","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/zhaobod1/skills/huo15-wecom-plugin","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:44:37.095Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:44:37.095Z","emptyReason":null},"stars":null,"forks":null,"downloads":1519,"packageName":null,"latestVersion":"2.9.5","tractionLabel":"1.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:44:37.095Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T09:44:37.095Z","lastCrawledAt":"2026-10-10T09:44:37.095Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T09:44:37.095Z","lastVerifiedAt":null,"highlights":[{"version":"2.9.5","createdAt":"2026-05-10T18:38:42.867Z","changelog":"- Added a new CHANGELOG.md file for improved change tracking. - Updated openclaw.plugin.json and package.json for this release.","fileCount":247,"zipByteSize":508448},{"version":"2.9.4","createdAt":"2026-05-09T15:48:47.413Z","changelog":"v2.9.4 更新内容： - 更新版本号至 2.9.4，并补充变更日志文件。 - 优化和调整核心 Agent API 相关代码（src/transport/agent-api/core.ts）。 - 文档（SKILL.md）版本号同步更新，无重大功能新增。","fileCount":245,"zipByteSize":506324},{"version":"2.9.2","createdAt":"2026-05-07T06:39:40.926Z","changelog":"v2.9.2 adds a changelog and includes minor updates. - Added changelog/v2.9.2.md for clearer release tracking - Updated version references in SKILL.md and package.json - Minor code/test adjustments in src/dynamic-agent.ts and src/dynamic-agent.test.ts","fileCount":244,"zipByteSize":504065},{"version":"2.9.1","createdAt":"2026-05-07T06:08:41.963Z","changelog":"- 更新版本至 v2.9.1 - 新增 changelog/v2.9.1.md 以记录本次变更 - 更新依赖和版本信息 - 优化和调整 dynamic-agent 相关实现 - 文档（SKILL.md）版本号同步至 2.9.1，无功能描述变更","fileCount":243,"zipByteSize":500588},{"version":"2.9.0","createdAt":"2026-05-07T05:55:36.575Z","changelog":"huo15-wecom-plugin v2.9.0 - Added new tests, including src/dynamic-agent.test.ts, improving automated test coverage. - Updated internal logic in dynamic agent handling and stream orchestrator modules. - Improved routing bridge with changes to both implementation and tests. - Updated documentation and metadata for version 2.9.0. - Added a changelog entry for this release.","fileCount":242,"zipByteSize":498742},{"version":"2.8.32","createdAt":"2026-05-06T09:38:01.095Z","changelog":"- Bump version to 2.8.32. - Add changelog for v2.8.32. - Update SKILL.md to reflect new version.","fileCount":240,"zipByteSize":490296},{"version":"2.8.31","createdAt":"2026-05-06T09:32:30.359Z","changelog":"huo15-wecom-plugin v2.8.31 - Updated version to 2.8.31 with documentation and metadata adjustments. - Added changelog entry for v2.8.31. - Made changes across bot WebSocket transport files for media and reply handling. - Minor updates to SKILL.md and package.json.","fileCount":239,"zipByteSize":489257},{"version":"2.8.30","createdAt":"2026-05-06T07:54:06.641Z","changelog":"- Bump version to 2.8.30. - Changelog file added for version 2.8.30. - Minor updates in SKILL.md version metadata. - Other internal code or documentation updates.","fileCount":238,"zipByteSize":486193}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17f6q72skfgyjycm2frgdc8dn83v5mk:huo15-wecom-plugin","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T11:52:52.452Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-zhaobod1-huo15-wecom-plugin/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T09:44:37.095Z","emptyReason":null},"readme":"Skill: Huo15 Wecom Plugin\n\nOwner: zhaobod1\n\nSummary: 火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担...\n\nTags: latest:2.9.5, plugin:2.8.30\n\nVersion history:\n\nv2.9.5 | 2026-05-10T18:38:42.867Z | auto\n\n- Added a new CHANGELOG.md file for improved change tracking.\n- Updated openclaw.plugin.json and package.json for this release.\n\nv2.9.4 | 2026-05-09T15:48:47.413Z | auto\n\nv2.9.4 更新内容：\n\n- 更新版本号至 2.9.4，并补充变更日志文件。\n- 优化和调整核心 Agent API 相关代码（src/transport/agent-api/core.ts）。\n- 文档（SKILL.md）版本号同步更新，无重大功能新增。\n\nv2.9.2 | 2026-05-07T06:39:40.926Z | auto\n\nv2.9.2 adds a changelog and includes minor updates.\n\n- Added changelog/v2.9.2.md for clearer release tracking\n- Updated version references in SKILL.md and package.json\n- Minor code/test adjustments in src/dynamic-agent.ts and src/dynamic-agent.test.ts\n\nv2.9.1 | 2026-05-07T06:08:41.963Z | auto\n\n- 更新版本至 v2.9.1\n- 新增 changelog/v2.9.1.md 以记录本次变更\n- 更新依赖和版本信息\n- 优化和调整 dynamic-agent 相关实现\n- 文档（SKILL.md）版本号同步至 2.9.1，无功能描述变更\n\nv2.9.0 | 2026-05-07T05:55:36.575Z | auto\n\nhuo15-wecom-plugin v2.9.0\n\n- Added new tests, including src/dynamic-agent.test.ts, improving automated test coverage.\n- Updated internal logic in dynamic agent handling and stream orchestrator modules.\n- Improved routing bridge with changes to both implementation and tests.\n- Updated documentation and metadata for version 2.9.0.\n- Added a changelog entry for this release.\n\nv2.8.32 | 2026-05-06T09:38:01.095Z | auto\n\n- Bump version to 2.8.32.\n- Add changelog for v2.8.32.\n- Update SKILL.md to reflect new version.\n\nv2.8.31 | 2026-05-06T09:32:30.359Z | auto\n\nhuo15-wecom-plugin v2.8.31\n\n- Updated version to 2.8.31 with documentation and metadata adjustments.\n- Added changelog entry for v2.8.31.\n- Made changes across bot WebSocket transport files for media and reply handling.\n- Minor updates to SKILL.md and package.json.\n\nv2.8.30 | 2026-05-06T07:54:06.641Z | auto\n\n- Bump version to 2.8.30.\n- Changelog file added for version 2.8.30.\n- Minor updates in SKILL.md version metadata. \n- Other internal code or documentation updates.\n\nv2.8.29 | 2026-05-06T00:27:18.832Z | auto\n\nhuo15-wecom-plugin v2.8.29\n\n- Updated SKILL.md to reflect version 2.8.29.\n- Added changelog for v2.8.29.\n- Minor code and documentation adjustments.\n\nv2.8.28 | 2026-05-05T17:59:45.047Z | auto\n\nhuo15-wecom-plugin v2.8.28\n\n- Updated version strings in documentation and package metadata to 2.8.28.\n- Added a changelog entry for v2.8.28.\n\nv2.8.27 | 2026-05-05T17:33:17.220Z | auto\n\nv2.8.27 is a regular update with minor improvements and maintenance.\n\n- Bumped version to 2.8.27.\n- Updated SKILL.md for new version.\n- Added changelog file for v2.8.27.\n- Minor code changes and housekeeping in src/transport/bot-ws/reply.ts.\n\nv2.8.26 | 2026-05-05T17:06:36.090Z | auto\n\nv2.8.26 is a maintenance update.\n\n- Updated SKILL.md version and metadata to v2.8.26.\n- Added changelog/v2.8.26.md file for version tracking.\n- Made minor adjustments in bot-ws/reply.ts and bot-ws/sdk-adapter.ts.\n- package.json updated for new version.\n\nv2.8.25 | 2026-05-05T15:52:34.436Z | auto\n\n- GUIDANCE 媒体优先级策略调整：MEDIA: 直发重新成为默认，仅大文件（超企微限制）走 enhance_share_file 链接\n- 新增 GUIDANCE 决策表与用户偏好覆盖机制，提供更灵活的发送策略\n- 保持 v2.8.24 的 placeholder timeout UI 解锁及群聊主动推送等修复和优化\n- 文档与 changelog 同步更新\n\nv2.8.24 | 2026-05-05T15:22:51.696Z | auto\n\n- 修复企微 UI 锁交互问题：当 placeholder timeout 120 秒触发时，发送 last=true 终结 stream，保证客户端 UI 解锁，用户可正常复制消息和操作链接\n- 之前仅 stopKeepalive 未发送 last=true，导致 streamId 停在 last=false，长任务场景下用户无法复制消息\n- 保持群聊主动推送通道支持和 GUIDANCE enhance_share_file 优先\n- 详细更新内容见 changelog/v2.8.24.md\n\nv2.8.23 | 2026-05-05T15:03:09.354Z | auto\n\nv2.8.23 重点修复：群聊下 WS 直接发文件失败问题，确保群聊媒体消息正常送达\n\n- 群聊发送文件修复：uploadAndReplyBotWsMedia 在群聊场景改用 sendMediaMessage（主动推送），避免 replyMedia 导致 86008 错误\n- 单聊（DM）场景继续用 replyMedia，保证被动回复正常与 reqId 绑定\n- 继承 v2.8.22 的 enhance_share_file 优先路径，大文件继续支持链接兜底\n- 代码和文档细节同步更新\n\nv2.8.22 | 2026-05-04T20:54:51.314Z | auto\n\n**Summary:** This release refines file sharing behavior for better reliability in OpenClaw stream scenarios.\n\n- Guidance now prefers the enhance_share_file tool for file sending, avoiding direct MEDIA: emissions.\n- This change circumvents issues where OpenClaw stream processing truncates MEDIA: lines, ensuring more reliable file delivery.\n- The MEDIA: path remains as a fallback if tool calls are unavailable.\n- Previous diagnostics and logging enhancements are retained.\n\nv2.8.21 | 2026-05-04T14:53:35.522Z | auto\n\nv2.8.21 focuses on diagnostic and resilience improvements.\n\n- Enhanced MEDIA: parser in reply.ts with detected/warning logs for better diagnosis (logs appear in gateway.log).\n- Improved media.ts to log detailed errcode information, including identification of 86008 group permission issues.\n- Updated GUIDANCE instructions with ✅/❌ examples to discourage LLM from embedding MEDIA: markers in message body.\n- Retained previous improvements to media extraction and outbound paths for reliable media handling.\n\nv2.8.20 | 2026-05-04T11:55:41.472Z | auto\n\nv2.8.20 resolves a gap in media handling for group chat replies (@机器人) in-context via bot-ws/reply.\n\n- Fixed: bot-ws/reply now recognizes MEDIA: <path> directives, not just outbound.sendText, ensuring in-group replies can send files like zip attachments.\n- Added: MEDIA: directives in reply.ts are extracted and merged to incomingMediaUrls, so uploadAndReplyBotWsMedia uses the correct path for file delivery.\n- Test: Updated tests to cover new MEDIA: extraction logic in bot-ws reply handling.\n- Documentation: Updated SKILL.md to reflect the fix and related use cases.\n\nv2.8.19 | 2026-05-04T09:14:58.070Z | auto\n\nOpenClaw 企业微信插件 v2.8.19 重点修复与增强：\n\n- outbound.sendText 现支持单行/多行 \"MEDIA: <path>\" 指令（不区分大小写），自动发送本地文件/媒体，修复过去 LLM 发送 zip、图片等被当作文本的问题。\n- 支持按序依次发送多条 MEDIA 指令，某一条失败不影响其它条。\n- 路径支持自动展开 ~ 及去除引号。\n- 继承 v2.8.18 的 ClawHub plugin tag 兼容性改进与 v2.8.17 起的长期监听、结果回流等修复。\n\nv2.8.18 | 2026-05-02T10:37:50.195Z | auto\n\n- Registered ClawHub plugin tag for improved compatibility with OpenClaw plugin installation (now supports `openclaw plugins install @huo15/wecom` without explicit version number).\n- Documentation updated to reflect new version and features.\n- Inherits previous updates: long-task result fallback (error code 846605/846608 fallback to sendMessage + Agent API), progressMode, and various media/file handling improvements.\n\nv2.8.16 | 2026-05-02T02:59:07.665Z | auto\n\nv2.8.16 hotfix: Improves reliability of media uploads/sends via WS by automatically falling back to the enhanced share link method when errors (such as SDK 5s ack timeout) occur.\n\n- WS upload/send failures now auto-fallback to enhanced share link, reducing file message failures during WeCom WS instability.\n- Continues large file share-fallback from v2.8.15 and WS BOT image handling fixes from v2.8.8.\n- No longer fails file messages solely due to WS interruptions.\n- All previous functionality and fixes are retained.\n\nArchive index:\n\nArchive v2.9.5: 247 files, 508448 bytes\n\nFiles: CHANGELOG.md (818b), changelog/v2.2.28.md (3745b), changelog/v2.3.10.md (1572b), changelog/v2.3.11.md (1837b), changelog/v2.3.12.md (3259b), changelog/v2.3.13.md (2018b), changelog/v2.3.14.md (4670b), changelog/v2.3.15.md (2241b), changelog/v2.3.16.md (1113b), changelog/v2.3.18.md (4080b), changelog/v2.3.19.md (6771b), changelog/v2.3.2.md (2795b), changelog/v2.3.26.md (1830b), changelog/v2.3.27.md (4345b), changelog/v2.3.273.md (680b), changelog/v2.3.4.md (1755b), changelog/v2.3.9.md (1711b), changelog/v2.4.12.md (4707b), changelog/v2.4.16.md (1157b), changelog/v2.7.4.md (2724b), changelog/v2.8.0.md (3687b), changelog/v2.8.1.md (2230b), changelog/v2.8.17.md (7630b), changelog/v2.8.18.md (3377b), changelog/v2.8.19.md (5692b), changelog/v2.8.2.md (2496b), changelog/v2.8.20.md (7103b), changelog/v2.8.21.md (8625b), changelog/v2.8.22.md (6594b), changelog/v2.8.23.md (6868b), changelog/v2.8.24.md (7061b), changelog/v2.8.25.md (5291b), changelog/v2.8.26.md (6532b), changelog/v2.8.27.md (5994b), changelog/v2.8.28.md (3728b), changelog/v2.8.29.md (4665b), changelog/v2.8.3.md (3447b), changelog/v2.8.30.md (4967b), changelog/v2.8.31.md (6539b), changelog/v2.8.32.md (1368b), changelog/v2.8.6.md (3301b), changelog/v2.8.8.md (5098b), changelog/v2.9.0.md (6833b), changelog/v2.9.1.md (2771b), changelog/v2.9.2.md (3292b), changelog/v2.9.4.md (3128b), compat-single-account.md (4135b), GOVERNANCE.md (1301b), index.test.ts (1058b), index.ts (5408b), openclaw.plugin.json (11697b), package.json (3045b), README.md (31424b), scripts/release.sh (11536b), scripts/test-proxy.ts (2377b), skill-card.md (2805b), SKILL.md (4871b), SKILLS_CAL.md (29478b), SKILLS_DOC.md (70311b), src/accounts.ts (1223b), src/agent/api-client.upload.test.ts (3909b), src/agent/handler.event-filter.test.ts (3469b), src/agent/handler.ts (39593b), src/agent/index.ts (248b), src/app/account-runtime.ts (11247b), src/app/bootstrap.ts (890b), src/app/index.ts (6075b), src/capability/agent/delivery-service.ts (4475b), src/capability/agent/fallback-policy.ts (484b), src/capability/agent/index.ts (221b), src/capability/agent/ingress-service.ts (1126b), src/capability/agent/upstream-delivery-service.ts (3728b), src/capability/bot/dispatch-config.ts (1854b), src/capability/bot/fallback-delivery.ts (6892b), src/capability/bot/index.ts (58b), src/capability/bot/local-path-delivery.ts (8059b), src/capability/bot/sandbox-media.test.ts (7025b), src/capability/bot/sandbox-media.ts (5688b), src/capability/bot/service.ts (1651b), src/capability/bot/stream-delivery.ts (16654b)\n\nFile v2.9.5:SKILL.md\n\n---\nname: huo15-wecom\ndescription: \"火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担心 stream 截断 + 86008 把链接设为优先，v2.8.23/v2.8.24 修了群聊主动推送通道 + UI 锁交互后 MEDIA: 路径稳定可靠，应用户偏好翻转：默认 MEDIA: 直发，仅大文件（> 企微上限）才走 enhance_share_file 链接。GUIDANCE 加决策表 + 用户偏好覆盖。继承 v2.8.24 placeholder timeout 解锁、v2.8.23 群聊主动推送、v2.8.20 MEDIA: parser。Use when: 接企业微信、给企微 Bot/自建应用接 OpenClaw、用微信客服收外部用户消息、需要图片/文件双向、跨账号切换。Do NOT use for 个人微信（不同协议）。\"\nversion: 2.9.4\nhomepage: https://cnb.cool/huo15/ai/huo15-wecom-plugin\nmetadata: { \"openclaw\": { \"emoji\": \"🦜\", \"requires\": { \"bins\": [] } } }\n---\n\n# 火一五企业微信插件\n\n`@huo15/wecom` 是 OpenClaw 的企业微信通道插件，fork 自 [yanhaidao/wecom](https://github.com/yanhaidao/wecom) 并持续合并上游。**默认 Bot WebSocket 模式**，配置简单、响应快；同时支持 Agent 自建应用主动推送和微信客服三方通道。\n\n## 三条消息通道\n\n| 通道 | 用途 | 配置入口 |\n|---|---|---|\n| **Bot WebSocket** | 默认推荐，企业微信\"智能机器人\"WS 协议，免公网回调 | `channels.wecom.accounts.<id>.bot.ws` |\n| **Agent 自建应用** | 走企微官方 API（CorpId/AgentId/Secret），支持主动推送给指定用户/群 | `channels.wecom.accounts.<id>.agent` |\n| **微信客服** | 接管\"客服会话\"，外部客户在微信/视频号里发给客服账号的消息 | `channels.wecom.accounts.<id>.kefu` |\n\n三条通道可以**单独启用**或**组合启用**，多账号场景每个账号独立配置。\n\n## 安装\n\n```bash\n# OpenClaw 内置安装（推荐）\nopenclaw plugins install @huo15/wecom\n\n# 或者直接 npm\nnpm install @huo15/wecom\n```\n\n## 最小配置（Bot WS 模式）\n\n```yaml\n# ~/.openclaw/openclaw.json 中\nchannels:\n  wecom:\n    enabled: true\n    accounts:\n      default:\n        bot:\n          ws:\n            botId: \"你的智能机器人 ID\"\n            secret: \"WS 密钥\"\n```\n\n启动后，Bot 收到的消息会自动路由到默认 Agent，回复也通过 WS 直接送回 — 不需要部署任何回调 endpoint。\n\n## 关键能力\n\n- **加密媒体解密**：图片/文件/语音 AES-256-CBC 解密直接拿 buffer，可让 Agent 直接读取（OCR / ASR / 文档解析）\n- **Markdown V2**：支持企微富文本（标题、表格、代码块、链接、引用），自动适配 chat 上下文\n- **图片回复**：`![alt](url)` 自动抽离 + uploadMedia + replyMedia，COS/OSS 预签名 URL 失败时降级为占位文本（不让\"链接已过期\"漏到客户端）\n- **多账号切换**：单实例支持多个企业、多个智能体并存，按 conversation 路由\n- **流式回复**：placeholder + partial replyStream（最多 8 次中间更新）+ ack timeout watchdog 自动重连\n\n## v2.8.8 关键修复（WS BOT 图片）\n\n1. **Reply 通道纠错**：reply 上下文从 `sendMediaMessage`（主动推送）改用 `replyMedia`（被动回复，绑定 reqId）\n2. **入向多图**：`mixed` 与 `quote.mixed` 类型从只取首张改为全部提取；首张挂 `ctx.MediaPath`，其余落盘 + info 日志\n3. **Outbound fetch UA**：从裸 `fetch` 切到 plugin-sdk `fetchRemoteMedia`，显式带 desktop User-Agent，避免部分 Tencent COS / 阿里 OSS bucket 拒绝 Node 默认 UA\n4. **解析可观测性**：媒体类型消息但无 attachments 时记 warn 日志（含 msgid + body keys），便于 SDK 字段漂移排查\n\n详见 [changelog/v2.8.8.md](./changelog/v2.8.8.md)。\n\n## 安全实践\n\n- LLM 输出的 `touser` / `chatid` 经 `resolveWecomTarget` sanitizer，**拒绝 `@all` / `@everyone` / `*` 等广播字面量**（v2.8.1 SECURITY 修复）\n- 跨企业上下游消息走 upstream-delivery 通道，不与本企业 Agent API 混用\n- 微信客服 `corpSecret` 可与 Agent `corpSecret` 独立配置，权限隔离\n\n## 不变的设计原则\n\n- **Bot WS 优先**：能用 WS 就不用 Agent API（少配置、低延迟）\n- **失败降级**：WS reply ack timeout 自动 fallback 到 Agent API（保留消息可达性），watchdog 连续 8 次后触发 WS 重连\n- **不修改 OpenClaw 核心**：所有功能通过 channel plugin SDK 注册\n\n## 仓库\n\n- 主仓库：https://cnb.cool/huo15/ai/huo15-wecom-plugin\n- 镜像：https://github.com/zhaobod1/huo15-wecom-plugin\n- 上游 fork 源：https://github.com/yanhaidao/wecom（**仅 fetch，不 push**）\n\n## License\n\nISC（继承自 yanhaidao/wecom 上游）。\n\nFile v2.9.5:README.md\n\n# OpenClaw 企业微信(WeCom)Channel 插件\n\n<p align=\"center\">\n  <a href=\"https://github.com/yanhaitao/wecom\"><img src=\"https://img.shields.io/badge/Original%20Project-逸寻智库-orange?style=for-the-badge&logo=github\" alt=\"Original Project\" /></a>\n  <img src=\"https://img.shields.io/badge/License-ISC-blue?style=for-the-badge\" alt=\"License\" />\n  <img src=\"https://img.shields.io/badge/Min%20Recommended-2.8.1+-red?style=for-the-badge\" alt=\"Minimum recommended\" />\n</p>\n\n> [!CAUTION]\n> **🛡️ 安全公告（2026-04-22）**：受影响版本 `<= 2.8.0`。Agent 在工作区写自定义脚本时可能把 `touser=\"@all\"` 当默认收件人，导致原本私聊的图片/视频/文档**被广播到企业微信应用可见范围全员**。\n>\n> **请所有部署立即升级到 `@huo15/wecom@2.8.1` 或以上**。修复见 [`changelog/v2.8.1.md`](changelog/v2.8.1.md)。\n\n> [!WARNING]\n> **原创声明**:本项目涉及的\"多账号隔离与矩阵路由架构\"、\"Bot+Agent双模融合架构\"、\"长任务超时接力逻辑\"及\"全自动媒体流转接\"等核心设计均为作者 **YanHaidao** 独立思考与实践的原创成果。\n> 欢迎技术交流与合规引用,但严禁任何不经授权的\"功能像素级抄袭\"或删除原作者署名的代码搬运行为。\n\n<p align=\"center\">\n  <strong>🚀 企业级多模式 AI 助手接入方案(统一运行时架构)</strong>\n</p>\n\n---\n\n## 💡 核心价值:为什么团队会真正选择这个插件?\n\n企业真正需要的,不是\"把一个模型接进企业微信\",而是让企业微信变成一个**能长期工作的 AI 协作入口**。\n\n大多数团队最终只关心五件事:\n\n- 能不能先低门槛接起来,而不是先做一轮重部署\n- 多人同时使用时,会不会串上下文、串身份、串会话\n- 长任务会不会因为长连接窗口太短而白跑\n- 能不能既有实时对话体验,又能做正式推送和稳定投递\n- AI 能不能真正进入文档、日程、会议、待办、通讯录这些协作层,而不只是停留在聊天框\n\n常见方案通常会很快碰到边界:\n\n- **只用 Bot WS**:接得快、聊得顺,但会受到单连接、心跳保活、会话边界和组织级广播能力的限制\n- **只用 Agent**:能力强、治理清晰,但部署门槛更高,对话体验不如 Bot WS 丝滑\n- **只选单一路径**:团队最后往往被迫在\"体验\"和\"能力\"之间二选一\n\n本插件的价值,就在于把这些原本互相冲突的目标,尽量同时成立。\n\n### 您真正会得到什么?\n\n1. **多人共用一个入口,但上下文不会串**\n   - **问题本质**:企业里真正难的不是\"接入一个机器人\",而是让几十上百个人同时使用时,仍然保持每个人的上下文隔离。\n   - **插件做法**:按 `(底层账号 + 部门/群组/人员)` 动态切分运行上下文和 Agent 实例。\n   - **用户收益**:同一个企业微信入口可以承接多人并发使用,而不会出现\"张三的问题让李四接上回答\"的串流灾难。\n\n2. **长任务不白跑,回复不轻易丢**\n   - **问题本质**:企业微信长连接的响应窗口很短,而推理模型的思考时间往往很长。\n   - **插件做法**:先保活,再流式推进;必要时走备用投递路径,把最终结果交付出去。\n   - **用户收益**:更敢把复杂任务、长文本分析、报告生成交给 AI,而不是每次都担心\"算完了却发不回来\"。\n\n3. **实时对话体验和正式投递能力,不用二选一**\n   - **问题本质**:实时聊天和组织级推送,往往不是同一条技术路径最擅长的事。\n   - **插件做法**:会话内实时交互、流式回复、异步追发优先走 `Bot WS`;组织级广播、冷启动触达、正式通知由 `Agent` 兜底。\n   - **用户收益**:日常使用时体验像聊天助手,正式落地时又有企业应用该有的稳定性和控制力。\n\n4. **AI 不只会聊天,还能进入企业微信协作层**\n   - **问题本质**:如果 AI 只能回消息,信息最终还是散落在聊天流里,业务并没有真正被推进。\n   - **插件做法**:把企业微信原生协作能力按两条能力平面接入 OpenClaw。\n   - **用户收益**:AI 不仅能回答问题,还能真正参与文档、日程、会议、待办和通讯录相关工作。\n\n5. **小团队能低门槛上手,大团队也能正式上线**\n   - **问题本质**:小团队怕折腾,大团队怕失控。\n   - **插件做法**:`Bot WS` 适合快速启用,`Agent` 适合正式治理,两者可以并存。\n   - **用户收益**:您不用在\"今天先跑起来\"和\"将来能不能正规化\"之间做破坏性迁移。\n\n---\n\n## 📊 为什么不是只选 Bot,或者只选 Agent?\n\n从用户视角看,差别不在于协议名词,而在于**你要解决的是什么问题**。\n\n| 你真正关心的事 | 🤖 Bot 模式 (WebSocket) | 🧩 Agent 模式 (自建应用 API) | ✨ 本插件的做法 |\n|:---|:---|:---|:---|\n| **先跑起来的速度** | ✅ 快,无需固定公网 IP | ❌ 较重,需要正式应用配置 | ✅ 先用 Bot 起步,后续平滑补 Agent |\n| **实时聊天体验** | ✅ 最强,天然适合低延迟和流式回复 | ⚠️ 能收能发,但不是最佳对话入口 | ✅ 默认把实时交互交给 Bot |\n| **异步结果回推** | ✅ 可以,适合已建立会话内追发 | ✅ 可以 | ✅ 会话内追发优先 Bot,必要时 Agent 兜底 |\n| **组织级广播与冷启动触达** | ⚠️ 受会话边界约束 | ✅ 更适合 | ✅ 正式通知和广播走 Agent |\n| **企业微信协作能力** | ✅ 适合个人身份能力入口 | ✅ 适合应用身份能力入口 | ✅ 两种身份平面都兼容 |\n| **适合谁** | 想快速上线、重视实时体验的团队 | 需要正式治理、自动化和组织级能力的团队 | 想同时要\"体验\"和\"能力\"的团队 |\n\n> **建议理解方式:**\n> - 如果您最在意的是\"先接起来、先用起来、先聊顺\",优先上 `Bot WS`\n> - 如果您最在意的是\"正式部署、组织级能力、自动化治理\",补齐 `Agent`\n> - 如果您真正想把 AI 在企业微信里长期用下去,最终往往需要两者并存\n\n---\n\n## 🧩 企业微信协作能力:为什么这件事比\"能聊天\"更重要?\n\n很多企业微信 AI 机器人,本质上只是把答案发回聊天框。\n真正有价值的,是让 AI 进入您**已经在工作的地方**。\n\n在本插件里,企业微信的**文档、日程、会议、待办、通讯录**等能力,不再只是外围说明,而是被接成了可以实际调用的协作平面。\n\n### 1. Bot WS 协作模式:适合小团队的个人身份入口\n\n根据企业微信最新开放说明,面向 **5 人及以下的小微企业**,`Bot WS` 模式现已开放以**用户个人身份**调用部分企业微信协作能力。\n\n在本插件里,这条链路以 `wecom_mcp` 的方式挂载,只在 **WeCom Bot WS 会话** 中可用:\n\n- 能力入口:`wecom_mcp`\n- 典型能力品类:`doc`、`meeting`、`todo`、`contact`\n- 触发条件:当前会话必须来自 `Bot WS`\n- 更适合的场景:个人身份读写文档、查询通讯录、处理待办、操作会议等轻量协作场景\n\n它的价值在于:\n\n- **门槛低**:无需先走完整的自建应用接入流程\n- **身份自然**:更贴近当前聊天用户自己的协作上下文\n- **启动快**:对小团队尤其友好\n\n它的边界也要明确:\n\n- 依赖 `Bot WS` 会话存在\n- 主动推送仍然以**已建立会话**为前提\n- 实际开放范围以企业微信后台可见权限为准\n\n### 2. Agent 协作模式:适合正式落地的应用身份入口\n\n`Agent` 模式走的是**自建应用 API** 平面,更适合企业级稳定自动化与组织级治理。\n\n在本插件里,当前内置的协作工具主要包括:\n\n- `wecom_doc`:文档、表格、权限、分享可用性诊断等\n- `wecom_calendar`:日历、日程、参与人、回执、默认日历等\n\n它更适合:\n\n- 把协作能力放进正式企业应用权限体系\n- 与定时任务、异步流程、正式投递联动\n- 面向组织对象做更稳定的自动化操作\n\n### 3. 这两条能力链在插件里已经实际接通\n\n当前插件已经把这两条协作链路都注册进来:\n\n- `wecom_mcp`:仅在 `Bot WS` 会话中暴露\n- `wecom_doc`:仅在 `Agent` 会话中暴露\n- `wecom_calendar`:仅在 `Agent` 会话中暴露\n\n也就是说,您拿到的不是\"一个只能聊天的企微插件\",而是:\n\n- 一条适合实时对话和个人协作的入口\n- 一条适合正式应用和组织自动化的入口\n\n### 4. 授权方式\n\n请按所选平面分别授权:\n\n- **Bot WS 模式授权**:前往企业微信管理后台 👉「工作台 - 智能机器人」,找到对应机器人,点击编辑,在「可使用权限」处勾选文档、日程、会议、待办、通讯录等对应权限。\n- **Agent 模式授权**:前往企业微信管理后台 👉「工作台 - 协作 - 文档 / 日程 / 会议等」,将您的自建应用加入\"可调用接口的应用\"。\n\n一句话理解:\n\n- **Bot WS** 更像\"当前聊天用户的实时协作入口\"\n- **Agent** 更像\"企业正式应用身份下的自动化执行入口\"\n\n两者同时配置后,您既能拿到顺滑的实时交互,也能拿到企业级可治理的协作能力。\n\n---\n\n## 📋 最近更新 (Changelog摘要)\n\n> 项目保持高频迭代,全面对齐甚至超越企业真实业务诉求。\n> **为保持精简,以下仅展示近期 5 次重要更新,完整历史版本(含全部 `v2.2.x`)请前往 [changelog/ 目录](./changelog/) 查阅。**\n\n#### 📌 v2.8.0(2026-04-22)\n- **[能力扩充] 微信客服(kefu)全通道落地** 🆕 Agent/Bot 之外,新增“企业微信客服”作为第三条消息通道:外部客户在微信、视频号、对外小程序里发给客服号的消息可直接走到 OpenClaw 里回复。配置独立(`channels.wecom.accounts.<id>.kefu.{corpId,corpSecret,openKfIds,webhook}`),`corpSecret` 允许与 Agent 分开建一套“只给客服用”的 Secret。\n- **[通道独立] 回调路径解耦** 🛣️ 客服挂载到独立路径 `/plugins/wecom/kefu`(推荐)或 `/plugins/wecom/kefu/<accountId>`,与 Bot / Agent 路径互不冲突。企微客服回调只携带 Token,插件内部调用 `kf/sync_msg` 按 `open_kfid` 维度维护 cursor 完整拉取,配合 LRU `msgid` 去重与 in-flight 并发守卫,确保消息不重、不漏。\n- **[入向覆盖] 10 类消息全量归一** 📥 text/image/voice/video/file/link/miniprogram/msgmenu/location/business_card/event(含 `enter_session` 映射成 `welcome`)均已 normalize 成 `UnifiedInboundEvent`,下游 Agent 无感消费。\n- **[出向能力] send_msg 一体化** 📤 text 按 3500 字符切片避开 4096 字节上限、media 由 content-type+扩展名分类分别走 image/voice/video/file,link 走 `payload.channelData.kefu.link` 专用卡片,统一走 `upload_media` 拿 `media_id` 后下发。新增 `toKefuText` 把 markdown 扁平成 kefu `content` 能识别的纯文本(保留代码块/链接/列表项标识,剔除标题/粗体/HTML 等)。\n- **[会话自动路由] Source Registry 扩展** 🔁 `WecomSourcePlane` 新增 `\"kefu\"`,入向会记录 `kefuOpenKfId`;下一轮 Agent 主动回复时会自动走客服出向,不会误发到 Agent 内部私信。显式目标 `wecom-kefu:<accountId>:<openKfId>:<externalUserId>` 同样支持。\n\n#### 📌 v2.7.3(2026-04-21)\n- **[格式升级] 全线切换到 `markdown_v2`** 🎨 自建应用(Agent API) / 群机器人(Bot WS) / 主动回复(Bot Webhook response_url)全部改用企微 2026 年新的 `markdown_v2` 消息类型,**原生支持 markdown 表格、图片 `![](url)`、粗体、链接、代码块、嵌套引用、列表**,消息上限从 2048 字节提到 4096 字节。\n- **[逻辑简化] 移除 textcard 降级路径** 🧹 以前遇到表格/大标题/链接会被\"降级\"成 textcard(title + 512 字纯文本描述,丢失 markdown 格式),现在统一走 markdown_v2,富文本完整渲染,不再需要 textcard workaround。\n- **[兼容注意]** ⚠️ markdown_v2 不支持 `<font color>` 标签和 `@userid` 群成员 at(原 markdown 支持),如果你依赖这两个特性请用 text 消息或保留 v1。本插件 adapter 本来就不生成这两个语法,用户无感。\n\n#### 📌 v2.7.2(2026-04-21)\n- **[Bug 修复] 引用群文件显示\"COS链接过期\"** 🔧 同步上游引用文件处理逻辑,新增 `channels.wecom.media.downloadTimeoutMs` 配置(默认 30s),分级区分超时/5 分钟 TTL 过期/网络错误,避免大文件抓取失败。\n- **[Bug 修复] 安装插件被安全扫描拦截** 🔒 移除上游已回滚的 `src/agent/script-runner.ts`(使用了 `child_process.spawn`),不再触发 OpenClaw 的 `dangerous-exec` 规则,v2.7.2 可以直接通过 `npm` 或 `clawhub` 方式安装。\n- **[上游同步] 合并 yanhaidao/wecom 至 c1158a9** 📦 包含引用附件在群聊/私聊中透传、媒体下载超时配置、菜单事件文档等;同时吸收上游对 jjjkkil 两次 agentcation PR 的 revert。\n- **[版本对齐] 保留 `@huo15/wecom` 独立包名** 📦 包名保持 `@huo15/wecom`,版本号跳至 `2.7.2`。\n\n#### 📌 v2.3.273(2026-03-31)\n- **[重要修复] WS 断连 Fallback** 🔧 耗时任务/Gateway 重启/WS 断线重连时,Bot WS 自动切换到 Agent API 发送回复,不再出现\"机器人没反应\"的问题。\n- **[markdown 修复] 表格和代码块渲染恢复** 📦 从 main 分支合并,表格不再强制转为纯文本,保留 markdown 格式。\n- **[包名变更] `@yanhaidao/wecom` 更名为 `@huo15/wecom`** 📦 npm 包名已更新。\n\n#### 📌 v2.3.27(2026-03-27)\n- **[重要修复] `channel add` 重新支持 WeCom guided setup** 🧭 之前有些环境下,`wecom` 虽然已经安装,却仍会在 OpenClaw 里显示成 \"does not support guided setup yet\",导致无法直接通过交互式向导添加。现在插件已经对齐 OpenClaw 当前的 `setupWizard` 接口,`openclaw channels add` 会重新正常识别和进入配置流程。\n- **[重要修复] 修复 `installedCatalogById is not defined`** 🔧 部分用户在渠道添加或选择阶段会直接遇到 `ReferenceError: installedCatalogById is not defined`,表现上像是\"选了渠道就报错\"或\"添加流程突然失效\"。这一版已经修复对应的目录访问逻辑,添加流程恢复稳定。\n- **[升级兼容] 清理 OpenClaw 新版下失效的 SDK 旧入口** 📦 这次同步迁移了 `wecom` 插件里几处已经不再建议继续从 `openclaw/plugin-sdk` 根入口直接拿的旧接口,重点覆盖工具上下文、outbound 适配器和 Bot WS 媒体发送链路,升级 OpenClaw 后更不容易再出现\"有的地方能跑、有的地方直接炸\"的兼容问题。\n\n#### 📌 v2.3.26(2026-03-26)\n- **[重要修复] 升级 OpenClaw 后不再乱报错** 🔧 修复了新版 OpenClaw 下 `wecom` 插件容易出现的 `is not a function` 一类启动/运行错误。\n- **[回复更稳] Agent 和 Bot WS 不再乱串** ↔️ 现在是谁收到消息,就尽量由谁来回复,不再容易出现\"在 Agent 里说话,结果 Bot WS 回你\"的情况。\n- **[体验修复] Bot WS 发图后不再多冒一条 `Done...`** 🖼 之前常见表现是:`正在思考` -> 图片 -> 又多一条完成提示。现在最终收尾会尽量接回原来的回复链路。\n- **[占位符修复] 不会一直卡在\"正在思考...\"** ⏳ 如果图片或文本已经发出去了,占位符会更自然地结束,不会继续无意义地刷屏。\n\n#### 📌 v2.3.19(2026-03-19)\n- **[重要修复] Bot WS 现在也真正走 `dynamicAgents`** 🧭 之前同样开启动态路由时,不同消息链路的行为并不完全一致:Webhook / Agent 能按用户、群聊隔离,Bot WebSocket 却可能重新落回主 Agent。现在 WS 运行时也执行同样的动态路由逻辑,会话隔离终于统一了。\n- **[配置统一] 媒体大小开始优先跟随 OpenClaw 标准 `mediaMaxMb`** 📦 之前 WeCom 插件更偏向读取自己的 `media.maxBytes`,用户改了 OpenClaw 主配置却可能感觉\"改了没生效\"。现在插件优先支持 `channels.wecom.mediaMaxMb`,并支持 `channels.wecom.accounts.<accountId>.mediaMaxMb` 做账号级覆盖;旧配置仍兼容,但只作为兜底。\n- **[体验修复] 常见本地目录文件现在更符合直觉地可发送** 🖼 过去本地媒体白名单更偏向 OpenClaw 自己目录,导致像 `Downloads`、`Desktop`、`Pictures` 里的图片明明存在,却常被拦下。现在插件默认额外放行这些常见用户目录,同时保留 `channels.wecom.media.localRoots` 继续追加共享盘、挂载盘和业务目录。\n\n#### 📌 v2.3.18(2026-03-18)\n- **[重大升级] 双平面能力融合(Bot WS + MCP 强化)** 🚀 独家引入挂载式的 MCP 能力层。在保留原生 Agent 强力工具的同时,将官方新开放的企业微信能力暴露给大模型。现在,大模型可凭用户身份读写待办、日程、查通讯录。\n- **[多账号硬隔离]** 彻底重构 MCP 缓存池实现 `accountId + category` 的二次硬维隔离,无论您的矩阵挂载了多少家企业的助手,上下文及鉴权缓存绝不会交叉重叠。\n- **[媒体通道重构]** 补齐 Bot WS 本地的媒体上传链,同时设立了严格的 `5秒熔断机制`,若 WebSocket 长通道大文件卡死将无感静默降级到 Agent 私信发送。\n\n*(查看更早期关于\"超时熔断代投、动态扩容矩阵\"等功能的更新日志，请移步 [changelog/ 目录](./changelog/))*\n\n---\n\n## 一、🚀 快速开始\n\n> 推荐统一使用**多账号矩阵模型**。\n> 即使您的企业只接入了一个账号,也强烈建议将其配入 `channels.wecom.accounts.default` 节点下。\n\n### 1.1 插件安装\n\n```bash\nopenclaw plugins install @yanhaidao/wecom\nopenclaw plugins enable wecom\n```\n\n### 1.2 互动向导式初配 (适合个人开发者与极客)\n\n如果您不想手写繁杂的 JSON 配置文件,可以通过交互式向导快速完成最轻量的 WebSocket 长连接部署。`v2.3.27` 起,`wecom` 已重新对齐 OpenClaw 当前的 guided setup 流程,`openclaw channels add` 可以直接识别并进入配置:\n\n1. 确保已启用本插件。\n2. 在终端运行添加渠道指令:\n   ```bash\n   openclaw channels add\n   ```\n3. 选择下拉列表中第一顺位的:**企业微信 (WeCom)**\n4. 根据终端亮色指引,填入企微机器人对应的 `Bot ID` 及 `Secret`,机器人即可完成握手并进入可用状态。\n\n> **如果您最近刚升级 OpenClaw:**\n> - 若之前在添加渠道时看到 `wecom does not support guided setup yet`,请更新到当前版本后重试。\n> - 若之前在渠道添加阶段见过 `ReferenceError: installedCatalogById is not defined`,这一版也已一并修复。\n\n### 1.3 生产环境顶配架构示范(Bot WS 流式交互 + Agent 私有通道兜底发送)\n\n如果您的目标不是\"接进来能聊两句\",而是让团队在企业微信里长期稳定使用 AI,这套组合更接近生产环境的推荐形态:\n\n- `Bot WS` 负责实时对话、低延迟流式回复和更轻的接入门槛\n- `Agent` 负责主动推送、媒体发送和长任务后的兜底交付\n- `dynamicAgents` 负责把不同用户、不同群聊的会话真正隔离开,避免多人共用一个入口时互相串上下文\n\n请进入 OpenClaw 配置文件(`openclaw.json`)的 `channels.wecom` 内使用:\n\n```jsonc\n{\n  \"channels\": {\n    \"wecom\": {\n      \"enabled\": true,\n      \"defaultAccount\": \"default\",\n      \"accounts\": {\n        \"default\": {\n          \"enabled\": true,\n          \"name\": \"企微销售二部支持中枢\",\n          \"bot\": {\n            \"primaryTransport\": \"ws\",             // 指定 Bot 主通讯协议:ws 或 webhook\n            \"streamPlaceholderContent\": \"正在深思熟虑,请稍候...\", // 避免流式回复开始前长时间无反馈\n            \"welcomeText\": \"你好,我是已连网的专属大脑。\",\n            \"dm\": {\n              \"policy\": \"pairing\",\n              \"allowFrom\": []\n            },\n            \"ws\": {                               // Bot WS 建连所需凭证\n              \"botId\": \"YOUR_BOT_ID\",\n              \"secret\": \"YOUR_BOT_SECRET\"\n            }\n          },\n          \"agent\": {                              // 主动推送、媒体发送与兜底交付链路\n            \"corpId\": \"YOUR_CORP_ID\",\n            \"agentSecret\": \"YOUR_AGENT_SECRET\",\n            \"agentId\": 1000001,\n            \"token\": \"AGENT_TOKEN\",\n            \"encodingAESKey\": \"AGENT_AES_KEY\",\n            \"welcomeText\": \"若长连接断开,我将使用此通道传递残存报告。\",\n            \"dm\": {\n              \"policy\": \"open\",\n              \"allowFrom\": []\n            }\n          }\n        }\n      },\n      \"mediaMaxMb\": 50,                           // 优先使用 OpenClaw 标准媒体上限配置\n      \"media\": {\n        \"tempDir\": \"/tmp/openclaw-wecom-media\",\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\"\n        ]\n      },\n      \"network\": {                                // 内网或受限网络环境可通过代理出网\n        \"egressProxyUrl\": \"http://127.0.0.1:3128\"\n      },\n      \"dynamicAgents\": {                          // 为单聊/群聊创建独立路由,减少多人串上下文\n        \"enabled\": true,\n        \"dmCreateAgent\": true,\n        \"groupEnabled\": true,\n        \"adminUsers\": [\"zhangsan001\"]             // 管理员绕过动态路由,直连主 Agent\n      }\n    }\n  }\n}\n```\n\n其中:\n\n- 插件现在默认额外放行常见用户目录:`~/Desktop`、`~/Documents`、`~/Downloads`、`~/Movies`、`~/Pictures`。\n- `channels.wecom.mediaMaxMb` 是首选的媒体大小上限配置,`channels.wecom.accounts.<id>.mediaMaxMb` 可以做账号级覆盖。\n- `channels.wecom.media.localRoots` 用于继续追加你自己的全局目录,例如共享盘、挂载盘或业务导出目录。\n- 旧的 `channels.wecom.media.maxBytes` 仍然兼容,但仅作为向后兼容兜底;新配置建议统一改成 `mediaMaxMb`。\n- 这些目录会和 OpenClaw 默认允许的媒体目录一起生效,不会覆盖默认白名单。\n- 也就是说,像 `~/Downloads/01.png` 这类本机文件现在默认就可以直接发到企微,不需要再单独配置。\n\n> **注意:** 历史配置里的 `agent.corpSecret` 引擎依然能够向后兼容拾起,但后续的新项目推荐采用标准的 `agentSecret` 作为对齐键。\n\n### 1.4 dynamicAgents 详细说明:为什么生产环境建议开启\n\n`dynamicAgents` 的核心价值,不是\"自动创建很多 Agent\",而是让企业微信里的每个用户、每个群聊都拥有稳定、独立的会话落点。\n如果不开它,所有消息更容易汇入同一个主 Agent;一旦开始多人共用,最先出问题的通常不是模型能力,而是上下文、长期记忆和处理边界混在一起。\n\n更简单地看,可以直接按下面这张表决定要不要开:\n\n| 场景 | 不开时的问题 | 建议配置 | 你得到的结果 |\n|---|---|---|---|\n| 多个同事同时私聊同一个机器人 | 容易共用同一条会话脉络,长期上下文可能互相污染 | `enabled=true` + `dmCreateAgent=true` | 每个人都有自己的稳定上下文 |\n| 一个或多个群长期拿机器人协作 | 不同群更容易共用主 Agent,群与群之间边界不清晰 | `enabled=true` + `groupEnabled=true` | 每个群都有独立会话空间 |\n| 管理员需要统一测试、巡检、接管 | 管理员也会被切进自己的动态 Agent,排障更分散 | `adminUsers=[\"管理员userid\"]` | 管理账号继续直连主 Agent |\n| 只是做 PoC 或单人试用 | 一上来就启用隔离,理解成本偏高 | `enabled=false` | 先把连通性和基础回复跑通 |\n\n系统当前的真实行为如下:\n\n- 开启后,会按 `账号 + 会话类型 + 对端 ID` 生成确定性的 Agent ID,例如 `wecom-default-dm-zhangsan` 或 `wecom-default-group-wr123456`\n- 同一个用户或同一个群,下次再发消息时会继续命中同一个动态 Agent,而不是临时随机分配\n- 首次命中时,插件会自动把这个动态 Agent 追加到 `agents.list`,不需要您手工维护一长串列表\n- 这套逻辑同时作用于 `Bot WS` 和 `Agent Callback` 两条主消息链路,不是只有某一种模式才生效\n- `adminUsers` 中的账号会始终绕过动态路由,直接走主 Agent,适合放管理员、运营或排障账号\n- 默认值是 `enabled=false`、`dmCreateAgent=true`、`groupEnabled=true`、`adminUsers=[]`,也就是不开总开关时不会生效,但一旦开启,单聊和群聊会默认一起进入隔离模式\n\n需要注意的是,`dynamicAgents` 解决的是\"路由隔离\"和\"会话隔离\",不是权限系统本身。\n也就是说,它能显著减少上下文串线,但账号是否允许私聊、谁能触发命令、某个账号绑定到哪个主 Agent,仍然要结合 `dm.policy`、`bindings` 和企业微信授权配置一起看。\n\n### 1.5 `localRoots` 详细说明:为什么\"文件明明存在\",系统却仍然不发\n\n`localRoots` 只决定一件事:**这个本地路径允不允许被当作可发送媒体读取。**\n\n| 现象 | 实际含义 |\n|---|---|\n| 文件存在,但发送失败 | 不代表系统允许读取它 |\n| 日志出现 `Local media path is not under an allowed directory` | 路径不在白名单里 |\n| 远程 `https://...` 媒体可以发 | 远程 URL 不走 `localRoots` |\n\n默认已经额外放行这些目录:\n\n| 默认允许目录 | 用途 |\n|---|---|\n| `~/Desktop` | 桌面文件、临时截图 |\n| `~/Documents` | 文档导出目录 |\n| `~/Downloads` | 下载图片、下载文件 |\n| `~/Movies` | 视频文件 |\n| `~/Pictures` | 图片、相册导出 |\n\n另外也保留 OpenClaw 自己的 `tmp / state / workspace` 相关目录。\n\n如果文件不在默认目录里,再补 `localRoots`:\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"media\": {\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\",\n          \"/mnt/nas/public\"\n        ]\n      }\n    }\n  }\n}\n```\n\n配置规则:\n\n| 规则 | 说明 |\n|---|---|\n| `localRoots` 是追加 | 不会覆盖默认目录 |\n| 建议写绝对路径 | 团队环境更稳定、更清楚 |\n| 只加业务需要的目录 | 不要为了省事把范围放太大 |\n| 不建议放整个大盘或整个用户目录 | 会把本地文件读取边界放得过宽 |\n\n排障判断:\n\n| 问题类型 | 看什么 |\n|---|---|\n| 本地路径是否允许读取 | `localRoots` |\n| 媒体能处理多大 | `channels.wecom.mediaMaxMb` |\n| 企业微信最终能不能收 | 企业微信自身媒体限制 |\n| 远程媒体能不能发 | URL 可访问性,不看 `localRoots` |\n\n一句话:`localRoots` 管\"能不能读这个本地路径\",`mediaMaxMb` 管\"最多读多大\"。\n\n---\n\n## 二、🏢 企业微信后台回调挂载指南 (针对使用了 Webhook 或 Agent Callback 的重度用户)\n\n如果您需要让 Agent 通道接收复杂的地理位置及交互式卡片事件,需要将系统的路径下发到企业微信管理后台。\n由于系统默认采纳**多账号分流路径派生**,请切记不要随意丢弃末尾的 `{accountId}`,如下所示:\n\n| 类型 | 您的 OpenClaw 可信域名 | 默认账号路由锚点 | 如果配置了 Ops 项目组子账号 |\n|---|---|---|---|\n| **Bot Webhook** | `https://x.com` | `/plugins/wecom/bot/default` | `/plugins/wecom/bot/ops` |\n| **Agent Callback** | `https://x.com` | `/plugins/wecom/agent/default`| `/plugins/wecom/agent/ops` |\n\n*警告:极度不推荐将老旧单一根路径(如 `/plugins/wecom/bot`)在未指定账户空间下裸奔使用,一旦您的业务扩张到第二个账号,将会引发难以追溯的回调抢占雪崩。*\n\n---\n\n## 三、📡 排障与抓包:洞悉黑盒下的脉搏\n\n当前版本请使用以下三条命令组合排障。注意:`openclaw channels status` **不支持** `--deep`,插件级探测参数是 `--probe`;`--deep` 属于顶层 `openclaw status`。\n\n### 3.1 先看插件级状态快照\n\n```bash\nopenclaw channels status --probe\n```\n\n适合回答这些问题:\n\n- 企业微信账号是否已被网关识别并加载\n- 账号当前是否 `enabled` / `configured`\n- 运行时是否 `running` / `connected` / `authenticated`\n- 最近一次错误、最近进出站时间是否异常\n\n如果网关可达,这条命令会返回企业微信账号的运行时快照。\n如果网关不可达,它会自动退化为\"只看配置\"的摘要输出。\n\n### 3.2 再看全局深度诊断\n\n```bash\nopenclaw status --deep\n```\n\n这条命令是 **OpenClaw 全局诊断入口**,适合确认:\n\n- Gateway 本身是否健康\n- 当前机器上的整体通道探测是否正常\n- 最近心跳、会话、服务状态是否异常\n\n当您怀疑问题不只在企业微信插件,而是 Gateway、网络、配置路径或其他通道共同影响时,优先跑这条。\n\n### 3.3 最后直接看 WeCom 日志\n\n```bash\nopenclaw channels logs --channel wecom --lines 200\n```\n\n当发生疑难连接断开、消息不回、媒体文件下发神秘消失时,直接看日志最有效。新版日志已经被精细地切分在不同命名空间锚点下,助你顺藤摸瓜:\n\n- `[wecom-runtime]`:统一运行时主线。看收消息、分发、回消息、最近错误与会话归属漂移。\n- `[wecom-ws]`:Bot WebSocket 通道。看连接、鉴权、断线、重连、帧收发与保活。\n- `[wecom-agent-delivery]`:Agent 主动发送链路。看用户/部门/标签目标解析、媒体发送和账号错配。\n\n### 3.4 推荐排障顺序\n\n建议按下面顺序执行:\n\n```bash\nopenclaw channels status --probe\nopenclaw status --deep\nopenclaw channels logs --channel wecom --lines 200\n```\n\n您可以按输出这样判断:\n\n- `configured=false`:先检查 `bot.ws.botId`、`bot.ws.secret`、`agent.corpId`、`agent.agentSecret`、`agent.agentId` 等配置是否完整。\n- `running=false`:说明账号没有真正启动,优先看 `[wecom-runtime]`。\n- `connected=false` 或 `authenticated=false`:优先看 `[wecom-ws]`,一般是 WebSocket 握手、密钥或连接稳定性问题。\n- 能收不能发,或群里发文件/卡片失败:优先看 `[wecom-agent-delivery]`。\n- `lastError` 持续刷新:通常不是一次性误报,建议结合最近 200 行日志一起看。\n\n---\n\n## 四、🤝 项目鸣谢\n\n感谢所有为本项目提交代码、测试、文档与反馈的协作者。\n\n- **原始项目**:[yanhaitao/wecom](https://github.com/yanhaitao/wecom)\n\n<p align=\"center\">\n  <a href=\"https://github.com/YanHaidao/wecom/graphs/contributors\">\n    <img src=\"https://contrib.rocks/image?repo=YanHaidao/wecom\" alt=\"WeCom contributors\" />\n  </a>\n</p>\n\n如果头像墙没有立刻刷新,通常是 GitHub 统计或第三方缓存延迟,稍后再看即可。\n\n---\n\n## 五、📮 版权与许可证协议指引\n\n<div align=\"center\">\n\n**公司名称：** 青岛火一五信息科技有限公司\n\n**联系邮箱：** postmaster@huo15.com | **QQ群：** 1093992108\n\n---\n\n**关注逸寻智库公众号，获取更多资讯**\n\n<img src=\"https://tools.huo15.com/uploads/images/system/qrcode_yxzk.jpg\" alt=\"逸寻智库公众号二维码\" style=\"width: 200px; height: auto; margin: 10px 0;\" />\n\n</div>\n\n### 最后的话:关于开源及署名\n本项目版权归 **青岛火一五信息科技有限公司** 所有,遵循 **ISC License**。\n您可以将其用于极其广阔的项目天地中。但开源不是拿来主义:\n在此明确强调,包括所谓的\"Bot+Agent 保活接力超时融合机制\"、\"千人千面多账户切面\"、\"自动寻的路由下沉\" 这背后全是作者无数个在企业真实现网撞墙实验出的架构结晶。**拒绝一切去除原作者署名、粗暴改名换姓占为己用的魔改上架行为。**\n愿我们能在彼此尊重的前提下,共同拓展 OpenClaw 生态的无垠边界。\n\nFile v2.9.5:_meta.json\n\n{\n  \"ownerId\": \"kn7byevkn40d6z4p7ghdb097z983tj33\",\n  \"slug\": \"huo15-wecom-plugin\",\n  \"version\": \"2.9.5\",\n  \"publishedAt\": 1778438322867\n}\n\nFile v2.9.5:CHANGELOG.md\n\n# Changelog\n\n## 2.9.5 — 2026-05-11(manifest contracts.tools — 适配 OpenClaw 2026.5.x loader 契约)\n\n### 触发\n\nOpenClaw 2026.5.x gateway 启动 log 大量 warning：\n\n```\n[gateway] [plugins] plugin must declare contracts.tools before registering agent tools\n  (plugin=wecom, source=...dist/index.js)\n```\n\n3 个工具(wecom_calendar / wecom_doc / wecom_mcp)各刷一条。\n\n### 根因\n\nOpenClaw 2026.5.x loader(`dist/loader-B-GXgDrk.js`)在 `registerTool` 加了契约校验,要求 manifest 根级 `contracts.tools[]` 显式声明。\n\n### 改动\n\n`openclaw.plugin.json` 加根级 `contracts.tools` 数组：\n\n```json\n\"contracts\": {\n  \"tools\": [\"wecom_calendar\", \"wecom_doc\", \"wecom_mcp\"]\n}\n```\n\n### 不影响\n\n- 没改任何代码逻辑,只动 manifest\n- 工具注册 / 调用方式不变\n- 兼容旧 OpenClaw\n\nFile v2.9.5:changelog/v2.2.28.md\n\n# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.2.28 - 多账号隔离与稳定性增强\n\n本次 v2.2.28 版本是 **OpenClaw 企业微信 (WeCom) 插件** 的一次重大里程碑更新。我们深度优化了 **微信 / 企业微信** 办公场景下的多智能体隔离逻辑，并修复了生命周期、XML 数据保真等多个生产环境的核心痛点。\n\n本次更新让 **OpenClaw** 在处理企业级复杂 **插件** 配置时更加得心应手，完美解决大模型接入 **WeCom** 的所有阻碍。\n\n---\n\n### 🌟 版本亮点 (Release Highlights)\n\n*   🎯 **多账号矩阵支持**：支持按 `accountId` 进行组内会话隔离。不同部门、不同业务的 **企业微信** 机器人可并行运行，互不干扰，彻底解决跨账号串会话问题。\n*   🔐 **数据保真解析**：针对 **WeCom** 的 XML 消息解析进行了重构。关闭了自动数值化，保留 `FromUserName` 前导 `0`，并完美解决 64 位 `MsgId` 精度风险。\n*   🔁 **Gateway 生命周期适配**：完美兼容最新版 **OpenClaw** Gateway 的生命周期管理，修复了在高频心跳监测下的重启循环问题，运行更稳健。\n*   🧹 **入站消息过滤**：优化了 **微信** 与 **企业微信** 的事件过滤逻辑，避免系统事件、缺失发送者等无效消息进入 AI 会话，防止“误回复”。\n*   🧱 **配置安全护栏**：新增 **企业微信** 账号冲突检测。自动拦截重复的 `bot.token` 或 `agentId` 配置，并提供友好的中文错误提示。\n\n---\n\n### 📝 详细更新日志 (Changelog)\n\n#### 【重磅更新】🎯 多账号/多智能体可用性增强\n- 支持按 `accountId` 做组内隔离（Bot + Agent + 路由绑定同组生效）。\n- 动态 Agent 与会话键增加 `accountId` 维度，避免跨账号串会话。\n\n#### 【稳定性】🔁 生命周期兼容修复\n- 适配新版 **OpenClaw** Gateway 生命周期，`startAccount` 改为长生命周期运行。\n- 修复了“几秒一次重启 + health-monitor 二次重启”的循环问题。\n\n#### 【准确性】🔐 XML 字段保真修复\n- **WeCom** Agent XML 解析关闭自动数值化，保留发送者原始 ID。\n- 避免 `MsgId` (64bit) 精度损失，确保回复目标不被误改。\n\n#### 【准确性】🧹 误回复修复\n- Bot/Agent 入站均增加事件过滤，避免处理 `event`、`sys` 及缺失发送者的消息。\n- 修复群聊缺失 `chatid` 时仍进入 AI 会话的问题，避免“一个消息触发多人误回复”。\n\n#### 【可控性】🧱 配置安全护栏\n- 新增多账号冲突检测，自动拦截重复 Token 或 Agent ID 的配置。\n- **账号管理修复**：`deleteAccount` 现在仅删除目标账号，不再误删整个 **插件** 的 `channels.wecom` 配置。\n\n#### 【质量保障】✅ 自动化回归\n- 新增账号解析、冲突检测、动态路由隔离、生命周期与入站过滤的多项自动化测试。\n- **文档优化**：README 快速开始文档更新，优先展示“多账号 + 多 Agent”矩阵配置。\n\n---\n\n### 💾 安装与升级 (Install & Update)\n\n使用 **OpenClaw** CLI 即可一键升级 **插件**：\n\n```bash\nopenclaw plugins upgrade wecom\n```\n\n或手动更新配置：\n```bash\nopenclaw config set channels.wecom.enabled true\n```\n\n---\n\n### 🔍 SEO 关键词 (Keywords)\n**openclaw** | **企业微信** | **微信** | **wecom** | **插件** | **AI 机器人** | **大模型网关** | **流式响应** | **多账号隔离** | **WeCom Plugin**\n\n---\n\n### 📮 联系我们\n如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 或加入我们的交流群。\n\n> **提示**：建议 **OpenClaw** 主程序版本保持在 **2026.2.24+** 以获得最佳体验。\n\nFile v2.9.5:changelog/v2.3.10.md\n\n# OpenClaw WeCom 插件 v2.3.10 变更简报\n\n> [!TIP]\n> **默认更易用、修复更直接的版本。**\n\n## 2026-03-10（v2.3.10）\n- 【消息防丢修复】🐛 **[重要修复]** 针对由于模型 API 限速或超长思考（如 DeepSeek R1）导致的企微 WebSocket 5秒超时断连问题，引入了 4 秒前置保活机制（自动下发\"⏳ 正在思考中...\"），彻底阻断了因为模型响应慢而造成的“消息卡死不再回复”。\n- 【双重回复修复】🐛 **[重要修复]** 修复 `Bot WS` 长文本场景下可能被超时截断并触发兜底通道进行二次重复回复的边界异常。\n- 【向导自动路由】✨ **[体验升级]** 重构了企业微信的渠道交互配置向导。在单账号场景下将静默触发自动路由绑定，丝滑跳过 OpenClaw 全局冗长的 Agent 路由分配询问。\n- 【账号兜底修复】🧩 修复企业微信 onboarding 在首个账号非字面量 `default` 时，后续流程报 `WeCom account \"default\" not found` 的问题。\n- 【默认选项收敛】🚀 onboarding 的默认回车选项已变更为更普适的 `Bot` 模式、`WS` 接入和 `开放模式` 策略。\n- 【字段命名收敛】📝 Agent 新配置统一推荐使用 `agentSecret`，历史 `corpSecret` 保持兼容读取，保障平滑升级。\n- 【文档与提示精简】📘 README、向导交互文案与示例结构已全面统一为更符合直觉的精简说明。\n\n## 验证结果\n- `bunx vitest run extensions/wecom/src/onboarding.test.ts extensions/wecom/src/channel.meta.test.ts`\n- `pnpm build`\n\nFile v2.9.5:changelog/v2.3.11.md\n\n# OpenClaw WeCom 插件 v2.3.11 变更简报\n\n> [!TIP]\n> **稳定性与多账号说明版本**：`v2.3.11` 重点修复 Bot WS 长思考场景下的 `invalid req_id`，同步收敛 onboarding 账号默认值与多账号隔离文档说明。\n\n## 2026-03-11（v2.3.11）\n- 【WS 保活升级】🚀 **[重要修复]** Bot WebSocket 从“4 秒后补发占位”升级为“收到用户消息立即下发占位符，并在长思考期间持续保活”，显著降低慢模型或长任务下的 `invalid req_id` 与回复丢失风险。\n- 【占位符配置生效】🌊 `bot.streamPlaceholderContent` 现在对 `Bot WS` 与 `Bot Webhook` 两条链路统一生效，配置一次即可保持体验一致。\n- 【错误兜底收敛】🛡 修复 `req_id` 已失效时仍尝试二次回错消息的问题，避免出现重复报错与未处理 Promise 拒绝。\n- 【账号选择兜底】🧩 onboarding 在“配置里还没有任何账号”时，也会显式提供 `default` 默认账号选项，减少首次接入时的困惑。\n- 【多账号文档补强】📘 README 新增说明：如果多个 `accountId` 复用同一个静态 Agent，建议配合 `session.dmScope = \"per-account-channel-peer\"`，避免不同账号的私聊上下文共用。\n- 【日志可读性】🔎 WeCom runtime 的 Bot WS 失败日志改为可读错误文本，排查时不再只看到 `[object Object]`。\n\n## 验证结果\n- `pnpm exec vitest run extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/onboarding.test.ts`\n\n## 升级提示\n- 已有 `bot.streamPlaceholderContent` 配置无需调整，升级后 `Bot WS` 会自动使用它。\n- 如果你在同一个 OpenClaw 实例里挂了多个 WeCom 账号，并让它们指向同一个静态 Agent，建议补上 `session.dmScope = \"per-account-channel-peer\"` 以隔离私聊上下文。\n\nFile v2.9.5:changelog/v2.3.12.md\n\n# OpenClaw WeCom 插件 v2.3.12 变更简报\n\n> [!TIP]\n> **WS 主动推送与过期更新兜底版本**：`v2.3.12` 重点修复企业微信 Bot WebSocket 在流式回复超过 6 分钟后返回 `846608 stream message update expired`，并同步调整主动消息路由为“WS 文本优先、Agent 文件兜底”。\n\n## 2026-03-12（v2.3.12）\n- 【6 分钟过期修复】🛠 **[重要修复]** `Bot WS` 现在会把企业微信 `846608 stream message update expired (>6 minutes)` 识别为回复窗口已结束的终态错误，不再继续把该错误向上抛出导致进程退出。\n- 【主动推送路由收敛】🚀 **[重要修复]** 当账号实际运行在 `Bot WS` 模式时，定时消息、heartbeat 和其他主动文本发送现在优先走 `wsClient.sendMessage()`，不再默认绕去 Agent。\n- 【WS/Agent 职责切分】🧩 `Agent` 现在主要承担两类兜底：一是账号没有启用 `Bot WS` 时的主动消息发送；二是 Bot 两种模式都不支持的文件/媒体发送。\n- 【UserID 纯数字解析修复】🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的图片发送失败（81013 错误）。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。\n- 【未处理拒绝隔离】🧯 `sdk-adapter` 为每个 WebSocket frame 的异步处理补上显式兜底捕获；即使后续再出现漏网异常，也会记录到 runtime issue，而不是变成 `unhandledRejection` 直接带崩 OpenClaw。\n- 【占位保活收敛】⏱ 当回复窗口已经过期时，WS 占位符保活会立即停止，避免过期后继续发送流式更新。\n- 【Ack 超时兜底】⏱ SDK 5 秒回执超时 (`Reply ack timeout`) 现在也被识别为终态错误，超时后立即停止占位保活并走 `onFail` 回调，不再产生 `unhandledRejection`。\n- 【回归测试补齐】✅ 新增针对 `846608` 过期更新和 `frame handler` reject 的回归测试，确保此类异常保持非致命。\n- 【Bot WS 图片/文件解密修复】🛠 **[重要修复]** `Bot WS` 模式下接收到的图片和文件现在会使用消息体中的独立 `aeskey` 进行 AES-256-CBC 解密，修复之前直接保存密文导致 `Failed to optimize image` 的问题。`media-service.ts` 新增 `downloadEncryptedMedia()` 方法，`normalizeFirstAttachment()` 自动检测 `aesKey` 并走解密路径。\n\n## 验证结果\n- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/outbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`\n\n## 升级提示\n- 无需新增配置，升级到 `v2.3.12` 后自动生效。\n- 如果账号正在使用 `Bot WS`，主动文本消息会优先走 WS 长连接；只有文件/媒体或未启用 WS 的场景才会继续使用 Agent。\n- 如果模型或工具链路存在超长执行，超过企业微信 6 分钟回复窗口时，OpenClaw 现在会保持存活并记录运行时错误，不再因该异常退出。\n\nFile v2.9.5:changelog/v2.3.13.md\n\n# OpenClaw WeCom 插件 v2.3.13 变更简报\n\n> [!TIP]\n> **Bot WS 引用上下文与流式展示修复版本**：`v2.3.13` 重点补齐企业微信 `Bot WS` 对引用消息的上下文注入，并修复长回答在客户端里显示为“断断续续碎片”的问题。\n\n## 2026-03-13（v2.3.13）\n- 【引用上下文补齐】🛠 **[重要修复]** `Bot WS` 现在会复用与 `Bot Webhook` 一致的入站正文拼装逻辑。用户通过“引用 + 提问”触发机器人时，引用内容会一并进入 Agent 上下文，不再只保留当前这句提问。\n- 【WS 流式刷新修复】🌊 **[重要修复]** `Bot WS replyStream` 现在按“累计全文刷新”发送，而不是只发送最新增量片段，修复企业微信客户端中长回答显示断断续续、像被拆成多块的问题。\n- 【协议语义对齐】🧩 这次调整显式对齐企业微信 `stream.id` 的刷新语义：同一条流式消息的后续更新会覆盖为“当前完整内容”，从而保持最终展示稳定、可连续阅读。\n- 【回归测试补齐】✅ 新增 `bot-ws` 引用上下文与累计流式发送测试，避免后续重构再次把引用消息或流式展示打回退。\n\n## 验证结果\n- `pnpm exec vitest run --config extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/inbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`\n\n## 升级提示\n- 无需新增配置，升级到 `v2.3.13` 后自动生效。\n- 如果企业微信 `WS` 推送里的 `quote.text.content` 仍然是 `[该消息类型暂不能展示]`，说明上游没有下发真实引用原文；OpenClaw 会把该占位文本带入上下文，但无法恢复企业微信未提供的原始内容。\n- 如果你之前观察到长回复在企业微信里呈现为“分段断裂”或“后段覆盖前段”，升级后会改为同一条流式消息持续刷新完整内容。\n\nFile v2.9.5:changelog/v2.3.14.md\n\n# OpenClaw WeCom 插件 v2.3.14 变更简报\n\n> [!TIP]\n> **企业微信“协作文档”原生整合与长连接稳定性修复版本**：`v2.3.14` 将机器人的能力从“陪聊”正式拓展到了“办公协同”。现在，你可以直接在微信群里让机器人去填报销单、建项目表；同时我们也彻底修复了多人并发聊天时机器人“正在思考”卡死刷屏的问题。\n>\n> 📣 **特别感谢** [@proyy](https://github.com/proyy) 提供的企业微信文档管理解决方案，使本版本的 Docs 能力得以落地。\n\n## 重磅功能：把聊天直接变成企业文档（用后即得）\n\n我们受够了问 AI 一个问题，答案最后只能被新消息顶没。这次更新，我们让机器人获得了操作“企业微信协作文档”的实体权限。\n\n### 场景 1：开新项目，不用再求人建表格拉权限了\n- **以前**：你在群里说“准备一下下周的活动追踪表”，然后得切出去打开文档中心，新建表格，再一个个抄名字把大家拉进来。\n- **现在**：直接在群里 `@机器人 帮我建一个名为『春季新品发布会追踪』的表格，并把群里的人都加上可写权限`。机器人建好后会直接在群里甩出一个链接，所有人点开就能直接编辑，全程零切换。\n\n### 场景 2：坐在地铁上，照样神操作填报销/跟进数据\n- **以前**：你刚下班，群里有人问“今天 C 组的面试谁通过了？”你只能回答“我等下回家用电脑打开「面试记录表」改一下状态”。全量改动很容易把别人的同行数据覆盖掉。\n- **现在**：你可以直接发语音或者敲字 `@机器人 把「第二周面试记录表」里的 B2 到 B5 单元格全部更新为“二面通过”`。机器人会像操作手术刀一样，只精准替换指定的数据块（`spreadsheet.edit_data`），丝毫不影响文档里的其他公式。\n\n### 场景 3：直接让 AI 读懂全公司的数据报表\n- **以前**：你要先自己把表格下载成 Excel，再一段段复制数据发给大模型：“帮我算算这堆数据谁最高”。\n- **现在**：你直接丢给他一个企微文档链接：`@机器人 分析一下这张表里的第一季度数据，告诉我谁的单产最差？`。由于具备了原生读取能力（`get_sheet_range_data`），它会自己去拉取数据查表，给你输出结论。\n\n## 💡 Docs 权限配置指引（只需一次）\n\n为了让上述场景跑通，光配 `agentSecret` 是不够的。这是因为哪怕是公司自建的机器人，默认也没资格动你们内部的文档资产。你需要：\n1. **去企微后台发“通行证”**：进入 [企业微信后台 -> 协作 -> 文档 -> 可调用接口的应用](https://work.weixin.qq.com/wework_admin/frame#apps/qykit/proxy/wedoc)，把你的机器人应用放进白名单。\n2. **在 OpenClaw 里激活能力**：打开 UI 界面 的 `Settings` -> `Agents` -> `Tools`，找到 `wecom`，把带有 `doc` 字眼的所有工具（创建文档、读取表格、改权限等）通通打勾。\n\n\n## 核心修复：终结“正在思考...”刷屏噩梦\n除了新功能，这次我们也彻底对长连接（WS）卡死问题做了一次大手术：\n- 🛑 **告别并发刷屏**：群里人多手杂的时候，以前机器人如果处理不过来，不仅不回话，还会满屏一直弹“正在思考...”。现在只要有一条真回复发出来，它会自动把同群里那些卡死、过期的“正在思考”全部瞬间清理干净。\n- 📡 **进群欢迎语报错 846605 终结**：修复了大家常反馈的“有人一进群，后台就疯狂报 invalid req_id”的陈年老 Bug。现在对进群、推卡片等非聊天事件，我们全面切换成了专属接口，彻底避免违规流式推送。\n- 🛡 **120 秒物理断网**：即使模型源站点挂了，我们现在也会在 120 秒内强制熔断提示，绝不让你面对一个无限转圈的加载框。\n\n---\n## 验证结果\n- `pnpm test -- src/transport/bot-ws`\n- 所有 WS 回复通道单测已全部通过，尤其是关于 `setInterval` 占位符存活期的验证得到了补全与修复。\n\n## 升级指引\n```bash\nopenclaw plugins update wecom\n```\n- 无需新增配置，执行上述命令即可一键升级到 `v2.3.14`。\n- 升级后，如果你拉几十个机器人进群并同时发言，曾经那种满屏飘“正在思考...”却无人回答的乱象将不复存在。\n- 如果之前查看后台日志总是看到 `stream message update expired (>6 minutes)` 甚至因为连带引发的 WS 断网重启，本次升级将大幅度平息日志告警红字，稳定长连接状态。\n\nFile v2.9.5:changelog/v2.3.15.md\n\n# OpenClaw WeCom 插件 v2.3.15 变更简报\n\n> [!TIP]\n> **企业微信文档写入稳定性与消息目标路由修复版本**：`v2.3.15` 重点解决了企微文档 `init_content` 初始化内容写入不稳定、图片插入失败、批量更新索引错误，以及群聊回复时容易触发的 `81013` 目标解析错误。同时，这次也补回并完善了文档、在线表格、智能表格、收集表等能力，避免相关工具调用缺接口或直接失败。\n\n## 2026-03-14（v2.3.15）\n- 【文档初始化内容修复】🛠 **[重要修复]** 创建企微文档时，`init_content` 现在会按官方 Wedoc 流程执行：图片先上传再插入，文本与图片段落会基于最新索引和版本号写入，减少标题正文错位、图片不显示、内容插到错误位置的问题。\n- 【批量更新稳定性修复】📄 **[重要修复]** 修复 `document.batch_update` 的索引计算与模式切换问题。混合执行 `insert_paragraph`、`insert_text`、`insert_image` 时，不再更容易触发 `ParagraphValidator`、`TextValidator`、`DrawingValidator` 一类报错。\n- 【文档客户端能力恢复】🔧 重新补齐此前精简时误删的企微文档客户端接口，恢复文档权限、在线表格、智能表格、收集表等相关方法，避免工具层调用缺方法、返回异常或直接不可用。\n- 【在线表格与收集表支持补齐】📊 完善企微在线表格和收集表的类型定义、参数校验与错误提示。现在会更早拦截超出 API 限制的请求，例如表格行列/单元格数量超限、收集表题目结构缺失、选项题参数不完整等问题。\n- 【群聊目标解析修复】💬 **[重要修复]** 修复企业微信群聊回复时 `To` 字段被错误硬编码为用户目标的问题。群聊、私聊、部门、标签目标现在会按正确前缀解析，减少发送时报 `81013 user & party & tag all invalid` 的情况。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.15`。\n- 如果你之前遇到“建文档成功但内容没写进去”“图片插不进去”“批量更新偶发报索引错误”或“群里回复机器人时报 81013”，本次升级后会明显改善。\n\nFile v2.9.5:changelog/v2.3.16.md\n\n# OpenClaw WeCom 插件 v2.3.16 变更简报\n\n> [!TIP]\n> **企业微信 Bot-WS 混合消息附件解析修复版本**：`v2.3.16` 重点解决了在 WebSocket 模式下，企业微信机器人接收到的混合消息（如同时包含图片和文字）由于解析遗漏导致附件丢失、AI 只能看到带签名的临时链接文本而无法查看真正图片内容的问题。\n\n## 2026-03-16（v2.3.16）\n- 【混合消息媒体解析修复】🛠 **[重要修复]** 补齐了 Bot WebSocket 传输通道（`bot-ws`）下对 `mixed` 结构消息的附件提取逻辑。现在，当用户在企微发出一条包含图片/文件与文字的混合消息时，底层框架会自动遍历并提取各个媒体节点的 URL 和 AES Key，确保核心处理管线能进行正常下载与安全解密。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.16`。\n- 如果你之前在企微发出“带图的一段话”时，曾遇到 AI 回复说“这是一个腾讯 COS 的临时签名链接”，本次升级后，此问题将被修复，AI 将可以直接分析图片内容本身。\n\nArchive v2.9.4: 245 files, 506324 bytes\n\nFiles: changelog/v2.2.28.md (3745b), changelog/v2.3.10.md (1572b), changelog/v2.3.11.md (1837b), changelog/v2.3.12.md (3259b), changelog/v2.3.13.md (2018b), changelog/v2.3.14.md (4670b), changelog/v2.3.15.md (2241b), changelog/v2.3.16.md (1113b), changelog/v2.3.18.md (4080b), changelog/v2.3.19.md (6771b), changelog/v2.3.2.md (2795b), changelog/v2.3.26.md (1830b), changelog/v2.3.27.md (4345b), changelog/v2.3.273.md (680b), changelog/v2.3.4.md (1755b), changelog/v2.3.9.md (1711b), changelog/v2.4.12.md (4707b), changelog/v2.4.16.md (1157b), changelog/v2.7.4.md (2724b), changelog/v2.8.0.md (3687b), changelog/v2.8.1.md (2230b), changelog/v2.8.17.md (7630b), changelog/v2.8.18.md (3377b), changelog/v2.8.19.md (5692b), changelog/v2.8.2.md (2496b), changelog/v2.8.20.md (7103b), changelog/v2.8.21.md (8625b), changelog/v2.8.22.md (6594b), changelog/v2.8.23.md (6868b), changelog/v2.8.24.md (7061b), changelog/v2.8.25.md (5291b), changelog/v2.8.26.md (6532b), changelog/v2.8.27.md (5994b), changelog/v2.8.28.md (3728b), changelog/v2.8.29.md (4665b), changelog/v2.8.3.md (3447b), changelog/v2.8.30.md (4967b), changelog/v2.8.31.md (6539b), changelog/v2.8.32.md (1368b), changelog/v2.8.6.md (3301b), changelog/v2.8.8.md (5098b), changelog/v2.9.0.md (6833b), changelog/v2.9.1.md (2771b), changelog/v2.9.2.md (3292b), changelog/v2.9.4.md (3128b), compat-single-account.md (4135b), GOVERNANCE.md (1301b), index.test.ts (1058b), index.ts (5408b), openclaw.plugin.json (11593b), package.json (3045b), README.md (31424b), scripts/release.sh (11536b), scripts/test-proxy.ts (2377b), SKILL.md (4871b), SKILLS_CAL.md (29478b), SKILLS_DOC.md (70311b), src/accounts.ts (1223b), src/agent/api-client.upload.test.ts (3909b), src/agent/handler.event-filter.test.ts (3469b), src/agent/handler.ts (39593b), src/agent/index.ts (248b), src/app/account-runtime.ts (11247b), src/app/bootstrap.ts (890b), src/app/index.ts (6075b), src/capability/agent/delivery-service.ts (4475b), src/capability/agent/fallback-policy.ts (484b), src/capability/agent/index.ts (221b), src/capability/agent/ingress-service.ts (1126b), src/capability/agent/upstream-delivery-service.ts (3728b), src/capability/bot/dispatch-config.ts (1854b), src/capability/bot/fallback-delivery.ts (6892b), src/capability/bot/index.ts (58b), src/capability/bot/local-path-delivery.ts (8059b), src/capability/bot/sandbox-media.test.ts (7025b), src/capability/bot/sandbox-media.ts (5688b), src/capability/bot/service.ts (1651b), src/capability/bot/stream-delivery.ts (16654b), src/capability/bot/stream-finalizer.ts (5769b), src/capability/bot/stream-orchestrator.ts (16350b)\n\nFile v2.9.4:SKILL.md\n\n---\nname: huo15-wecom\ndescription: \"火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担心 stream 截断 + 86008 把链接设为优先，v2.8.23/v2.8.24 修了群聊主动推送通道 + UI 锁交互后 MEDIA: 路径稳定可靠，应用户偏好翻转：默认 MEDIA: 直发，仅大文件（> 企微上限）才走 enhance_share_file 链接。GUIDANCE 加决策表 + 用户偏好覆盖。继承 v2.8.24 placeholder timeout 解锁、v2.8.23 群聊主动推送、v2.8.20 MEDIA: parser。Use when: 接企业微信、给企微 Bot/自建应用接 OpenClaw、用微信客服收外部用户消息、需要图片/文件双向、跨账号切换。Do NOT use for 个人微信（不同协议）。\"\nversion: 2.9.4\nhomepage: https://cnb.cool/huo15/ai/huo15-wecom-plugin\nmetadata: { \"openclaw\": { \"emoji\": \"🦜\", \"requires\": { \"bins\": [] } } }\n---\n\n# 火一五企业微信插件\n\n`@huo15/wecom` 是 OpenClaw 的企业微信通道插件，fork 自 [yanhaidao/wecom](https://github.com/yanhaidao/wecom) 并持续合并上游。**默认 Bot WebSocket 模式**，配置简单、响应快；同时支持 Agent 自建应用主动推送和微信客服三方通道。\n\n## 三条消息通道\n\n| 通道 | 用途 | 配置入口 |\n|---|---|---|\n| **Bot WebSocket** | 默认推荐，企业微信\"智能机器人\"WS 协议，免公网回调 | `channels.wecom.accounts.<id>.bot.ws` |\n| **Agent 自建应用** | 走企微官方 API（CorpId/AgentId/Secret），支持主动推送给指定用户/群 | `channels.wecom.accounts.<id>.agent` |\n| **微信客服** | 接管\"客服会话\"，外部客户在微信/视频号里发给客服账号的消息 | `channels.wecom.accounts.<id>.kefu` |\n\n三条通道可以**单独启用**或**组合启用**，多账号场景每个账号独立配置。\n\n## 安装\n\n```bash\n# OpenClaw 内置安装（推荐）\nopenclaw plugins install @huo15/wecom\n\n# 或者直接 npm\nnpm install @huo15/wecom\n```\n\n## 最小配置（Bot WS 模式）\n\n```yaml\n# ~/.openclaw/openclaw.json 中\nchannels:\n  wecom:\n    enabled: true\n    accounts:\n      default:\n        bot:\n          ws:\n            botId: \"你的智能机器人 ID\"\n            secret: \"WS 密钥\"\n```\n\n启动后，Bot 收到的消息会自动路由到默认 Agent，回复也通过 WS 直接送回 — 不需要部署任何回调 endpoint。\n\n## 关键能力\n\n- **加密媒体解密**：图片/文件/语音 AES-256-CBC 解密直接拿 buffer，可让 Agent 直接读取（OCR / ASR / 文档解析）\n- **Markdown V2**：支持企微富文本（标题、表格、代码块、链接、引用），自动适配 chat 上下文\n- **图片回复**：`![alt](url)` 自动抽离 + uploadMedia + replyMedia，COS/OSS 预签名 URL 失败时降级为占位文本（不让\"链接已过期\"漏到客户端）\n- **多账号切换**：单实例支持多个企业、多个智能体并存，按 conversation 路由\n- **流式回复**：placeholder + partial replyStream（最多 8 次中间更新）+ ack timeout watchdog 自动重连\n\n## v2.8.8 关键修复（WS BOT 图片）\n\n1. **Reply 通道纠错**：reply 上下文从 `sendMediaMessage`（主动推送）改用 `replyMedia`（被动回复，绑定 reqId）\n2. **入向多图**：`mixed` 与 `quote.mixed` 类型从只取首张改为全部提取；首张挂 `ctx.MediaPath`，其余落盘 + info 日志\n3. **Outbound fetch UA**：从裸 `fetch` 切到 plugin-sdk `fetchRemoteMedia`，显式带 desktop User-Agent，避免部分 Tencent COS / 阿里 OSS bucket 拒绝 Node 默认 UA\n4. **解析可观测性**：媒体类型消息但无 attachments 时记 warn 日志（含 msgid + body keys），便于 SDK 字段漂移排查\n\n详见 [changelog/v2.8.8.md](./changelog/v2.8.8.md)。\n\n## 安全实践\n\n- LLM 输出的 `touser` / `chatid` 经 `resolveWecomTarget` sanitizer，**拒绝 `@all` / `@everyone` / `*` 等广播字面量**（v2.8.1 SECURITY 修复）\n- 跨企业上下游消息走 upstream-delivery 通道，不与本企业 Agent API 混用\n- 微信客服 `corpSecret` 可与 Agent `corpSecret` 独立配置，权限隔离\n\n## 不变的设计原则\n\n- **Bot WS 优先**：能用 WS 就不用 Agent API（少配置、低延迟）\n- **失败降级**：WS reply ack timeout 自动 fallback 到 Agent API（保留消息可达性），watchdog 连续 8 次后触发 WS 重连\n- **不修改 OpenClaw 核心**：所有功能通过 channel plugin SDK 注册\n\n## 仓库\n\n- 主仓库：https://cnb.cool/huo15/ai/huo15-wecom-plugin\n- 镜像：https://github.com/zhaobod1/huo15-wecom-plugin\n- 上游 fork 源：https://github.com/yanhaidao/wecom（**仅 fetch，不 push**）\n\n## License\n\nISC（继承自 yanhaidao/wecom 上游）。\n\nFile v2.9.4:README.md\n\n# OpenClaw 企业微信(WeCom)Channel 插件\n\n<p align=\"center\">\n  <a href=\"https://github.com/yanhaitao/wecom\"><img src=\"https://img.shields.io/badge/Original%20Project-逸寻智库-orange?style=for-the-badge&logo=github\" alt=\"Original Project\" /></a>\n  <img src=\"https://img.shields.io/badge/License-ISC-blue?style=for-the-badge\" alt=\"License\" />\n  <img src=\"https://img.shields.io/badge/Min%20Recommended-2.8.1+-red?style=for-the-badge\" alt=\"Minimum recommended\" />\n</p>\n\n> [!CAUTION]\n> **🛡️ 安全公告（2026-04-22）**：受影响版本 `<= 2.8.0`。Agent 在工作区写自定义脚本时可能把 `touser=\"@all\"` 当默认收件人，导致原本私聊的图片/视频/文档**被广播到企业微信应用可见范围全员**。\n>\n> **请所有部署立即升级到 `@huo15/wecom@2.8.1` 或以上**。修复见 [`changelog/v2.8.1.md`](changelog/v2.8.1.md)。\n\n> [!WARNING]\n> **原创声明**:本项目涉及的\"多账号隔离与矩阵路由架构\"、\"Bot+Agent双模融合架构\"、\"长任务超时接力逻辑\"及\"全自动媒体流转接\"等核心设计均为作者 **YanHaidao** 独立思考与实践的原创成果。\n> 欢迎技术交流与合规引用,但严禁任何不经授权的\"功能像素级抄袭\"或删除原作者署名的代码搬运行为。\n\n<p align=\"center\">\n  <strong>🚀 企业级多模式 AI 助手接入方案(统一运行时架构)</strong>\n</p>\n\n---\n\n## 💡 核心价值:为什么团队会真正选择这个插件?\n\n企业真正需要的,不是\"把一个模型接进企业微信\",而是让企业微信变成一个**能长期工作的 AI 协作入口**。\n\n大多数团队最终只关心五件事:\n\n- 能不能先低门槛接起来,而不是先做一轮重部署\n- 多人同时使用时,会不会串上下文、串身份、串会话\n- 长任务会不会因为长连接窗口太短而白跑\n- 能不能既有实时对话体验,又能做正式推送和稳定投递\n- AI 能不能真正进入文档、日程、会议、待办、通讯录这些协作层,而不只是停留在聊天框\n\n常见方案通常会很快碰到边界:\n\n- **只用 Bot WS**:接得快、聊得顺,但会受到单连接、心跳保活、会话边界和组织级广播能力的限制\n- **只用 Agent**:能力强、治理清晰,但部署门槛更高,对话体验不如 Bot WS 丝滑\n- **只选单一路径**:团队最后往往被迫在\"体验\"和\"能力\"之间二选一\n\n本插件的价值,就在于把这些原本互相冲突的目标,尽量同时成立。\n\n### 您真正会得到什么?\n\n1. **多人共用一个入口,但上下文不会串**\n   - **问题本质**:企业里真正难的不是\"接入一个机器人\",而是让几十上百个人同时使用时,仍然保持每个人的上下文隔离。\n   - **插件做法**:按 `(底层账号 + 部门/群组/人员)` 动态切分运行上下文和 Agent 实例。\n   - **用户收益**:同一个企业微信入口可以承接多人并发使用,而不会出现\"张三的问题让李四接上回答\"的串流灾难。\n\n2. **长任务不白跑,回复不轻易丢**\n   - **问题本质**:企业微信长连接的响应窗口很短,而推理模型的思考时间往往很长。\n   - **插件做法**:先保活,再流式推进;必要时走备用投递路径,把最终结果交付出去。\n   - **用户收益**:更敢把复杂任务、长文本分析、报告生成交给 AI,而不是每次都担心\"算完了却发不回来\"。\n\n3. **实时对话体验和正式投递能力,不用二选一**\n   - **问题本质**:实时聊天和组织级推送,往往不是同一条技术路径最擅长的事。\n   - **插件做法**:会话内实时交互、流式回复、异步追发优先走 `Bot WS`;组织级广播、冷启动触达、正式通知由 `Agent` 兜底。\n   - **用户收益**:日常使用时体验像聊天助手,正式落地时又有企业应用该有的稳定性和控制力。\n\n4. **AI 不只会聊天,还能进入企业微信协作层**\n   - **问题本质**:如果 AI 只能回消息,信息最终还是散落在聊天流里,业务并没有真正被推进。\n   - **插件做法**:把企业微信原生协作能力按两条能力平面接入 OpenClaw。\n   - **用户收益**:AI 不仅能回答问题,还能真正参与文档、日程、会议、待办和通讯录相关工作。\n\n5. **小团队能低门槛上手,大团队也能正式上线**\n   - **问题本质**:小团队怕折腾,大团队怕失控。\n   - **插件做法**:`Bot WS` 适合快速启用,`Agent` 适合正式治理,两者可以并存。\n   - **用户收益**:您不用在\"今天先跑起来\"和\"将来能不能正规化\"之间做破坏性迁移。\n\n---\n\n## 📊 为什么不是只选 Bot,或者只选 Agent?\n\n从用户视角看,差别不在于协议名词,而在于**你要解决的是什么问题**。\n\n| 你真正关心的事 | 🤖 Bot 模式 (WebSocket) | 🧩 Agent 模式 (自建应用 API) | ✨ 本插件的做法 |\n|:---|:---|:---|:---|\n| **先跑起来的速度** | ✅ 快,无需固定公网 IP | ❌ 较重,需要正式应用配置 | ✅ 先用 Bot 起步,后续平滑补 Agent |\n| **实时聊天体验** | ✅ 最强,天然适合低延迟和流式回复 | ⚠️ 能收能发,但不是最佳对话入口 | ✅ 默认把实时交互交给 Bot |\n| **异步结果回推** | ✅ 可以,适合已建立会话内追发 | ✅ 可以 | ✅ 会话内追发优先 Bot,必要时 Agent 兜底 |\n| **组织级广播与冷启动触达** | ⚠️ 受会话边界约束 | ✅ 更适合 | ✅ 正式通知和广播走 Agent |\n| **企业微信协作能力** | ✅ 适合个人身份能力入口 | ✅ 适合应用身份能力入口 | ✅ 两种身份平面都兼容 |\n| **适合谁** | 想快速上线、重视实时体验的团队 | 需要正式治理、自动化和组织级能力的团队 | 想同时要\"体验\"和\"能力\"的团队 |\n\n> **建议理解方式:**\n> - 如果您最在意的是\"先接起来、先用起来、先聊顺\",优先上 `Bot WS`\n> - 如果您最在意的是\"正式部署、组织级能力、自动化治理\",补齐 `Agent`\n> - 如果您真正想把 AI 在企业微信里长期用下去,最终往往需要两者并存\n\n---\n\n## 🧩 企业微信协作能力:为什么这件事比\"能聊天\"更重要?\n\n很多企业微信 AI 机器人,本质上只是把答案发回聊天框。\n真正有价值的,是让 AI 进入您**已经在工作的地方**。\n\n在本插件里,企业微信的**文档、日程、会议、待办、通讯录**等能力,不再只是外围说明,而是被接成了可以实际调用的协作平面。\n\n### 1. Bot WS 协作模式:适合小团队的个人身份入口\n\n根据企业微信最新开放说明,面向 **5 人及以下的小微企业**,`Bot WS` 模式现已开放以**用户个人身份**调用部分企业微信协作能力。\n\n在本插件里,这条链路以 `wecom_mcp` 的方式挂载,只在 **WeCom Bot WS 会话** 中可用:\n\n- 能力入口:`wecom_mcp`\n- 典型能力品类:`doc`、`meeting`、`todo`、`contact`\n- 触发条件:当前会话必须来自 `Bot WS`\n- 更适合的场景:个人身份读写文档、查询通讯录、处理待办、操作会议等轻量协作场景\n\n它的价值在于:\n\n- **门槛低**:无需先走完整的自建应用接入流程\n- **身份自然**:更贴近当前聊天用户自己的协作上下文\n- **启动快**:对小团队尤其友好\n\n它的边界也要明确:\n\n- 依赖 `Bot WS` 会话存在\n- 主动推送仍然以**已建立会话**为前提\n- 实际开放范围以企业微信后台可见权限为准\n\n### 2. Agent 协作模式:适合正式落地的应用身份入口\n\n`Agent` 模式走的是**自建应用 API** 平面,更适合企业级稳定自动化与组织级治理。\n\n在本插件里,当前内置的协作工具主要包括:\n\n- `wecom_doc`:文档、表格、权限、分享可用性诊断等\n- `wecom_calendar`:日历、日程、参与人、回执、默认日历等\n\n它更适合:\n\n- 把协作能力放进正式企业应用权限体系\n- 与定时任务、异步流程、正式投递联动\n- 面向组织对象做更稳定的自动化操作\n\n### 3. 这两条能力链在插件里已经实际接通\n\n当前插件已经把这两条协作链路都注册进来:\n\n- `wecom_mcp`:仅在 `Bot WS` 会话中暴露\n- `wecom_doc`:仅在 `Agent` 会话中暴露\n- `wecom_calendar`:仅在 `Agent` 会话中暴露\n\n也就是说,您拿到的不是\"一个只能聊天的企微插件\",而是:\n\n- 一条适合实时对话和个人协作的入口\n- 一条适合正式应用和组织自动化的入口\n\n### 4. 授权方式\n\n请按所选平面分别授权:\n\n- **Bot WS 模式授权**:前往企业微信管理后台 👉「工作台 - 智能机器人」,找到对应机器人,点击编辑,在「可使用权限」处勾选文档、日程、会议、待办、通讯录等对应权限。\n- **Agent 模式授权**:前往企业微信管理后台 👉「工作台 - 协作 - 文档 / 日程 / 会议等」,将您的自建应用加入\"可调用接口的应用\"。\n\n一句话理解:\n\n- **Bot WS** 更像\"当前聊天用户的实时协作入口\"\n- **Agent** 更像\"企业正式应用身份下的自动化执行入口\"\n\n两者同时配置后,您既能拿到顺滑的实时交互,也能拿到企业级可治理的协作能力。\n\n---\n\n## 📋 最近更新 (Changelog摘要)\n\n> 项目保持高频迭代,全面对齐甚至超越企业真实业务诉求。\n> **为保持精简,以下仅展示近期 5 次重要更新,完整历史版本(含全部 `v2.2.x`)请前往 [changelog/ 目录](./changelog/) 查阅。**\n\n#### 📌 v2.8.0(2026-04-22)\n- **[能力扩充] 微信客服(kefu)全通道落地** 🆕 Agent/Bot 之外,新增“企业微信客服”作为第三条消息通道:外部客户在微信、视频号、对外小程序里发给客服号的消息可直接走到 OpenClaw 里回复。配置独立(`channels.wecom.accounts.<id>.kefu.{corpId,corpSecret,openKfIds,webhook}`),`corpSecret` 允许与 Agent 分开建一套“只给客服用”的 Secret。\n- **[通道独立] 回调路径解耦** 🛣️ 客服挂载到独立路径 `/plugins/wecom/kefu`(推荐)或 `/plugins/wecom/kefu/<accountId>`,与 Bot / Agent 路径互不冲突。企微客服回调只携带 Token,插件内部调用 `kf/sync_msg` 按 `open_kfid` 维度维护 cursor 完整拉取,配合 LRU `msgid` 去重与 in-flight 并发守卫,确保消息不重、不漏。\n- **[入向覆盖] 10 类消息全量归一** 📥 text/image/voice/video/file/link/miniprogram/msgmenu/location/business_card/event(含 `enter_session` 映射成 `welcome`)均已 normalize 成 `UnifiedInboundEvent`,下游 Agent 无感消费。\n- **[出向能力] send_msg 一体化** 📤 text 按 3500 字符切片避开 4096 字节上限、media 由 content-type+扩展名分类分别走 image/voice/video/file,link 走 `payload.channelData.kefu.link` 专用卡片,统一走 `upload_media` 拿 `media_id` 后下发。新增 `toKefuText` 把 markdown 扁平成 kefu `content` 能识别的纯文本(保留代码块/链接/列表项标识,剔除标题/粗体/HTML 等)。\n- **[会话自动路由] Source Registry 扩展** 🔁 `WecomSourcePlane` 新增 `\"kefu\"`,入向会记录 `kefuOpenKfId`;下一轮 Agent 主动回复时会自动走客服出向,不会误发到 Agent 内部私信。显式目标 `wecom-kefu:<accountId>:<openKfId>:<externalUserId>` 同样支持。\n\n#### 📌 v2.7.3(2026-04-21)\n- **[格式升级] 全线切换到 `markdown_v2`** 🎨 自建应用(Agent API) / 群机器人(Bot WS) / 主动回复(Bot Webhook response_url)全部改用企微 2026 年新的 `markdown_v2` 消息类型,**原生支持 markdown 表格、图片 `![](url)`、粗体、链接、代码块、嵌套引用、列表**,消息上限从 2048 字节提到 4096 字节。\n- **[逻辑简化] 移除 textcard 降级路径** 🧹 以前遇到表格/大标题/链接会被\"降级\"成 textcard(title + 512 字纯文本描述,丢失 markdown 格式),现在统一走 markdown_v2,富文本完整渲染,不再需要 textcard workaround。\n- **[兼容注意]** ⚠️ markdown_v2 不支持 `<font color>` 标签和 `@userid` 群成员 at(原 markdown 支持),如果你依赖这两个特性请用 text 消息或保留 v1。本插件 adapter 本来就不生成这两个语法,用户无感。\n\n#### 📌 v2.7.2(2026-04-21)\n- **[Bug 修复] 引用群文件显示\"COS链接过期\"** 🔧 同步上游引用文件处理逻辑,新增 `channels.wecom.media.downloadTimeoutMs` 配置(默认 30s),分级区分超时/5 分钟 TTL 过期/网络错误,避免大文件抓取失败。\n- **[Bug 修复] 安装插件被安全扫描拦截** 🔒 移除上游已回滚的 `src/agent/script-runner.ts`(使用了 `child_process.spawn`),不再触发 OpenClaw 的 `dangerous-exec` 规则,v2.7.2 可以直接通过 `npm` 或 `clawhub` 方式安装。\n- **[上游同步] 合并 yanhaidao/wecom 至 c1158a9** 📦 包含引用附件在群聊/私聊中透传、媒体下载超时配置、菜单事件文档等;同时吸收上游对 jjjkkil 两次 agentcation PR 的 revert。\n- **[版本对齐] 保留 `@huo15/wecom` 独立包名** 📦 包名保持 `@huo15/wecom`,版本号跳至 `2.7.2`。\n\n#### 📌 v2.3.273(2026-03-31)\n- **[重要修复] WS 断连 Fallback** 🔧 耗时任务/Gateway 重启/WS 断线重连时,Bot WS 自动切换到 Agent API 发送回复,不再出现\"机器人没反应\"的问题。\n- **[markdown 修复] 表格和代码块渲染恢复** 📦 从 main 分支合并,表格不再强制转为纯文本,保留 markdown 格式。\n- **[包名变更] `@yanhaidao/wecom` 更名为 `@huo15/wecom`** 📦 npm 包名已更新。\n\n#### 📌 v2.3.27(2026-03-27)\n- **[重要修复] `channel add` 重新支持 WeCom guided setup** 🧭 之前有些环境下,`wecom` 虽然已经安装,却仍会在 OpenClaw 里显示成 \"does not support guided setup yet\",导致无法直接通过交互式向导添加。现在插件已经对齐 OpenClaw 当前的 `setupWizard` 接口,`openclaw channels add` 会重新正常识别和进入配置流程。\n- **[重要修复] 修复 `installedCatalogById is not defined`** 🔧 部分用户在渠道添加或选择阶段会直接遇到 `ReferenceError: installedCatalogById is not defined`,表现上像是\"选了渠道就报错\"或\"添加流程突然失效\"。这一版已经修复对应的目录访问逻辑,添加流程恢复稳定。\n- **[升级兼容] 清理 OpenClaw 新版下失效的 SDK 旧入口** 📦 这次同步迁移了 `wecom` 插件里几处已经不再建议继续从 `openclaw/plugin-sdk` 根入口直接拿的旧接口,重点覆盖工具上下文、outbound 适配器和 Bot WS 媒体发送链路,升级 OpenClaw 后更不容易再出现\"有的地方能跑、有的地方直接炸\"的兼容问题。\n\n#### 📌 v2.3.26(2026-03-26)\n- **[重要修复] 升级 OpenClaw 后不再乱报错** 🔧 修复了新版 OpenClaw 下 `wecom` 插件容易出现的 `is not a function` 一类启动/运行错误。\n- **[回复更稳] Agent 和 Bot WS 不再乱串** ↔️ 现在是谁收到消息,就尽量由谁来回复,不再容易出现\"在 Agent 里说话,结果 Bot WS 回你\"的情况。\n- **[体验修复] Bot WS 发图后不再多冒一条 `Done...`** 🖼 之前常见表现是:`正在思考` -> 图片 -> 又多一条完成提示。现在最终收尾会尽量接回原来的回复链路。\n- **[占位符修复] 不会一直卡在\"正在思考...\"** ⏳ 如果图片或文本已经发出去了,占位符会更自然地结束,不会继续无意义地刷屏。\n\n#### 📌 v2.3.19(2026-03-19)\n- **[重要修复] Bot WS 现在也真正走 `dynamicAgents`** 🧭 之前同样开启动态路由时,不同消息链路的行为并不完全一致:Webhook / Agent 能按用户、群聊隔离,Bot WebSocket 却可能重新落回主 Agent。现在 WS 运行时也执行同样的动态路由逻辑,会话隔离终于统一了。\n- **[配置统一] 媒体大小开始优先跟随 OpenClaw 标准 `mediaMaxMb`** 📦 之前 WeCom 插件更偏向读取自己的 `media.maxBytes`,用户改了 OpenClaw 主配置却可能感觉\"改了没生效\"。现在插件优先支持 `channels.wecom.mediaMaxMb`,并支持 `channels.wecom.accounts.<accountId>.mediaMaxMb` 做账号级覆盖;旧配置仍兼容,但只作为兜底。\n- **[体验修复] 常见本地目录文件现在更符合直觉地可发送** 🖼 过去本地媒体白名单更偏向 OpenClaw 自己目录,导致像 `Downloads`、`Desktop`、`Pictures` 里的图片明明存在,却常被拦下。现在插件默认额外放行这些常见用户目录,同时保留 `channels.wecom.media.localRoots` 继续追加共享盘、挂载盘和业务目录。\n\n#### 📌 v2.3.18(2026-03-18)\n- **[重大升级] 双平面能力融合(Bot WS + MCP 强化)** 🚀 独家引入挂载式的 MCP 能力层。在保留原生 Agent 强力工具的同时,将官方新开放的企业微信能力暴露给大模型。现在,大模型可凭用户身份读写待办、日程、查通讯录。\n- **[多账号硬隔离]** 彻底重构 MCP 缓存池实现 `accountId + category` 的二次硬维隔离,无论您的矩阵挂载了多少家企业的助手,上下文及鉴权缓存绝不会交叉重叠。\n- **[媒体通道重构]** 补齐 Bot WS 本地的媒体上传链,同时设立了严格的 `5秒熔断机制`,若 WebSocket 长通道大文件卡死将无感静默降级到 Agent 私信发送。\n\n*(查看更早期关于\"超时熔断代投、动态扩容矩阵\"等功能的更新日志，请移步 [changelog/ 目录](./changelog/))*\n\n---\n\n## 一、🚀 快速开始\n\n> 推荐统一使用**多账号矩阵模型**。\n> 即使您的企业只接入了一个账号,也强烈建议将其配入 `channels.wecom.accounts.default` 节点下。\n\n### 1.1 插件安装\n\n```bash\nopenclaw plugins install @yanhaidao/wecom\nopenclaw plugins enable wecom\n```\n\n### 1.2 互动向导式初配 (适合个人开发者与极客)\n\n如果您不想手写繁杂的 JSON 配置文件,可以通过交互式向导快速完成最轻量的 WebSocket 长连接部署。`v2.3.27` 起,`wecom` 已重新对齐 OpenClaw 当前的 guided setup 流程,`openclaw channels add` 可以直接识别并进入配置:\n\n1. 确保已启用本插件。\n2. 在终端运行添加渠道指令:\n   ```bash\n   openclaw channels add\n   ```\n3. 选择下拉列表中第一顺位的:**企业微信 (WeCom)**\n4. 根据终端亮色指引,填入企微机器人对应的 `Bot ID` 及 `Secret`,机器人即可完成握手并进入可用状态。\n\n> **如果您最近刚升级 OpenClaw:**\n> - 若之前在添加渠道时看到 `wecom does not support guided setup yet`,请更新到当前版本后重试。\n> - 若之前在渠道添加阶段见过 `ReferenceError: installedCatalogById is not defined`,这一版也已一并修复。\n\n### 1.3 生产环境顶配架构示范(Bot WS 流式交互 + Agent 私有通道兜底发送)\n\n如果您的目标不是\"接进来能聊两句\",而是让团队在企业微信里长期稳定使用 AI,这套组合更接近生产环境的推荐形态:\n\n- `Bot WS` 负责实时对话、低延迟流式回复和更轻的接入门槛\n- `Agent` 负责主动推送、媒体发送和长任务后的兜底交付\n- `dynamicAgents` 负责把不同用户、不同群聊的会话真正隔离开,避免多人共用一个入口时互相串上下文\n\n请进入 OpenClaw 配置文件(`openclaw.json`)的 `channels.wecom` 内使用:\n\n```jsonc\n{\n  \"channels\": {\n    \"wecom\": {\n      \"enabled\": true,\n      \"defaultAccount\": \"default\",\n      \"accounts\": {\n        \"default\": {\n          \"enabled\": true,\n          \"name\": \"企微销售二部支持中枢\",\n          \"bot\": {\n            \"primaryTransport\": \"ws\",             // 指定 Bot 主通讯协议:ws 或 webhook\n            \"streamPlaceholderContent\": \"正在深思熟虑,请稍候...\", // 避免流式回复开始前长时间无反馈\n            \"welcomeText\": \"你好,我是已连网的专属大脑。\",\n            \"dm\": {\n              \"policy\": \"pairing\",\n              \"allowFrom\": []\n            },\n            \"ws\": {                               // Bot WS 建连所需凭证\n              \"botId\": \"YOUR_BOT_ID\",\n              \"secret\": \"YOUR_BOT_SECRET\"\n            }\n          },\n          \"agent\": {                              // 主动推送、媒体发送与兜底交付链路\n            \"corpId\": \"YOUR_CORP_ID\",\n            \"agentSecret\": \"YOUR_AGENT_SECRET\",\n            \"agentId\": 1000001,\n            \"token\": \"AGENT_TOKEN\",\n            \"encodingAESKey\": \"AGENT_AES_KEY\",\n            \"welcomeText\": \"若长连接断开,我将使用此通道传递残存报告。\",\n            \"dm\": {\n              \"policy\": \"open\",\n              \"allowFrom\": []\n            }\n          }\n        }\n      },\n      \"mediaMaxMb\": 50,                           // 优先使用 OpenClaw 标准媒体上限配置\n      \"media\": {\n        \"tempDir\": \"/tmp/openclaw-wecom-media\",\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\"\n        ]\n      },\n      \"network\": {                                // 内网或受限网络环境可通过代理出网\n        \"egressProxyUrl\": \"http://127.0.0.1:3128\"\n      },\n      \"dynamicAgents\": {                          // 为单聊/群聊创建独立路由,减少多人串上下文\n        \"enabled\": true,\n        \"dmCreateAgent\": true,\n        \"groupEnabled\": true,\n        \"adminUsers\": [\"zhangsan001\"]             // 管理员绕过动态路由,直连主 Agent\n      }\n    }\n  }\n}\n```\n\n其中:\n\n- 插件现在默认额外放行常见用户目录:`~/Desktop`、`~/Documents`、`~/Downloads`、`~/Movies`、`~/Pictures`。\n- `channels.wecom.mediaMaxMb` 是首选的媒体大小上限配置,`channels.wecom.accounts.<id>.mediaMaxMb` 可以做账号级覆盖。\n- `channels.wecom.media.localRoots` 用于继续追加你自己的全局目录,例如共享盘、挂载盘或业务导出目录。\n- 旧的 `channels.wecom.media.maxBytes` 仍然兼容,但仅作为向后兼容兜底;新配置建议统一改成 `mediaMaxMb`。\n- 这些目录会和 OpenClaw 默认允许的媒体目录一起生效,不会覆盖默认白名单。\n- 也就是说,像 `~/Downloads/01.png` 这类本机文件现在默认就可以直接发到企微,不需要再单独配置。\n\n> **注意:** 历史配置里的 `agent.corpSecret` 引擎依然能够向后兼容拾起,但后续的新项目推荐采用标准的 `agentSecret` 作为对齐键。\n\n### 1.4 dynamicAgents 详细说明:为什么生产环境建议开启\n\n`dynamicAgents` 的核心价值,不是\"自动创建很多 Agent\",而是让企业微信里的每个用户、每个群聊都拥有稳定、独立的会话落点。\n如果不开它,所有消息更容易汇入同一个主 Agent;一旦开始多人共用,最先出问题的通常不是模型能力,而是上下文、长期记忆和处理边界混在一起。\n\n更简单地看,可以直接按下面这张表决定要不要开:\n\n| 场景 | 不开时的问题 | 建议配置 | 你得到的结果 |\n|---|---|---|---|\n| 多个同事同时私聊同一个机器人 | 容易共用同一条会话脉络,长期上下文可能互相污染 | `enabled=true` + `dmCreateAgent=true` | 每个人都有自己的稳定上下文 |\n| 一个或多个群长期拿机器人协作 | 不同群更容易共用主 Agent,群与群之间边界不清晰 | `enabled=true` + `groupEnabled=true` | 每个群都有独立会话空间 |\n| 管理员需要统一测试、巡检、接管 | 管理员也会被切进自己的动态 Agent,排障更分散 | `adminUsers=[\"管理员userid\"]` | 管理账号继续直连主 Agent |\n| 只是做 PoC 或单人试用 | 一上来就启用隔离,理解成本偏高 | `enabled=false` | 先把连通性和基础回复跑通 |\n\n系统当前的真实行为如下:\n\n- 开启后,会按 `账号 + 会话类型 + 对端 ID` 生成确定性的 Agent ID,例如 `wecom-default-dm-zhangsan` 或 `wecom-default-group-wr123456`\n- 同一个用户或同一个群,下次再发消息时会继续命中同一个动态 Agent,而不是临时随机分配\n- 首次命中时,插件会自动把这个动态 Agent 追加到 `agents.list`,不需要您手工维护一长串列表\n- 这套逻辑同时作用于 `Bot WS` 和 `Agent Callback` 两条主消息链路,不是只有某一种模式才生效\n- `adminUsers` 中的账号会始终绕过动态路由,直接走主 Agent,适合放管理员、运营或排障账号\n- 默认值是 `enabled=false`、`dmCreateAgent=true`、`groupEnabled=true`、`adminUsers=[]`,也就是不开总开关时不会生效,但一旦开启,单聊和群聊会默认一起进入隔离模式\n\n需要注意的是,`dynamicAgents` 解决的是\"路由隔离\"和\"会话隔离\",不是权限系统本身。\n也就是说,它能显著减少上下文串线,但账号是否允许私聊、谁能触发命令、某个账号绑定到哪个主 Agent,仍然要结合 `dm.policy`、`bindings` 和企业微信授权配置一起看。\n\n### 1.5 `localRoots` 详细说明:为什么\"文件明明存在\",系统却仍然不发\n\n`localRoots` 只决定一件事:**这个本地路径允不允许被当作可发送媒体读取。**\n\n| 现象 | 实际含义 |\n|---|---|\n| 文件存在,但发送失败 | 不代表系统允许读取它 |\n| 日志出现 `Local media path is not under an allowed directory` | 路径不在白名单里 |\n| 远程 `https://...` 媒体可以发 | 远程 URL 不走 `localRoots` |\n\n默认已经额外放行这些目录:\n\n| 默认允许目录 | 用途 |\n|---|---|\n| `~/Desktop` | 桌面文件、临时截图 |\n| `~/Documents` | 文档导出目录 |\n| `~/Downloads` | 下载图片、下载文件 |\n| `~/Movies` | 视频文件 |\n| `~/Pictures` | 图片、相册导出 |\n\n另外也保留 OpenClaw 自己的 `tmp / state / workspace` 相关目录。\n\n如果文件不在默认目录里,再补 `localRoots`:\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"media\": {\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\",\n          \"/mnt/nas/public\"\n        ]\n      }\n    }\n  }\n}\n```\n\n配置规则:\n\n| 规则 | 说明 |\n|---|---|\n| `localRoots` 是追加 | 不会覆盖默认目录 |\n| 建议写绝对路径 | 团队环境更稳定、更清楚 |\n| 只加业务需要的目录 | 不要为了省事把范围放太大 |\n| 不建议放整个大盘或整个用户目录 | 会把本地文件读取边界放得过宽 |\n\n排障判断:\n\n| 问题类型 | 看什么 |\n|---|---|\n| 本地路径是否允许读取 | `localRoots` |\n| 媒体能处理多大 | `channels.wecom.mediaMaxMb` |\n| 企业微信最终能不能收 | 企业微信自身媒体限制 |\n| 远程媒体能不能发 | URL 可访问性,不看 `localRoots` |\n\n一句话:`localRoots` 管\"能不能读这个本地路径\",`mediaMaxMb` 管\"最多读多大\"。\n\n---\n\n## 二、🏢 企业微信后台回调挂载指南 (针对使用了 Webhook 或 Agent Callback 的重度用户)\n\n如果您需要让 Agent 通道接收复杂的地理位置及交互式卡片事件,需要将系统的路径下发到企业微信管理后台。\n由于系统默认采纳**多账号分流路径派生**,请切记不要随意丢弃末尾的 `{accountId}`,如下所示:\n\n| 类型 | 您的 OpenClaw 可信域名 | 默认账号路由锚点 | 如果配置了 Ops 项目组子账号 |\n|---|---|---|---|\n| **Bot Webhook** | `https://x.com` | `/plugins/wecom/bot/default` | `/plugins/wecom/bot/ops` |\n| **Agent Callback** | `https://x.com` | `/plugins/wecom/agent/default`| `/plugins/wecom/agent/ops` |\n\n*警告:极度不推荐将老旧单一根路径(如 `/plugins/wecom/bot`)在未指定账户空间下裸奔使用,一旦您的业务扩张到第二个账号,将会引发难以追溯的回调抢占雪崩。*\n\n---\n\n## 三、📡 排障与抓包:洞悉黑盒下的脉搏\n\n当前版本请使用以下三条命令组合排障。注意:`openclaw channels status` **不支持** `--deep`,插件级探测参数是 `--probe`;`--deep` 属于顶层 `openclaw status`。\n\n### 3.1 先看插件级状态快照\n\n```bash\nopenclaw channels status --probe\n```\n\n适合回答这些问题:\n\n- 企业微信账号是否已被网关识别并加载\n- 账号当前是否 `enabled` / `configured`\n- 运行时是否 `running` / `connected` / `authenticated`\n- 最近一次错误、最近进出站时间是否异常\n\n如果网关可达,这条命令会返回企业微信账号的运行时快照。\n如果网关不可达,它会自动退化为\"只看配置\"的摘要输出。\n\n### 3.2 再看全局深度诊断\n\n```bash\nopenclaw status --deep\n```\n\n这条命令是 **OpenClaw 全局诊断入口**,适合确认:\n\n- Gateway 本身是否健康\n- 当前机器上的整体通道探测是否正常\n- 最近心跳、会话、服务状态是否异常\n\n当您怀疑问题不只在企业微信插件,而是 Gateway、网络、配置路径或其他通道共同影响时,优先跑这条。\n\n### 3.3 最后直接看 WeCom 日志\n\n```bash\nopenclaw channels logs --channel wecom --lines 200\n```\n\n当发生疑难连接断开、消息不回、媒体文件下发神秘消失时,直接看日志最有效。新版日志已经被精细地切分在不同命名空间锚点下,助你顺藤摸瓜:\n\n- `[wecom-runtime]`:统一运行时主线。看收消息、分发、回消息、最近错误与会话归属漂移。\n- `[wecom-ws]`:Bot WebSocket 通道。看连接、鉴权、断线、重连、帧收发与保活。\n- `[wecom-agent-delivery]`:Agent 主动发送链路。看用户/部门/标签目标解析、媒体发送和账号错配。\n\n### 3.4 推荐排障顺序\n\n建议按下面顺序执行:\n\n```bash\nopenclaw channels status --probe\nopenclaw status --deep\nopenclaw channels logs --channel wecom --lines 200\n```\n\n您可以按输出这样判断:\n\n- `configured=false`:先检查 `bot.ws.botId`、`bot.ws.secret`、`agent.corpId`、`agent.agentSecret`、`agent.agentId` 等配置是否完整。\n- `running=false`:说明账号没有真正启动,优先看 `[wecom-runtime]`。\n- `connected=false` 或 `authenticated=false`:优先看 `[wecom-ws]`,一般是 WebSocket 握手、密钥或连接稳定性问题。\n- 能收不能发,或群里发文件/卡片失败:优先看 `[wecom-agent-delivery]`。\n- `lastError` 持续刷新:通常不是一次性误报,建议结合最近 200 行日志一起看。\n\n---\n\n## 四、🤝 项目鸣谢\n\n感谢所有为本项目提交代码、测试、文档与反馈的协作者。\n\n- **原始项目**:[yanhaitao/wecom](https://github.com/yanhaitao/wecom)\n\n<p align=\"center\">\n  <a href=\"https://github.com/YanHaidao/wecom/graphs/contributors\">\n    <img src=\"https://contrib.rocks/image?repo=YanHaidao/wecom\" alt=\"WeCom contributors\" />\n  </a>\n</p>\n\n如果头像墙没有立刻刷新,通常是 GitHub 统计或第三方缓存延迟,稍后再看即可。\n\n---\n\n## 五、📮 版权与许可证协议指引\n\n<div align=\"center\">\n\n**公司名称：** 青岛火一五信息科技有限公司\n\n**联系邮箱：** postmaster@huo15.com | **QQ群：** 1093992108\n\n---\n\n**关注逸寻智库公众号，获取更多资讯**\n\n<img src=\"https://tools.huo15.com/uploads/images/system/qrcode_yxzk.jpg\" alt=\"逸寻智库公众号二维码\" style=\"width: 200px; height: auto; margin: 10px 0;\" />\n\n</div>\n\n### 最后的话:关于开源及署名\n本项目版权归 **青岛火一五信息科技有限公司** 所有,遵循 **ISC License**。\n您可以将其用于极其广阔的项目天地中。但开源不是拿来主义:\n在此明确强调,包括所谓的\"Bot+Agent 保活接力超时融合机制\"、\"千人千面多账户切面\"、\"自动寻的路由下沉\" 这背后全是作者无数个在企业真实现网撞墙实验出的架构结晶。**拒绝一切去除原作者署名、粗暴改名换姓占为己用的魔改上架行为。**\n愿我们能在彼此尊重的前提下,共同拓展 OpenClaw 生态的无垠边界。\n\nFile v2.9.4:_meta.json\n\n{\n  \"ownerId\": \"kn7byevkn40d6z4p7ghdb097z983tj33\",\n  \"slug\": \"huo15-wecom-plugin\",\n  \"version\": \"2.9.4\",\n  \"publishedAt\": 1778341727413\n}\n\nFile v2.9.4:changelog/v2.2.28.md\n\n# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.2.28 - 多账号隔离与稳定性增强\n\n本次 v2.2.28 版本是 **OpenClaw 企业微信 (WeCom) 插件** 的一次重大里程碑更新。我们深度优化了 **微信 / 企业微信** 办公场景下的多智能体隔离逻辑，并修复了生命周期、XML 数据保真等多个生产环境的核心痛点。\n\n本次更新让 **OpenClaw** 在处理企业级复杂 **插件** 配置时更加得心应手，完美解决大模型接入 **WeCom** 的所有阻碍。\n\n---\n\n### 🌟 版本亮点 (Release Highlights)\n\n*   🎯 **多账号矩阵支持**：支持按 `accountId` 进行组内会话隔离。不同部门、不同业务的 **企业微信** 机器人可并行运行，互不干扰，彻底解决跨账号串会话问题。\n*   🔐 **数据保真解析**：针对 **WeCom** 的 XML 消息解析进行了重构。关闭了自动数值化，保留 `FromUserName` 前导 `0`，并完美解决 64 位 `MsgId` 精度风险。\n*   🔁 **Gateway 生命周期适配**：完美兼容最新版 **OpenClaw** Gateway 的生命周期管理，修复了在高频心跳监测下的重启循环问题，运行更稳健。\n*   🧹 **入站消息过滤**：优化了 **微信** 与 **企业微信** 的事件过滤逻辑，避免系统事件、缺失发送者等无效消息进入 AI 会话，防止“误回复”。\n*   🧱 **配置安全护栏**：新增 **企业微信** 账号冲突检测。自动拦截重复的 `bot.token` 或 `agentId` 配置，并提供友好的中文错误提示。\n\n---\n\n### 📝 详细更新日志 (Changelog)\n\n#### 【重磅更新】🎯 多账号/多智能体可用性增强\n- 支持按 `accountId` 做组内隔离（Bot + Agent + 路由绑定同组生效）。\n- 动态 Agent 与会话键增加 `accountId` 维度，避免跨账号串会话。\n\n#### 【稳定性】🔁 生命周期兼容修复\n- 适配新版 **OpenClaw** Gateway 生命周期，`startAccount` 改为长生命周期运行。\n- 修复了“几秒一次重启 + health-monitor 二次重启”的循环问题。\n\n#### 【准确性】🔐 XML 字段保真修复\n- **WeCom** Agent XML 解析关闭自动数值化，保留发送者原始 ID。\n- 避免 `MsgId` (64bit) 精度损失，确保回复目标不被误改。\n\n#### 【准确性】🧹 误回复修复\n- Bot/Agent 入站均增加事件过滤，避免处理 `event`、`sys` 及缺失发送者的消息。\n- 修复群聊缺失 `chatid` 时仍进入 AI 会话的问题，避免“一个消息触发多人误回复”。\n\n#### 【可控性】🧱 配置安全护栏\n- 新增多账号冲突检测，自动拦截重复 Token 或 Agent ID 的配置。\n- **账号管理修复**：`deleteAccount` 现在仅删除目标账号，不再误删整个 **插件** 的 `channels.wecom` 配置。\n\n#### 【质量保障】✅ 自动化回归\n- 新增账号解析、冲突检测、动态路由隔离、生命周期与入站过滤的多项自动化测试。\n- **文档优化**：README 快速开始文档更新，优先展示“多账号 + 多 Agent”矩阵配置。\n\n---\n\n### 💾 安装与升级 (Install & Update)\n\n使用 **OpenClaw** CLI 即可一键升级 **插件**：\n\n```bash\nopenclaw plugins upgrade wecom\n```\n\n或手动更新配置：\n```bash\nopenclaw config set channels.wecom.enabled true\n```\n\n---\n\n### 🔍 SEO 关键词 (Keywords)\n**openclaw** | **企业微信** | **微信** | **wecom** | **插件** | **AI 机器人** | **大模型网关** | **流式响应** | **多账号隔离** | **WeCom Plugin**\n\n---\n\n### 📮 联系我们\n如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 或加入我们的交流群。\n\n> **提示**：建议 **OpenClaw** 主程序版本保持在 **2026.2.24+** 以获得最佳体验。\n\nFile v2.9.4:changelog/v2.3.10.md\n\n# OpenClaw WeCom 插件 v2.3.10 变更简报\n\n> [!TIP]\n> **默认更易用、修复更直接的版本。**\n\n## 2026-03-10（v2.3.10）\n- 【消息防丢修复】🐛 **[重要修复]** 针对由于模型 API 限速或超长思考（如 DeepSeek R1）导致的企微 WebSocket 5秒超时断连问题，引入了 4 秒前置保活机制（自动下发\"⏳ 正在思考中...\"），彻底阻断了因为模型响应慢而造成的“消息卡死不再回复”。\n- 【双重回复修复】🐛 **[重要修复]** 修复 `Bot WS` 长文本场景下可能被超时截断并触发兜底通道进行二次重复回复的边界异常。\n- 【向导自动路由】✨ **[体验升级]** 重构了企业微信的渠道交互配置向导。在单账号场景下将静默触发自动路由绑定，丝滑跳过 OpenClaw 全局冗长的 Agent 路由分配询问。\n- 【账号兜底修复】🧩 修复企业微信 onboarding 在首个账号非字面量 `default` 时，后续流程报 `WeCom account \"default\" not found` 的问题。\n- 【默认选项收敛】🚀 onboarding 的默认回车选项已变更为更普适的 `Bot` 模式、`WS` 接入和 `开放模式` 策略。\n- 【字段命名收敛】📝 Agent 新配置统一推荐使用 `agentSecret`，历史 `corpSecret` 保持兼容读取，保障平滑升级。\n- 【文档与提示精简】📘 README、向导交互文案与示例结构已全面统一为更符合直觉的精简说明。\n\n## 验证结果\n- `bunx vitest run extensions/wecom/src/onboarding.test.ts extensions/wecom/src/channel.meta.test.ts`\n- `pnpm build`\n\nFile v2.9.4:changelog/v2.3.11.md\n\n# OpenClaw WeCom 插件 v2.3.11 变更简报\n\n> [!TIP]\n> **稳定性与多账号说明版本**：`v2.3.11` 重点修复 Bot WS 长思考场景下的 `invalid req_id`，同步收敛 onboarding 账号默认值与多账号隔离文档说明。\n\n## 2026-03-11（v2.3.11）\n- 【WS 保活升级】🚀 **[重要修复]** Bot WebSocket 从“4 秒后补发占位”升级为“收到用户消息立即下发占位符，并在长思考期间持续保活”，显著降低慢模型或长任务下的 `invalid req_id` 与回复丢失风险。\n- 【占位符配置生效】🌊 `bot.streamPlaceholderContent` 现在对 `Bot WS` 与 `Bot Webhook` 两条链路统一生效，配置一次即可保持体验一致。\n- 【错误兜底收敛】🛡 修复 `req_id` 已失效时仍尝试二次回错消息的问题，避免出现重复报错与未处理 Promise 拒绝。\n- 【账号选择兜底】🧩 onboarding 在“配置里还没有任何账号”时，也会显式提供 `default` 默认账号选项，减少首次接入时的困惑。\n- 【多账号文档补强】📘 README 新增说明：如果多个 `accountId` 复用同一个静态 Agent，建议配合 `session.dmScope = \"per-account-channel-peer\"`，避免不同账号的私聊上下文共用。\n- 【日志可读性】🔎 WeCom runtime 的 Bot WS 失败日志改为可读错误文本，排查时不再只看到 `[object Object]`。\n\n## 验证结果\n- `pnpm exec vitest run extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/onboarding.test.ts`\n\n## 升级提示\n- 已有 `bot.streamPlaceholderContent` 配置无需调整，升级后 `Bot WS` 会自动使用它。\n- 如果你在同一个 OpenClaw 实例里挂了多个 WeCom 账号，并让它们指向同一个静态 Agent，建议补上 `session.dmScope = \"per-account-channel-peer\"` 以隔离私聊上下文。\n\nFile v2.9.4:changelog/v2.3.12.md\n\n# OpenClaw WeCom 插件 v2.3.12 变更简报\n\n> [!TIP]\n> **WS 主动推送与过期更新兜底版本**：`v2.3.12` 重点修复企业微信 Bot WebSocket 在流式回复超过 6 分钟后返回 `846608 stream message update expired`，并同步调整主动消息路由为“WS 文本优先、Agent 文件兜底”。\n\n## 2026-03-12（v2.3.12）\n- 【6 分钟过期修复】🛠 **[重要修复]** `Bot WS` 现在会把企业微信 `846608 stream message update expired (>6 minutes)` 识别为回复窗口已结束的终态错误，不再继续把该错误向上抛出导致进程退出。\n- 【主动推送路由收敛】🚀 **[重要修复]** 当账号实际运行在 `Bot WS` 模式时，定时消息、heartbeat 和其他主动文本发送现在优先走 `wsClient.sendMessage()`，不再默认绕去 Agent。\n- 【WS/Agent 职责切分】🧩 `Agent` 现在主要承担两类兜底：一是账号没有启用 `Bot WS` 时的主动消息发送；二是 Bot 两种模式都不支持的文件/媒体发送。\n- 【UserID 纯数字解析修复】🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的图片发送失败（81013 错误）。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。\n- 【未处理拒绝隔离】🧯 `sdk-adapter` 为每个 WebSocket frame 的异步处理补上显式兜底捕获；即使后续再出现漏网异常，也会记录到 runtime issue，而不是变成 `unhandledRejection` 直接带崩 OpenClaw。\n- 【占位保活收敛】⏱ 当回复窗口已经过期时，WS 占位符保活会立即停止，避免过期后继续发送流式更新。\n- 【Ack 超时兜底】⏱ SDK 5 秒回执超时 (`Reply ack timeout`) 现在也被识别为终态错误，超时后立即停止占位保活并走 `onFail` 回调，不再产生 `unhandledRejection`。\n- 【回归测试补齐】✅ 新增针对 `846608` 过期更新和 `frame handler` reject 的回归测试，确保此类异常保持非致命。\n- 【Bot WS 图片/文件解密修复】🛠 **[重要修复]** `Bot WS` 模式下接收到的图片和文件现在会使用消息体中的独立 `aeskey` 进行 AES-256-CBC 解密，修复之前直接保存密文导致 `Failed to optimize image` 的问题。`media-service.ts` 新增 `downloadEncryptedMedia()` 方法，`normalizeFirstAttachment()` 自动检测 `aesKey` 并走解密路径。\n\n## 验证结果\n- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/outbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`\n\n## 升级提示\n- 无需新增配置，升级到 `v2.3.12` 后自动生效。\n- 如果账号正在使用 `Bot WS`，主动文本消息会优先走 WS 长连接；只有文件/媒体或未启用 WS 的场景才会继续使用 Agent。\n- 如果模型或工具链路存在超长执行，超过企业微信 6 分钟回复窗口时，OpenClaw 现在会保持存活并记录运行时错误，不再因该异常退出。\n\nFile v2.9.4:changelog/v2.3.13.md\n\n# OpenClaw WeCom 插件 v2.3.13 变更简报\n\n> [!TIP]\n> **Bot WS 引用上下文与流式展示修复版本**：`v2.3.13` 重点补齐企业微信 `Bot WS` 对引用消息的上下文注入，并修复长回答在客户端里显示为“断断续续碎片”的问题。\n\n## 2026-03-13（v2.3.13）\n- 【引用上下文补齐】🛠 **[重要修复]** `Bot WS` 现在会复用与 `Bot Webhook` 一致的入站正文拼装逻辑。用户通过“引用 + 提问”触发机器人时，引用内容会一并进入 Agent 上下文，不再只保留当前这句提问。\n- 【WS 流式刷新修复】🌊 **[重要修复]** `Bot WS replyStream` 现在按“累计全文刷新”发送，而不是只发送最新增量片段，修复企业微信客户端中长回答显示断断续续、像被拆成多块的问题。\n- 【协议语义对齐】🧩 这次调整显式对齐企业微信 `stream.id` 的刷新语义：同一条流式消息的后续更新会覆盖为“当前完整内容”，从而保持最终展示稳定、可连续阅读。\n- 【回归测试补齐】✅ 新增 `bot-ws` 引用上下文与累计流式发送测试，避免后续重构再次把引用消息或流式展示打回退。\n\n## 验证结果\n- `pnpm exec vitest run --config extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/inbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`\n\n## 升级提示\n- 无需新增配置，升级到 `v2.3.13` 后自动生效。\n- 如果企业微信 `WS` 推送里的 `quote.text.content` 仍然是 `[该消息类型暂不能展示]`，说明上游没有下发真实引用原文；OpenClaw 会把该占位文本带入上下文，但无法恢复企业微信未提供的原始内容。\n- 如果你之前观察到长回复在企业微信里呈现为“分段断裂”或“后段覆盖前段”，升级后会改为同一条流式消息持续刷新完整内容。\n\nFile v2.9.4:changelog/v2.3.14.md\n\n# OpenClaw WeCom 插件 v2.3.14 变更简报\n\n> [!TIP]\n> **企业微信“协作文档”原生整合与长连接稳定性修复版本**：`v2.3.14` 将机器人的能力从“陪聊”正式拓展到了“办公协同”。现在，你可以直接在微信群里让机器人去填报销单、建项目表；同时我们也彻底修复了多人并发聊天时机器人“正在思考”卡死刷屏的问题。\n>\n> 📣 **特别感谢** [@proyy](https://github.com/proyy) 提供的企业微信文档管理解决方案，使本版本的 Docs 能力得以落地。\n\n## 重磅功能：把聊天直接变成企业文档（用后即得）\n\n我们受够了问 AI 一个问题，答案最后只能被新消息顶没。这次更新，我们让机器人获得了操作“企业微信协作文档”的实体权限。\n\n### 场景 1：开新项目，不用再求人建表格拉权限了\n- **以前**：你在群里说“准备一下下周的活动追踪表”，然后得切出去打开文档中心，新建表格，再一个个抄名字把大家拉进来。\n- **现在**：直接在群里 `@机器人 帮我建一个名为『春季新品发布会追踪』的表格，并把群里的人都加上可写权限`。机器人建好后会直接在群里甩出一个链接，所有人点开就能直接编辑，全程零切换。\n\n### 场景 2：坐在地铁上，照样神操作填报销/跟进数据\n- **以前**：你刚下班，群里有人问“今天 C 组的面试谁通过了？”你只能回答“我等下回家用电脑打开「面试记录表」改一下状态”。全量改动很容易把别人的同行数据覆盖掉。\n- **现在**：你可以直接发语音或者敲字 `@机器人 把「第二周面试记录表」里的 B2 到 B5 单元格全部更新为“二面通过”`。机器人会像操作手术刀一样，只精准替换指定的数据块（`spreadsheet.edit_data`），丝毫不影响文档里的其他公式。\n\n### 场景 3：直接让 AI 读懂全公司的数据报表\n- **以前**：你要先自己把表格下载成 Excel，再一段段复制数据发给大模型：“帮我算算这堆数据谁最高”。\n- **现在**：你直接丢给他一个企微文档链接：`@机器人 分析一下这张表里的第一季度数据，告诉我谁的单产最差？`。由于具备了原生读取能力（`get_sheet_range_data`），它会自己去拉取数据查表，给你输出结论。\n\n## 💡 Docs 权限配置指引（只需一次）\n\n为了让上述场景跑通，光配 `agentSecret` 是不够的。这是因为哪怕是公司自建的机器人，默认也没资格动你们内部的文档资产。你需要：\n1. **去企微后台发“通行证”**：进入 [企业微信后台 -> 协作 -> 文档 -> 可调用接口的应用](https://work.weixin.qq.com/wework_admin/frame#apps/qykit/proxy/wedoc)，把你的机器人应用放进白名单。\n2. **在 OpenClaw 里激活能力**：打开 UI 界面 的 `Settings` -> `Agents` -> `Tools`，找到 `wecom`，把带有 `doc` 字眼的所有工具（创建文档、读取表格、改权限等）通通打勾。\n\n\n## 核心修复：终结“正在思考...”刷屏噩梦\n除了新功能，这次我们也彻底对长连接（WS）卡死问题做了一次大手术：\n- 🛑 **告别并发刷屏**：群里人多手杂的时候，以前机器人如果处理不过来，不仅不回话，还会满屏一直弹“正在思考...”。现在只要有一条真回复发出来，它会自动把同群里那些卡死、过期的“正在思考”全部瞬间清理干净。\n- 📡 **进群欢迎语报错 846605 终结**：修复了大家常反馈的“有人一进群，后台就疯狂报 invalid req_id”的陈年老 Bug。现在对进群、推卡片等非聊天事件，我们全面切换成了专属接口，彻底避免违规流式推送。\n- 🛡 **120 秒物理断网**：即使模型源站点挂了，我们现在也会在 120 秒内强制熔断提示，绝不让你面对一个无限转圈的加载框。\n\n---\n## 验证结果\n- `pnpm test -- src/transport/bot-ws`\n- 所有 WS 回复通道单测已全部通过，尤其是关于 `setInterval` 占位符存活期的验证得到了补全与修复。\n\n## 升级指引\n```bash\nopenclaw plugins update wecom\n```\n- 无需新增配置，执行上述命令即可一键升级到 `v2.3.14`。\n- 升级后，如果你拉几十个机器人进群并同时发言，曾经那种满屏飘“正在思考...”却无人回答的乱象将不复存在。\n- 如果之前查看后台日志总是看到 `stream message update expired (>6 minutes)` 甚至因为连带引发的 WS 断网重启，本次升级将大幅度平息日志告警红字，稳定长连接状态。\n\nFile v2.9.4:changelog/v2.3.15.md\n\n# OpenClaw WeCom 插件 v2.3.15 变更简报\n\n> [!TIP]\n> **企业微信文档写入稳定性与消息目标路由修复版本**：`v2.3.15` 重点解决了企微文档 `init_content` 初始化内容写入不稳定、图片插入失败、批量更新索引错误，以及群聊回复时容易触发的 `81013` 目标解析错误。同时，这次也补回并完善了文档、在线表格、智能表格、收集表等能力，避免相关工具调用缺接口或直接失败。\n\n## 2026-03-14（v2.3.15）\n- 【文档初始化内容修复】🛠 **[重要修复]** 创建企微文档时，`init_content` 现在会按官方 Wedoc 流程执行：图片先上传再插入，文本与图片段落会基于最新索引和版本号写入，减少标题正文错位、图片不显示、内容插到错误位置的问题。\n- 【批量更新稳定性修复】📄 **[重要修复]** 修复 `document.batch_update` 的索引计算与模式切换问题。混合执行 `insert_paragraph`、`insert_text`、`insert_image` 时，不再更容易触发 `ParagraphValidator`、`TextValidator`、`DrawingValidator` 一类报错。\n- 【文档客户端能力恢复】🔧 重新补齐此前精简时误删的企微文档客户端接口，恢复文档权限、在线表格、智能表格、收集表等相关方法，避免工具层调用缺方法、返回异常或直接不可用。\n- 【在线表格与收集表支持补齐】📊 完善企微在线表格和收集表的类型定义、参数校验与错误提示。现在会更早拦截超出 API 限制的请求，例如表格行列/单元格数量超限、收集表题目结构缺失、选项题参数不完整等问题。\n- 【群聊目标解析修复】💬 **[重要修复]** 修复企业微信群聊回复时 `To` 字段被错误硬编码为用户目标的问题。群聊、私聊、部门、标签目标现在会按正确前缀解析，减少发送时报 `81013 user & party & tag all invalid` 的情况。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.15`。\n- 如果你之前遇到“建文档成功但内容没写进去”“图片插不进去”“批量更新偶发报索引错误”或“群里回复机器人时报 81013”，本次升级后会明显改善。\n\nFile v2.9.4:changelog/v2.3.16.md\n\n# OpenClaw WeCom 插件 v2.3.16 变更简报\n\n> [!TIP]\n> **企业微信 Bot-WS 混合消息附件解析修复版本**：`v2.3.16` 重点解决了在 WebSocket 模式下，企业微信机器人接收到的混合消息（如同时包含图片和文字）由于解析遗漏导致附件丢失、AI 只能看到带签名的临时链接文本而无法查看真正图片内容的问题。\n\n## 2026-03-16（v2.3.16）\n- 【混合消息媒体解析修复】🛠 **[重要修复]** 补齐了 Bot WebSocket 传输通道（`bot-ws`）下对 `mixed` 结构消息的附件提取逻辑。现在，当用户在企微发出一条包含图片/文件与文字的混合消息时，底层框架会自动遍历并提取各个媒体节点的 URL 和 AES Key，确保核心处理管线能进行正常下载与安全解密。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.16`。\n- 如果你之前在企微发出“带图的一段话”时，曾遇到 AI 回复说“这是一个腾讯 COS 的临时签名链接”，本次升级后，此问题将被修复，AI 将可以直接分析图片内容本身。\n\nFile v2.9.4:changelog/v2.3.18.md\n\n# OpenClaw WeCom 插件 v2.3.18 变更简报\n\n> [!TIP]\n> **企业微信面向中小企业的新能力开放版本**：`v2.3.18` 重点完善了 `wecom` 插件在 Bot WebSocket 场景下的能力层。现在，面向 5 人及以下小企业，OpenClaw 已支持以用户个人身份在企业微信内使用文档读写、日程读写、会议读写、待办读写、通讯录查询等能力。同时，本次也补齐了 Bot WS 媒体发送、建立了 Bot 与 Agent 双平面路由，并修复了企业微信里容易卡在“正在思考...”不结束的问题。\n\n## 2026-03-18（v2.3.18）\n- 【中小企业能力开放】🚀 **[重大更新]** 面向 5 人及以下小企业，OpenClaw 在企业微信内正式开放以用户个人身份使用的协作能力入口。现在，大模型可以在具备相应授权的前提下，调用企业微信文档读写、日程读写、会议读写、待办读写以及通讯录查询等能力，把原本分散在多个协作入口中的企业操作集中到同一条智能对话链路中。\n- 【新增 Bot WS MCP 工具层】新增 `wecom_mcp` 工具，将企业微信 Bot WS 能力以挂载式能力层接入 `wecom` 插件。现在 Bot 侧可以按业务类别动态获取 MCP 配置，并把企业微信开放的能力暴露给大模型调用。\n- 【建立 Bot / Agent 双平面路由】新增基于会话来源的能力分流。Bot WS 会话优先使用 `wecom_mcp`；Agent 回调会话继续保留原生 `wecom_doc`、`wecom_calendar` 工具链，避免不同能力面互相干扰。\n- 【多账号能力隔离加强】MCP 相关缓存和状态改为按 `accountId + category` 隔离。在多账号矩阵下，同一类能力不会再共用同一份 Bot 侧配置，减少串账号、串上下文、串连接状态的问题。\n- 【补齐 Bot WS 命令与媒体链】扩展 Bot WS 运行时接口，除了主动文本发送外，现在还支持命令桥接、连接状态探测和媒体发送。Bot WebSocket 会话下的图片、文件回复不再必须依赖 Agent API 补送。\n- 【新增媒体发送提示注入】在企业微信 Bot WS 会话里定向注入 `MEDIA:` 使用提示，帮助模型更稳定地触发图片和文件回复，同时避免把这类提示扩散到非 WeCom 或 Agent 会话。\n- 【修复回复流不收口问题】**[重要修复]** 处理 Bot WS 回复时，带媒体的中间块不再错误中断文本发送。现在文本会先正常下发，媒体在结束阶段继续处理；如果上游没有显式 final，系统也会自动补一个收口帧，避免企业微信里长期停留在“正在思考...”。\n- 【欢迎语路径提速】`enter_chat` 欢迎事件在配置静态欢迎语时改为直发，不再额外启动完整推理流程。首次进入会话时的响应更直接，链路也更短。\n- 【运行时日志增强】新增更细的派发与投递日志，包括 `dispatch-start`、`dispatch-done`、`dispatch-fail`、`deliver-start`、`deliver-done`。现在排查问题时可以更快区分是模型处理慢、回复已被企微确认、MCP 类别未开通，还是本地媒体路径被限制拦截。\n- 【能力边界提示更明确】当企业微信后台只开放部分能力时，插件会更明确地把限制反馈给用户和日志。例如只开通文档类能力时，待办、会议、日程类请求会直接提示当前账号尚未开放对应能力，而不是表现成模糊失败。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.18`。\n- 本次版本是企业微信能力面的重要开放版本，尤其适合希望在企业微信内直接完成文档、日程、会议、待办与通讯录协作的小型团队。\n- 如果你之前在企业微信 Bot WS 会话里只看到反复“正在思考...”、最终不出结果，本次升级后应已修复。\n- 如果你希望在企业微信里直接使用会议、待办、日程等 Bot 侧能力，请同时确认企业微信后台已经为当前 Bot 开通相应业务类别；插件侧已经具备调用链，但实际可用范围仍以企业微信侧授权为准。\n\nArchive v2.9.2: 244 files, 504065 bytes\n\nFiles: changelog/v2.2.28.md (3745b), changelog/v2.3.10.md (1572b), changelog/v2.3.11.md (1837b), changelog/v2.3.12.md (3259b), changelog/v2.3.13.md (2018b), changelog/v2.3.14.md (4670b), changelog/v2.3.15.md (2241b), changelog/v2.3.16.md (1113b), changelog/v2.3.18.md (4080b), changelog/v2.3.19.md (6771b), changelog/v2.3.2.md (2795b), changelog/v2.3.26.md (1830b), changelog/v2.3.27.md (4345b), changelog/v2.3.273.md (680b), changelog/v2.3.4.md (1755b), changelog/v2.3.9.md (1711b), changelog/v2.4.12.md (4707b), changelog/v2.4.16.md (1157b), changelog/v2.7.4.md (2724b), changelog/v2.8.0.md (3687b), changelog/v2.8.1.md (2230b), changelog/v2.8.17.md (7630b), changelog/v2.8.18.md (3377b), changelog/v2.8.19.md (5692b), changelog/v2.8.2.md (2496b), changelog/v2.8.20.md (7103b), changelog/v2.8.21.md (8625b), changelog/v2.8.22.md (6594b), changelog/v2.8.23.md (6868b), changelog/v2.8.24.md (7061b), changelog/v2.8.25.md (5291b), changelog/v2.8.26.md (6532b), changelog/v2.8.27.md (5994b), changelog/v2.8.28.md (3728b), changelog/v2.8.29.md (4665b), changelog/v2.8.3.md (3447b), changelog/v2.8.30.md (4967b), changelog/v2.8.31.md (6539b), changelog/v2.8.32.md (1368b), changelog/v2.8.6.md (3301b), changelog/v2.8.8.md (5098b), changelog/v2.9.0.md (6833b), changelog/v2.9.1.md (2771b), changelog/v2.9.2.md (3292b), compat-single-account.md (4135b), GOVERNANCE.md (1301b), index.test.ts (1058b), index.ts (5408b), openclaw.plugin.json (11593b), package.json (2717b), README.md (31424b), scripts/release.sh (11536b), scripts/test-proxy.ts (2377b), SKILL.md (4871b), SKILLS_CAL.md (29478b), SKILLS_DOC.md (70311b), src/accounts.ts (1223b), src/agent/api-client.upload.test.ts (3909b), src/agent/handler.event-filter.test.ts (3469b), src/agent/handler.ts (39593b), src/agent/index.ts (248b), src/app/account-runtime.ts (11247b), src/app/bootstrap.ts (890b), src/app/index.ts (6075b), src/capability/agent/delivery-service.ts (4475b), src/capability/agent/fallback-policy.ts (484b), src/capability/agent/index.ts (221b), src/capability/agent/ingress-service.ts (1126b), src/capability/agent/upstream-delivery-service.ts (3728b), src/capability/bot/dispatch-config.ts (1854b), src/capability/bot/fallback-delivery.ts (6892b), src/capability/bot/index.ts (58b), src/capability/bot/local-path-delivery.ts (8059b), src/capability/bot/sandbox-media.test.ts (7025b), src/capability/bot/sandbox-media.ts (5688b), src/capability/bot/service.ts (1651b), src/capability/bot/stream-delivery.ts (16654b), src/capability/bot/stream-finalizer.ts (5769b), src/capability/bot/stream-orchestrator.ts (16350b), src/capability/bot/types.ts (352b)\n\nFile v2.9.2:SKILL.md\n\n---\nname: huo15-wecom\ndescription: \"火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担心 stream 截断 + 86008 把链接设为优先，v2.8.23/v2.8.24 修了群聊主动推送通道 + UI 锁交互后 MEDIA: 路径稳定可靠，应用户偏好翻转：默认 MEDIA: 直发，仅大文件（> 企微上限）才走 enhance_share_file 链接。GUIDANCE 加决策表 + 用户偏好覆盖。继承 v2.8.24 placeholder timeout 解锁、v2.8.23 群聊主动推送、v2.8.20 MEDIA: parser。Use when: 接企业微信、给企微 Bot/自建应用接 OpenClaw、用微信客服收外部用户消息、需要图片/文件双向、跨账号切换。Do NOT use for 个人微信（不同协议）。\"\nversion: 2.9.2\nhomepage: https://cnb.cool/huo15/ai/huo15-wecom-plugin\nmetadata: { \"openclaw\": { \"emoji\": \"🦜\", \"requires\": { \"bins\": [] } } }\n---\n\n# 火一五企业微信插件\n\n`@huo15/wecom` 是 OpenClaw 的企业微信通道插件，fork 自 [yanhaidao/wecom](https://github.com/yanhaidao/wecom) 并持续合并上游。**默认 Bot WebSocket 模式**，配置简单、响应快；同时支持 Agent 自建应用主动推送和微信客服三方通道。\n\n## 三条消息通道\n\n| 通道 | 用途 | 配置入口 |\n|---|---|---|\n| **Bot WebSocket** | 默认推荐，企业微信\"智能机器人\"WS 协议，免公网回调 | `channels.wecom.accounts.<id>.bot.ws` |\n| **Agent 自建应用** | 走企微官方 API（CorpId/AgentId/Secret），支持主动推送给指定用户/群 | `channels.wecom.accounts.<id>.agent` |\n| **微信客服** | 接管\"客服会话\"，外部客户在微信/视频号里发给客服账号的消息 | `channels.wecom.accounts.<id>.kefu` |\n\n三条通道可以**单独启用**或**组合启用**，多账号场景每个账号独立配置。\n\n## 安装\n\n```bash\n# OpenClaw 内置安装（推荐）\nopenclaw plugins install @huo15/wecom\n\n# 或者直接 npm\nnpm install @huo15/wecom\n```\n\n## 最小配置（Bot WS 模式）\n\n```yaml\n# ~/.openclaw/openclaw.json 中\nchannels:\n  wecom:\n    enabled: true\n    accounts:\n      default:\n        bot:\n          ws:\n            botId: \"你的智能机器人 ID\"\n            secret: \"WS 密钥\"\n```\n\n启动后，Bot 收到的消息会自动路由到默认 Agent，回复也通过 WS 直接送回 — 不需要部署任何回调 endpoint。\n\n## 关键能力\n\n- **加密媒体解密**：图片/文件/语音 AES-256-CBC 解密直接拿 buffer，可让 Agent 直接读取（OCR / ASR / 文档解析）\n- **Markdown V2**：支持企微富文本（标题、表格、代码块、链接、引用），自动适配 chat 上下文\n- **图片回复**：`![alt](url)` 自动抽离 + uploadMedia + replyMedia，COS/OSS 预签名 URL 失败时降级为占位文本（不让\"链接已过期\"漏到客户端）\n- **多账号切换**：单实例支持多个企业、多个智能体并存，按 conversation 路由\n- **流式回复**：placeholder + partial replyStream（最多 8 次中间更新）+ ack timeout watchdog 自动重连\n\n## v2.8.8 关键修复（WS BOT 图片）\n\n1. **Reply 通道纠错**：reply 上下文从 `sendMediaMessage`（主动推送）改用 `replyMedia`（被动回复，绑定 reqId）\n2. **入向多图**：`mixed` 与 `quote.mixed` 类型从只取首张改为全部提取；首张挂 `ctx.MediaPath`，其余落盘 + info 日志\n3. **Outbound fetch UA**：从裸 `fetch` 切到 plugin-sdk `fetchRemoteMedia`，显式带 desktop User-Agent，避免部分 Tencent COS / 阿里 OSS bucket 拒绝 Node 默认 UA\n4. **解析可观测性**：媒体类型消息但无 attachments 时记 warn 日志（含 msgid + body keys），便于 SDK 字段漂移排查\n\n详见 [changelog/v2.8.8.md](./changelog/v2.8.8.md)。\n\n## 安全实践\n\n- LLM 输出的 `touser` / `chatid` 经 `resolveWecomTarget` sanitizer，**拒绝 `@all` / `@everyone` / `*` 等广播字面量**（v2.8.1 SECURITY 修复）\n- 跨企业上下游消息走 upstream-delivery 通道，不与本企业 Agent API 混用\n- 微信客服 `corpSecret` 可与 Agent `corpSecret` 独立配置，权限隔离\n\n## 不变的设计原则\n\n- **Bot WS 优先**：能用 WS 就不用 Agent API（少配置、低延迟）\n- **失败降级**：WS reply ack timeout 自动 fallback 到 Agent API（保留消息可达性），watchdog 连续 8 次后触发 WS 重连\n- **不修改 OpenClaw 核心**：所有功能通过 channel plugin SDK 注册\n\n## 仓库\n\n- 主仓库：https://cnb.cool/huo15/ai/huo15-wecom-plugin\n- 镜像：https://github.com/zhaobod1/huo15-wecom-plugin\n- 上游 fork 源：https://github.com/yanhaidao/wecom（**仅 fetch，不 push**）\n\n## License\n\nISC（继承自 yanhaidao/wecom 上游）。\n\nFile v2.9.2:README.md\n\n# OpenClaw 企业微信(WeCom)Channel 插件\n\n<p align=\"center\">\n  <a href=\"https://github.com/yanhaitao/wecom\"><img src=\"https://img.shields.io/badge/Original%20Project-逸寻智库-orange?style=for-the-badge&logo=github\" alt=\"Original Project\" /></a>\n  <img src=\"https://img.shields.io/badge/License-ISC-blue?style=for-the-badge\" alt=\"License\" />\n  <img src=\"https://img.shields.io/badge/Min%20Recommended-2.8.1+-red?style=for-the-badge\" alt=\"Minimum recommended\" />\n</p>\n\n> [!CAUTION]\n> **🛡️ 安全公告（2026-04-22）**：受影响版本 `<= 2.8.0`。Agent 在工作区写自定义脚本时可能把 `touser=\"@all\"` 当默认收件人，导致原本私聊的图片/视频/文档**被广播到企业微信应用可见范围全员**。\n>\n> **请所有部署立即升级到 `@huo15/wecom@2.8.1` 或以上**。修复见 [`changelog/v2.8.1.md`](changelog/v2.8.1.md)。\n\n> [!WARNING]\n> **原创声明**:本项目涉及的\"多账号隔离与矩阵路由架构\"、\"Bot+Agent双模融合架构\"、\"长任务超时接力逻辑\"及\"全自动媒体流转接\"等核心设计均为作者 **YanHaidao** 独立思考与实践的原创成果。\n> 欢迎技术交流与合规引用,但严禁任何不经授权的\"功能像素级抄袭\"或删除原作者署名的代码搬运行为。\n\n<p align=\"center\">\n  <strong>🚀 企业级多模式 AI 助手接入方案(统一运行时架构)</strong>\n</p>\n\n---\n\n## 💡 核心价值:为什么团队会真正选择这个插件?\n\n企业真正需要的,不是\"把一个模型接进企业微信\",而是让企业微信变成一个**能长期工作的 AI 协作入口**。\n\n大多数团队最终只关心五件事:\n\n- 能不能先低门槛接起来,而不是先做一轮重部署\n- 多人同时使用时,会不会串上下文、串身份、串会话\n- 长任务会不会因为长连接窗口太短而白跑\n- 能不能既有实时对话体验,又能做正式推送和稳定投递\n- AI 能不能真正进入文档、日程、会议、待办、通讯录这些协作层,而不只是停留在聊天框\n\n常见方案通常会很快碰到边界:\n\n- **只用 Bot WS**:接得快、聊得顺,但会受到单连接、心跳保活、会话边界和组织级广播能力的限制\n- **只用 Agent**:能力强、治理清晰,但部署门槛更高,对话体验不如 Bot WS 丝滑\n- **只选单一路径**:团队最后往往被迫在\"体验\"和\"能力\"之间二选一\n\n本插件的价值,就在于把这些原本互相冲突的目标,尽量同时成立。\n\n### 您真正会得到什么?\n\n1. **多人共用一个入口,但上下文不会串**\n   - **问题本质**:企业里真正难的不是\"接入一个机器人\",而是让几十上百个人同时使用时,仍然保持每个人的上下文隔离。\n   - **插件做法**:按 `(底层账号 + 部门/群组/人员)` 动态切分运行上下文和 Agent 实例。\n   - **用户收益**:同一个企业微信入口可以承接多人并发使用,而不会出现\"张三的问题让李四接上回答\"的串流灾难。\n\n2. **长任务不白跑,回复不轻易丢**\n   - **问题本质**:企业微信长连接的响应窗口很短,而推理模型的思考时间往往很长。\n   - **插件做法**:先保活,再流式推进;必要时走备用投递路径,把最终结果交付出去。\n   - **用户收益**:更敢把复杂任务、长文本分析、报告生成交给 AI,而不是每次都担心\"算完了却发不回来\"。\n\n3. **实时对话体验和正式投递能力,不用二选一**\n   - **问题本质**:实时聊天和组织级推送,往往不是同一条技术路径最擅长的事。\n   - **插件做法**:会话内实时交互、流式回复、异步追发优先走 `Bot WS`;组织级广播、冷启动触达、正式通知由 `Agent` 兜底。\n   - **用户收益**:日常使用时体验像聊天助手,正式落地时又有企业应用该有的稳定性和控制力。\n\n4. **AI 不只会聊天,还能进入企业微信协作层**\n   - **问题本质**:如果 AI 只能回消息,信息最终还是散落在聊天流里,业务并没有真正被推进。\n   - **插件做法**:把企业微信原生协作能力按两条能力平面接入 OpenClaw。\n   - **用户收益**:AI 不仅能回答问题,还能真正参与文档、日程、会议、待办和通讯录相关工作。\n\n5. **小团队能低门槛上手,大团队也能正式上线**\n   - **问题本质**:小团队怕折腾,大团队怕失控。\n   - **插件做法**:`Bot WS` 适合快速启用,`Agent` 适合正式治理,两者可以并存。\n   - **用户收益**:您不用在\"今天先跑起来\"和\"将来能不能正规化\"之间做破坏性迁移。\n\n---\n\n## 📊 为什么不是只选 Bot,或者只选 Agent?\n\n从用户视角看,差别不在于协议名词,而在于**你要解决的是什么问题**。\n\n| 你真正关心的事 | 🤖 Bot 模式 (WebSocket) | 🧩 Agent 模式 (自建应用 API) | ✨ 本插件的做法 |\n|:---|:---|:---|:---|\n| **先跑起来的速度** | ✅ 快,无需固定公网 IP | ❌ 较重,需要正式应用配置 | ✅ 先用 Bot 起步,后续平滑补 Agent |\n| **实时聊天体验** | ✅ 最强,天然适合低延迟和流式回复 | ⚠️ 能收能发,但不是最佳对话入口 | ✅ 默认把实时交互交给 Bot |\n| **异步结果回推** | ✅ 可以,适合已建立会话内追发 | ✅ 可以 | ✅ 会话内追发优先 Bot,必要时 Agent 兜底 |\n| **组织级广播与冷启动触达** | ⚠️ 受会话边界约束 | ✅ 更适合 | ✅ 正式通知和广播走 Agent |\n| **企业微信协作能力** | ✅ 适合个人身份能力入口 | ✅ 适合应用身份能力入口 | ✅ 两种身份平面都兼容 |\n| **适合谁** | 想快速上线、重视实时体验的团队 | 需要正式治理、自动化和组织级能力的团队 | 想同时要\"体验\"和\"能力\"的团队 |\n\n> **建议理解方式:**\n> - 如果您最在意的是\"先接起来、先用起来、先聊顺\",优先上 `Bot WS`\n> - 如果您最在意的是\"正式部署、组织级能力、自动化治理\",补齐 `Agent`\n> - 如果您真正想把 AI 在企业微信里长期用下去,最终往往需要两者并存\n\n---\n\n## 🧩 企业微信协作能力:为什么这件事比\"能聊天\"更重要?\n\n很多企业微信 AI 机器人,本质上只是把答案发回聊天框。\n真正有价值的,是让 AI 进入您**已经在工作的地方**。\n\n在本插件里,企业微信的**文档、日程、会议、待办、通讯录**等能力,不再只是外围说明,而是被接成了可以实际调用的协作平面。\n\n### 1. Bot WS 协作模式:适合小团队的个人身份入口\n\n根据企业微信最新开放说明,面向 **5 人及以下的小微企业**,`Bot WS` 模式现已开放以**用户个人身份**调用部分企业微信协作能力。\n\n在本插件里,这条链路以 `wecom_mcp` 的方式挂载,只在 **WeCom Bot WS 会话** 中可用:\n\n- 能力入口:`wecom_mcp`\n- 典型能力品类:`doc`、`meeting`、`todo`、`contact`\n- 触发条件:当前会话必须来自 `Bot WS`\n- 更适合的场景:个人身份读写文档、查询通讯录、处理待办、操作会议等轻量协作场景\n\n它的价值在于:\n\n- **门槛低**:无需先走完整的自建应用接入流程\n- **身份自然**:更贴近当前聊天用户自己的协作上下文\n- **启动快**:对小团队尤其友好\n\n它的边界也要明确:\n\n- 依赖 `Bot WS` 会话存在\n- 主动推送仍然以**已建立会话**为前提\n- 实际开放范围以企业微信后台可见权限为准\n\n### 2. Agent 协作模式:适合正式落地的应用身份入口\n\n`Agent` 模式走的是**自建应用 API** 平面,更适合企业级稳定自动化与组织级治理。\n\n在本插件里,当前内置的协作工具主要包括:\n\n- `wecom_doc`:文档、表格、权限、分享可用性诊断等\n- `wecom_calendar`:日历、日程、参与人、回执、默认日历等\n\n它更适合:\n\n- 把协作能力放进正式企业应用权限体系\n- 与定时任务、异步流程、正式投递联动\n- 面向组织对象做更稳定的自动化操作\n\n### 3. 这两条能力链在插件里已经实际接通\n\n当前插件已经把这两条协作链路都注册进来:\n\n- `wecom_mcp`:仅在 `Bot WS` 会话中暴露\n- `wecom_doc`:仅在 `Agent` 会话中暴露\n- `wecom_calendar`:仅在 `Agent` 会话中暴露\n\n也就是说,您拿到的不是\"一个只能聊天的企微插件\",而是:\n\n- 一条适合实时对话和个人协作的入口\n- 一条适合正式应用和组织自动化的入口\n\n### 4. 授权方式\n\n请按所选平面分别授权:\n\n- **Bot WS 模式授权**:前往企业微信管理后台 👉「工作台 - 智能机器人」,找到对应机器人,点击编辑,在「可使用权限」处勾选文档、日程、会议、待办、通讯录等对应权限。\n- **Agent 模式授权**:前往企业微信管理后台 👉「工作台 - 协作 - 文档 / 日程 / 会议等」,将您的自建应用加入\"可调用接口的应用\"。\n\n一句话理解:\n\n- **Bot WS** 更像\"当前聊天用户的实时协作入口\"\n- **Agent** 更像\"企业正式应用身份下的自动化执行入口\"\n\n两者同时配置后,您既能拿到顺滑的实时交互,也能拿到企业级可治理的协作能力。\n\n---\n\n## 📋 最近更新 (Changelog摘要)\n\n> 项目保持高频迭代,全面对齐甚至超越企业真实业务诉求。\n> **为保持精简,以下仅展示近期 5 次重要更新,完整历史版本(含全部 `v2.2.x`)请前往 [changelog/ 目录](./changelog/) 查阅。**\n\n#### 📌 v2.8.0(2026-04-22)\n- **[能力扩充] 微信客服(kefu)全通道落地** 🆕 Agent/Bot 之外,新增“企业微信客服”作为第三条消息通道:外部客户在微信、视频号、对外小程序里发给客服号的消息可直接走到 OpenClaw 里回复。配置独立(`channels.wecom.accounts.<id>.kefu.{corpId,corpSecret,openKfIds,webhook}`),`corpSecret` 允许与 Agent 分开建一套“只给客服用”的 Secret。\n- **[通道独立] 回调路径解耦** 🛣️ 客服挂载到独立路径 `/plugins/wecom/kefu`(推荐)或 `/plugins/wecom/kefu/<accountId>`,与 Bot / Agent 路径互不冲突。企微客服回调只携带 Token,插件内部调用 `kf/sync_msg` 按 `open_kfid` 维度维护 cursor 完整拉取,配合 LRU `msgid` 去重与 in-flight 并发守卫,确保消息不重、不漏。\n- **[入向覆盖] 10 类消息全量归一** 📥 text/image/voice/video/file/link/miniprogram/msgmenu/location/business_card/event(含 `enter_session` 映射成 `welcome`)均已 normalize 成 `UnifiedInboundEvent`,下游 Agent 无感消费。\n- **[出向能力] send_msg 一体化** 📤 text 按 3500 字符切片避开 4096 字节上限、media 由 content-type+扩展名分类分别走 image/voice/video/file,link 走 `payload.channelData.kefu.link` 专用卡片,统一走 `upload_media` 拿 `media_id` 后下发。新增 `toKefuText` 把 markdown 扁平成 kefu `content` 能识别的纯文本(保留代码块/链接/列表项标识,剔除标题/粗体/HTML 等)。\n- **[会话自动路由] Source Registry 扩展** 🔁 `WecomSourcePlane` 新增 `\"kefu\"`,入向会记录 `kefuOpenKfId`;下一轮 Agent 主动回复时会自动走客服出向,不会误发到 Agent 内部私信。显式目标 `wecom-kefu:<accountId>:<openKfId>:<externalUserId>` 同样支持。\n\n#### 📌 v2.7.3(2026-04-21)\n- **[格式升级] 全线切换到 `markdown_v2`** 🎨 自建应用(Agent API) / 群机器人(Bot WS) / 主动回复(Bot Webhook response_url)全部改用企微 2026 年新的 `markdown_v2` 消息类型,**原生支持 markdown 表格、图片 `![](url)`、粗体、链接、代码块、嵌套引用、列表**,消息上限从 2048 字节提到 4096 字节。\n- **[逻辑简化] 移除 textcard 降级路径** 🧹 以前遇到表格/大标题/链接会被\"降级\"成 textcard(title + 512 字纯文本描述,丢失 markdown 格式),现在统一走 markdown_v2,富文本完整渲染,不再需要 textcard workaround。\n- **[兼容注意]** ⚠️ markdown_v2 不支持 `<font color>` 标签和 `@userid` 群成员 at(原 markdown 支持),如果你依赖这两个特性请用 text 消息或保留 v1。本插件 adapter 本来就不生成这两个语法,用户无感。\n\n#### 📌 v2.7.2(2026-04-21)\n- **[Bug 修复] 引用群文件显示\"COS链接过期\"** 🔧 同步上游引用文件处理逻辑,新增 `channels.wecom.media.downloadTimeoutMs` 配置(默认 30s),分级区分超时/5 分钟 TTL 过期/网络错误,避免大文件抓取失败。\n- **[Bug 修复] 安装插件被安全扫描拦截** 🔒 移除上游已回滚的 `src/agent/script-runner.ts`(使用了 `child_process.spawn`),不再触发 OpenClaw 的 `dangerous-exec` 规则,v2.7.2 可以直接通过 `npm` 或 `clawhub` 方式安装。\n- **[上游同步] 合并 yanhaidao/wecom 至 c1158a9** 📦 包含引用附件在群聊/私聊中透传、媒体下载超时配置、菜单事件文档等;同时吸收上游对 jjjkkil 两次 agentcation PR 的 revert。\n- **[版本对齐] 保留 `@huo15/wecom` 独立包名** 📦 包名保持 `@huo15/wecom`,版本号跳至 `2.7.2`。\n\n#### 📌 v2.3.273(2026-03-31)\n- **[重要修复] WS 断连 Fallback** 🔧 耗时任务/Gateway 重启/WS 断线重连时,Bot WS 自动切换到 Agent API 发送回复,不再出现\"机器人没反应\"的问题。\n- **[markdown 修复] 表格和代码块渲染恢复** 📦 从 main 分支合并,表格不再强制转为纯文本,保留 markdown 格式。\n- **[包名变更] `@yanhaidao/wecom` 更名为 `@huo15/wecom`** 📦 npm 包名已更新。\n\n#### 📌 v2.3.27(2026-03-27)\n- **[重要修复] `channel add` 重新支持 WeCom guided setup** 🧭 之前有些环境下,`wecom` 虽然已经安装,却仍会在 OpenClaw 里显示成 \"does not support guided setup yet\",导致无法直接通过交互式向导添加。现在插件已经对齐 OpenClaw 当前的 `setupWizard` 接口,`openclaw channels add` 会重新正常识别和进入配置流程。\n- **[重要修复] 修复 `installedCatalogById is not defined`** 🔧 部分用户在渠道添加或选择阶段会直接遇到 `ReferenceError: installedCatalogById is not defined`,表现上像是\"选了渠道就报错\"或\"添加流程突然失效\"。这一版已经修复对应的目录访问逻辑,添加流程恢复稳定。\n- **[升级兼容] 清理 OpenClaw 新版下失效的 SDK 旧入口** 📦 这次同步迁移了 `wecom` 插件里几处已经不再建议继续从 `openclaw/plugin-sdk` 根入口直接拿的旧接口,重点覆盖工具上下文、outbound 适配器和 Bot WS 媒体发送链路,升级 OpenClaw 后更不容易再出现\"有的地方能跑、有的地方直接炸\"的兼容问题。\n\n#### 📌 v2.3.26(2026-03-26)\n- **[重要修复] 升级 OpenClaw 后不再乱报错** 🔧 修复了新版 OpenClaw 下 `wecom` 插件容易出现的 `is not a function` 一类启动/运行错误。\n- **[回复更稳] Agent 和 Bot WS 不再乱串** ↔️ 现在是谁收到消息,就尽量由谁来回复,不再容易出现\"在 Agent 里说话,结果 Bot WS 回你\"的情况。\n- **[体验修复] Bot WS 发图后不再多冒一条 `Done...`** 🖼 之前常见表现是:`正在思考` -> 图片 -> 又多一条完成提示。现在最终收尾会尽量接回原来的回复链路。\n- **[占位符修复] 不会一直卡在\"正在思考...\"** ⏳ 如果图片或文本已经发出去了,占位符会更自然地结束,不会继续无意义地刷屏。\n\n#### 📌 v2.3.19(2026-03-19)\n- **[重要修复] Bot WS 现在也真正走 `dynamicAgents`** 🧭 之前同样开启动态路由时,不同消息链路的行为并不完全一致:Webhook / Agent 能按用户、群聊隔离,Bot WebSocket 却可能重新落回主 Agent。现在 WS 运行时也执行同样的动态路由逻辑,会话隔离终于统一了。\n- **[配置统一] 媒体大小开始优先跟随 OpenClaw 标准 `mediaMaxMb`** 📦 之前 WeCom 插件更偏向读取自己的 `media.maxBytes`,用户改了 OpenClaw 主配置却可能感觉\"改了没生效\"。现在插件优先支持 `channels.wecom.mediaMaxMb`,并支持 `channels.wecom.accounts.<accountId>.mediaMaxMb` 做账号级覆盖;旧配置仍兼容,但只作为兜底。\n- **[体验修复] 常见本地目录文件现在更符合直觉地可发送** 🖼 过去本地媒体白名单更偏向 OpenClaw 自己目录,导致像 `Downloads`、`Desktop`、`Pictures` 里的图片明明存在,却常被拦下。现在插件默认额外放行这些常见用户目录,同时保留 `channels.wecom.media.localRoots` 继续追加共享盘、挂载盘和业务目录。\n\n#### 📌 v2.3.18(2026-03-18)\n- **[重大升级] 双平面能力融合(Bot WS + MCP 强化)** 🚀 独家引入挂载式的 MCP 能力层。在保留原生 Agent 强力工具的同时,将官方新开放的企业微信能力暴露给大模型。现在,大模型可凭用户身份读写待办、日程、查通讯录。\n- **[多账号硬隔离]** 彻底重构 MCP 缓存池实现 `accountId + category` 的二次硬维隔离,无论您的矩阵挂载了多少家企业的助手,上下文及鉴权缓存绝不会交叉重叠。\n- **[媒体通道重构]** 补齐 Bot WS 本地的媒体上传链,同时设立了严格的 `5秒熔断机制`,若 WebSocket 长通道大文件卡死将无感静默降级到 Agent 私信发送。\n\n*(查看更早期关于\"超时熔断代投、动态扩容矩阵\"等功能的更新日志，请移步 [changelog/ 目录](./changelog/))*\n\n---\n\n## 一、🚀 快速开始\n\n> 推荐统一使用**多账号矩阵模型**。\n> 即使您的企业只接入了一个账号,也强烈建议将其配入 `channels.wecom.accounts.default` 节点下。\n\n### 1.1 插件安装\n\n```bash\nopenclaw plugins install @yanhaidao/wecom\nopenclaw plugins enable wecom\n```\n\n### 1.2 互动向导式初配 (适合个人开发者与极客)\n\n如果您不想手写繁杂的 JSON 配置文件,可以通过交互式向导快速完成最轻量的 WebSocket 长连接部署。`v2.3.27` 起,`wecom` 已重新对齐 OpenClaw 当前的 guided setup 流程,`openclaw channels add` 可以直接识别并进入配置:\n\n1. 确保已启用本插件。\n2. 在终端运行添加渠道指令:\n   ```bash\n   openclaw channels add\n   ```\n3. 选择下拉列表中第一顺位的:**企业微信 (WeCom)**\n4. 根据终端亮色指引,填入企微机器人对应的 `Bot ID` 及 `Secret`,机器人即可完成握手并进入可用状态。\n\n> **如果您最近刚升级 OpenClaw:**\n> - 若之前在添加渠道时看到 `wecom does not support guided setup yet`,请更新到当前版本后重试。\n> - 若之前在渠道添加阶段见过 `ReferenceError: installedCatalogById is not defined`,这一版也已一并修复。\n\n### 1.3 生产环境顶配架构示范(Bot WS 流式交互 + Agent 私有通道兜底发送)\n\n如果您的目标不是\"接进来能聊两句\",而是让团队在企业微信里长期稳定使用 AI,这套组合更接近生产环境的推荐形态:\n\n- `Bot WS` 负责实时对话、低延迟流式回复和更轻的接入门槛\n- `Agent` 负责主动推送、媒体发送和长任务后的兜底交付\n- `dynamicAgents` 负责把不同用户、不同群聊的会话真正隔离开,避免多人共用一个入口时互相串上下文\n\n请进入 OpenClaw 配置文件(`openclaw.json`)的 `channels.wecom` 内使用:\n\n```jsonc\n{\n  \"channels\": {\n    \"wecom\": {\n      \"enabled\": true,\n      \"defaultAccount\": \"default\",\n      \"accounts\": {\n        \"default\": {\n          \"enabled\": true,\n          \"name\": \"企微销售二部支持中枢\",\n          \"bot\": {\n            \"primaryTransport\": \"ws\",             // 指定 Bot 主通讯协议:ws 或 webhook\n            \"streamPlaceholderContent\": \"正在深思熟虑,请稍候...\", // 避免流式回复开始前长时间无反馈\n            \"welcomeText\": \"你好,我是已连网的专属大脑。\",\n            \"dm\": {\n              \"policy\": \"pairing\",\n              \"allowFrom\": []\n            },\n            \"ws\": {                               // Bot WS 建连所需凭证\n              \"botId\": \"YOUR_BOT_ID\",\n              \"secret\": \"YOUR_BOT_SECRET\"\n            }\n          },\n          \"agent\": {                              // 主动推送、媒体发送与兜底交付链路\n            \"corpId\": \"YOUR_CORP_ID\",\n            \"agentSecret\": \"YOUR_AGENT_SECRET\",\n            \"agentId\": 1000001,\n            \"token\": \"AGENT_TOKEN\",\n            \"encodingAESKey\": \"AGENT_AES_KEY\",\n            \"welcomeText\": \"若长连接断开,我将使用此通道传递残存报告。\",\n            \"dm\": {\n              \"policy\": \"open\",\n              \"allowFrom\": []\n            }\n          }\n        }\n      },\n      \"mediaMaxMb\": 50,                           // 优先使用 OpenClaw 标准媒体上限配置\n      \"media\": {\n        \"tempDir\": \"/tmp/openclaw-wecom-media\",\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\"\n        ]\n      },\n      \"network\": {                                // 内网或受限网络环境可通过代理出网\n        \"egressProxyUrl\": \"http://127.0.0.1:3128\"\n      },\n      \"dynamicAgents\": {                          // 为单聊/群聊创建独立路由,减少多人串上下文\n        \"enabled\": true,\n        \"dmCreateAgent\": true,\n        \"groupEnabled\": true,\n        \"adminUsers\": [\"zhangsan001\"]             // 管理员绕过动态路由,直连主 Agent\n      }\n    }\n  }\n}\n```\n\n其中:\n\n- 插件现在默认额外放行常见用户目录:`~/Desktop`、`~/Documents`、`~/Downloads`、`~/Movies`、`~/Pictures`。\n- `channels.wecom.mediaMaxMb` 是首选的媒体大小上限配置,`channels.wecom.accounts.<id>.mediaMaxMb` 可以做账号级覆盖。\n- `channels.wecom.media.localRoots` 用于继续追加你自己的全局目录,例如共享盘、挂载盘或业务导出目录。\n- 旧的 `channels.wecom.media.maxBytes` 仍然兼容,但仅作为向后兼容兜底;新配置建议统一改成 `mediaMaxMb`。\n- 这些目录会和 OpenClaw 默认允许的媒体目录一起生效,不会覆盖默认白名单。\n- 也就是说,像 `~/Downloads/01.png` 这类本机文件现在默认就可以直接发到企微,不需要再单独配置。\n\n> **注意:** 历史配置里的 `agent.corpSecret` 引擎依然能够向后兼容拾起,但后续的新项目推荐采用标准的 `agentSecret` 作为对齐键。\n\n### 1.4 dynamicAgents 详细说明:为什么生产环境建议开启\n\n`dynamicAgents` 的核心价值,不是\"自动创建很多 Agent\",而是让企业微信里的每个用户、每个群聊都拥有稳定、独立的会话落点。\n如果不开它,所有消息更容易汇入同一个主 Agent;一旦开始多人共用,最先出问题的通常不是模型能力,而是上下文、长期记忆和处理边界混在一起。\n\n更简单地看,可以直接按下面这张表决定要不要开:\n\n| 场景 | 不开时的问题 | 建议配置 | 你得到的结果 |\n|---|---|---|---|\n| 多个同事同时私聊同一个机器人 | 容易共用同一条会话脉络,长期上下文可能互相污染 | `enabled=true` + `dmCreateAgent=true` | 每个人都有自己的稳定上下文 |\n| 一个或多个群长期拿机器人协作 | 不同群更容易共用主 Agent,群与群之间边界不清晰 | `enabled=true` + `groupEnabled=true` | 每个群都有独立会话空间 |\n| 管理员需要统一测试、巡检、接管 | 管理员也会被切进自己的动态 Agent,排障更分散 | `adminUsers=[\"管理员userid\"]` | 管理账号继续直连主 Agent |\n| 只是做 PoC 或单人试用 | 一上来就启用隔离,理解成本偏高 | `enabled=false` | 先把连通性和基础回复跑通 |\n\n系统当前的真实行为如下:\n\n- 开启后,会按 `账号 + 会话类型 + 对端 ID` 生成确定性的 Agent ID,例如 `wecom-default-dm-zhangsan` 或 `wecom-default-group-wr123456`\n- 同一个用户或同一个群,下次再发消息时会继续命中同一个动态 Agent,而不是临时随机分配\n- 首次命中时,插件会自动把这个动态 Agent 追加到 `agents.list`,不需要您手工维护一长串列表\n- 这套逻辑同时作用于 `Bot WS` 和 `Agent Callback` 两条主消息链路,不是只有某一种模式才生效\n- `adminUsers` 中的账号会始终绕过动态路由,直接走主 Agent,适合放管理员、运营或排障账号\n- 默认值是 `enabled=false`、`dmCreateAgent=true`、`groupEnabled=true`、`adminUsers=[]`,也就是不开总开关时不会生效,但一旦开启,单聊和群聊会默认一起进入隔离模式\n\n需要注意的是,`dynamicAgents` 解决的是\"路由隔离\"和\"会话隔离\",不是权限系统本身。\n也就是说,它能显著减少上下文串线,但账号是否允许私聊、谁能触发命令、某个账号绑定到哪个主 Agent,仍然要结合 `dm.policy`、`bindings` 和企业微信授权配置一起看。\n\n### 1.5 `localRoots` 详细说明:为什么\"文件明明存在\",系统却仍然不发\n\n`localRoots` 只决定一件事:**这个本地路径允不允许被当作可发送媒体读取。**\n\n| 现象 | 实际含义 |\n|---|---|\n| 文件存在,但发送失败 | 不代表系统允许读取它 |\n| 日志出现 `Local media path is not under an allowed directory` | 路径不在白名单里 |\n| 远程 `https://...` 媒体可以发 | 远程 URL 不走 `localRoots` |\n\n默认已经额外放行这些目录:\n\n| 默认允许目录 | 用途 |\n|---|---|\n| `~/Desktop` | 桌面文件、临时截图 |\n| `~/Documents` | 文档导出目录 |\n| `~/Downloads` | 下载图片、下载文件 |\n| `~/Movies` | 视频文件 |\n| `~/Pictures` | 图片、相册导出 |\n\n另外也保留 OpenClaw 自己的 `tmp / state / workspace` 相关目录。\n\n如果文件不在默认目录里,再补 `localRoots`:\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"media\": {\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\",\n          \"/mnt/nas/public\"\n        ]\n      }\n    }\n  }\n}\n```\n\n配置规则:\n\n| 规则 | 说明 |\n|---|---|\n| `localRoots` 是追加 | 不会覆盖默认目录 |\n| 建议写绝对路径 | 团队环境更稳定、更清楚 |\n| 只加业务需要的目录 | 不要为了省事把范围放太大 |\n| 不建议放整个大盘或整个用户目录 | 会把本地文件读取边界放得过宽 |\n\n排障判断:\n\n| 问题类型 | 看什么 |\n|---|---|\n| 本地路径是否允许读取 | `localRoots` |\n| 媒体能处理多大 | `channels.wecom.mediaMaxMb` |\n| 企业微信最终能不能收 | 企业微信自身媒体限制 |\n| 远程媒体能不能发 | URL 可访问性,不看 `localRoots` |\n\n一句话:`localRoots` 管\"能不能读这个本地路径\",`mediaMaxMb` 管\"最多读多大\"。\n\n---\n\n## 二、🏢 企业微信后台回调挂载指南 (针对使用了 Webhook 或 Agent Callback 的重度用户)\n\n如果您需要让 Agent 通道接收复杂的地理位置及交互式卡片事件,需要将系统的路径下发到企业微信管理后台。\n由于系统默认采纳**多账号分流路径派生**,请切记不要随意丢弃末尾的 `{accountId}`,如下所示:\n\n| 类型 | 您的 OpenClaw 可信域名 | 默认账号路由锚点 | 如果配置了 Ops 项目组子账号 |\n|---|---|---|---|\n| **Bot Webhook** | `https://x.com` | `/plugins/wecom/bot/default` | `/plugins/wecom/bot/ops` |\n| **Agent Callback** | `https://x.com` | `/plugins/wecom/agent/default`| `/plugins/wecom/agent/ops` |\n\n*警告:极度不推荐将老旧单一根路径(如 `/plugins/wecom/bot`)在未指定账户空间下裸奔使用,一旦您的业务扩张到第二个账号,将会引发难以追溯的回调抢占雪崩。*\n\n---\n\n## 三、📡 排障与抓包:洞悉黑盒下的脉搏\n\n当前版本请使用以下三条命令组合排障。注意:`openclaw channels status` **不支持** `--deep`,插件级探测参数是 `--probe`;`--deep` 属于顶层 `openclaw status`。\n\n### 3.1 先看插件级状态快照\n\n```bash\nopenclaw channels status --probe\n```\n\n适合回答这些问题:\n\n- 企业微信账号是否已被网关识别并加载\n- 账号当前是否 `enabled` / `configured`\n- 运行时是否 `running` / `connected` / `authenticated`\n- 最近一次错误、最近进出站时间是否异常\n\n如果网关可达,这条命令会返回企业微信账号的运行时快照。\n如果网关不可达,它会自动退化为\"只看配置\"的摘要输出。\n\n### 3.2 再看全局深度诊断\n\n```bash\nopenclaw status --deep\n```\n\n这条命令是 **OpenClaw 全局诊断入口**,适合确认:\n\n- Gateway 本身是否健康\n- 当前机器上的整体通道探测是否正常\n- 最近心跳、会话、服务状态是否异常\n\n当您怀疑问题不只在企业微信插件,而是 Gateway、网络、配置路径或其他通道共同影响时,优先跑这条。\n\n### 3.3 最后直接看 WeCom 日志\n\n```bash\nopenclaw channels logs --channel wecom --lines 200\n```\n\n当发生疑难连接断开、消息不回、媒体文件下发神秘消失时,直接看日志最有效。新版日志已经被精细地切分在不同命名空间锚点下,助你顺藤摸瓜:\n\n- `[wecom-runtime]`:统一运行时主线。看收消息、分发、回消息、最近错误与会话归属漂移。\n- `[wecom-ws]`:Bot WebSocket 通道。看连接、鉴权、断线、重连、帧收发与保活。\n- `[wecom-agent-delivery]`:Agent 主动发送链路。看用户/部门/标签目标解析、媒体发送和账号错配。\n\n### 3.4 推荐排障顺序\n\n建议按下面顺序执行:\n\n```bash\nopenclaw channels status --probe\nopenclaw status --deep\nopenclaw channels logs --channel wecom --lines 200\n```\n\n您可以按输出这样判断:\n\n- `configured=false`:先检查 `bot.ws.botId`、`bot.ws.secret`、`agent.corpId`、`agent.agentSecret`、`agent.agentId` 等配置是否完整。\n- `running=false`:说明账号没有真正启动,优先看 `[wecom-runtime]`。\n- `connected=false` 或 `authenticated=false`:优先看 `[wecom-ws]`,一般是 WebSocket 握手、密钥或连接稳定性问题。\n- 能收不能发,或群里发文件/卡片失败:优先看 `[wecom-agent-delivery]`。\n- `lastError` 持续刷新:通常不是一次性误报,建议结合最近 200 行日志一起看。\n\n---\n\n## 四、🤝 项目鸣谢\n\n感谢所有为本项目提交代码、测试、文档与反馈的协作者。\n\n- **原始项目**:[yanhaitao/wecom](https://github.com/yanhaitao/wecom)\n\n<p align=\"center\">\n  <a href=\"https://github.com/YanHaidao/wecom/graphs/contributors\">\n    <img src=\"https://contrib.rocks/image?repo=YanHaidao/wecom\" alt=\"WeCom contributors\" />\n  </a>\n</p>\n\n如果头像墙没有立刻刷新,通常是 GitHub 统计或第三方缓存延迟,稍后再看即可。\n\n---\n\n## 五、📮 版权与许可证协议指引\n\n<div align=\"center\">\n\n**公司名称：** 青岛火一五信息科技有限公司\n\n**联系邮箱：** postmaster@huo15.com | **QQ群：** 1093992108\n\n---\n\n**关注逸寻智库公众号，获取更多资讯**\n\n<img src=\"https://tools.huo15.com/uploads/images/system/qrcode_yxzk.jpg\" alt=\"逸寻智库公众号二维码\" style=\"width: 200px; height: auto; margin: 10px 0;\" />\n\n</div>\n\n### 最后的话:关于开源及署名\n本项目版权归 **青岛火一五信息科技有限公司** 所有,遵循 **ISC License**。\n您可以将其用于极其广阔的项目天地中。但开源不是拿来主义:\n在此明确强调,包括所谓的\"Bot+Agent 保活接力超时融合机制\"、\"千人千面多账户切面\"、\"自动寻的路由下沉\" 这背后全是作者无数个在企业真实现网撞墙实验出的架构结晶。**拒绝一切去除原作者署名、粗暴改名换姓占为己用的魔改上架行为。**\n愿我们能在彼此尊重的前提下,共同拓展 OpenClaw 生态的无垠边界。\n\nFile v2.9.2:_meta.json\n\n{\n  \"ownerId\": \"kn7byevkn40d6z4p7ghdb097z983tj33\",\n  \"slug\": \"huo15-wecom-plugin\",\n  \"version\": \"2.9.2\",\n  \"publishedAt\": 1778135980926\n}\n\nFile v2.9.2:changelog/v2.2.28.md\n\n# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.2.28 - 多账号隔离与稳定性增强\n\n本次 v2.2.28 版本是 **OpenClaw 企业微信 (WeCom) 插件** 的一次重大里程碑更新。我们深度优化了 **微信 / 企业微信** 办公场景下的多智能体隔离逻辑，并修复了生命周期、XML 数据保真等多个生产环境的核心痛点。\n\n本次更新让 **OpenClaw** 在处理企业级复杂 **插件** 配置时更加得心应手，完美解决大模型接入 **WeCom** 的所有阻碍。\n\n---\n\n### 🌟 版本亮点 (Release Highlights)\n\n*   🎯 **多账号矩阵支持**：支持按 `accountId` 进行组内会话隔离。不同部门、不同业务的 **企业微信** 机器人可并行运行，互不干扰，彻底解决跨账号串会话问题。\n*   🔐 **数据保真解析**：针对 **WeCom** 的 XML 消息解析进行了重构。关闭了自动数值化，保留 `FromUserName` 前导 `0`，并完美解决 64 位 `MsgId` 精度风险。\n*   🔁 **Gateway 生命周期适配**：完美兼容最新版 **OpenClaw** Gateway 的生命周期管理，修复了在高频心跳监测下的重启循环问题，运行更稳健。\n*   🧹 **入站消息过滤**：优化了 **微信** 与 **企业微信** 的事件过滤逻辑，避免系统事件、缺失发送者等无效消息进入 AI 会话，防止“误回复”。\n*   🧱 **配置安全护栏**：新增 **企业微信** 账号冲突检测。自动拦截重复的 `bot.token` 或 `agentId` 配置，并提供友好的中文错误提示。\n\n---\n\n### 📝 详细更新日志 (Changelog)\n\n#### 【重磅更新】🎯 多账号/多智能体可用性增强\n- 支持按 `accountId` 做组内隔离（Bot + Agent + 路由绑定同组生效）。\n- 动态 Agent 与会话键增加 `accountId` 维度，避免跨账号串会话。\n\n#### 【稳定性】🔁 生命周期兼容修复\n- 适配新版 **OpenClaw** Gateway 生命周期，`startAccount` 改为长生命周期运行。\n- 修复了“几秒一次重启 + health-monitor 二次重启”的循环问题。\n\n#### 【准确性】🔐 XML 字段保真修复\n- **WeCom** Agent XML 解析关闭自动数值化，保留发送者原始 ID。\n- 避免 `MsgId` (64bit) 精度损失，确保回复目标不被误改。\n\n#### 【准确性】🧹 误回复修复\n- Bot/Agent 入站均增加事件过滤，避免处理 `event`、`sys` 及缺失发送者的消息。\n- 修复群聊缺失 `chatid` 时仍进入 AI 会话的问题，避免“一个消息触发多人误回复”。\n\n#### 【可控性】🧱 配置安全护栏\n- 新增多账号冲突检测，自动拦截重复 Token 或 Agent ID 的配置。\n- **账号管理修复**：`deleteAccount` 现在仅删除目标账号，不再误删整个 **插件** 的 `channels.wecom` 配置。\n\n#### 【质量保障】✅ 自动化回归\n- 新增账号解析、冲突检测、动态路由隔离、生命周期与入站过滤的多项自动化测试。\n- **文档优化**：README 快速开始文档更新，优先展示“多账号 + 多 Agent”矩阵配置。\n\n---\n\n### 💾 安装与升级 (Install & Update)\n\n使用 **OpenClaw** CLI 即可一键升级 **插件**：\n\n```bash\nopenclaw plugins upgrade wecom\n```\n\n或手动更新配置：\n```bash\nopenclaw config set channels.wecom.enabled true\n```\n\n---\n\n### 🔍 SEO 关键词 (Keywords)\n**openclaw** | **企业微信** | **微信** | **wecom** | **插件** | **AI 机器人** | **大模型网关** | **流式响应** | **多账号隔离** | **WeCom Plugin**\n\n---\n\n### 📮 联系我们\n如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 或加入我们的交流群。\n\n> **提示**：建议 **OpenClaw** 主程序版本保持在 **2026.2.24+** 以获得最佳体验。\n\nFile v2.9.2:changelog/v2.3.10.md\n\n# OpenClaw WeCom 插件 v2.3.10 变更简报\n\n> [!TIP]\n> **默认更易用、修复更直接的版本。**\n\n## 2026-03-10（v2.3.10）\n- 【消息防丢修复】🐛 **[重要修复]** 针对由于模型 API 限速或超长思考（如 DeepSeek R1）导致的企微 WebSocket 5秒超时断连问题，引入了 4 秒前置保活机制（自动下发\"⏳ 正在思考中...\"），彻底阻断了因为模型响应慢而造成的“消息卡死不再回复”。\n- 【双重回复修复】🐛 **[重要修复]** 修复 `Bot WS` 长文本场景下可能被超时截断并触发兜底通道进行二次重复回复的边界异常。\n- 【向导自动路由】✨ **[体验升级]** 重构了企业微信的渠道交互配置向导。在单账号场景下将静默触发自动路由绑定，丝滑跳过 OpenClaw 全局冗长的 Agent 路由分配询问。\n- 【账号兜底修复】🧩 修复企业微信 onboarding 在首个账号非字面量 `default` 时，后续流程报 `WeCom account \"default\" not found` 的问题。\n- 【默认选项收敛】🚀 onboarding 的默认回车选项已变更为更普适的 `Bot` 模式、`WS` 接入和 `开放模式` 策略。\n- 【字段命名收敛】📝 Agent 新配置统一推荐使用 `agentSecret`，历史 `corpSecret` 保持兼容读取，保障平滑升级。\n- 【文档与提示精简】📘 README、向导交互文案与示例结构已全面统一为更符合直觉的精简说明。\n\n## 验证结果\n- `bunx vitest run extensions/wecom/src/onboarding.test.ts extensions/wecom/src/channel.meta.test.ts`\n- `pnpm build`\n\nFile v2.9.2:changelog/v2.3.11.md\n\n# OpenClaw WeCom 插件 v2.3.11 变更简报\n\n> [!TIP]\n> **稳定性与多账号说明版本**：`v2.3.11` 重点修复 Bot WS 长思考场景下的 `invalid req_id`，同步收敛 onboarding 账号默认值与多账号隔离文档说明。\n\n## 2026-03-11（v2.3.11）\n- 【WS 保活升级】🚀 **[重要修复]** Bot WebSocket 从“4 秒后补发占位”升级为“收到用户消息立即下发占位符，并在长思考期间持续保活”，显著降低慢模型或长任务下的 `invalid req_id` 与回复丢失风险。\n- 【占位符配置生效】🌊 `bot.streamPlaceholderContent` 现在对 `Bot WS` 与 `Bot Webhook` 两条链路统一生效，配置一次即可保持体验一致。\n- 【错误兜底收敛】🛡 修复 `req_id` 已失效时仍尝试二次回错消息的问题，避免出现重复报错与未处理 Promise 拒绝。\n- 【账号选择兜底】🧩 onboarding 在“配置里还没有任何账号”时，也会显式提供 `default` 默认账号选项，减少首次接入时的困惑。\n- 【多账号文档补强】📘 README 新增说明：如果多个 `accountId` 复用同一个静态 Agent，建议配合 `session.dmScope = \"per-account-channel-peer\"`，避免不同账号的私聊上下文共用。\n- 【日志可读性】🔎 WeCom runtime 的 Bot WS 失败日志改为可读错误文本，排查时不再只看到 `[object Object]`。\n\n## 验证结果\n- `pnpm exec vitest run extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/onboarding.test.ts`\n\n## 升级提示\n- 已有 `bot.streamPlaceholderContent` 配置无需调整，升级后 `Bot WS` 会自动使用它。\n- 如果你在同一个 OpenClaw 实例里挂了多个 WeCom 账号，并让它们指向同一个静态 Agent，建议补上 `session.dmScope = \"per-account-channel-peer\"` 以隔离私聊上下文。\n\nFile v2.9.2:changelog/v2.3.12.md\n\n# OpenClaw WeCom 插件 v2.3.12 变更简报\n\n> [!TIP]\n> **WS 主动推送与过期更新兜底版本**：`v2.3.12` 重点修复企业微信 Bot WebSocket 在流式回复超过 6 分钟后返回 `846608 stream message update expired`，并同步调整主动消息路由为“WS 文本优先、Agent 文件兜底”。\n\n## 2026-03-12（v2.3.12）\n- 【6 分钟过期修复】🛠 **[重要修复]** `Bot WS` 现在会把企业微信 `846608 stream message update expired (>6 minutes)` 识别为回复窗口已结束的终态错误，不再继续把该错误向上抛出导致进程退出。\n- 【主动推送路由收敛】🚀 **[重要修复]** 当账号实际运行在 `Bot WS` 模式时，定时消息、heartbeat 和其他主动文本发送现在优先走 `wsClient.sendMessage()`，不再默认绕去 Agent。\n- 【WS/Agent 职责切分】🧩 `Agent` 现在主要承担两类兜底：一是账号没有启用 `Bot WS` 时的主动消息发送；二是 Bot 两种模式都不支持的文件/媒体发送。\n- 【UserID 纯数字解析修复】🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的图片发送失败（81013 错误）。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。\n- 【未处理拒绝隔离】🧯 `sdk-adapter` 为每个 WebSocket frame 的异步处理补上显式兜底捕获；即使后续再出现漏网异常，也会记录到 runtime issue，而不是变成 `unhandledRejection` 直接带崩 OpenClaw。\n- 【占位保活收敛】⏱ 当回复窗口已经过期时，WS 占位符保活会立即停止，避免过期后继续发送流式更新。\n- 【Ack 超时兜底】⏱ SDK 5 秒回执超时 (`Reply ack timeout`) 现在也被识别为终态错误，超时后立即停止占位保活并走 `onFail` 回调，不再产生 `unhandledRejection`。\n- 【回归测试补齐】✅ 新增针对 `846608` 过期更新和 `frame handler` reject 的回归测试，确保此类异常保持非致命。\n- 【Bot WS 图片/文件解密修复】🛠 **[重要修复]** `Bot WS` 模式下接收到的图片和文件现在会使用消息体中的独立 `aeskey` 进行 AES-256-CBC 解密，修复之前直接保存密文导致 `Failed to optimize image` 的问题。`media-service.ts` 新增 `downloadEncryptedMedia()` 方法，`normalizeFirstAttachment()` 自动检测 `aesKey` 并走解密路径。\n\n## 验证结果\n- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/outbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`\n\n## 升级提示\n- 无需新增配置，升级到 `v2.3.12` 后自动生效。\n- 如果账号正在使用 `Bot WS`，主动文本消息会优先走 WS 长连接；只有文件/媒体或未启用 WS 的场景才会继续使用 Agent。\n- 如果模型或工具链路存在超长执行，超过企业微信 6 分钟回复窗口时，OpenClaw 现在会保持存活并记录运行时错误，不再因该异常退出。\n\nFile v2.9.2:changelog/v2.3.13.md\n\n# OpenClaw WeCom 插件 v2.3.13 变更简报\n\n> [!TIP]\n> **Bot WS 引用上下文与流式展示修复版本**：`v2.3.13` 重点补齐企业微信 `Bot WS` 对引用消息的上下文注入，并修复长回答在客户端里显示为“断断续续碎片”的问题。\n\n## 2026-03-13（v2.3.13）\n- 【引用上下文补齐】🛠 **[重要修复]** `Bot WS` 现在会复用与 `Bot Webhook` 一致的入站正文拼装逻辑。用户通过“引用 + 提问”触发机器人时，引用内容会一并进入 Agent 上下文，不再只保留当前这句提问。\n- 【WS 流式刷新修复】🌊 **[重要修复]** `Bot WS replyStream` 现在按“累计全文刷新”发送，而不是只发送最新增量片段，修复企业微信客户端中长回答显示断断续续、像被拆成多块的问题。\n- 【协议语义对齐】🧩 这次调整显式对齐企业微信 `stream.id` 的刷新语义：同一条流式消息的后续更新会覆盖为“当前完整内容”，从而保持最终展示稳定、可连续阅读。\n- 【回归测试补齐】✅ 新增 `bot-ws` 引用上下文与累计流式发送测试，避免后续重构再次把引用消息或流式展示打回退。\n\n## 验证结果\n- `pnpm exec vitest run --config extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/inbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`\n\n## 升级提示\n- 无需新增配置，升级到 `v2.3.13` 后自动生效。\n- 如果企业微信 `WS` 推送里的 `quote.text.content` 仍然是 `[该消息类型暂不能展示]`，说明上游没有下发真实引用原文；OpenClaw 会把该占位文本带入上下文，但无法恢复企业微信未提供的原始内容。\n- 如果你之前观察到长回复在企业微信里呈现为“分段断裂”或“后段覆盖前段”，升级后会改为同一条流式消息持续刷新完整内容。\n\nFile v2.9.2:changelog/v2.3.14.md\n\n# OpenClaw WeCom 插件 v2.3.14 变更简报\n\n> [!TIP]\n> **企业微信“协作文档”原生整合与长连接稳定性修复版本**：`v2.3.14` 将机器人的能力从“陪聊”正式拓展到了“办公协同”。现在，你可以直接在微信群里让机器人去填报销单、建项目表；同时我们也彻底修复了多人并发聊天时机器人“正在思考”卡死刷屏的问题。\n>\n> 📣 **特别感谢** [@proyy](https://github.com/proyy) 提供的企业微信文档管理解决方案，使本版本的 Docs 能力得以落地。\n\n## 重磅功能：把聊天直接变成企业文档（用后即得）\n\n我们受够了问 AI 一个问题，答案最后只能被新消息顶没。这次更新，我们让机器人获得了操作“企业微信协作文档”的实体权限。\n\n### 场景 1：开新项目，不用再求人建表格拉权限了\n- **以前**：你在群里说“准备一下下周的活动追踪表”，然后得切出去打开文档中心，新建表格，再一个个抄名字把大家拉进来。\n- **现在**：直接在群里 `@机器人 帮我建一个名为『春季新品发布会追踪』的表格，并把群里的人都加上可写权限`。机器人建好后会直接在群里甩出一个链接，所有人点开就能直接编辑，全程零切换。\n\n### 场景 2：坐在地铁上，照样神操作填报销/跟进数据\n- **以前**：你刚下班，群里有人问“今天 C 组的面试谁通过了？”你只能回答“我等下回家用电脑打开「面试记录表」改一下状态”。全量改动很容易把别人的同行数据覆盖掉。\n- **现在**：你可以直接发语音或者敲字 `@机器人 把「第二周面试记录表」里的 B2 到 B5 单元格全部更新为“二面通过”`。机器人会像操作手术刀一样，只精准替换指定的数据块（`spreadsheet.edit_data`），丝毫不影响文档里的其他公式。\n\n### 场景 3：直接让 AI 读懂全公司的数据报表\n- **以前**：你要先自己把表格下载成 Excel，再一段段复制数据发给大模型：“帮我算算这堆数据谁最高”。\n- **现在**：你直接丢给他一个企微文档链接：`@机器人 分析一下这张表里的第一季度数据，告诉我谁的单产最差？`。由于具备了原生读取能力（`get_sheet_range_data`），它会自己去拉取数据查表，给你输出结论。\n\n## 💡 Docs 权限配置指引（只需一次）\n\n为了让上述场景跑通，光配 `agentSecret` 是不够的。这是因为哪怕是公司自建的机器人，默认也没资格动你们内部的文档资产。你需要：\n1. **去企微后台发“通行证”**：进入 [企业微信后台 -> 协作 -> 文档 -> 可调用接口的应用](https://work.weixin.qq.com/wework_admin/frame#apps/qykit/proxy/wedoc)，把你的机器人应用放进白名单。\n2. **在 OpenClaw 里激活能力**：打开 UI 界面 的 `Settings` -> `Agents` -> `Tools`，找到 `wecom`，把带有 `doc` 字眼的所有工具（创建文档、读取表格、改权限等）通通打勾。\n\n\n## 核心修复：终结“正在思考...”刷屏噩梦\n除了新功能，这次我们也彻底对长连接（WS）卡死问题做了一次大手术：\n- 🛑 **告别并发刷屏**：群里人多手杂的时候，以前机器人如果处理不过来，不仅不回话，还会满屏一直弹“正在思考...”。现在只要有一条真回复发出来，它会自动把同群里那些卡死、过期的“正在思考”全部瞬间清理干净。\n- 📡 **进群欢迎语报错 846605 终结**：修复了大家常反馈的“有人一进群，后台就疯狂报 invalid req_id”的陈年老 Bug。现在对进群、推卡片等非聊天事件，我们全面切换成了专属接口，彻底避免违规流式推送。\n- 🛡 **120 秒物理断网**：即使模型源站点挂了，我们现在也会在 120 秒内强制熔断提示，绝不让你面对一个无限转圈的加载框。\n\n---\n## 验证结果\n- `pnpm test -- src/transport/bot-ws`\n- 所有 WS 回复通道单测已全部通过，尤其是关于 `setInterval` 占位符存活期的验证得到了补全与修复。\n\n## 升级指引\n```bash\nopenclaw plugins update wecom\n```\n- 无需新增配置，执行上述命令即可一键升级到 `v2.3.14`。\n- 升级后，如果你拉几十个机器人进群并同时发言，曾经那种满屏飘“正在思考...”却无人回答的乱象将不复存在。\n- 如果之前查看后台日志总是看到 `stream message update expired (>6 minutes)` 甚至因为连带引发的 WS 断网重启，本次升级将大幅度平息日志告警红字，稳定长连接状态。\n\nFile v2.9.2:changelog/v2.3.15.md\n\n# OpenClaw WeCom 插件 v2.3.15 变更简报\n\n> [!TIP]\n> **企业微信文档写入稳定性与消息目标路由修复版本**：`v2.3.15` 重点解决了企微文档 `init_content` 初始化内容写入不稳定、图片插入失败、批量更新索引错误，以及群聊回复时容易触发的 `81013` 目标解析错误。同时，这次也补回并完善了文档、在线表格、智能表格、收集表等能力，避免相关工具调用缺接口或直接失败。\n\n## 2026-03-14（v2.3.15）\n- 【文档初始化内容修复】🛠 **[重要修复]** 创建企微文档时，`init_content` 现在会按官方 Wedoc 流程执行：图片先上传再插入，文本与图片段落会基于最新索引和版本号写入，减少标题正文错位、图片不显示、内容插到错误位置的问题。\n- 【批量更新稳定性修复】📄 **[重要修复]** 修复 `document.batch_update` 的索引计算与模式切换问题。混合执行 `insert_paragraph`、`insert_text`、`insert_image` 时，不再更容易触发 `ParagraphValidator`、`TextValidator`、`DrawingValidator` 一类报错。\n- 【文档客户端能力恢复】🔧 重新补齐此前精简时误删的企微文档客户端接口，恢复文档权限、在线表格、智能表格、收集表等相关方法，避免工具层调用缺方法、返回异常或直接不可用。\n- 【在线表格与收集表支持补齐】📊 完善企微在线表格和收集表的类型定义、参数校验与错误提示。现在会更早拦截超出 API 限制的请求，例如表格行列/单元格数量超限、收集表题目结构缺失、选项题参数不完整等问题。\n- 【群聊目标解析修复】💬 **[重要修复]** 修复企业微信群聊回复时 `To` 字段被错误硬编码为用户目标的问题。群聊、私聊、部门、标签目标现在会按正确前缀解析，减少发送时报 `81013 user & party & tag all invalid` 的情况。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.15`。\n- 如果你之前遇到“建文档成功但内容没写进去”“图片插不进去”“批量更新偶发报索引错误”或“群里回复机器人时报 81013”，本次升级后会明显改善。\n\nFile v2.9.2:changelog/v2.3.16.md\n\n# OpenClaw WeCom 插件 v2.3.16 变更简报\n\n> [!TIP]\n> **企业微信 Bot-WS 混合消息附件解析修复版本**：`v2.3.16` 重点解决了在 WebSocket 模式下，企业微信机器人接收到的混合消息（如同时包含图片和文字）由于解析遗漏导致附件丢失、AI 只能看到带签名的临时链接文本而无法查看真正图片内容的问题。\n\n## 2026-03-16（v2.3.16）\n- 【混合消息媒体解析修复】🛠 **[重要修复]** 补齐了 Bot WebSocket 传输通道（`bot-ws`）下对 `mixed` 结构消息的附件提取逻辑。现在，当用户在企微发出一条包含图片/文件与文字的混合消息时，底层框架会自动遍历并提取各个媒体节点的 URL 和 AES Key，确保核心处理管线能进行正常下载与安全解密。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.16`。\n- 如果你之前在企微发出“带图的一段话”时，曾遇到 AI 回复说“这是一个腾讯 COS 的临时签名链接”，本次升级后，此问题将被修复，AI 将可以直接分析图片内容本身。\n\nFile v2.9.2:changelog/v2.3.18.md\n\n# OpenClaw WeCom 插件 v2.3.18 变更简报\n\n> [!TIP]\n> **企业微信面向中小企业的新能力开放版本**：`v2.3.18` 重点完善了 `wecom` 插件在 Bot WebSocket 场景下的能力层。现在，面向 5 人及以下小企业，OpenClaw 已支持以用户个人身份在企业微信内使用文档读写、日程读写、会议读写、待办读写、通讯录查询等能力。同时，本次也补齐了 Bot WS 媒体发送、建立了 Bot 与 Agent 双平面路由，并修复了企业微信里容易卡在“正在思考...”不结束的问题。\n\n## 2026-03-18（v2.3.18）\n- 【中小企业能力开放】🚀 **[重大更新]** 面向 5 人及以下小企业，OpenClaw 在企业微信内正式开放以用户个人身份使用的协作能力入口。现在，大模型可以在具备相应授权的前提下，调用企业微信文档读写、日程读写、会议读写、待办读写以及通讯录查询等能力，把原本分散在多个协作入口中的企业操作集中到同一条智能对话链路中。\n- 【新增 Bot WS MCP 工具层】新增 `wecom_mcp` 工具，将企业微信 Bot WS 能力以挂载式能力层接入 `wecom` 插件。现在 Bot 侧可以按业务类别动态获取 MCP 配置，并把企业微信开放的能力暴露给大模型调用。\n- 【建立 Bot / Agent 双平面路由】新增基于会话来源的能力分流。Bot WS 会话优先使用 `wecom_mcp`；Agent 回调会话继续保留原生 `wecom_doc`、`wecom_calendar` 工具链，避免不同能力面互相干扰。\n- 【多账号能力隔离加强】MCP 相关缓存和状态改为按 `accountId + category` 隔离。在多账号矩阵下，同一类能力不会再共用同一份 Bot 侧配置，减少串账号、串上下文、串连接状态的问题。\n- 【补齐 Bot WS 命令与媒体链】扩展 Bot WS 运行时接口，除了主动文本发送外，现在还支持命令桥接、连接状态探测和媒体发送。Bot WebSocket 会话下的图片、文件回复不再必须依赖 Agent API 补送。\n- 【新增媒体发送提示注入】在企业微信 Bot WS 会话里定向注入 `MEDIA:` 使用提示，帮助模型更稳定地触发图片和文件回复，同时避免把这类提示扩散到非 WeCom 或 Agent 会话。\n- 【修复回复流不收口问题】**[重要修复]** 处理 Bot WS 回复时，带媒体的中间块不再错误中断文本发送。现在文本会先正常下发，媒体在结束阶段继续处理；如果上游没有显式 final，系统也会自动补一个收口帧，避免企业微信里长期停留在“正在思考...”。\n- 【欢迎语路径提速】`enter_chat` 欢迎事件在配置静态欢迎语时改为直发，不再额外启动完整推理流程。首次进入会话时的响应更直接，链路也更短。\n- 【运行时日志增强】新增更细的派发与投递日志，包括 `dispatch-start`、`dispatch-done`、`dispatch-fail`、`deliver-start`、`deliver-done`。现在排查问题时可以更快区分是模型处理慢、回复已被企微确认、MCP 类别未开通，还是本地媒体路径被限制拦截。\n- 【能力边界提示更明确】当企业微信后台只开放部分能力时，插件会更明确地把限制反馈给用户和日志。例如只开通文档类能力时，待办、会议、日程类请求会直接提示当前账号尚未开放对应能力，而不是表现成模糊失败。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.18`。\n- 本次版本是企业微信能力面的重要开放版本，尤其适合希望在企业微信内直接完成文档、日程、会议、待办与通讯录协作的小型团队。\n- 如果你之前在企业微信 Bot WS 会话里只看到反复“正在思考...”、最终不出结果，本次升级后应已修复。\n- 如果你希望在企业微信里直接使用会议、待办、日程等 Bot 侧能力，请同时确认企业微信后台已经为当前 Bot 开通相应业务类别；插件侧已经具备调用链，但实际可用范围仍以企业微信侧授权为准。\n\nArchive v2.9.1: 243 files, 500588 bytes\n\nFiles: changelog/v2.2.28.md (3745b), changelog/v2.3.10.md (1572b), changelog/v2.3.11.md (1837b), changelog/v2.3.12.md (3259b), changelog/v2.3.13.md (2018b), changelog/v2.3.14.md (4670b), changelog/v2.3.15.md (2241b), changelog/v2.3.16.md (1113b), changelog/v2.3.18.md (4080b), changelog/v2.3.19.md (6771b), changelog/v2.3.2.md (2795b), changelog/v2.3.26.md (1830b), changelog/v2.3.27.md (4345b), changelog/v2.3.273.md (680b), changelog/v2.3.4.md (1755b), changelog/v2.3.9.md (1711b), changelog/v2.4.12.md (4707b), changelog/v2.4.16.md (1157b), changelog/v2.7.4.md (2724b), changelog/v2.8.0.md (3687b), changelog/v2.8.1.md (2230b), changelog/v2.8.17.md (7630b), changelog/v2.8.18.md (3377b), changelog/v2.8.19.md (5692b), changelog/v2.8.2.md (2496b), changelog/v2.8.20.md (7103b), changelog/v2.8.21.md (8625b), changelog/v2.8.22.md (6594b), changelog/v2.8.23.md (6868b), changelog/v2.8.24.md (7061b), changelog/v2.8.25.md (5291b), changelog/v2.8.26.md (6532b), changelog/v2.8.27.md (5994b), changelog/v2.8.28.md (3728b), changelog/v2.8.29.md (4665b), changelog/v2.8.3.md (3447b), changelog/v2.8.30.md (4967b), changelog/v2.8.31.md (6539b), changelog/v2.8.32.md (1368b), changelog/v2.8.6.md (3301b), changelog/v2.8.8.md (5098b), changelog/v2.9.0.md (6833b), changelog/v2.9.1.md (2771b), compat-single-account.md (4135b), GOVERNANCE.md (1301b), index.test.ts (1058b), index.ts (5408b), openclaw.plugin.json (11593b), package.json (2717b), README.md (31424b), scripts/release.sh (11536b), scripts/test-proxy.ts (2377b), SKILL.md (4871b), SKILLS_CAL.md (29478b), SKILLS_DOC.md (70311b), src/accounts.ts (1223b), src/agent/api-client.upload.test.ts (3909b), src/agent/handler.event-filter.test.ts (3469b), src/agent/handler.ts (39593b), src/agent/index.ts (248b), src/app/account-runtime.ts (11247b), src/app/bootstrap.ts (890b), src/app/index.ts (6075b), src/capability/agent/delivery-service.ts (4475b), src/capability/agent/fallback-policy.ts (484b), src/capability/agent/index.ts (221b), src/capability/agent/ingress-service.ts (1126b), src/capability/agent/upstream-delivery-service.ts (3728b), src/capability/bot/dispatch-config.ts (1854b), src/capability/bot/fallback-delivery.ts (6892b), src/capability/bot/index.ts (58b), src/capability/bot/local-path-delivery.ts (8059b), src/capability/bot/sandbox-media.test.ts (7025b), src/capability/bot/sandbox-media.ts (5688b), src/capability/bot/service.ts (1651b), src/capability/bot/stream-delivery.ts (16654b), src/capability/bot/stream-finalizer.ts (5769b), src/capability/bot/stream-orchestrator.ts (16350b), src/capability/bot/types.ts (352b), src/capability/calendar/client.ts (36126b)\n\nFile v2.9.1:SKILL.md\n\n---\nname: huo15-wecom\ndescription: \"火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担心 stream 截断 + 86008 把链接设为优先，v2.8.23/v2.8.24 修了群聊主动推送通道 + UI 锁交互后 MEDIA: 路径稳定可靠，应用户偏好翻转：默认 MEDIA: 直发，仅大文件（> 企微上限）才走 enhance_share_file 链接。GUIDANCE 加决策表 + 用户偏好覆盖。继承 v2.8.24 placeholder timeout 解锁、v2.8.23 群聊主动推送、v2.8.20 MEDIA: parser。Use when: 接企业微信、给企微 Bot/自建应用接 OpenClaw、用微信客服收外部用户消息、需要图片/文件双向、跨账号切换。Do NOT use for 个人微信（不同协议）。\"\nversion: 2.9.1\nhomepage: https://cnb.cool/huo15/ai/huo15-wecom-plugin\nmetadata: { \"openclaw\": { \"emoji\": \"🦜\", \"requires\": { \"bins\": [] } } }\n---\n\n# 火一五企业微信插件\n\n`@huo15/wecom` 是 OpenClaw 的企业微信通道插件，fork 自 [yanhaidao/wecom](https://github.com/yanhaidao/wecom) 并持续合并上游。**默认 Bot WebSocket 模式**，配置简单、响应快；同时支持 Agent 自建应用主动推送和微信客服三方通道。\n\n## 三条消息通道\n\n| 通道 | 用途 | 配置入口 |\n|---|---|---|\n| **Bot WebSocket** | 默认推荐，企业微信\"智能机器人\"WS 协议，免公网回调 | `channels.wecom.accounts.<id>.bot.ws` |\n| **Agent 自建应用** | 走企微官方 API（CorpId/AgentId/Secret），支持主动推送给指定用户/群 | `channels.wecom.accounts.<id>.agent` |\n| **微信客服** | 接管\"客服会话\"，外部客户在微信/视频号里发给客服账号的消息 | `channels.wecom.accounts.<id>.kefu` |\n\n三条通道可以**单独启用**或**组合启用**，多账号场景每个账号独立配置。\n\n## 安装\n\n```bash\n# OpenClaw 内置安装（推荐）\nopenclaw plugins install @huo15/wecom\n\n# 或者直接 npm\nnpm install @huo15/wecom\n```\n\n## 最小配置（Bot WS 模式）\n\n```yaml\n# ~/.openclaw/openclaw.json 中\nchannels:\n  wecom:\n    enabled: true\n    accounts:\n      default:\n        bot:\n          ws:\n            botId: \"你的智能机器人 ID\"\n            secret: \"WS 密钥\"\n```\n\n启动后，Bot 收到的消息会自动路由到默认 Agent，回复也通过 WS 直接送回 — 不需要部署任何回调 endpoint。\n\n## 关键能力\n\n- **加密媒体解密**：图片/文件/语音 AES-256-CBC 解密直接拿 buffer，可让 Agent 直接读取（OCR / ASR / 文档解析）\n- **Markdown V2**：支持企微富文本（标题、表格、代码块、链接、引用），自动适配 chat 上下文\n- **图片回复**：`![alt](url)` 自动抽离 + uploadMedia + replyMedia，COS/OSS 预签名 URL 失败时降级为占位文本（不让\"链接已过期\"漏到客户端）\n- **多账号切换**：单实例支持多个企业、多个智能体并存，按 conversation 路由\n- **流式回复**：placeholder + partial replyStream（最多 8 次中间更新）+ ack timeout watchdog 自动重连\n\n## v2.8.8 关键修复（WS BOT 图片）\n\n1. **Reply 通道纠错**：reply 上下文从 `sendMediaMessage`（主动推送）改用 `replyMedia`（被动回复，绑定 reqId）\n2. **入向多图**：`mixed` 与 `quote.mixed` 类型从只取首张改为全部提取；首张挂 `ctx.MediaPath`，其余落盘 + info 日志\n3. **Outbound fetch UA**：从裸 `fetch` 切到 plugin-sdk `fetchRemoteMedia`，显式带 desktop User-Agent，避免部分 Tencent COS / 阿里 OSS bucket 拒绝 Node 默认 UA\n4. **解析可观测性**：媒体类型消息但无 attachments 时记 warn 日志（含 msgid + body keys），便于 SDK 字段漂移排查\n\n详见 [changelog/v2.8.8.md](./changelog/v2.8.8.md)。\n\n## 安全实践\n\n- LLM 输出的 `touser` / `chatid` 经 `resolveWecomTarget` sanitizer，**拒绝 `@all` / `@everyone` / `*` 等广播字面量**（v2.8.1 SECURITY 修复）\n- 跨企业上下游消息走 upstream-delivery 通道，不与本企业 Agent API 混用\n- 微信客服 `corpSecret` 可与 Agent `corpSecret` 独立配置，权限隔离\n\n## 不变的设计原则\n\n- **Bot WS 优先**：能用 WS 就不用 Agent API（少配置、低延迟）\n- **失败降级**：WS reply ack timeout 自动 fallback 到 Agent API（保留消息可达性），watchdog 连续 8 次后触发 WS 重连\n- **不修改 OpenClaw 核心**：所有功能通过 channel plugin SDK 注册\n\n## 仓库\n\n- 主仓库：https://cnb.cool/huo15/ai/huo15-wecom-plugin\n- 镜像：https://github.com/zhaobod1/huo15-wecom-plugin\n- 上游 fork 源：https://github.com/yanhaidao/wecom（**仅 fetch，不 push**）\n\n## License\n\nISC（继承自 yanhaidao/wecom 上游）。\n\nFile v2.9.1:README.md\n\n# OpenClaw 企业微信(WeCom)Channel 插件\n\n<p align=\"center\">\n  <a href=\"https://github.com/yanhaitao/wecom\"><img src=\"https://img.shields.io/badge/Original%20Project-逸寻智库-orange?style=for-the-badge&logo=github\" alt=\"Original Project\" /></a>\n  <img src=\"https://img.shields.io/badge/License-ISC-blue?style=for-the-badge\" alt=\"License\" />\n  <img src=\"https://img.shields.io/badge/Min%20Recommended-2.8.1+-red?style=for-the-badge\" alt=\"Minimum recommended\" />\n</p>\n\n> [!CAUTION]\n> **🛡️ 安全公告（2026-04-22）**：受影响版本 `<= 2.8.0`。Agent 在工作区写自定义脚本时可能把 `touser=\"@all\"` 当默认收件人，导致原本私聊的图片/视频/文档**被广播到企业微信应用可见范围全员**。\n>\n> **请所有部署立即升级到 `@huo15/wecom@2.8.1` 或以上**。修复见 [`changelog/v2.8.1.md`](changelog/v2.8.1.md)。\n\n> [!WARNING]\n> **原创声明**:本项目涉及的\"多账号隔离与矩阵路由架构\"、\"Bot+Agent双模融合架构\"、\"长任务超时接力逻辑\"及\"全自动媒体流转接\"等核心设计均为作者 **YanHaidao** 独立思考与实践的原创成果。\n> 欢迎技术交流与合规引用,但严禁任何不经授权的\"功能像素级抄袭\"或删除原作者署名的代码搬运行为。\n\n<p align=\"center\">\n  <strong>🚀 企业级多模式 AI 助手接入方案(统一运行时架构)</strong>\n</p>\n\n---\n\n## 💡 核心价值:为什么团队会真正选择这个插件?\n\n企业真正需要的,不是\"把一个模型接进企业微信\",而是让企业微信变成一个**能长期工作的 AI 协作入口**。\n\n大多数团队最终只关心五件事:\n\n- 能不能先低门槛接起来,而不是先做一轮重部署\n- 多人同时使用时,会不会串上下文、串身份、串会话\n- 长任务会不会因为长连接窗口太短而白跑\n- 能不能既有实时对话体验,又能做正式推送和稳定投递\n- AI 能不能真正进入文档、日程、会议、待办、通讯录这些协作层,而不只是停留在聊天框\n\n常见方案通常会很快碰到边界:\n\n- **只用 Bot WS**:接得快、聊得顺,但会受到单连接、心跳保活、会话边界和组织级广播能力的限制\n- **只用 Agent**:能力强、治理清晰,但部署门槛更高,对话体验不如 Bot WS 丝滑\n- **只选单一路径**:团队最后往往被迫在\"体验\"和\"能力\"之间二选一\n\n本插件的价值,就在于把这些原本互相冲突的目标,尽量同时成立。\n\n### 您真正会得到什么?\n\n1. **多人共用一个入口,但上下文不会串**\n   - **问题本质**:企业里真正难的不是\"接入一个机器人\",而是让几十上百个人同时使用时,仍然保持每个人的上下文隔离。\n   - **插件做法**:按 `(底层账号 + 部门/群组/人员)` 动态切分运行上下文和 Agent 实例。\n   - **用户收益**:同一个企业微信入口可以承接多人并发使用,而不会出现\"张三的问题让李四接上回答\"的串流灾难。\n\n2. **长任务不白跑,回复不轻易丢**\n   - **问题本质**:企业微信长连接的响应窗口很短,而推理模型的思考时间往往很长。\n   - **插件做法**:先保活,再流式推进;必要时走备用投递路径,把最终结果交付出去。\n   - **用户收益**:更敢把复杂任务、长文本分析、报告生成交给 AI,而不是每次都担心\"算完了却发不回来\"。\n\n3. **实时对话体验和正式投递能力,不用二选一**\n   - **问题本质**:实时聊天和组织级推送,往往不是同一条技术路径最擅长的事。\n   - **插件做法**:会话内实时交互、流式回复、异步追发优先走 `Bot WS`;组织级广播、冷启动触达、正式通知由 `Agent` 兜底。\n   - **用户收益**:日常使用时体验像聊天助手,正式落地时又有企业应用该有的稳定性和控制力。\n\n4. **AI 不只会聊天,还能进入企业微信协作层**\n   - **问题本质**:如果 AI 只能回消息,信息最终还是散落在聊天流里,业务并没有真正被推进。\n   - **插件做法**:把企业微信原生协作能力按两条能力平面接入 OpenClaw。\n   - **用户收益**:AI 不仅能回答问题,还能真正参与文档、日程、会议、待办和通讯录相关工作。\n\n5. **小团队能低门槛上手,大团队也能正式上线**\n   - **问题本质**:小团队怕折腾,大团队怕失控。\n   - **插件做法**:`Bot WS` 适合快速启用,`Agent` 适合正式治理,两者可以并存。\n   - **用户收益**:您不用在\"今天先跑起来\"和\"将来能不能正规化\"之间做破坏性迁移。\n\n---\n\n## 📊 为什么不是只选 Bot,或者只选 Agent?\n\n从用户视角看,差别不在于协议名词,而在于**你要解决的是什么问题**。\n\n| 你真正关心的事 | 🤖 Bot 模式 (WebSocket) | 🧩 Agent 模式 (自建应用 API) | ✨ 本插件的做法 |\n|:---|:---|:---|:---|\n| **先跑起来的速度** | ✅ 快,无需固定公网 IP | ❌ 较重,需要正式应用配置 | ✅ 先用 Bot 起步,后续平滑补 Agent |\n| **实时聊天体验** | ✅ 最强,天然适合低延迟和流式回复 | ⚠️ 能收能发,但不是最佳对话入口 | ✅ 默认把实时交互交给 Bot |\n| **异步结果回推** | ✅ 可以,适合已建立会话内追发 | ✅ 可以 | ✅ 会话内追发优先 Bot,必要时 Agent 兜底 |\n| **组织级广播与冷启动触达** | ⚠️ 受会话边界约束 | ✅ 更适合 | ✅ 正式通知和广播走 Agent |\n| **企业微信协作能力** | ✅ 适合个人身份能力入口 | ✅ 适合应用身份能力入口 | ✅ 两种身份平面都兼容 |\n| **适合谁** | 想快速上线、重视实时体验的团队 | 需要正式治理、自动化和组织级能力的团队 | 想同时要\"体验\"和\"能力\"的团队 |\n\n> **建议理解方式:**\n> - 如果您最在意的是\"先接起来、先用起来、先聊顺\",优先上 `Bot WS`\n> - 如果您最在意的是\"正式部署、组织级能力、自动化治理\",补齐 `Agent`\n> - 如果您真正想把 AI 在企业微信里长期用下去,最终往往需要两者并存\n\n---\n\n## 🧩 企业微信协作能力:为什么这件事比\"能聊天\"更重要?\n\n很多企业微信 AI 机器人,本质上只是把答案发回聊天框。\n真正有价值的,是让 AI 进入您**已经在工作的地方**。\n\n在本插件里,企业微信的**文档、日程、会议、待办、通讯录**等能力,不再只是外围说明,而是被接成了可以实际调用的协作平面。\n\n### 1. Bot WS 协作模式:适合小团队的个人身份入口\n\n根据企业微信最新开放说明,面向 **5 人及以下的小微企业**,`Bot WS` 模式现已开放以**用户个人身份**调用部分企业微信协作能力。\n\n在本插件里,这条链路以 `wecom_mcp` 的方式挂载,只在 **WeCom Bot WS 会话** 中可用:\n\n- 能力入口:`wecom_mcp`\n- 典型能力品类:`doc`、`meeting`、`todo`、`contact`\n- 触发条件:当前会话必须来自 `Bot WS`\n- 更适合的场景:个人身份读写文档、查询通讯录、处理待办、操作会议等轻量协作场景\n\n它的价值在于:\n\n- **门槛低**:无需先走完整的自建应用接入流程\n- **身份自然**:更贴近当前聊天用户自己的协作上下文\n- **启动快**:对小团队尤其友好\n\n它的边界也要明确:\n\n- 依赖 `Bot WS` 会话存在\n- 主动推送仍然以**已建立会话**为前提\n- 实际开放范围以企业微信后台可见权限为准\n\n### 2. Agent 协作模式:适合正式落地的应用身份入口\n\n`Agent` 模式走的是**自建应用 API** 平面,更适合企业级稳定自动化与组织级治理。\n\n在本插件里,当前内置的协作工具主要包括:\n\n- `wecom_doc`:文档、表格、权限、分享可用性诊断等\n- `wecom_calendar`:日历、日程、参与人、回执、默认日历等\n\n它更适合:\n\n- 把协作能力放进正式企业应用权限体系\n- 与定时任务、异步流程、正式投递联动\n- 面向组织对象做更稳定的自动化操作\n\n### 3. 这两条能力链在插件里已经实际接通\n\n当前插件已经把这两条协作链路都注册进来:\n\n- `wecom_mcp`:仅在 `Bot WS` 会话中暴露\n- `wecom_doc`:仅在 `Agent` 会话中暴露\n- `wecom_calendar`:仅在 `Agent` 会话中暴露\n\n也就是说,您拿到的不是\"一个只能聊天的企微插件\",而是:\n\n- 一条适合实时对话和个人协作的入口\n- 一条适合正式应用和组织自动化的入口\n\n### 4. 授权方式\n\n请按所选平面分别授权:\n\n- **Bot WS 模式授权**:前往企业微信管理后台 👉「工作台 - 智能机器人」,找到对应机器人,点击编辑,在「可使用权限」处勾选文档、日程、会议、待办、通讯录等对应权限。\n- **Agent 模式授权**:前往企业微信管理后台 👉「工作台 - 协作 - 文档 / 日程 / 会议等」,将您的自建应用加入\"可调用接口的应用\"。\n\n一句话理解:\n\n- **Bot WS** 更像\"当前聊天用户的实时协作入口\"\n- **Agent** 更像\"企业正式应用身份下的自动化执行入口\"\n\n两者同时配置后,您既能拿到顺滑的实时交互,也能拿到企业级可治理的协作能力。\n\n---\n\n## 📋 最近更新 (Changelog摘要)\n\n> 项目保持高频迭代,全面对齐甚至超越企业真实业务诉求。\n> **为保持精简,以下仅展示近期 5 次重要更新,完整历史版本(含全部 `v2.2.x`)请前往 [changelog/ 目录](./changelog/) 查阅。**\n\n#### 📌 v2.8.0(2026-04-22)\n- **[能力扩充] 微信客服(kefu)全通道落地** 🆕 Agent/Bot 之外,新增“企业微信客服”作为第三条消息通道:外部客户在微信、视频号、对外小程序里发给客服号的消息可直接走到 OpenClaw 里回复。配置独立(`channels.wecom.accounts.<id>.kefu.{corpId,corpSecret,openKfIds,webhook}`),`corpSecret` 允许与 Agent 分开建一套“只给客服用”的 Secret。\n- **[通道独立] 回调路径解耦** 🛣️ 客服挂载到独立路径 `/plugins/wecom/kefu`(推荐)或 `/plugins/wecom/kefu/<accountId>`,与 Bot / Agent 路径互不冲突。企微客服回调只携带 Token,插件内部调用 `kf/sync_msg` 按 `open_kfid` 维度维护 cursor 完整拉取,配合 LRU `msgid` 去重与 in-flight 并发守卫,确保消息不重、不漏。\n- **[入向覆盖] 10 类消息全量归一** 📥 text/image/voice/video/file/link/miniprogram/msgmenu/location/business_card/event(含 `enter_session` 映射成 `welcome`)均已 normalize 成 `UnifiedInboundEvent`,下游 Agent 无感消费。\n- **[出向能力] send_msg 一体化** 📤 text 按 3500 字符切片避开 4096 字节上限、media 由 content-type+扩展名分类分别走 image/voice/video/file,link 走 `payload.channelData.kefu.link` 专用卡片,统一走 `upload_media` 拿 `media_id` 后下发。新增 `toKefuText` 把 markdown 扁平成 kefu `content` 能识别的纯文本(保留代码块/链接/列表项标识,剔除标题/粗体/HTML 等)。\n- **[会话自动路由] Source Registry 扩展** 🔁 `WecomSourcePlane` 新增 `\"kefu\"`,入向会记录 `kefuOpenKfId`;下一轮 Agent 主动回复时会自动走客服出向,不会误发到 Agent 内部私信。显式目标 `wecom-kefu:<accountId>:<openKfId>:<externalUserId>` 同样支持。\n\n#### 📌 v2.7.3(2026-04-21)\n- **[格式升级] 全线切换到 `markdown_v2`** 🎨 自建应用(Agent API) / 群机器人(Bot WS) / 主动回复(Bot Webhook response_url)全部改用企微 2026 年新的 `markdown_v2` 消息类型,**原生支持 markdown 表格、图片 `![](url)`、粗体、链接、代码块、嵌套引用、列表**,消息上限从 2048 字节提到 4096 字节。\n- **[逻辑简化] 移除 textcard 降级路径** 🧹 以前遇到表格/大标题/链接会被\"降级\"成 textcard(title + 512 字纯文本描述,丢失 markdown 格式),现在统一走 markdown_v2,富文本完整渲染,不再需要 textcard workaround。\n- **[兼容注意]** ⚠️ markdown_v2 不支持 `<font color>` 标签和 `@userid` 群成员 at(原 markdown 支持),如果你依赖这两个特性请用 text 消息或保留 v1。本插件 adapter 本来就不生成这两个语法,用户无感。\n\n#### 📌 v2.7.2(2026-04-21)\n- **[Bug 修复] 引用群文件显示\"COS链接过期\"** 🔧 同步上游引用文件处理逻辑,新增 `channels.wecom.media.downloadTimeoutMs` 配置(默认 30s),分级区分超时/5 分钟 TTL 过期/网络错误,避免大文件抓取失败。\n- **[Bug 修复] 安装插件被安全扫描拦截** 🔒 移除上游已回滚的 `src/agent/script-runner.ts`(使用了 `child_process.spawn`),不再触发 OpenClaw 的 `dangerous-exec` 规则,v2.7.2 可以直接通过 `npm` 或 `clawhub` 方式安装。\n- **[上游同步] 合并 yanhaidao/wecom 至 c1158a9** 📦 包含引用附件在群聊/私聊中透传、媒体下载超时配置、菜单事件文档等;同时吸收上游对 jjjkkil 两次 agentcation PR 的 revert。\n- **[版本对齐] 保留 `@huo15/wecom` 独立包名** 📦 包名保持 `@huo15/wecom`,版本号跳至 `2.7.2`。\n\n#### 📌 v2.3.273(2026-03-31)\n- **[重要修复] WS 断连 Fallback** 🔧 耗时任务/Gateway 重启/WS 断线重连时,Bot WS 自动切换到 Agent API 发送回复,不再出现\"机器人没反应\"的问题。\n- **[markdown 修复] 表格和代码块渲染恢复** 📦 从 main 分支合并,表格不再强制转为纯文本,保留 markdown 格式。\n- **[包名变更] `@yanhaidao/wecom` 更名为 `@huo15/wecom`** 📦 npm 包名已更新。\n\n#### 📌 v2.3.27(2026-03-27)\n- **[重要修复] `channel add` 重新支持 WeCom guided setup** 🧭 之前有些环境下,`wecom` 虽然已经安装,却仍会在 OpenClaw 里显示成 \"does not support guided setup yet\",导致无法直接通过交互式向导添加。现在插件已经对齐 OpenClaw 当前的 `setupWizard` 接口,`openclaw channels add` 会重新正常识别和进入配置流程。\n- **[重要修复] 修复 `installedCatalogById is not defined`** 🔧 部分用户在渠道添加或选择阶段会直接遇到 `ReferenceError: installedCatalogById is not defined`,表现上像是\"选了渠道就报错\"或\"添加流程突然失效\"。这一版已经修复对应的目录访问逻辑,添加流程恢复稳定。\n- **[升级兼容] 清理 OpenClaw 新版下失效的 SDK 旧入口** 📦 这次同步迁移了 `wecom` 插件里几处已经不再建议继续从 `openclaw/plugin-sdk` 根入口直接拿的旧接口,重点覆盖工具上下文、outbound 适配器和 Bot WS 媒体发送链路,升级 OpenClaw 后更不容易再出现\"有的地方能跑、有的地方直接炸\"的兼容问题。\n\n#### 📌 v2.3.26(2026-03-26)\n- **[重要修复] 升级 OpenClaw 后不再乱报错** 🔧 修复了新版 OpenClaw 下 `wecom` 插件容易出现的 `is not a function` 一类启动/运行错误。\n- **[回复更稳] Agent 和 Bot WS 不再乱串** ↔️ 现在是谁收到消息,就尽量由谁来回复,不再容易出现\"在 Agent 里说话,结果 Bot WS 回你\"的情况。\n- **[体验修复] Bot WS 发图后不再多冒一条 `Done...`** 🖼 之前常见表现是:`正在思考` -> 图片 -> 又多一条完成提示。现在最终收尾会尽量接回原来的回复链路。\n- **[占位符修复] 不会一直卡在\"正在思考...\"** ⏳ 如果图片或文本已经发出去了,占位符会更自然地结束,不会继续无意义地刷屏。\n\n#### 📌 v2.3.19(2026-03-19)\n- **[重要修复] Bot WS 现在也真正走 `dynamicAgents`** 🧭 之前同样开启动态路由时,不同消息链路的行为并不完全一致:Webhook / Agent 能按用户、群聊隔离,Bot WebSocket 却可能重新落回主 Agent。现在 WS 运行时也执行同样的动态路由逻辑,会话隔离终于统一了。\n- **[配置统一] 媒体大小开始优先跟随 OpenClaw 标准 `mediaMaxMb`** 📦 之前 WeCom 插件更偏向读取自己的 `media.maxBytes`,用户改了 OpenClaw 主配置却可能感觉\"改了没生效\"。现在插件优先支持 `channels.wecom.mediaMaxMb`,并支持 `channels.wecom.accounts.<accountId>.mediaMaxMb` 做账号级覆盖;旧配置仍兼容,但只作为兜底。\n- **[体验修复] 常见本地目录文件现在更符合直觉地可发送** 🖼 过去本地媒体白名单更偏向 OpenClaw 自己目录,导致像 `Downloads`、`Desktop`、`Pictures` 里的图片明明存在,却常被拦下。现在插件默认额外放行这些常见用户目录,同时保留 `channels.wecom.media.localRoots` 继续追加共享盘、挂载盘和业务目录。\n\n#### 📌 v2.3.18(2026-03-18)\n- **[重大升级] 双平面能力融合(Bot WS + MCP 强化)** 🚀 独家引入挂载式的 MCP 能力层。在保留原生 Agent 强力工具的同时,将官方新开放的企业微信能力暴露给大模型。现在,大模型可凭用户身份读写待办、日程、查通讯录。\n- **[多账号硬隔离]** 彻底重构 MCP 缓存池实现 `accountId + category` 的二次硬维隔离,无论您的矩阵挂载了多少家企业的助手,上下文及鉴权缓存绝不会交叉重叠。\n- **[媒体通道重构]** 补齐 Bot WS 本地的媒体上传链,同时设立了严格的 `5秒熔断机制`,若 WebSocket 长通道大文件卡死将无感静默降级到 Agent 私信发送。\n\n*(查看更早期关于\"超时熔断代投、动态扩容矩阵\"等功能的更新日志，请移步 [changelog/ 目录](./changelog/))*\n\n---\n\n## 一、🚀 快速开始\n\n> 推荐统一使用**多账号矩阵模型**。\n> 即使您的企业只接入了一个账号,也强烈建议将其配入 `channels.wecom.accounts.default` 节点下。\n\n### 1.1 插件安装\n\n```bash\nopenclaw plugins install @yanhaidao/wecom\nopenclaw plugins enable wecom\n```\n\n### 1.2 互动向导式初配 (适合个人开发者与极客)\n\n如果您不想手写繁杂的 JSON 配置文件,可以通过交互式向导快速完成最轻量的 WebSocket 长连接部署。`v2.3.27` 起,`wecom` 已重新对齐 OpenClaw 当前的 guided setup 流程,`openclaw channels add` 可以直接识别并进入配置:\n\n1. 确保已启用本插件。\n2. 在终端运行添加渠道指令:\n   ```bash\n   openclaw channels add\n   ```\n3. 选择下拉列表中第一顺位的:**企业微信 (WeCom)**\n4. 根据终端亮色指引,填入企微机器人对应的 `Bot ID` 及 `Secret`,机器人即可完成握手并进入可用状态。\n\n> **如果您最近刚升级 OpenClaw:**\n> - 若之前在添加渠道时看到 `wecom does not support guided setup yet`,请更新到当前版本后重试。\n> - 若之前在渠道添加阶段见过 `ReferenceError: installedCatalogById is not defined`,这一版也已一并修复。\n\n### 1.3 生产环境顶配架构示范(Bot WS 流式交互 + Agent 私有通道兜底发送)\n\n如果您的目标不是\"接进来能聊两句\",而是让团队在企业微信里长期稳定使用 AI,这套组合更接近生产环境的推荐形态:\n\n- `Bot WS` 负责实时对话、低延迟流式回复和更轻的接入门槛\n- `Agent` 负责主动推送、媒体发送和长任务后的兜底交付\n- `dynamicAgents` 负责把不同用户、不同群聊的会话真正隔离开,避免多人共用一个入口时互相串上下文\n\n请进入 OpenClaw 配置文件(`openclaw.json`)的 `channels.wecom` 内使用:\n\n```jsonc\n{\n  \"channels\": {\n    \"wecom\": {\n      \"enabled\": true,\n      \"defaultAccount\": \"default\",\n      \"accounts\": {\n        \"default\": {\n          \"enabled\": true,\n          \"name\": \"企微销售二部支持中枢\",\n          \"bot\": {\n            \"primaryTransport\": \"ws\",             // 指定 Bot 主通讯协议:ws 或 webhook\n            \"streamPlaceholderContent\": \"正在深思熟虑,请稍候...\", // 避免流式回复开始前长时间无反馈\n            \"welcomeText\": \"你好,我是已连网的专属大脑。\",\n            \"dm\": {\n              \"policy\": \"pairing\",\n              \"allowFrom\": []\n            },\n            \"ws\": {                               // Bot WS 建连所需凭证\n              \"botId\": \"YOUR_BOT_ID\",\n              \"secret\": \"YOUR_BOT_SECRET\"\n            }\n          },\n          \"agent\": {                              // 主动推送、媒体发送与兜底交付链路\n            \"corpId\": \"YOUR_CORP_ID\",\n            \"agentSecret\": \"YOUR_AGENT_SECRET\",\n            \"agentId\": 1000001,\n            \"token\": \"AGENT_TOKEN\",\n            \"encodingAESKey\": \"AGENT_AES_KEY\",\n            \"welcomeText\": \"若长连接断开,我将使用此通道传递残存报告。\",\n            \"dm\": {\n              \"policy\": \"open\",\n              \"allowFrom\": []\n            }\n          }\n        }\n      },\n      \"mediaMaxMb\": 50,                           // 优先使用 OpenClaw 标准媒体上限配置\n      \"media\": {\n        \"tempDir\": \"/tmp/openclaw-wecom-media\",\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\"\n        ]\n      },\n      \"network\": {                                // 内网或受限网络环境可通过代理出网\n        \"egressProxyUrl\": \"http://127.0.0.1:3128\"\n      },\n      \"dynamicAgents\": {                          // 为单聊/群聊创建独立路由,减少多人串上下文\n        \"enabled\": true,\n        \"dmCreateAgent\": true,\n        \"groupEnabled\": true,\n        \"adminUsers\": [\"zhangsan001\"]             // 管理员绕过动态路由,直连主 Agent\n      }\n    }\n  }\n}\n```\n\n其中:\n\n- 插件现在默认额外放行常见用户目录:`~/Desktop`、`~/Documents`、`~/Downloads`、`~/Movies`、`~/Pictures`。\n- `channels.wecom.mediaMaxMb` 是首选的媒体大小上限配置,`channels.wecom.accounts.<id>.mediaMaxMb` 可以做账号级覆盖。\n- `channels.wecom.media.localRoots` 用于继续追加你自己的全局目录,例如共享盘、挂载盘或业务导出目录。\n- 旧的 `channels.wecom.media.maxBytes` 仍然兼容,但仅作为向后兼容兜底;新配置建议统一改成 `mediaMaxMb`。\n- 这些目录会和 OpenClaw 默认允许的媒体目录一起生效,不会覆盖默认白名单。\n- 也就是说,像 `~/Downloads/01.png` 这类本机文件现在默认就可以直接发到企微,不需要再单独配置。\n\n> **注意:** 历史配置里的 `agent.corpSecret` 引擎依然能够向后兼容拾起,但后续的新项目推荐采用标准的 `agentSecret` 作为对齐键。\n\n### 1.4 dynamicAgents 详细说明:为什么生产环境建议开启\n\n`dynamicAgents` 的核心价值,不是\"自动创建很多 Agent\",而是让企业微信里的每个用户、每个群聊都拥有稳定、独立的会话落点。\n如果不开它,所有消息更容易汇入同一个主 Agent;一旦开始多人共用,最先出问题的通常不是模型能力,而是上下文、长期记忆和处理边界混在一起。\n\n更简单地看,可以直接按下面这张表决定要不要开:\n\n| 场景 | 不开时的问题 | 建议配置 | 你得到的结果 |\n|---|---|---|---|\n| 多个同事同时私聊同一个机器人 | 容易共用同一条会话脉络,长期上下文可能互相污染 | `enabled=true` + `dmCreateAgent=true` | 每个人都有自己的稳定上下文 |\n| 一个或多个群长期拿机器人协作 | 不同群更容易共用主 Agent,群与群之间边界不清晰 | `enabled=true` + `groupEnabled=true` | 每个群都有独立会话空间 |\n| 管理员需要统一测试、巡检、接管 | 管理员也会被切进自己的动态 Agent,排障更分散 | `adminUsers=[\"管理员userid\"]` | 管理账号继续直连主 Agent |\n| 只是做 PoC 或单人试用 | 一上来就启用隔离,理解成本偏高 | `enabled=false` | 先把连通性和基础回复跑通 |\n\n系统当前的真实行为如下:\n\n- 开启后,会按 `账号 + 会话类型 + 对端 ID` 生成确定性的 Agent ID,例如 `wecom-default-dm-zhangsan` 或 `wecom-default-group-wr123456`\n- 同一个用户或同一个群,下次再发消息时会继续命中同一个动态 Agent,而不是临时随机分配\n- 首次命中时,插件会自动把这个动态 Agent 追加到 `agents.list`,不需要您手工维护一长串列表\n- 这套逻辑同时作用于 `Bot WS` 和 `Agent Callback` 两条主消息链路,不是只有某一种模式才生效\n- `adminUsers` 中的账号会始终绕过动态路由,直接走主 Agent,适合放管理员、运营或排障账号\n- 默认值是 `enabled=false`、`dmCreateAgent=true`、`groupEnabled=true`、`adminUsers=[]`,也就是不开总开关时不会生效,但一旦开启,单聊和群聊会默认一起进入隔离模式\n\n需要注意的是,`dynamicAgents` 解决的是\"路由隔离\"和\"会话隔离\",不是权限系统本身。\n也就是说,它能显著减少上下文串线,但账号是否允许私聊、谁能触发命令、某个账号绑定到哪个主 Agent,仍然要结合 `dm.policy`、`bindings` 和企业微信授权配置一起看。\n\n### 1.5 `localRoots` 详细说明:为什么\"文件明明存在\",系统却仍然不发\n\n`localRoots` 只决定一件事:**这个本地路径允不允许被当作可发送媒体读取。**\n\n| 现象 | 实际含义 |\n|---|---|\n| 文件存在,但发送失败 | 不代表系统允许读取它 |\n| 日志出现 `Local media path is not under an allowed directory` | 路径不在白名单里 |\n| 远程 `https://...` 媒体可以发 | 远程 URL 不走 `localRoots` |\n\n默认已经额外放行这些目录:\n\n| 默认允许目录 | 用途 |\n|---|---|\n| `~/Desktop` | 桌面文件、临时截图 |\n| `~/Documents` | 文档导出目录 |\n| `~/Downloads` | 下载图片、下载文件 |\n| `~/Movies` | 视频文件 |\n| `~/Pictures` | 图片、相册导出 |\n\n另外也保留 OpenClaw 自己的 `tmp / state / workspace` 相关目录。\n\n如果文件不在默认目录里,再补 `localRoots`:\n\n```json\n{\n  \"channels\": {\n    \"wecom\": {\n      \"media\": {\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\",\n          \"/mnt/nas/public\"\n        ]\n      }\n    }\n  }\n}\n```\n\n配置规则:\n\n| 规则 | 说明 |\n|---|---|\n| `localRoots` 是追加 | 不会覆盖默认目录 |\n| 建议写绝对路径 | 团队环境更稳定、更清楚 |\n| 只加业务需要的目录 | 不要为了省事把范围放太大 |\n| 不建议放整个大盘或整个用户目录 | 会把本地文件读取边界放得过宽 |\n\n排障判断:\n\n| 问题类型 | 看什么 |\n|---|---|\n| 本地路径是否允许读取 | `localRoots` |\n| 媒体能处理多大 | `channels.wecom.mediaMaxMb` |\n| 企业微信最终能不能收 | 企业微信自身媒体限制 |\n| 远程媒体能不能发 | URL 可访问性,不看 `localRoots` |\n\n一句话:`localRoots` 管\"能不能读这个本地路径\",`mediaMaxMb` 管\"最多读多大\"。\n\n---\n\n## 二、🏢 企业微信后台回调挂载指南 (针对使用了 Webhook 或 Agent Callback 的重度用户)\n\n如果您需要让 Agent 通道接收复杂的地理位置及交互式卡片事件,需要将系统的路径下发到企业微信管理后台。\n由于系统默认采纳**多账号分流路径派生**,请切记不要随意丢弃末尾的 `{accountId}`,如下所示:\n\n| 类型 | 您的 OpenClaw 可信域名 | 默认账号路由锚点 | 如果配置了 Ops 项目组子账号 |\n|---|---|---|---|\n| **Bot Webhook** | `https://x.com` | `/plugins/wecom/bot/default` | `/plugins/wecom/bot/ops` |\n| **Agent Callback** | `https://x.com` | `/plugins/wecom/agent/default`| `/plugins/wecom/agent/ops` |\n\n*警告:极度不推荐将老旧单一根路径(如 `/plugins/wecom/bot`)在未指定账户空间下裸奔使用,一旦您的业务扩张到第二个账号,将会引发难以追溯的回调抢占雪崩。*\n\n---\n\n## 三、📡 排障与抓包:洞悉黑盒下的脉搏\n\n当前版本请使用以下三条命令组合排障。注意:`openclaw channels status` **不支持** `--deep`,插件级探测参数是 `--probe`;`--deep` 属于顶层 `openclaw status`。\n\n### 3.1 先看插件级状态快照\n\n```bash\nopenclaw channels status --probe\n```\n\n适合回答这些问题:\n\n- 企业微信账号是否已被网关识别并加载\n- 账号当前是否 `enabled` / `configured`\n- 运行时是否 `running` / `connected` / `authenticated`\n- 最近一次错误、最近进出站时间是否异常\n\n如果网关可达,这条命令会返回企业微信账号的运行时快照。\n如果网关不可达,它会自动退化为\"只看配置\"的摘要输出。\n\n### 3.2 再看全局深度诊断\n\n```bash\nopenclaw status --deep\n```\n\n这条命令是 **OpenClaw 全局诊断入口**,适合确认:\n\n- Gateway 本身是否健康\n- 当前机器上的整体通道探测是否正常\n- 最近心跳、会话、服务状态是否异常\n\n当您怀疑问题不只在企业微信插件,而是 Gateway、网络、配置路径或其他通道共同影响时,优先跑这条。\n\n### 3.3 最后直接看 WeCom 日志\n\n```bash\nopenclaw channels logs --channel wecom --lines 200\n```\n\n当发生疑难连接断开、消息不回、媒体文件下发神秘消失时,直接看日志最有效。新版日志已经被精细地切分在不同命名空间锚点下,助你顺藤摸瓜:\n\n- `[wecom-runtime]`:统一运行时主线。看收消息、分发、回消息、最近错误与会话归属漂移。\n- `[wecom-ws]`:Bot WebSocket 通道。看连接、鉴权、断线、重连、帧收发与保活。\n- `[wecom-agent-delivery]`:Agent 主动发送链路。看用户/部门/标签目标解析、媒体发送和账号错配。\n\n### 3.4 推荐排障顺序\n\n建议按下面顺序执行:\n\n```bash\nopenclaw channels status --probe\nopenclaw status --deep\nopenclaw channels logs --channel wecom --lines 200\n```\n\n您可以按输出这样判断:\n\n- `configured=false`:先检查 `bot.ws.botId`、`bot.ws.secret`、`agent.corpId`、`agent.agentSecret`、`agent.agentId` 等配置是否完整。\n- `running=false`:说明账号没有真正启动,优先看 `[wecom-runtime]`。\n- `connected=false` 或 `authenticated=false`:优先看 `[wecom-ws]`,一般是 WebSocket 握手、密钥或连接稳定性问题。\n- 能收不能发,或群里发文件/卡片失败:优先看 `[wecom-agent-delivery]`。\n- `lastError` 持续刷新:通常不是一次性误报,建议结合最近 200 行日志一起看。\n\n---\n\n## 四、🤝 项目鸣谢\n\n感谢所有为本项目提交代码、测试、文档与反馈的协作者。\n\n- **原始项目**:[yanhaitao/wecom](https://github.com/yanhaitao/wecom)\n\n<p align=\"center\">\n  <a href=\"https://github.com/YanHaidao/wecom/graphs/contributors\">\n    <img src=\"https://contrib.rocks/image?repo=YanHaidao/wecom\" alt=\"WeCom contributors\" />\n  </a>\n</p>\n\n如果头像墙没有立刻刷新,通常是 GitHub 统计或第三方缓存延迟,稍后再看即可。\n\n---\n\n## 五、📮 版权与许可证协议指引\n\n<div align=\"center\">\n\n**公司名称：** 青岛火一五信息科技有限公司\n\n**联系邮箱：** postmaster@huo15.com | **QQ群：** 1093992108\n\n---\n\n**关注逸寻智库公众号，获取更多资讯**\n\n<img src=\"https://tools.huo15.com/uploads/images/system/qrcode_yxzk.jpg\" alt=\"逸寻智库公众号二维码\" style=\"width: 200px; height: auto; margin: 10px 0;\" />\n\n</div>\n\n### 最后的话:关于开源及署名\n本项目版权归 **青岛火一五信息科技有限公司** 所有,遵循 **ISC License**。\n您可以将其用于极其广阔的项目天地中。但开源不是拿来主义:\n在此明确强调,包括所谓的\"Bot+Agent 保活接力超时融合机制\"、\"千人千面多账户切面\"、\"自动寻的路由下沉\" 这背后全是作者无数个在企业真实现网撞墙实验出的架构结晶。**拒绝一切去除原作者署名、粗暴改名换姓占为己用的魔改上架行为。**\n愿我们能在彼此尊重的前提下,共同拓展 OpenClaw 生态的无垠边界。\n\nFile v2.9.1:_meta.json\n\n{\n  \"ownerId\": \"kn7byevkn40d6z4p7ghdb097z983tj33\",\n  \"slug\": \"huo15-wecom-plugin\",\n  \"version\": \"2.9.1\",\n  \"publishedAt\": 1778134121963\n}\n\nFile v2.9.1:changelog/v2.2.28.md\n\n# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.2.28 - 多账号隔离与稳定性增强\n\n本次 v2.2.28 版本是 **OpenClaw 企业微信 (WeCom) 插件** 的一次重大里程碑更新。我们深度优化了 **微信 / 企业微信** 办公场景下的多智能体隔离逻辑，并修复了生命周期、XML 数据保真等多个生产环境的核心痛点。\n\n本次更新让 **OpenClaw** 在处理企业级复杂 **插件** 配置时更加得心应手，完美解决大模型接入 **WeCom** 的所有阻碍。\n\n---\n\n### 🌟 版本亮点 (Release Highlights)\n\n*   🎯 **多账号矩阵支持**：支持按 `accountId` 进行组内会话隔离。不同部门、不同业务的 **企业微信** 机器人可并行运行，互不干扰，彻底解决跨账号串会话问题。\n*   🔐 **数据保真解析**：针对 **WeCom** 的 XML 消息解析进行了重构。关闭了自动数值化，保留 `FromUserName` 前导 `0`，并完美解决 64 位 `MsgId` 精度风险。\n*   🔁 **Gateway 生命周期适配**：完美兼容最新版 **OpenClaw** Gateway 的生命周期管理，修复了在高频心跳监测下的重启循环问题，运行更稳健。\n*   🧹 **入站消息过滤**：优化了 **微信** 与 **企业微信** 的事件过滤逻辑，避免系统事件、缺失发送者等无效消息进入 AI 会话，防止“误回复”。\n*   🧱 **配置安全护栏**：新增 **企业微信** 账号冲突检测。自动拦截重复的 `bot.token` 或 `agentId` 配置，并提供友好的中文错误提示。\n\n---\n\n### 📝 详细更新日志 (Changelog)\n\n#### 【重磅更新】🎯 多账号/多智能体可用性增强\n- 支持按 `accountId` 做组内隔离（Bot + Agent + 路由绑定同组生效）。\n- 动态 Agent 与会话键增加 `accountId` 维度，避免跨账号串会话。\n\n#### 【稳定性】🔁 生命周期兼容修复\n- 适配新版 **OpenClaw** Gateway 生命周期，`startAccount` 改为长生命周期运行。\n- 修复了“几秒一次重启 + health-monitor 二次重启”的循环问题。\n\n#### 【准确性】🔐 XML 字段保真修复\n- **WeCom** Agent XML 解析关闭自动数值化，保留发送者原始 ID。\n- 避免 `MsgId` (64bit) 精度损失，确保回复目标不被误改。\n\n#### 【准确性】🧹 误回复修复\n- Bot/Agent 入站均增加事件过滤，避免处理 `event`、`sys` 及缺失发送者的消息。\n- 修复群聊缺失 `chatid` 时仍进入 AI 会话的问题，避免“一个消息触发多人误回复”。\n\n#### 【可控性】🧱 配置安全护栏\n- 新增多账号冲突检测，自动拦截重复 Token 或 Agent ID 的配置。\n- **账号管理修复**：`deleteAccount` 现在仅删除目标账号，不再误删整个 **插件** 的 `channels.wecom` 配置。\n\n#### 【质量保障】✅ 自动化回归\n- 新增账号解析、冲突检测、动态路由隔离、生命周期与入站过滤的多项自动化测试。\n- **文档优化**：README 快速开始文档更新，优先展示“多账号 + 多 Agent”矩阵配置。\n\n---\n\n### 💾 安装与升级 (Install & Update)\n\n使用 **OpenClaw** CLI 即可一键升级 **插件**：\n\n```bash\nopenclaw plugins upgrade wecom\n```\n\n或手动更新配置：\n```bash\nopenclaw config set channels.wecom.enabled true\n```\n\n---\n\n### 🔍 SEO 关键词 (Keywords)\n**openclaw** | **企业微信** | **微信** | **wecom** | **插件** | **AI 机器人** | **大模型网关** | **流式响应** | **多账号隔离** | **WeCom Plugin**\n\n---\n\n### 📮 联系我们\n如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 或加入我们的交流群。\n\n> **提示**：建议 **OpenClaw** 主程序版本保持在 **2026.2.24+** 以获得最佳体验。\n\nFile v2.9.1:changelog/v2.3.10.md\n\n# OpenClaw WeCom 插件 v2.3.10 变更简报\n\n> [!TIP]\n> **默认更易用、修复更直接的版本。**\n\n## 2026-03-10（v2.3.10）\n- 【消息防丢修复】🐛 **[重要修复]** 针对由于模型 API 限速或超长思考（如 DeepSeek R1）导致的企微 WebSocket 5秒超时断连问题，引入了 4 秒前置保活机制（自动下发\"⏳ 正在思考中...\"），彻底阻断了因为模型响应慢而造成的“消息卡死不再回复”。\n- 【双重回复修复】🐛 **[重要修复]** 修复 `Bot WS` 长文本场景下可能被超时截断并触发兜底通道进行二次重复回复的边界异常。\n- 【向导自动路由】✨ **[体验升级]** 重构了企业微信的渠道交互配置向导。在单账号场景下将静默触发自动路由绑定，丝滑跳过 OpenClaw 全局冗长的 Agent 路由分配询问。\n- 【账号兜底修复】🧩 修复企业微信 onboarding 在首个账号非字面量 `default` 时，后续流程报 `WeCom account \"default\" not found` 的问题。\n- 【默认选项收敛】🚀 onboarding 的默认回车选项已变更为更普适的 `Bot` 模式、`WS` 接入和 `开放模式` 策略。\n- 【字段命名收敛】📝 Agent 新配置统一推荐使用 `agentSecret`，历史 `corpSecret` 保持兼容读取，保障平滑升级。\n- 【文档与提示精简】📘 README、向导交互文案与示例结构已全面统一为更符合直觉的精简说明。\n\n## 验证结果\n- `bunx vitest run extensions/wecom/src/onboarding.test.ts extensions/wecom/src/channel.meta.test.ts`\n- `pnpm build`\n\nFile v2.9.1:changelog/v2.3.11.md\n\n# OpenClaw WeCom 插件 v2.3.11 变更简报\n\n> [!TIP]\n> **稳定性与多账号说明版本**：`v2.3.11` 重点修复 Bot WS 长思考场景下的 `invalid req_id`，同步收敛 onboarding 账号默认值与多账号隔离文档说明。\n\n## 2026-03-11（v2.3.11）\n- 【WS 保活升级】🚀 **[重要修复]** Bot WebSocket 从“4 秒后补发占位”升级为“收到用户消息立即下发占位符，并在长思考期间持续保活”，显著降低慢模型或长任务下的 `invalid req_id` 与回复丢失风险。\n- 【占位符配置生效】🌊 `bot.streamPlaceholderContent` 现在对 `Bot WS` 与 `Bot Webhook` 两条链路统一生效，配置一次即可保持体验一致。\n- 【错误兜底收敛】🛡 修复 `req_id` 已失效时仍尝试二次回错消息的问题，避免出现重复报错与未处理 Promise 拒绝。\n- 【账号选择兜底】🧩 onboarding 在“配置里还没有任何账号”时，也会显式提供 `default` 默认账号选项，减少首次接入时的困惑。\n- 【多账号文档补强】📘 README 新增说明：如果多个 `accountId` 复用同一个静态 Agent，建议配合 `session.dmScope = \"per-account-channel-peer\"`，避免不同账号的私聊上下文共用。\n- 【日志可读性】🔎 WeCom runtime 的 Bot WS 失败日志改为可读错误文本，排查时不再只看到 `[object Object]`。\n\n## 验证结果\n- `pnpm exec vitest run extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/onboarding.test.ts`\n\n## 升级提示\n- 已有 `bot.streamPlaceholderContent` 配置无需调整，升级后 `Bot WS` 会自动使用它。\n- 如果你在同一个 OpenClaw 实例里挂了多个 WeCom 账号，并让它们指向同一个静态 Agent，建议补上 `session.dmScope = \"per-account-channel-peer\"` 以隔离私聊上下文。\n\nFile v2.9.1:changelog/v2.3.12.md\n\n# OpenClaw WeCom 插件 v2.3.12 变更简报\n\n> [!TIP]\n> **WS 主动推送与过期更新兜底版本**：`v2.3.12` 重点修复企业微信 Bot WebSocket 在流式回复超过 6 分钟后返回 `846608 stream message update expired`，并同步调整主动消息路由为“WS 文本优先、Agent 文件兜底”。\n\n## 2026-03-12（v2.3.12）\n- 【6 分钟过期修复】🛠 **[重要修复]** `Bot WS` 现在会把企业微信 `846608 stream message update expired (>6 minutes)` 识别为回复窗口已结束的终态错误，不再继续把该错误向上抛出导致进程退出。\n- 【主动推送路由收敛】🚀 **[重要修复]** 当账号实际运行在 `Bot WS` 模式时，定时消息、heartbeat 和其他主动文本发送现在优先走 `wsClient.sendMessage()`，不再默认绕去 Agent。\n- 【WS/Agent 职责切分】🧩 `Agent` 现在主要承担两类兜底：一是账号没有启用 `Bot WS` 时的主动消息发送；二是 Bot 两种模式都不支持的文件/媒体发送。\n- 【UserID 纯数字解析修复】🛠 **[重要修复]** 解决 Agent 模式下纯数字 UserID 被误判为部门 ID 导致的图片发送失败（81013 错误）。在 `wecom-agent:` 作用域下，纯数字目标现在优先解析为用户。\n- 【未处理拒绝隔离】🧯 `sdk-adapter` 为每个 WebSocket frame 的异步处理补上显式兜底捕获；即使后续再出现漏网异常，也会记录到 runtime issue，而不是变成 `unhandledRejection` 直接带崩 OpenClaw。\n- 【占位保活收敛】⏱ 当回复窗口已经过期时，WS 占位符保活会立即停止，避免过期后继续发送流式更新。\n- 【Ack 超时兜底】⏱ SDK 5 秒回执超时 (`Reply ack timeout`) 现在也被识别为终态错误，超时后立即停止占位保活并走 `onFail` 回调，不再产生 `unhandledRejection`。\n- 【回归测试补齐】✅ 新增针对 `846608` 过期更新和 `frame handler` reject 的回归测试，确保此类异常保持非致命。\n- 【Bot WS 图片/文件解密修复】🛠 **[重要修复]** `Bot WS` 模式下接收到的图片和文件现在会使用消息体中的独立 `aeskey` 进行 AES-256-CBC 解密，修复之前直接保存密文导致 `Failed to optimize image` 的问题。`media-service.ts` 新增 `downloadEncryptedMedia()` 方法，`normalizeFirstAttachment()` 自动检测 `aesKey` 并走解密路径。\n\n## 验证结果\n- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec vitest -c extensions/wecom/vitest.config.ts extensions/wecom/src/outbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`\n\n## 升级提示\n- 无需新增配置，升级到 `v2.3.12` 后自动生效。\n- 如果账号正在使用 `Bot WS`，主动文本消息会优先走 WS 长连接；只有文件/媒体或未启用 WS 的场景才会继续使用 Agent。\n- 如果模型或工具链路存在超长执行，超过企业微信 6 分钟回复窗口时，OpenClaw 现在会保持存活并记录运行时错误，不再因该异常退出。\n\nFile v2.9.1:changelog/v2.3.13.md\n\n# OpenClaw WeCom 插件 v2.3.13 变更简报\n\n> [!TIP]\n> **Bot WS 引用上下文与流式展示修复版本**：`v2.3.13` 重点补齐企业微信 `Bot WS` 对引用消息的上下文注入，并修复长回答在客户端里显示为“断断续续碎片”的问题。\n\n## 2026-03-13（v2.3.13）\n- 【引用上下文补齐】🛠 **[重要修复]** `Bot WS` 现在会复用与 `Bot Webhook` 一致的入站正文拼装逻辑。用户通过“引用 + 提问”触发机器人时，引用内容会一并进入 Agent 上下文，不再只保留当前这句提问。\n- 【WS 流式刷新修复】🌊 **[重要修复]** `Bot WS replyStream` 现在按“累计全文刷新”发送，而不是只发送最新增量片段，修复企业微信客户端中长回答显示断断续续、像被拆成多块的问题。\n- 【协议语义对齐】🧩 这次调整显式对齐企业微信 `stream.id` 的刷新语义：同一条流式消息的后续更新会覆盖为“当前完整内容”，从而保持最终展示稳定、可连续阅读。\n- 【回归测试补齐】✅ 新增 `bot-ws` 引用上下文与累计流式发送测试，避免后续重构再次把引用消息或流式展示打回退。\n\n## 验证结果\n- `pnpm exec vitest run --config extensions/wecom/vitest.config.ts extensions/wecom/src/transport/bot-ws/inbound.test.ts extensions/wecom/src/transport/bot-ws/reply.test.ts extensions/wecom/src/transport/bot-ws/sdk-adapter.test.ts`\n- `pnpm exec tsc -p extensions/wecom/tsconfig.json --noEmit`\n\n## 升级提示\n- 无需新增配置，升级到 `v2.3.13` 后自动生效。\n- 如果企业微信 `WS` 推送里的 `quote.text.content` 仍然是 `[该消息类型暂不能展示]`，说明上游没有下发真实引用原文；OpenClaw 会把该占位文本带入上下文，但无法恢复企业微信未提供的原始内容。\n- 如果你之前观察到长回复在企业微信里呈现为“分段断裂”或“后段覆盖前段”，升级后会改为同一条流式消息持续刷新完整内容。\n\nFile v2.9.1:changelog/v2.3.14.md\n\n# OpenClaw WeCom 插件 v2.3.14 变更简报\n\n> [!TIP]\n> **企业微信“协作文档”原生整合与长连接稳定性修复版本**：`v2.3.14` 将机器人的能力从“陪聊”正式拓展到了“办公协同”。现在，你可以直接在微信群里让机器人去填报销单、建项目表；同时我们也彻底修复了多人并发聊天时机器人“正在思考”卡死刷屏的问题。\n>\n> 📣 **特别感谢** [@proyy](https://github.com/proyy) 提供的企业微信文档管理解决方案，使本版本的 Docs 能力得以落地。\n\n## 重磅功能：把聊天直接变成企业文档（用后即得）\n\n我们受够了问 AI 一个问题，答案最后只能被新消息顶没。这次更新，我们让机器人获得了操作“企业微信协作文档”的实体权限。\n\n### 场景 1：开新项目，不用再求人建表格拉权限了\n- **以前**：你在群里说“准备一下下周的活动追踪表”，然后得切出去打开文档中心，新建表格，再一个个抄名字把大家拉进来。\n- **现在**：直接在群里 `@机器人 帮我建一个名为『春季新品发布会追踪』的表格，并把群里的人都加上可写权限`。机器人建好后会直接在群里甩出一个链接，所有人点开就能直接编辑，全程零切换。\n\n### 场景 2：坐在地铁上，照样神操作填报销/跟进数据\n- **以前**：你刚下班，群里有人问“今天 C 组的面试谁通过了？”你只能回答“我等下回家用电脑打开「面试记录表」改一下状态”。全量改动很容易把别人的同行数据覆盖掉。\n- **现在**：你可以直接发语音或者敲字 `@机器人 把「第二周面试记录表」里的 B2 到 B5 单元格全部更新为“二面通过”`。机器人会像操作手术刀一样，只精准替换指定的数据块（`spreadsheet.edit_data`），丝毫不影响文档里的其他公式。\n\n### 场景 3：直接让 AI 读懂全公司的数据报表\n- **以前**：你要先自己把表格下载成 Excel，再一段段复制数据发给大模型：“帮我算算这堆数据谁最高”。\n- **现在**：你直接丢给他一个企微文档链接：`@机器人 分析一下这张表里的第一季度数据，告诉我谁的单产最差？`。由于具备了原生读取能力（`get_sheet_range_data`），它会自己去拉取数据查表，给你输出结论。\n\n## 💡 Docs 权限配置指引（只需一次）\n\n为了让上述场景跑通，光配 `agentSecret` 是不够的。这是因为哪怕是公司自建的机器人，默认也没资格动你们内部的文档资产。你需要：\n1. **去企微后台发“通行证”**：进入 [企业微信后台 -> 协作 -> 文档 -> 可调用接口的应用](https://work.weixin.qq.com/wework_admin/frame#apps/qykit/proxy/wedoc)，把你的机器人应用放进白名单。\n2. **在 OpenClaw 里激活能力**：打开 UI 界面 的 `Settings` -> `Agents` -> `Tools`，找到 `wecom`，把带有 `doc` 字眼的所有工具（创建文档、读取表格、改权限等）通通打勾。\n\n\n## 核心修复：终结“正在思考...”刷屏噩梦\n除了新功能，这次我们也彻底对长连接（WS）卡死问题做了一次大手术：\n- 🛑 **告别并发刷屏**：群里人多手杂的时候，以前机器人如果处理不过来，不仅不回话，还会满屏一直弹“正在思考...”。现在只要有一条真回复发出来，它会自动把同群里那些卡死、过期的“正在思考”全部瞬间清理干净。\n- 📡 **进群欢迎语报错 846605 终结**：修复了大家常反馈的“有人一进群，后台就疯狂报 invalid req_id”的陈年老 Bug。现在对进群、推卡片等非聊天事件，我们全面切换成了专属接口，彻底避免违规流式推送。\n- 🛡 **120 秒物理断网**：即使模型源站点挂了，我们现在也会在 120 秒内强制熔断提示，绝不让你面对一个无限转圈的加载框。\n\n---\n## 验证结果\n- `pnpm test -- src/transport/bot-ws`\n- 所有 WS 回复通道单测已全部通过，尤其是关于 `setInterval` 占位符存活期的验证得到了补全与修复。\n\n## 升级指引\n```bash\nopenclaw plugins update wecom\n```\n- 无需新增配置，执行上述命令即可一键升级到 `v2.3.14`。\n- 升级后，如果你拉几十个机器人进群并同时发言，曾经那种满屏飘“正在思考...”却无人回答的乱象将不复存在。\n- 如果之前查看后台日志总是看到 `stream message update expired (>6 minutes)` 甚至因为连带引发的 WS 断网重启，本次升级将大幅度平息日志告警红字，稳定长连接状态。\n\nFile v2.9.1:changelog/v2.3.15.md\n\n# OpenClaw WeCom 插件 v2.3.15 变更简报\n\n> [!TIP]\n> **企业微信文档写入稳定性与消息目标路由修复版本**：`v2.3.15` 重点解决了企微文档 `init_content` 初始化内容写入不稳定、图片插入失败、批量更新索引错误，以及群聊回复时容易触发的 `81013` 目标解析错误。同时，这次也补回并完善了文档、在线表格、智能表格、收集表等能力，避免相关工具调用缺接口或直接失败。\n\n## 2026-03-14（v2.3.15）\n- 【文档初始化内容修复】🛠 **[重要修复]** 创建企微文档时，`init_content` 现在会按官方 Wedoc 流程执行：图片先上传再插入，文本与图片段落会基于最新索引和版本号写入，减少标题正文错位、图片不显示、内容插到错误位置的问题。\n- 【批量更新稳定性修复】📄 **[重要修复]** 修复 `document.batch_update` 的索引计算与模式切换问题。混合执行 `insert_paragraph`、`insert_text`、`insert_image` 时，不再更容易触发 `ParagraphValidator`、`TextValidator`、`DrawingValidator` 一类报错。\n- 【文档客户端能力恢复】🔧 重新补齐此前精简时误删的企微文档客户端接口，恢复文档权限、在线表格、智能表格、收集表等相关方法，避免工具层调用缺方法、返回异常或直接不可用。\n- 【在线表格与收集表支持补齐】📊 完善企微在线表格和收集表的类型定义、参数校验与错误提示。现在会更早拦截超出 API 限制的请求，例如表格行列/单元格数量超限、收集表题目结构缺失、选项题参数不完整等问题。\n- 【群聊目标解析修复】💬 **[重要修复]** 修复企业微信群聊回复时 `To` 字段被错误硬编码为用户目标的问题。群聊、私聊、部门、标签目标现在会按正确前缀解析，减少发送时报 `81013 user & party & tag all invalid` 的情况。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.15`。\n- 如果你之前遇到“建文档成功但内容没写进去”“图片插不进去”“批量更新偶发报索引错误”或“群里回复机器人时报 81013”，本次升级后会明显改善。\n\nFile v2.9.1:changelog/v2.3.16.md\n\n# OpenClaw WeCom 插件 v2.3.16 变更简报\n\n> [!TIP]\n> **企业微信 Bot-WS 混合消息附件解析修复版本**：`v2.3.16` 重点解决了在 WebSocket 模式下，企业微信机器人接收到的混合消息（如同时包含图片和文字）由于解析遗漏导致附件丢失、AI 只能看到带签名的临时链接文本而无法查看真正图片内容的问题。\n\n## 2026-03-16（v2.3.16）\n- 【混合消息媒体解析修复】🛠 **[重要修复]** 补齐了 Bot WebSocket 传输通道（`bot-ws`）下对 `mixed` 结构消息的附件提取逻辑。现在，当用户在企微发出一条包含图片/文件与文字的混合消息时，底层框架会自动遍历并提取各个媒体节点的 URL 和 AES Key，确保核心处理管线能进行正常下载与安全解密。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.16`。\n- 如果你之前在企微发出“带图的一段话”时，曾遇到 AI 回复说“这是一个腾讯 COS 的临时签名链接”，本次升级后，此问题将被修复，AI 将可以直接分析图片内容本身。\n\nFile v2.9.1:changelog/v2.3.18.md\n\n# OpenClaw WeCom 插件 v2.3.18 变更简报\n\n> [!TIP]\n> **企业微信面向中小企业的新能力开放版本**：`v2.3.18` 重点完善了 `wecom` 插件在 Bot WebSocket 场景下的能力层。现在，面向 5 人及以下小企业，OpenClaw 已支持以用户个人身份在企业微信内使用文档读写、日程读写、会议读写、待办读写、通讯录查询等能力。同时，本次也补齐了 Bot WS 媒体发送、建立了 Bot 与 Agent 双平面路由，并修复了企业微信里容易卡在“正在思考...”不结束的问题。\n\n## 2026-03-18（v2.3.18）\n- 【中小企业能力开放】🚀 **[重大更新]** 面向 5 人及以下小企业，OpenClaw 在企业微信内正式开放以用户个人身份使用的协作能力入口。现在，大模型可以在具备相应授权的前提下，调用企业微信文档读写、日程读写、会议读写、待办读写以及通讯录查询等能力，把原本分散在多个协作入口中的企业操作集中到同一条智能对话链路中。\n- 【新增 Bot WS MCP 工具层】新增 `wecom_mcp` 工具，将企业微信 Bot WS 能力以挂载式能力层接入 `wecom` 插件。现在 Bot 侧可以按业务类别动态获取 MCP 配置，并把企业微信开放的能力暴露给大模型调用。\n- 【建立 Bot / Agent 双平面路由】新增基于会话来源的能力分流。Bot WS 会话优先使用 `wecom_mcp`；Agent 回调会话继续保留原生 `wecom_doc`、`wecom_calendar` 工具链，避免不同能力面互相干扰。\n- 【多账号能力隔离加强】MCP 相关缓存和状态改为按 `accountId + category` 隔离。在多账号矩阵下，同一类能力不会再共用同一份 Bot 侧配置，减少串账号、串上下文、串连接状态的问题。\n- 【补齐 Bot WS 命令与媒体链】扩展 Bot WS 运行时接口，除了主动文本发送外，现在还支持命令桥接、连接状态探测和媒体发送。Bot WebSocket 会话下的图片、文件回复不再必须依赖 Agent API 补送。\n- 【新增媒体发送提示注入】在企业微信 Bot WS 会话里定向注入 `MEDIA:` 使用提示，帮助模型更稳定地触发图片和文件回复，同时避免把这类提示扩散到非 WeCom 或 Agent 会话。\n- 【修复回复流不收口问题】**[重要修复]** 处理 Bot WS 回复时，带媒体的中间块不再错误中断文本发送。现在文本会先正常下发，媒体在结束阶段继续处理；如果上游没有显式 final，系统也会自动补一个收口帧，避免企业微信里长期停留在“正在思考...”。\n- 【欢迎语路径提速】`enter_chat` 欢迎事件在配置静态欢迎语时改为直发，不再额外启动完整推理流程。首次进入会话时的响应更直接，链路也更短。\n- 【运行时日志增强】新增更细的派发与投递日志，包括 `dispatch-start`、`dispatch-done`、`dispatch-fail`、`deliver-start`、`deliver-done`。现在排查问题时可以更快区分是模型处理慢、回复已被企微确认、MCP 类别未开通，还是本地媒体路径被限制拦截。\n- 【能力边界提示更明确】当企业微信后台只开放部分能力时，插件会更明确地把限制反馈给用户和日志。例如只开通文档类能力时，待办、会议、日程类请求会直接提示当前账号尚未开放对应能力，而不是表现成模糊失败。\n\n## 升级提示\n- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.18`。\n- 本次版本是企业微信能力面的重要开放版本，尤其适合希望在企业微信内直接完成文档、日程、会议、待办与通讯录协作的小型团队。\n- 如果你之前在企业微信 Bot WS 会话里只看到反复“正在思考...”、最终不出结果，本次升级后应已修复。\n- 如果你希望在企业微信里直接使用会议、待办、日程等 Bot 侧能力，请同时确认企业微信后台已经为当前 Bot 开通相应业务类别；插件侧已经具备调用链，但实际可用范围仍以企业微信侧授权为准。\n\nArchive v2.9.0: 242 files, 498742 bytes\n\nFiles: changelog/v2.2.28.md (3745b), changelog/v2.3.10.md (1572b), changelog/v2.3.11.md (1837b), changelog/v2.3.12.md (3259b), changelog/v2.3.13.md (2018b), changelog/v2.3.14.md (4670b), changelog/v2.3.15.md (2241b), changelog/v2.3.16.md (1113b), changelog/v2.3.18.md (4080b), changelog/v2.3.19.md (6771b), changelog/v2.3.2.md (2795b), changelog/v2.3.26.md (1830b), changelog/v2.3.27.md (4345b), changelog/v2.3.273.md (680b), changelog/v2.3.4.md (1755b), changelog/v2.3.9.md (1711b), changelog/v2.4.12.md (4707b), changelog/v2.4.16.md (1157b), changelog/v2.7.4.md (2724b), changelog/v2.8.0.md (3687b), changelog/v2.8.1.md (2230b), changelog/v2.8.17.md (7630b), changelog/v2.8.18.md (3377b), changelog/v2.8.19.md (5692b), changelog/v2.8.2.md (2496b), changelog/v2.8.20.md (7103b), changelog/v2.8.21.md (8625b), changelog/v2.8.22.md (6594b), changelog/v2.8.23.md (6868b), changelog/v2.8.24.md (7061b), changelog/v2.8.25.md (5291b), changelog/v2.8.26.md (6532b), changelog/v2.8.27.md (5994b), changelog/v2.8.28.md (3728b), changelog/v2.8.29.md (4665b), changelog/v2.8.3.md (3447b), changelog/v2.8.30.md (4967b), changelog/v2.8.31.md (6539b), changelog/v2.8.32.md (1368b), changelog/v2.8.6.md (3301b), changelog/v2.8.8.md (5098b), changelog/v2.9.0.md (6833b), compat-single-account.md (4135b), GOVERNANCE.md (1301b), index.test.ts (1058b), index.ts (5408b), openclaw.plugin.json (11593b), package.json (2717b), README.md (31424b), scripts/release.sh (11536b), scripts/test-proxy.ts (2377b), SKILL.md (4871b), SKILLS_CAL.md (29478b), SKILLS_DOC.md (70311b), src/accounts.ts (1223b), src/agent/api-client.upload.test.ts (3909b), src/agent/handler.event-filter.test.ts (3469b), src/agent/handler.ts (39593b), src/agent/index.ts (248b), src/app/account-runtime.ts (11247b), src/app/bootstrap.ts (890b), src/app/index.ts (6075b), src/capability/agent/delivery-service.ts (4475b), src/capability/agent/fallback-policy.ts (484b), src/capability/agent/index.ts (221b), src/capability/agent/ingress-service.ts (1126b), src/capability/agent/upstream-delivery-service.ts (3728b), src/capability/bot/dispatch-config.ts (1854b), src/capability/bot/fallback-delivery.ts (6892b), src/capability/bot/index.ts (58b), src/capability/bot/local-path-delivery.ts (8059b), src/capability/bot/sandbox-media.test.ts (7025b), src/capability/bot/sandbox-media.ts (5688b), src/capability/bot/service.ts (1651b), src/capability/bot/stream-delivery.ts (16654b), src/capability/bot/stream-finalizer.ts (5769b), src/capability/bot/stream-orchestrator.ts (16350b), src/capability/bot/types.ts (352b), src/capability/calendar/client.ts (36126b), src/capability/calendar/index.ts (133b)\n\nFile v2.9.0:SKILL.md\n\n---\nname: huo15-wecom\ndescription: \"火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担心 stream 截断 + 86008 把链接设为优先，v2.8.23/v2.8.24 修了群聊主动推送通道 + UI 锁交互后 MEDIA: 路径稳定可靠，应用户偏好翻转：默认 MEDIA: 直发，仅大文件（> 企微上限）才走 enhance_share_file 链接。GUIDANCE 加决策表 + 用户偏好覆盖。继承 v2.8.24 placeholder timeout 解锁、v2.8.23 群聊主动推送、v2.8.20 MEDIA: parser。Use when: 接企业微信、给企微 Bot/自建应用接 OpenClaw、用微信客服收外部用户消息、需要图片/文件双向、跨账号切换。Do NOT use for 个人微信（不同协议）。\"\nversion: 2.9.0\nhomepage: https://cnb.cool/huo15/ai/huo15-wecom-plugin\nmetadata: { \"openclaw\": { \"emoji\": \"🦜\", \"requires\": { \"bins\": [] } } }\n---\n\n# 火一五企业微信插件\n\n`@huo15/wecom` 是 OpenClaw 的企业微信通道插件，fork 自 [yanhaidao/wecom](https://github.com/yanhaidao/wecom) 并持续合并上游。**默认 Bot WebSocket 模式**，配置简单、响应快；同时支持 Agent 自建应用主动推送和微信客服三方通道。\n\n## 三条消息通道\n\n| 通道 | 用途 | 配置入口 |\n|---|---|---|\n| **Bot WebSocket** | 默认推荐，企业微信\"智能机器人\"WS 协议，免公网回调 | `channels.wecom.accounts.<id>.bot.ws` |\n| **Agent 自建应用** | 走企微官方 API（CorpId/AgentId/Secret），支持主动推送给指定用户/群 | `channels.wecom.accounts.<id>.agent` |\n| **微信客服** | 接管\"客服会话\"，外部客户在微信/视频号里发给客服账号的消息 | `channels.wecom.accounts.<id>.kefu` |\n\n三条通道可以**单独启用**或**组合启用**，多账号场景每个账号独立配置。\n\n## 安装\n\n```bash\n# OpenClaw 内置安装（推荐）\nopenclaw plugins install @huo15/wecom\n\n# 或者直接 npm\nnpm install @huo15/wecom\n```\n\n## 最小配置（Bot WS 模式）\n\n```yaml\n# ~/.openclaw/openclaw.json 中\nchannels:\n  wecom:\n    enabled: true\n    accounts:\n      default:\n        bot:\n          ws:\n            botId: \"你的智能机器人 ID\"\n            secret: \"WS 密钥\"\n```\n\n启动后，Bot 收到的消息会自动路由到默认 Agent，回复也通过 WS 直接送回 — 不需要部署任何回调 endpoint。\n\n## 关键能力\n\n- **加密媒体解密**：图片/文件/语音 AES-256-CBC 解密直接拿 buffer，可让 Agent 直接读取（OCR / ASR / 文档解析）\n- **Markdown V2**：支持企微富文本（标题、表格、代码块、链接、引用），自动适配 chat 上下文\n- **图片回复**：`![alt](url)` 自动抽离 + uploadMedia + replyMedia，COS/OSS 预签名 URL 失败时降级为占位文本（不让\"链接已过期\"漏到客户端）\n- **多账号切换**：单实例支持多个企业、多个智能体并存，按 conversation 路由\n- **流式回复**：placeholder + partial replyStream（最多 8 次中间更新）+ ack timeout watchdog 自动重连\n\n## v2.8.8 关键修复（WS BOT 图片）\n\n1. **Reply 通道纠错**：reply 上下文从 `sendMediaMessage`（主动推送）改用 `replyMedia`（被动回复，绑定 reqId）\n2. **入向多图**：`mixed` 与 `quote.mixed` 类型从只取首张改为全部提取；首张挂 `ctx.MediaPath`，其余落盘 + info 日志\n3. **Outbound fetch UA**：从裸 `fetch` 切到 plugin-sdk `fetchRemoteMedia`，显式带 desktop User-Agent，避免部分 Tencent COS / 阿里 OSS bucket 拒绝 Node 默认 UA\n4. **解析可观测性**：媒体类型消息但无 attachments 时记 warn 日志（含 msgid + body keys），便于 SDK 字段漂移排查\n\n详见 [changelog/v2.8.8.md](./changelog/v2.8.8.md)。\n\n## 安全实践\n\n- LLM 输出的 `touser` / `chatid` 经 `resolveWecomTarget` sanitizer，**拒绝 `@all` / `@everyone` / `*` 等广播字面量**（v2.8.1 SECURITY 修复）\n- 跨企业上下游消息走 upstream-delivery 通道，不与本企业 Agent API 混用\n- 微信客服 `corpSecret` 可与 Agent `corpSecret` 独立配置，权限隔离\n\n## 不变的设计原则\n\n- **Bot WS 优先**：能用 WS 就不用 Agent API（少配置、低延迟）\n- **失败降级**：WS reply ack timeout 自动 fallback 到 Agent API（保留消息可达性），watchdog 连续 8 次后触发 WS 重连\n- **不修改 OpenClaw 核心**：所有功能通过 channel plugin SDK 注册\n\n## 仓库\n\n- 主仓库：https://cnb.cool/huo15/ai/huo15-wecom-plugin\n- 镜像：https://github.com/zhaobod1/huo15-wecom-plugin\n- 上游 fork 源：https://github.com/yanhaidao/wecom（**仅 fetch，不 push**）\n\n## License\n\nISC（继承自 yanhaidao/wecom 上游）。\n\nFile v2.9.0:README.md\n\n# OpenClaw 企业微信(WeCom)Channel 插件\n\n<p align=\"center\">\n  <a href=\"https://github.com/yanhaitao/wecom\"><img src=\"https://img.shields.io/badge/Original%20Project-逸寻智库-orange?style=for-the-badge&logo=github\" alt=\"Original Project\" /></a>\n  <img src=\"https://img.shields.io/badge/License-ISC-blue?style=for-the-badge\" alt=\"License\" />\n  <img src=\"https://img.shields.io/badge/Min%20Recommended-2.8.1+-red?style=for-the-badge\" alt=\"Minimum recommended\" />\n</p>\n\n> [!CAUTION]\n> **🛡️ 安全公告（2026-04-22）**：受影响版本 `<= 2.8.0`。Agent 在工作区写自定义脚本时可能把 `touser=\"@all\"` 当默认收件人，导致原本私聊的图片/视频/文档**被广播到企业微信应用可见范围全员**。\n>\n> **请所有部署立即升级到 `@huo15/wecom@2.8.1` 或以上**。修复见 [`changelog/v2.8.1.md`](changelog/v2.8.1.md)。\n\n> [!WARNING]\n> **原创声明**:本项目涉及的\"多账号隔离与矩阵路由架构\"、\"Bot+Agent双模融合架构\"、\"长任务超时接力逻辑\"及\"全自动媒体流转接\"等核心设计均为作者 **YanHaidao** 独立思考与实践的原创成果。\n> 欢迎技术交流与合规引用,但严禁任何不经授权的\"功能像素级抄袭\"或删除原作者署名的代码搬运行为。\n\n<p align=\"center\">\n  <strong>🚀 企业级多模式 AI 助手接入方案(统一运行时架构)</strong>\n</p>\n\n---\n\n## 💡 核心价值:为什么团队会真正选择这个插件?\n\n企业真正需要的,不是\"把一个模型接进企业微信\",而是让企业微信变成一个**能长期工作的 AI 协作入口**。\n\n大多数团队最终只关心五件事:\n\n- 能不能先低门槛接起来,而不是先做一轮重部署\n- 多人同时使用时,会不会串上下文、串身份、串会话\n- 长任务会不会因为长连接窗口太短而白跑\n- 能不能既有实时对话体验,又能做正式推送和稳定投递\n- AI 能不能真正进入文档、日程、会议、待办、通讯录这些协作层,而不只是停留在聊天框\n\n常见方案通常会很快碰到边界:\n\n- **只用 Bot WS**:接得快、聊得顺,但会受到单连接、心跳保活、会话边界和组织级广播能力的限制\n- **只用 Agent**:能力强、治理清晰,但部署门槛更高,对话体验不如 Bot WS 丝滑\n- **只选单一路径**:团队最后往往被迫在\"体验\"和\"能力\"之间二选一\n\n本插件的价值,就在于把这些原本互相冲突的目标,尽量同时成立。\n\n### 您真正会得到什么?\n\n1. **多人共用一个入口,但上下文不会串**\n   - **问题本质**:企业里真正难的不是\"接入一个机器人\",而是让几十上百个人同时使用时,仍然保持每个人的上下文隔离。\n   - **插件做法**:按 `(底层账号 + 部门/群组/人员)` 动态切分运行上下文和 Agent 实例。\n   - **用户收益**:同一个企业微信入口可以承接多人并发使用,而不会出现\"张三的问题让李四接上回答\"的串流灾难。\n\n2. **长任务不白跑,回复不轻易丢**\n   - **问题本质**:企业微信长连接的响应窗口很短,而推理模型的思考时间往往很长。\n   - **插件做法**:先保活,再流式推进;必要时走备用投递路径,把最终结果交付出去。\n   - **用户收益**:更敢把复杂任务、长文本分析、报告生成交给 AI,而不是每次都担心\"算完了却发不回来\"。\n\n3. **实时对话体验和正式投递能力,不用二选一**\n   - **问题本质**:实时聊天和组织级推送,往往不是同一条技术路径最擅长的事。\n   - **插件做法**:会话内实时交互、流式回复、异步追发优先走 `Bot WS`;组织级广播、冷启动触达、正式通知由 `Agent` 兜底。\n   - **用户收益**:日常使用时体验像聊天助手,正式落地时又有企业应用该有的稳定性和控制力。\n\n4. **AI 不只会聊天,还能进入企业微信协作层**\n   - **问题本质**:如果 AI 只能回消息,信息最终还是散落在聊天流里,业务并没有真正被推进。\n   - **插件做法**:把企业微信原生协作能力按两条能力平面接入 OpenClaw。\n   - **用户收益**:AI 不仅能回答问题,还能真正参与文档、日程、会议、待办和通讯录相关工作。\n\n5. **小团队能低门槛上手,大团队也能正式上线**\n   - **问题本质**:小团队怕折腾,大团队怕失控。\n   - **插件做法**:`Bot WS` 适合快速启用,`Agent` 适合正式治理,两者可以并存。\n   - **用户收益**:您不用在\"今天先跑起来\"和\"将来能不能正规化\"之间做破坏性迁移。\n\n---\n\n## 📊 为什么不是只选 Bot,或者只选 Agent?\n\n从用户视角看,差别不在于协议名词,而在于**你要解决的是什么问题**。\n\n| 你真正关心的事 | 🤖 Bot 模式 (WebSocket) | 🧩 Agent 模式 (自建应用 API) | ✨ 本插件的做法 |\n|:---|:---|:---|:---|\n| **先跑起来的速度** | ✅ 快,无需固定公网 IP | ❌ 较重,需要正式应用配置 | ✅ 先用 Bot 起步,后续平滑补 Agent |\n| **实时聊天体验** | ✅ 最强,天然适合低延迟和流式回复 | ⚠️ 能收能发,但不是最佳对话入口 | ✅ 默认把实时交互交给 Bot |\n| **异步结果回推** | ✅ 可以,适合已建立会话内追发 | ✅ 可以 | ✅ 会话内追发优先 Bot,必要时 Agent 兜底 |\n| **组织级广播与冷启动触达** | ⚠️ 受会话边界约束 | ✅ 更适合 | ✅ 正式通知和广播走 Agent |\n| **企业微信协作能力** | ✅ 适合个人身份能力入口 | ✅ 适合应用身份能力入口 | ✅ 两种身份平面都兼容 |\n| **适合谁** | 想快速上线、重视实时体验的团队 | 需要正式治理、自动化和组织级能力的团队 | 想同时要\"体验\"和\"能力\"的团队 |\n\n> **建议理解方式:**\n> - 如果您最在意的是\"先接起来、先用起来、先聊顺\",优先上 `Bot WS`\n> - 如果您最在意的是\"正式部署、组织级能力、自动化治理\",补齐 `Agent`\n> - 如果您真正想把 AI 在企业微信里长期用下去,最终往往需要两者并存\n\n---\n\n## 🧩 企业微信协作能力:为什么这件事比\"能聊天\"更重要?\n\n很多企业微信 AI 机器人,本质上只是把答案发回聊天框。\n真正有价值的,是让 AI 进入您**已经在工作的地方**。\n\n在本插件里,企业微信的**文档、日程、会议、待办、通讯录**等能力,不再只是外围说明,而是被接成了可以实际调用的协作平面。\n\n### 1. Bot WS 协作模式:适合小团队的个人身份入口\n\n根据企业微信最新开放说明,面向 **5 人及以下的小微企业**,`Bot WS` 模式现已开放以**用户个人身份**调用部分企业微信协作能力。\n\n在本插件里,这条链路以 `wecom_mcp` 的方式挂载,只在 **WeCom Bot WS 会话** 中可用:\n\n- 能力入口:`wecom_mcp`\n- 典型能力品类:`doc`、`meeting`、`todo`、`contact`\n- 触发条件:当前会话必须来自 `Bot WS`\n- 更适合的场景:个人身份读写文档、查询通讯录、处理待办、操作会议等轻量协作场景\n\n它的价值在于:\n\n- **门槛低**:无需先走完整的自建应用接入流程\n- **身份自然**:更贴近当前聊天用户自己的协作上下文\n- **启动快**:对小团队尤其友好\n\n它的边界也要明确:\n\n- 依赖 `Bot WS` 会话存在\n- 主动推送仍然以**已建立会话**为前提\n- 实际开放范围以企业微信后台可见权限为准\n\n### 2. Agent 协作模式:适合正式落地的应用身份入口\n\n`Agent` 模式走的是**自建应用 API** 平面,更适合企业级稳定自动化与组织级治理。\n\n在本插件里,当前内置的协作工具主要包括:\n\n- `wecom_doc`:文档、表格、权限、分享可用性诊断等\n- `wecom_calendar`:日历、日程、参与人、回执、默认日历等\n\n它更适合:\n\n- 把协作能力放进正式企业应用权限体系\n- 与定时任务、异步流程、正式投递联动\n- 面向组织对象做更稳定的自动化操作\n\n### 3. 这两条能力链在插件里已经实际接通\n\n当前插件已经把这两条协作链路都注册进来:\n\n- `wecom_mcp`:仅在 `Bot WS` 会话中暴露\n- `wecom_doc`:仅在 `Agent` 会话中暴露\n- `wecom_calendar`:仅在 `Agent` 会话中暴露\n\n也就是说,您拿到的不是\"一个只能聊天的企微插件\",而是:\n\n- 一条适合实时对话和个人协作的入口\n- 一条适合正式应用和组织自动化的入口\n\n### 4. 授权方式\n\n请按所选平面分别授权:\n\n- **Bot WS 模式授权**:前往企业微信管理后台 👉「工作台 -...","readmeExcerpt":"Skill: Huo15 Wecom Plugin Owner: zhaobod1 Summary: 火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担... Tags: latest:2.9.5, plugin:2.8.30 Version history: v2.9.5 | 2026-05-10T18:38:42.867Z | auto - Added a new CHANGELOG.md file for improved change tracking. - Updated openclaw.plugin.json and package.json for th","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# OpenClaw 内置安装（推荐）\nopenclaw plugins install @huo15/wecom\n\n# 或者直接 npm\nnpm install @huo15/wecom"},{"language":"yaml","snippet":"# ~/.openclaw/openclaw.json 中\nchannels:\n  wecom:\n    enabled: true\n    accounts:\n      default:\n        bot:\n          ws:\n            botId: \"你的智能机器人 ID\"\n            secret: \"WS 密钥\""},{"language":"bash","snippet":"openclaw plugins install @yanhaidao/wecom\nopenclaw plugins enable wecom"},{"language":"bash","snippet":"openclaw channels add"},{"language":"jsonc","snippet":"{\n  \"channels\": {\n    \"wecom\": {\n      \"enabled\": true,\n      \"defaultAccount\": \"default\",\n      \"accounts\": {\n        \"default\": {\n          \"enabled\": true,\n          \"name\": \"企微销售二部支持中枢\",\n          \"bot\": {\n            \"primaryTransport\": \"ws\",             // 指定 Bot 主通讯协议:ws 或 webhook\n            \"streamPlaceholderContent\": \"正在深思熟虑,请稍候...\", // 避免流式回复开始前长时间无反馈\n            \"welcomeText\": \"你好,我是已连网的专属大脑。\",\n            \"dm\": {\n              \"policy\": \"pairing\",\n              \"allowFrom\": []\n            },\n            \"ws\": {                               // Bot WS 建连所需凭证\n              \"botId\": \"YOUR_BOT_ID\",\n              \"secret\": \"YOUR_BOT_SECRET\"\n            }\n          },\n          \"agent\": {                              // 主动推送、媒体发送与兜底交付链路\n            \"corpId\": \"YOUR_CORP_ID\",\n            \"agentSecret\": \"YOUR_AGENT_SECRET\",\n            \"agentId\": 1000001,\n            \"token\": \"AGENT_TOKEN\",\n            \"encodingAESKey\": \"AGENT_AES_KEY\",\n            \"welcomeText\": \"若长连接断开,我将使用此通道传递残存报告。\",\n            \"dm\": {\n              \"policy\": \"open\",\n              \"allowFrom\": []\n            }\n          }\n        }\n      },\n      \"mediaMaxMb\": 50,                           // 优先使用 OpenClaw 标准媒体上限配置\n      \"media\": {\n        \"tempDir\": \"/tmp/openclaw-wecom-media\",\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\"\n        ]\n      },\n      \"network\": {                                // 内网或受限网络环境可通过代理出网\n        \"egressProxyUrl\": \"http://127.0.0.1:3128\"\n      },\n      \"dynamicAgents\": {                          // 为单聊/群聊创建独立路由,减少多人串上下文\n        \"enabled\": true,\n        \"dmCreateAgent\": true,\n        \"groupEnabled\": true,\n        \"adminUsers\": [\"zhangsan001\"]             // 管理员绕过动态路由,直连主 Agent\n      }\n    }\n  }\n}"},{"language":"json","snippet":"{\n  \"channels\": {\n    \"wecom\": {\n      \"media\": {\n        \"localRoots\": [\n          \"/srv/company-share\",\n          \"/data/reports\",\n          \"/mnt/nas/public\"\n        ]\n      }\n    }\n  }\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: huo15-wecom\ndescription: \"火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担心 stream 截断 + 86008 把链接设为优先，v2.8.23/v2.8.24 修了群聊主动推送通道 + UI 锁交互后 MEDIA: 路径稳定可靠，应用户偏好翻转：默认 MEDIA: 直发，仅大文件（> 企微上限）才走 enhance_share_file 链接。GUIDANCE 加决策表 + 用户偏好覆盖。继承 v2.8.24 placeholder timeout 解锁、v2.8.23 群聊主动推送、v2.8.20 MEDIA: parser。Use when: 接企业微信、给企微 Bot/自建应用接 OpenClaw、用微信客服收外部用户消息、需要图片/文件双向、跨账号切换。Do NOT use for 个人微信（不同协议）。\"\nversion: 2.9.4\nhomepage: https://cnb.cool/huo15/ai/huo15-wecom-plugin\nmetadata: { \"openclaw\": { \"emoji\": \"🦜\", \"requires\": { \"bins\": [] } } }\n---\n\n# 火一五企业微信插件\n\n`@huo15/wecom` 是 OpenClaw 的企业微信通道插件，fork 自 [yanhaidao/wecom](https://github.com/yanhaidao/wecom) 并持续合并上游。**默认 Bot WebSocket 模式**，配置简单、响应快；同时支持 Agent 自建应用主动推送和微信客服三方通道。\n\n## 三条消息通道\n\n| 通道 | 用途 | 配置入口 |\n|---|---|---|\n| **Bot WebSocket** | 默认推荐，企业微信\"智能机器人\"WS 协议，免公网回调 | `channels.wecom.accounts.<id>.bot.ws` |\n| **Agent 自建应用** | 走企微官方 API（CorpId/AgentId/Secret），支持主动推送给指定用户/群 | `channels.wecom.accounts.<id>.agent` |\n| **微信客服** | 接管\"客服会话\"，外部客户在微信/视频号里发给客服账号的消息 | `channels.wecom.accounts.<id>.kefu` |\n\n三条通道可以**单独启用**或**组合启用**，多账号场景每个账号独立配置。\n\n## 安装\n\n```bash\n# OpenClaw 内置安装（推荐）\nopenclaw plugins install @huo15/wecom\n\n# 或者直接 npm\nnpm install @huo15/wecom\n```\n\n## 最小配置（Bot WS 模式）\n\n```yaml\n# ~/.openclaw/openclaw.json 中\nchannels:\n  wecom:\n    enabled: true\n    accounts:\n      default:\n        bot:\n          ws:\n            botId: \"你的智能机器人 ID\"\n            secret: \"WS 密钥\"\n```\n\n启动后，Bot 收到的消息会自动路由到默认 Agent，回复也通过 WS 直接送回 — 不需要部署任何回调 endpoint。\n\n## 关键能力\n\n- **加密媒体解密**：图片/文件/语音 AES-256-CBC 解密直接拿 buffer，可让 Agent 直接读取（OCR / ASR / 文档解析）\n- **Markdown V2**：支持企微富文本（标题、表格、代码块、链接、引用），自动适配 chat 上下文\n- **图片回复**：`![alt](url)` 自动抽离 + uploadMedia + replyMedia，COS/OSS 预签名 URL 失败时降级为占位文本（不让\"链接已过期\"漏到客户端）\n- **多账号切换**：单实例支持多个企业、多个智能体并存，按 conversation 路由\n- **流式回复**：placeholder + partial replyStream（最多 8 次中间更新）+ ack timeout watchdog 自动重连\n\n## v2.8.8 关键修复（WS BOT 图片）\n\n1. **Reply 通道纠错**：reply 上下文从 `sendMediaMessage`（主动推送）改用 `replyMedia`（被动回复，绑定 reqId）\n2. **入向多图**：`mixed` 与 `quote.mixed` 类型从只取首张改为全部提取；首张挂 `ctx.MediaPath`，其余落盘 + info 日志\n3. **Outbound fetch UA**：从裸 `fetch` 切到 plugin-sdk `fetchRemoteMedia`，显式带 desktop User-Agent，避免部分 Tencent COS / 阿里 OSS bucket 拒绝 Node 默认 UA\n4. **解析可观测性**：媒体类型消息但无 attachments 时记 warn 日志（含 msgid + body keys），便于 SDK 字段漂移排查\n\n详见 [changelog/v2.8.8.md](./changelog/v2.8.8.md)。\n\n## 安全实践\n\n- LLM 输出的 `touser` / `chatid` 经 `resolveWecomTarget` sanitizer，**拒绝 `@all` / `@everyone` / `*` 等广播字面量**（v2.8.1 SECURITY 修复）\n- 跨企业上下游消息走 upstream-delivery 通道，不与本企业 Agent API 混用\n- 微信客服 `corpSecret` 可与 Agent `corpSecret` 独立配置，权限隔离\n\n## 不变的设计原则\n\n- **Bot WS 优先**：能用 WS 就不用 Agent API（少配置、低延迟）\n- **失败降级**：WS reply ack timeout 自动 fallback 到 Agent API（保留消息可达性），watchdog 连续 8 次后触发 WS 重连\n- **不修改 OpenClaw 核心**：所有功能通过 channel plugin SDK 注册\n\n## 仓库\n\n- 主仓库：https://cnb.cool/huo15/ai/huo15-wecom-plugin\n- 镜像：https://github.com/zhaobod1/huo15-wecom-pl"},{"path":"README.md","content":"# OpenClaw 企业微信(WeCom)Channel 插件\n\n<p align=\"center\">\n  <a href=\"https://github.com/yanhaitao/wecom\"><img src=\"https://img.shields.io/badge/Original%20Project-逸寻智库-orange?style=for-the-badge&logo=github\" alt=\"Original Project\" /></a>\n  <img src=\"https://img.shields.io/badge/License-ISC-blue?style=for-the-badge\" alt=\"License\" />\n  <img src=\"https://img.shields.io/badge/Min%20Recommended-2.8.1+-red?style=for-the-badge\" alt=\"Minimum recommended\" />\n</p>\n\n> [!CAUTION]\n> **🛡️ 安全公告（2026-04-22）**：受影响版本 `<= 2.8.0`。Agent 在工作区写自定义脚本时可能把 `touser=\"@all\"` 当默认收件人，导致原本私聊的图片/视频/文档**被广播到企业微信应用可见范围全员**。\n>\n> **请所有部署立即升级到 `@huo15/wecom@2.8.1` 或以上**。修复见 [`changelog/v2.8.1.md`](changelog/v2.8.1.md)。\n\n> [!WARNING]\n> **原创声明**:本项目涉及的\"多账号隔离与矩阵路由架构\"、\"Bot+Agent双模融合架构\"、\"长任务超时接力逻辑\"及\"全自动媒体流转接\"等核心设计均为作者 **YanHaidao** 独立思考与实践的原创成果。\n> 欢迎技术交流与合规引用,但严禁任何不经授权的\"功能像素级抄袭\"或删除原作者署名的代码搬运行为。\n\n<p align=\"center\">\n  <strong>🚀 企业级多模式 AI 助手接入方案(统一运行时架构)</strong>\n</p>\n\n---\n\n## 💡 核心价值:为什么团队会真正选择这个插件?\n\n企业真正需要的,不是\"把一个模型接进企业微信\",而是让企业微信变成一个**能长期工作的 AI 协作入口**。\n\n大多数团队最终只关心五件事:\n\n- 能不能先低门槛接起来,而不是先做一轮重部署\n- 多人同时使用时,会不会串上下文、串身份、串会话\n- 长任务会不会因为长连接窗口太短而白跑\n- 能不能既有实时对话体验,又能做正式推送和稳定投递\n- AI 能不能真正进入文档、日程、会议、待办、通讯录这些协作层,而不只是停留在聊天框\n\n常见方案通常会很快碰到边界:\n\n- **只用 Bot WS**:接得快、聊得顺,但会受到单连接、心跳保活、会话边界和组织级广播能力的限制\n- **只用 Agent**:能力强、治理清晰,但部署门槛更高,对话体验不如 Bot WS 丝滑\n- **只选单一路径**:团队最后往往被迫在\"体验\"和\"能力\"之间二选一\n\n本插件的价值,就在于把这些原本互相冲突的目标,尽量同时成立。\n\n### 您真正会得到什么?\n\n1. **多人共用一个入口,但上下文不会串**\n   - **问题本质**:企业里真正难的不是\"接入一个机器人\",而是让几十上百个人同时使用时,仍然保持每个人的上下文隔离。\n   - **插件做法**:按 `(底层账号 + 部门/群组/人员)` 动态切分运行上下文和 Agent 实例。\n   - **用户收益**:同一个企业微信入口可以承接多人并发使用,而不会出现\"张三的问题让李四接上回答\"的串流灾难。\n\n2. **长任务不白跑,回复不轻易丢**\n   - **问题本质**:企业微信长连接的响应窗口很短,而推理模型的思考时间往往很长。\n   - **插件做法**:先保活,再流式推进;必要时走备用投递路径,把最终结果交付出去。\n   - **用户收益**:更敢把复杂任务、长文本分析、报告生成交给 AI,而不是每次都担心\"算完了却发不回来\"。\n\n3. **实时对话体验和正式投递能力,不用二选一**\n   - **问题本质**:实时聊天和组织级推送,往往不是同一条技术路径最擅长的事。\n   - **插件做法**:会话内实时交互、流式回复、异步追发优先走 `Bot WS`;组织级广播、冷启动触达、正式通知由 `Agent` 兜底。\n   - **用户收益**:日常使用时体验像聊天助手,正式落地时又有企业应用该有的稳定性和控制力。\n\n4. **AI 不只会聊天,还能进入企业微信协作层**\n   - **问题本质**:如果 AI 只能回消息,信息最终还是散落在聊天流里,业务并没有真正被推进。\n   - **插件做法**:把企业微信原生协作能力按两条能力平面接入 OpenClaw。\n   - **用户收益**:AI 不仅能回答问题,还能真正参与文档、日程、会议、待办和通讯录相关工作。\n\n5. **小团队能低门槛上手,大团队也能正式上线**\n   - **问题本质**:小团队怕折腾,大团队怕失控。\n   - **插件做法**:`Bot WS` 适合快速启用,`Agent` 适合正式治理,两者可以并存。\n   - **用户收益**:您不用在\"今天先跑起来\"和\"将来能不能正规化\"之间做破坏性迁移。\n\n---\n\n## 📊 为什么不是只选 Bot,或者只选 Agent?\n\n从用户视角看,差别不在于协议名词,而在于**你要解决的是什么问题**。\n\n| 你真正关心的事 | 🤖 Bot 模式 (WebSocket) | 🧩 Agent 模式 (自建应用 API) | ✨ 本插件的做法 |\n|:---|:---|:---|:---|\n| **先跑起来的速度** | ✅ 快,无需固定公网 IP | ❌ 较重,需要正式应用配置 | ✅ 先用 Bot 起步,后续平滑补 Agent |\n| **实时聊天体验** | ✅ 最强,天然适合低延迟和流式回复 | ⚠️ 能收能发,但不是最佳对话入口 | ✅ 默认把实时交互交给 Bot |\n| **异步结果回推** | ✅ 可以,适合已建立会话内追发 | ✅ 可以 | ✅ 会话内追发优先 Bot,必要时 Agent 兜底 |\n| **组织级广播与冷启动触达** | ⚠️ 受会话边界约束 | ✅ 更适合 | ✅ 正式通知和广播走 Agent |\n| **企业微信协作能力** | ✅ 适合个人身份能力入口 | ✅ 适合应用身份能力入口 | ✅ 两种身份平面都兼容 |\n| **适合谁** | 想快速上线、重视实时体验的团队 | 需要正式治理、自动化和组织级能力的团队 | 想同时要\"体验\"和\"能力\"的团队 |\n\n> **建议理解方式:**\n> - 如果您最在意的是\"先接起来、先用起来、先聊顺\",优先上 `Bot WS`\n> - 如果您最在意的是\"正式部署、组织级能力、自动化治理\",补齐 `Agent`\n> - 如果您真正想把 AI 在企业微信里长期用下去,最终往往需要两者"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7byevkn40d6z4p7ghdb097z983tj33\",\n  \"slug\": \"huo15-wecom-plugin\",\n  \"version\": \"2.9.5\",\n  \"publishedAt\": 1778438322867\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\n## 2.9.5 — 2026-05-11(manifest contracts.tools — 适配 OpenClaw 2026.5.x loader 契约)\n\n### 触发\n\nOpenClaw 2026.5.x gateway 启动 log 大量 warning：\n\n```\n[gateway] [plugins] plugin must declare contracts.tools before registering agent tools\n  (plugin=wecom, source=...dist/index.js)\n```\n\n3 个工具(wecom_calendar / wecom_doc / wecom_mcp)各刷一条。\n\n### 根因\n\nOpenClaw 2026.5.x loader(`dist/loader-B-GXgDrk.js`)在 `registerTool` 加了契约校验,要求 manifest 根级 `contracts.tools[]` 显式声明。\n\n### 改动\n\n`openclaw.plugin.json` 加根级 `contracts.tools` 数组：\n\n```json\n\"contracts\": {\n  \"tools\": [\"wecom_calendar\", \"wecom_doc\", \"wecom_mcp\"]\n}\n```\n\n### 不影响\n\n- 没改任何代码逻辑,只动 manifest\n- 工具注册 / 调用方式不变\n- 兼容旧 OpenClaw"},{"path":"changelog/v2.2.28.md","content":"# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.2.28 - 多账号隔离与稳定性增强\n\n本次 v2.2.28 版本是 **OpenClaw 企业微信 (WeCom) 插件** 的一次重大里程碑更新。我们深度优化了 **微信 / 企业微信** 办公场景下的多智能体隔离逻辑，并修复了生命周期、XML 数据保真等多个生产环境的核心痛点。\n\n本次更新让 **OpenClaw** 在处理企业级复杂 **插件** 配置时更加得心应手，完美解决大模型接入 **WeCom** 的所有阻碍。\n\n---\n\n### 🌟 版本亮点 (Release Highlights)\n\n*   🎯 **多账号矩阵支持**：支持按 `accountId` 进行组内会话隔离。不同部门、不同业务的 **企业微信** 机器人可并行运行，互不干扰，彻底解决跨账号串会话问题。\n*   🔐 **数据保真解析**：针对 **WeCom** 的 XML 消息解析进行了重构。关闭了自动数值化，保留 `FromUserName` 前导 `0`，并完美解决 64 位 `MsgId` 精度风险。\n*   🔁 **Gateway 生命周期适配**：完美兼容最新版 **OpenClaw** Gateway 的生命周期管理，修复了在高频心跳监测下的重启循环问题，运行更稳健。\n*   🧹 **入站消息过滤**：优化了 **微信** 与 **企业微信** 的事件过滤逻辑，避免系统事件、缺失发送者等无效消息进入 AI 会话，防止“误回复”。\n*   🧱 **配置安全护栏**：新增 **企业微信** 账号冲突检测。自动拦截重复的 `bot.token` 或 `agentId` 配置，并提供友好的中文错误提示。\n\n---\n\n### 📝 详细更新日志 (Changelog)\n\n#### 【重磅更新】🎯 多账号/多智能体可用性增强\n- 支持按 `accountId` 做组内隔离（Bot + Agent + 路由绑定同组生效）。\n- 动态 Agent 与会话键增加 `accountId` 维度，避免跨账号串会话。\n\n#### 【稳定性】🔁 生命周期兼容修复\n- 适配新版 **OpenClaw** Gateway 生命周期，`startAccount` 改为长生命周期运行。\n- 修复了“几秒一次重启 + health-monitor 二次重启”的循环问题。\n\n#### 【准确性】🔐 XML 字段保真修复\n- **WeCom** Agent XML 解析关闭自动数值化，保留发送者原始 ID。\n- 避免 `MsgId` (64bit) 精度损失，确保回复目标不被误改。\n\n#### 【准确性】🧹 误回复修复\n- Bot/Agent 入站均增加事件过滤，避免处理 `event`、`sys` 及缺失发送者的消息。\n- 修复群聊缺失 `chatid` 时仍进入 AI 会话的问题，避免“一个消息触发多人误回复”。\n\n#### 【可控性】🧱 配置安全护栏\n- 新增多账号冲突检测，自动拦截重复 Token 或 Agent ID 的配置。\n- **账号管理修复**：`deleteAccount` 现在仅删除目标账号，不再误删整个 **插件** 的 `channels.wecom` 配置。\n\n#### 【质量保障】✅ 自动化回归\n- 新增账号解析、冲突检测、动态路由隔离、生命周期与入站过滤的多项自动化测试。\n- **文档优化**：README 快速开始文档更新，优先展示“多账号 + 多 Agent”矩阵配置。\n\n---\n\n### 💾 安装与升级 (Install & Update)\n\n使用 **OpenClaw** CLI 即可一键升级 **插件**：\n\n```bash\nopenclaw plugins upgrade wecom\n```\n\n或手动更新配置：\n```bash\nopenclaw config set channels.wecom.enabled true\n```\n\n---\n\n### 🔍 SEO 关键词 (Keywords)\n**openclaw** | **企业微信** | **微信** | **wecom** | **插件** | **AI 机器人** | **大模型网关** | **流式响应** | **多账号隔离** | **WeCom Plugin**\n\n---\n\n### 📮 联系我们\n如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 或加入我们的交流群。\n\n> **提示**：建议 **OpenClaw** 主程序版本保持在 **2026.2.24+** 以获得最佳体验。"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担... Skill: Huo15 Wecom Plugin Owner: zhaobod1 Summary: 火一五·企业微信（WeCom）OpenClaw 插件 v2.8.25 — 默认走 Bot WebSocket（响应快、配置简单），自带加密媒体解密 / Agent 主动发消息 / 微信客服三通道接入 / 多账号切换。v2.8.25 重点：GUIDANCE 优先级翻转回 MEDIA: 直发——v2.8.22 当时担... Tags: latest:2.9.5, plugin:2.8.30 Version history: v2.9.5 | 2026-05-10T18:38:42.867Z | auto - Added a new CHANGELOG.md file for improved change tracking. - Updated openclaw.plugin.json and package.json for th","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1050,"uniquenessScore":46,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:44:37.095Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:44:37.095Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:52:52.457Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}