openclaw-extensions/wecom

OpenClaw 企业微信（WeCom）Channel 插件

🚀 企业级双模式 AI 助手接入方案

功能亮点 • 模式对比 • 快速开始 • 配置说明 • 联系我

---

💡 核心价值：为什么选择本插件？

🏗 独创架构：Bot + Agent 双模融合

传统的企微插件通常只能在 "只能聊天的机器人 (Bot)" 和 "只能推送的自建应用 (Agent)" 之间二选一。 本插件采用 双模并行架构，同时压榨两种模式的极限能力：

• Bot 通道 (智能体)：负责 实时对话。提供毫秒级流式响应（打字机效果），零延迟交互。
• Agent 通道 (自建应用)：负责 能力兜底。当需要发送图片/文件、进行全员广播、或 Bot 对话超时（>6分钟）时，无缝切换到 Agent 通道接管。

🧩 功能特性全景

1. 🗣 沉浸式交互 (Immersive Interaction)

• 原生流式 (Stream)：基于 HTTP 分块传输，拒绝 "转圈等待"，体验如 ChatGPT 网页版般丝滑。
• 交互式卡片 (Card)：支持 Button/Menu 交互回传，可构建审批、查询等复杂业务流 (Agent模式)。

2. 📎 全模态支持 (Multi-Modal)

• 发什么都能看：支持接收图片、文件 (PDF/Doc/Zip)、语音 (自动转文字)、视频。
• 要什么都能给：AI 生成的图表、代码文件、语音回复，均可自动上传并推送到企微。

3. 📢 企业级触达 (Enterprise Reach)

• 精准广播：支持向 部门 (Party)、标签 (Tag) 或 外部群 批量推送消息。
• Cronjob 集成：通过简单的 JSON 配置实现早报推送、日报提醒、服务器报警。

4. 🛡 生产级稳定 (Production Ready)

• 容灾切换：Bot 模式 6 分钟超时自动熔断，切换 Agent 私信送达，防止长任务回答丢失。
• Token 自动运维：内置 AccessToken 守护进程，自动缓存、提前刷新、过期重试。

---

📊 模式能力对比

能力维度	🤖 Bot 模式	🧩 Agent 模式	✨ 本插件 (双模)
接收消息 (单聊)	✅ 文本/图片/语音/文件	✅ 文本/图片/语音/视频/位置/链接	✅ 全能互补 (覆盖所有类型)
接收消息 (群聊)	✅ 文本/引用	❌ 不支持 (无回调)	✅ 文本/引用
发送消息	❌ 仅支持文本/图片/Markdown	✅ 全格式支持 (文本/图片/视频/文件等)	✅ 智能路由 (自动切换)
流式响应	✅ 支持 (打字机效果)	❌ 不支持	✅ 完美支持
主动推送	❌ 仅被动回复	✅ 支持 (指定用户/部门/标签)	✅ 完整 API

---

快速开始

1. 安装插件

openclaw plugins install @openclaw/wecom
openclaw plugins enable wecom

也可以通过命令行向导快速配置：

openclaw config --section channels

2. 配置 Bot 模式（智能体）

openclaw config set channels.wecom.enabled true
openclaw config set channels.wecom.bot.token "YOUR_BOT_TOKEN"
openclaw config set channels.wecom.bot.encodingAESKey "YOUR_BOT_AES_KEY"
openclaw config set channels.wecom.bot.receiveId ""
openclaw config set channels.wecom.bot.streamPlaceholderContent "正在思考..."
openclaw config set channels.wecom.bot.welcomeText "你好！我是 AI 助手"

# DM 门禁（推荐显式设置 policy）
# - open: 默认放开（所有人可用）
# - disabled: 全部禁用
# - allowlist: 仅 allowFrom 允许的人可用
openclaw config set channels.wecom.bot.dm.policy "open"
# policy=allowlist 时生效（例如只允许某些 userid；"*" 表示允许所有人）
openclaw config set channels.wecom.bot.dm.allowFrom '["*"]'

3. 配置 Agent 模式（自建应用，可选）

openclaw config set channels.wecom.enabled true
openclaw config set channels.wecom.agent.corpId "YOUR_CORP_ID"
openclaw config set channels.wecom.agent.corpSecret "YOUR_CORP_SECRET"
openclaw config set channels.wecom.agent.agentId 1000001
openclaw config set channels.wecom.agent.token "YOUR_CALLBACK_TOKEN"
openclaw config set channels.wecom.agent.encodingAESKey "YOUR_CALLBACK_AES_KEY"
openclaw config set channels.wecom.agent.welcomeText "欢迎使用智能助手"
openclaw config set channels.wecom.agent.dm.policy "open"
openclaw config set channels.wecom.agent.dm.allowFrom '["*"]'

4. 高级网络配置 (公网出口代理)

如果您的服务器使用 动态 IP (如家庭宽带、内网穿透) 或 无公网 IP，企业微信 API 会因 IP 变动报错 60020 not allow to access from your ip。 此时需配置一个固定 IP 的正向代理 (如 Squid)，让插件通过该代理访问企微 API。

openclaw config set channels.wecom.network.egressProxyUrl "http://proxy.company.local:3128"

5. 验证

openclaw gateway restart
openclaw channels status

---

配置说明

完整配置结构

{
  "channels": {
    "wecom": {
      "enabled": true,
      
      // Bot 模式配置（智能体）
      "bot": {
        "token": "YOUR_BOT_TOKEN",
        "encodingAESKey": "YOUR_BOT_AES_KEY",
        "receiveId": "",                        // 可选，用于解密校验
        "streamPlaceholderContent": "正在思考...",
        "welcomeText": "你好！我是 AI 助手",
        "dm": { "allowFrom": [] }               // 私聊限制
      },
      
      // Agent 模式配置（自建应用）
      "agent": {
        "corpId": "YOUR_CORP_ID",
        "corpSecret": "YOUR_CORP_SECRET",
        "agentId": 1000001,
        "token": "YOUR_CALLBACK_TOKEN",         // 企微后台「设置API接收」
        "encodingAESKey": "YOUR_CALLBACK_AES_KEY",
        "welcomeText": "欢迎使用智能助手",
        "dm": { "allowFrom": [] }
      },

      // 网络配置（可选）
      "network": {
        "egressProxyUrl": "http://proxy.company.local:3128"
      }
    }
  }
}

Webhook 路径（固定）

模式	路径	说明
Bot	/wecom/bot	智能体回调
Agent	/wecom/agent	自建应用回调

DM 策略

• 不配置 dm.allowFrom → 所有人可用（默认）
• 配置 dm.allowFrom: ["user1", "user2"] → 白名单模式，仅列表内用户可私聊

常用指令

指令	说明	示例
/new	🆕 开启新会话 (重置上下文)	/new 或 /new GPT-4
/reset	🔄 重置会话 (同 /new)	/reset

---

企业微信接入指南

Bot 模式（智能机器人）

1. 登录 企业微信管理后台
2. 进入「安全与管理」→「管理工具」→「智能机器人」
3. 创建机器人，选择 API 模式
4. 填写回调 URL：https://your-domain.com/wecom/bot
5. 记录 Token 和 EncodingAESKey

Agent 模式（自建应用）

1. 登录 企业微信管理后台
2. 进入「应用管理」→「自建」→ 创建应用
3. 获取 AgentId、CorpId、Secret
4. 重要： 进入「企业可信IP」→「配置」→ 添加你服务器的 IP 地址
   • 如果你使用内网穿透/动态 IP，建议配置 channels.wecom.network.egressProxyUrl 走固定出口代理，否则可能出现：60020 not allow to access from your ip
5. 在应用详情中设置「接收消息 - 设置API接收」
6. 填写回调 URL：https://your-domain.com/wecom/agent
7. 记录回调 Token 和 EncodingAESKey

---

高级功能

A2UI 交互卡片

Agent 输出 {"template_card": ...} 时自动渲染为交互卡片：

• ✅ 单聊场景：发送真实交互卡片
• ✅ 按钮点击：触发 template_card_event 回调
• ✅ 自动去重：基于 msgid 避免重复处理
• ⚠️ 群聊降级：自动转为文本描述

⏰ Cronjob 企业级定时推送

本插件深度集成了 OpenClaw 的 Cronjob 调度能力，配合 Agent 强大的广播 API，轻松实现企业级通知服务。

核心场景：早报推送、服务器报警、日报提醒、节日祝福。

1. 目标配置 (Target)

无需遍历用户列表，直接利用 Agent 强大的组织架构触达能力：

目标类型	格式示例	推送范围	典型场景
部门 (Party)	party:1 (或 1)	📢 全员广播	全员通知、技术部周报
标签 (Tag)	tag:Ops	🎯 精准分组	运维报警、管理层汇报
外部群 (Group)	group:wr...	💬 群聊推送	项目组群日报 (需由Agent建群)
用户 (User)	user:zhangsan	👤 即时私信	个人待办提醒

2. 配置示例 (schedule.json)

只需在工作区根目录创建 schedule.json 即可生效：

{
  "tasks": [
    {
      "cron": "0 9 * * 1-5", // 每周一至周五 早上9:00
      "action": "reply.send",
      "params": {
        "channel": "wecom",
        "to": "party:1",      // 一键发送给根部门所有人！
        "text": "🌞 早安！请查收[今日行业简报](https://example.com/daily)。"
      }
    },
    {
      "cron": "0 18 * * 5",
      "action": "reply.send",
      "params": {
        "channel": "wecom",
        "to": "tag:Ops",       // 仅发送给运维组
        "text": "🔒 周五封网提醒：请检查服务器状态。"
      }
    }
  ]
}

---

📖 详细行为说明 (Behavior Detail)

1. 企业微信群聊交付规则

• 默认 (Bot 回复)：群聊里 @Bot，默认由 Bot 在群内直接回复（优先文本/图片/Markdown）。
• 例外 (文件兜底)：如果回复内容包含非图片文件（如 PDF/Word/表格/压缩包等），由于企微 Bot 接口不支持，插件会自动：
  1. Bot 在群里提示："由于格式限制，文件将通过私信发送给您"。
  2. 无缝切换到 自建应用 (Agent) 通道，将文件私信发送给触发者。
• 提示：若未配置 Agent，Bot 会明确提示“需要管理员配置自建应用通道”。

2. 长任务可靠性保障

• 超时熔断：企业微信限制 Bot 流式回复窗口约为 6 分钟。
• 自动接力：当对话时长接近此阈值时，Monitor 会自动截断 Bot 流，提示 "剩余内容将私信发送"，并立即启动 Agent 通道私信发送完整结果。这彻底解决了长思考任务（如深度推理、代码生成）因超时导致用户收不到结果的问题。

3. 主动发送安全机制

• 群发保护：Agent 主动发送接口不再尝试向普通群 chatid (wr/wc...) 发消息（该路径常因权限与归属产生的隐蔽错误）。
• 引导提示：系统会明确拦截并通过日志提示中文错误："请使用 Bot 群内交付或改为私信目标（userid/部门/标签）"，帮助管理员快速排查配置。

4. 管理员友好

• 所有兜底逻辑（Fallback）触发时，如果因配置缺失导致失败，Bot 都会给出清晰的中文提示，而不是沉默或报代码错误，极大降低了排查难度。

---

🙋 社区问答 (FAQ)

针对社区反馈的高频问题，我们已在 v2.2.4 版本中全部解决：

Q1: 同时使用 Bot 和 Agent 会导致消息重复吗？

A: 不会。本插件采用“Bot 优先”策略。用户在哪个通道发消息，就从哪个通道回。只有在 Bot 无法处理（如发文件）时才会智能切换到 Agent 通道作为补充。

Q2: 使用内网穿透时，企业微信报错 60020 (IP 不白名单) 怎么办？

A: 新增了 config.network.egressProxyUrl 配置。您可以配置一个拥有固定公网 IP 的代理服务器（如 Squid），让插件通过该代理与企微 API 通信，从而绕过动态 IP 限制。

Q3: 原生 Bot 模式支持图片，为什么 Agent 模式不行？

A: Agent 模式之前确实存在此短板。但在 v2.2.4 中，我们完整实现了 Agent 端的 XML 媒体解析与 media_id 下载逻辑，现在 Agent 模式也能完美看图、听语音了。

Q4: 群里 @机器人 发送文件失败？

A: 因为企业微信 Bot 接口本身不支持发送非图片文件。我们的解决方案是：自动检测到文件发送需求后，改为通过 Agent 私信该用户发送文件，并在群里给出 "文件已私信发给您" 的提示。

Q5: 为什么在 Agent 模式下发送文件（如 PDF、Word）给机器人没有反应？

A: 这是由于企业微信官方接口限制。自建应用（Agent）的消息回调接口仅支持：文本、图片、语音、视频、位置和链接信息。不支持通用文件（File）类型的回调，因此插件无法感知您发送的文件。

Q6: Cronjob 定时任务怎么发给群？

A: Cronjob 必须走 Agent 通道（Bot 无法主动发消息）。您只需在配置中指定 to: "party:1" (部门) 或 to: "group:wr123..." (外部群)，即可实现定时推送到群。

Q7: 为什么发视频给 Bot 没反应？

A: 官方 Bot 接口不支持接收视频。如果您需要处理视频内容，请配置并使用 Agent 模式（Agent 支持接收视频）。

---

---

更新日志

2026.2.5

• 🛠 体验优化：WeCom 媒体（图片/语音/视频/文件）处理的默认大小上限提升到 25MB，减少大文件因超限导致的“下载/保存失败”。
• 📌 可配置提示：若仍遇到 Media exceeds ... limit，日志/回复会提示通过 channels.wecom.media.maxBytes 调整上限，并给出可直接执行的 openclaw config set 示例命令。

2026.2.4

• 🚀 架构升级：实施 "Bot 优先 + Agent 兜底" 策略，兼顾流式体验与长任务稳定性（6分钟切换）。
• ✨ 全模态支持：Agent 模式完整支持接收图片/语音/视频（文件仅支持发送）。
• ✨ Cronjob 增强：支持向部门 (party:ID) 和标签 (tag:ID) 广播消息。
• 🛠 Monitor 重构：统一的消息防抖与流状态管理，提升并发稳定性。
• 🛠 体验优化：修复企微重试导致的重复回复（Bot/Agent 均做 msgid 去重）；优化 Bot 连续多条消息的排队/合并回执，避免“重复同一答案”或“消息失败提示”。
• 🐞 修复：Outbound ID 解析逻辑及 API 客户端参数缺失问题。

2026.2.3

• 🎉 重大更新：新增 Agent 模式（自建应用）支持
• ✨ 双模式并行：Bot + Agent 可同时运行
• ✨ 多模态支持：Agent 模式支持图片/语音/文件/视频的接收与自动下载
• ✨ AccessToken 自动管理：缓存 + 智能刷新
• ✨ Agent 主动推送：脱离回调限制
• ✨ XML 加解密：完整 Agent 回调支持
• 📁 代码重构：模块化解耦设计

2026.1.31

• 文档：补充入模与测试截图说明
• 新增文件支持
• 新增卡片支持

2026.1.30

• 项目更名：Clawdbot → OpenClaw