@huo15/wecom

v2.10.0

Published

2 months ago

OpenClaw 企业微信（WeCom）插件 v2.9.0 — 动态 agent 派生补全（每个企微群/DM 独立 workspace 与 agentDir）。v2.8.x 起 dynamic-agent.ts 已派生 agentId 但只写 cfg.agents.list 的 {id}（不写 workspace/agentDir 也不写 cfg.bindings），OpenClaw 核心 routing 找不到 binding → 全部消息 fallback 回 main 共用 ~/.openclaw/

0High
0Medium
0Low

huo15

OpenClaw 企业微信(WeCom) Channel 插件

| 🏫 教学机构 | 👨‍🏫 讲师 | 📧 联系方式 | 💬 QQ群 | 📺 配套视频 | |:-----------:|:--------:|:------------------:|:-----------:|:-----------------------------------:| | 逸寻智库 | Job | [email protected] | 1093992108 | 📺 B站视频 |

[!CAUTION] 🛡️ 安全公告（2026-04-22）：受影响版本 <= 2.8.0。Agent 在工作区写自定义脚本时可能把 touser="@all" 当默认收件人，导致原本私聊的图片/视频/文档被广播到企业微信应用可见范围全员。
请所有部署立即升级到 @huo15/[email protected] 或以上。修复见 changelog/v2.8.1.md。

[!WARNING] 原创声明:本项目涉及的"多账号隔离与矩阵路由架构"、"Bot+Agent双模融合架构"、"长任务超时接力逻辑"及"全自动媒体流转接"等核心设计均为作者 YanHaidao 独立思考与实践的原创成果。欢迎技术交流与合规引用,但严禁任何不经授权的"功能像素级抄袭"或删除原作者署名的代码搬运行为。

💡 核心价值:为什么团队会真正选择这个插件?

企业真正需要的,不是"把一个模型接进企业微信",而是让企业微信变成一个能长期工作的 AI 协作入口。

大多数团队最终只关心五件事:

能不能先低门槛接起来,而不是先做一轮重部署
多人同时使用时,会不会串上下文、串身份、串会话
长任务会不会因为长连接窗口太短而白跑
能不能既有实时对话体验,又能做正式推送和稳定投递
AI 能不能真正进入文档、日程、会议、待办、通讯录这些协作层,而不只是停留在聊天框

常见方案通常会很快碰到边界:

只用 Bot WS:接得快、聊得顺,但会受到单连接、心跳保活、会话边界和组织级广播能力的限制
只用 Agent:能力强、治理清晰,但部署门槛更高,对话体验不如 Bot WS 丝滑
只选单一路径:团队最后往往被迫在"体验"和"能力"之间二选一

本插件的价值,就在于把这些原本互相冲突的目标,尽量同时成立。

您真正会得到什么?

多人共用一个入口,但上下文不会串
- 问题本质:企业里真正难的不是"接入一个机器人",而是让几十上百个人同时使用时,仍然保持每个人的上下文隔离。
- 插件做法:按 (底层账号 + 部门/群组/人员) 动态切分运行上下文和 Agent 实例。
- 用户收益:同一个企业微信入口可以承接多人并发使用,而不会出现"张三的问题让李四接上回答"的串流灾难。
长任务不白跑,回复不轻易丢
- 问题本质:企业微信长连接的响应窗口很短,而推理模型的思考时间往往很长。
- 插件做法:先保活,再流式推进;必要时走备用投递路径,把最终结果交付出去。
- 用户收益:更敢把复杂任务、长文本分析、报告生成交给 AI,而不是每次都担心"算完了却发不回来"。
实时对话体验和正式投递能力,不用二选一
- 问题本质:实时聊天和组织级推送,往往不是同一条技术路径最擅长的事。
- 插件做法:会话内实时交互、流式回复、异步追发优先走 Bot WS;组织级广播、冷启动触达、正式通知由 Agent 兜底。
- 用户收益:日常使用时体验像聊天助手,正式落地时又有企业应用该有的稳定性和控制力。
AI 不只会聊天,还能进入企业微信协作层
- 问题本质:如果 AI 只能回消息,信息最终还是散落在聊天流里,业务并没有真正被推进。
- 插件做法:把企业微信原生协作能力按两条能力平面接入 OpenClaw。
- 用户收益:AI 不仅能回答问题,还能真正参与文档、日程、会议、待办和通讯录相关工作。
小团队能低门槛上手,大团队也能正式上线
- 问题本质:小团队怕折腾,大团队怕失控。
- 插件做法:Bot WS 适合快速启用,Agent 适合正式治理,两者可以并存。
- 用户收益:您不用在"今天先跑起来"和"将来能不能正规化"之间做破坏性迁移。

📊 为什么不是只选 Bot,或者只选 Agent?

| 你真正关心的事 | 🤖 Bot 模式 (WebSocket) | 🧩 Agent 模式 (自建应用 API) | ✨ 本插件的做法 | |:---|:---|:---|:---| | 先跑起来的速度 | ✅ 快,无需固定公网 IP | ❌ 较重,需要正式应用配置 | ✅ 先用 Bot 起步,后续平滑补 Agent | | 实时聊天体验 | ✅ 最强,天然适合低延迟和流式回复 | ⚠️ 能收能发,但不是最佳对话入口 | ✅ 默认把实时交互交给 Bot | | 异步结果回推 | ✅ 可以,适合已建立会话内追发 | ✅ 可以 | ✅ 会话内追发优先 Bot,必要时 Agent 兜底 | | 组织级广播与冷启动触达 | ⚠️ 受会话边界约束 | ✅ 更适合 | ✅ 正式通知和广播走 Agent | | 企业微信协作能力 | ✅ 适合个人身份能力入口 | ✅ 适合应用身份能力入口 | ✅ 两种身份平面都兼容 | | 适合谁 | 想快速上线、重视实时体验的团队 | 需要正式治理、自动化和组织级能力的团队 | 想同时要"体验"和"能力"的团队 |

🧩 企业微信协作能力

| 能力 | Bot WS 会话 | Agent 会话 | |---|---|---| | wecom_mcp（doc/meeting/todo/contact） | ✅ | ❌ | | wecom_doc（文档/表格/权限） | ❌ | ✅ | | wecom_calendar（日历/日程/参与人） | ❌ | ✅ |

授权方式

Bot WS 模式:企微管理后台 → 工作台 → 智能机器人 → 编辑 → 可使用权限
Agent 模式:企微管理后台 → 工作台 → 协作 → 文档/日程/会议等 → 可调用接口的应用

📋 最近更新 (Changelog摘要)

为保持精简,以下仅展示近期 5 次重要更新,完整历史请前往 changelog/ 目录查阅。

📌 v2.9.x(2026-05)

[动态 Agent] 派生补全 🧭 workspace/agentDir/bindings 持久化，enabled 默认翻 true，maxAgents 上限保护，seedFromMainWorkspace 种子复制。
[manifest] contracts.tools 声明 📦 适配 OpenClaw 2026.5.x loader 契约，显式声明 ["wecom_calendar", "wecom_doc", "wecom_mcp"]。

📌 v2.8.0(2026-04-22)

[能力扩充] 微信客服(kefu)全通道落地 🆕 Agent/Bot 之外,新增"企业微信客服"作为第三条消息通道。
[通道独立] 回调路径解耦 🛣️ 客服挂载到独立路径 /plugins/wecom/kefu。
[入向覆盖] 10 类消息全量归一 📥 text/image/voice/video/file/link/miniprogram/msgmenu/location/business_card/event。

📌 v2.7.3(2026-04-21)

[格式升级] 全线切换到 markdown_v2 🎨 原生支持 markdown 表格、图片、粗体、链接、代码块。
[逻辑简化] 移除 textcard 降级路径 🧹 统一走 markdown_v2,富文本完整渲染。

📌 v2.7.2(2026-04-21)

[Bug 修复] 引用群文件显示"COS链接过期" 🔧 新增 mediaDownloadTimeoutMs 配置。
[Bug 修复] 安装插件被安全扫描拦截 🔒 移除 script-runner.ts（child_process.spawn）。

📌 v2.3.273(2026-03-31)

[重要修复] WS 断连 Fallback 🔧 Bot WS 自动切换到 Agent API 发送回复。
[包名变更] @yanhaidao/wecom 更名为 @huo15/wecom。

一、🚀 快速开始

推荐统一使用多账号矩阵模型。即使您的企业只接入了一个账号,也强烈建议将其配入 channels.wecom.accounts.default 节点下。

1.1 插件安装

openclaw plugins install @huo15/wecom
openclaw plugins enable wecom

1.2 互动向导式初配 (适合个人开发者与极客)

openclaw channels add

选择 企业微信 (WeCom)，根据终端指引填入 Bot ID 及 Secret。

1.3 生产环境顶配架构示范

{
  "channels": {
    "wecom": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "enabled": true,
          "name": "企微销售二部支持中枢",
          "bot": {
            "primaryTransport": "ws",
            "streamPlaceholderContent": "正在深思熟虑,请稍候...",
            "welcomeText": "你好,我是已连网的专属大脑。",
            "ws": {
              "botId": "YOUR_BOT_ID",
              "secret": "YOUR_BOT_SECRET"
            }
          },
          "agent": {
            "corpId": "YOUR_CORP_ID",
            "agentSecret": "YOUR_AGENT_SECRET",
            "agentId": 1000001,
            "token": "AGENT_TOKEN",
            "encodingAESKey": "AGENT_AES_KEY"
          }
        }
      },
      "mediaMaxMb": 50,
      "dynamicAgents": {
        "enabled": true,
        "dmCreateAgent": true,
        "groupEnabled": true,
        "adminUsers": ["zhangsan001"]
      }
    }
  }
}

更多配置详情请参考用户手册 SOP

二、🏢 企业微信后台回调挂载指南

| 类型 | 可信域名 | 默认账号路由 | 子账号路由 | |---|---|---|---| | Bot Webhook | https://x.com | /plugins/wecom/bot/default | /plugins/wecom/bot/ops | | Agent Callback | https://x.com | /plugins/wecom/agent/default | /plugins/wecom/agent/ops | | Kefu | https://x.com | /plugins/wecom/kefu | /plugins/wecom/kefu/<accountId> |

警告:极度不推荐将老旧单一根路径(如 /plugins/wecom/bot)在未指定账户空间下裸奔使用。

三、📡 排障与抓包

# 步骤1：插件级状态快照
openclaw channels status --probe

# 步骤2：全局深度诊断
openclaw status --deep

# 步骤3：查看 WeCom 日志
openclaw channels logs --channel wecom --lines 200

详细排障指南请参考用户手册 SOP §12

四、📚 文档导航

| 文档 | 路径 | 说明 | |---|---|---| | 产品需求文档 (PRD) | docs/prd.md | 功能需求、用户场景、版本规划 | | 用户手册 (SOP) | docs/user-sop.md | 安装、配置、排障、FAQ | | 开发者 (SOP) | docs/developer-sop.md | 架构内幕、发版流程、红线 | | AI 编程助手规则 | CLAUDE.md | Claude Code / CatPaw 项目规则 | | 上下游企业配置 | UPSTREAM_CONFIG.md | 上下游企业接入指南 | | 项目治理 | GOVERNANCE.md | 项目所有权与协作 | | 变更日志 | changelog/ | 各版本详细更新 |

五、🤝 项目鸣谢

感谢所有为本项目提交代码、测试、文档与反馈的协作者。

原始项目:yanhaitao/wecom

六、📮 版权与许可证

公司名称： 青岛火一五信息科技有限公司

联系邮箱： [email protected] | QQ群： 1093992108

关注逸寻智库公众号，获取更多资讯

最后的话:关于开源及署名

本项目版权归 青岛火一五信息科技有限公司 所有,遵循 ISC License。您可以将其用于极其广阔的项目天地中。但开源不是拿来主义: 在此明确强调,包括所谓的"Bot+Agent 保活接力超时融合机制"、"千人千面多账户切面"、"自动寻的路由下沉" 这背后全是作者无数个在企业真实现网撞墙实验出的架构结晶。拒绝一切去除原作者署名、粗暴改名换姓占为己用的魔改上架行为。 愿我们能在彼此尊重的前提下,共同拓展 OpenClaw 生态的无垠边界。