dingxiang-me / OpenClaw-Wechat

OpenClaw-Wechat 企业微信插件 中文 README | English README OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件，支持两种接入方式： • ：企业微信自建应用（XML 回调，经典模式） • ：企业微信智能机器人 API 模式（JSON 回调，原生 stream） • ：将消息主动投递到企业微信群 Webhook 或命名 Webhook 目标 适用于“个人微信扫码进入企业微信应用对话”、“企业内员工问答助手”、“多账户多业务线消息分流”等场景。 目录 • 可靠投递更新（v2.2.0） • 功能概览 • 模式对比 • 5 分钟极速上手 • 前置要求 • 安装与加载 • 配置文件与路径职责 • 快速开始 • 文档工具（WeCom Doc） • 配置参考 • 消息能力矩阵 • 命令与会话策略 • 环境变量速查 • 公网回调与 Gateway Auth • Webhook 与 Heartbeat 运维 • 与其他渠道并存建议 • 故障排查 • 开发与发布 • FAQ • 版本与贡献 可靠投递更新（v2.2.0） 这版重点不在接入元信息，而是把 WeCom 回复链路补成“可感知、可补发、可诊断”的可靠投递。 这版新增了什么 | 项目 | 结果 | |---|---| | 可靠投递状态 | 新增 摘要 | | Pending Reply | 最终回复投递失败后自动入队，支持定时重试和下次入站补发 | | Pending Reply 持久化 | 可选落盘，gateway 重启后继续补发未送达的最终回复 | | 配额感知 | 统一区分 | | 推理展示策略 | 可控制 内容分离显示、合并到最终回复或隐藏 | | Selfcheck 摘要 | / / 增加 摘要 | | 群策略诊断 | 与 selfcheck 会显示当前群规则来源、准入模式以及白名单是否生效 | | 最终回复格式 | 支持 ，会按链路选择纯文本或 markdown 能力 | | 媒体指令 | 模型最终回复支持 / 指令，自动回传图片/文件并隐藏指令行 | | Bot/Agent 收口 | Bot fallback 与 Agent 最终回复统一纳入可靠投递跟踪 | | 长连接日志降噪 | 正常的 connect / opened / subscribed 继续保持 ，默认日志更安静 | 这版对接入有什么实际影响 • 现在能直接看出当前会话是否仍在 回复窗口内，以及是否存在待补发的最终回复。 • Bot / Agent 不再只是超时兜底，而是会把失败结果分类并进入 Pending Reply 重试。 • selfcheck 会明确告诉你可靠投递追踪是否打开、是否持久化，以及当前推理展示模式。 • 群聊策略不再只能靠日志反推， 和 selfcheck 会直接说明当前命中的群规则来源与白名单是否真的在限制触发。 • Bot 长连接默认日志仍然更安静，排障时再开 看正常心跳和订阅细节。 当前推荐的接入顺序 现在 package / manifest / runtime channel meta 都会暴露同一套 quickstart metadata，便于 installer、quickstart、doctor 和后续集成入口读取同一份推荐模式、starter config 和 setup checklist。 • 先选一个主入口： • Bot 长连接：适合最快跑通对话 • Agent：适合需要主动发送、菜单、自建应用能力 • 再决定私聊准入： • ：直接可聊 • ：仅显式白名单 • ：首次私聊先审批 • 最后再加增强项： • - • Quickstart 命令 推荐入口： 如果你更想留在仓库内执行同一套流程： 如果你想走交互式向导： 如果你已经准备好了 / 环境变量，也可以使用兼容性的 env-backed 初始化路径： 这条 路径不需要任何 OpenClaw core 补丁，但它只适合 env-backed 初始化。 日常文档、排障和安装说明都默认以 为主路径；如果你需要完整接入和迁移闭环，仍然优先用 。 常见用法： 可选值有： 、 、 、 、 。 默认行为只打印 starter config 和检查清单；只有显式传 才会写文件。 会把当前 CLI 参数当作默认值，然后逐步提问，最后再确认是否写入 。 会按当前 mode 的推荐命令执行自检；若 starter config 里还有占位项，默认会阻止执行，除非显式传 。 会把 直接 merge 到 指向的配置文件，并自动备份原文件。 会先打印将要修改的字段，再询问是否真正执行 ；交互提示走 ，不会污染 的机器输出。 不再生成 starter config，只做当前安装 / 迁移状态盘点，适合排查 。 和 现在还会给出 ，直接区分 。 会把 聚合成一份报告；可以加 先只看本地安装 / 迁移问题。 会先应用当前可落盘的本地 fix patch（例如 migration patch、 ），再用修正后的配置重跑 doctor。 会先预览将要修改的字段，再确认是否真正写回。 现在也会带 ，把当前来源推荐的检查顺序、占位项提示和默认 repair 策略一起返回。 会先尝试执行 ，再写入 starter config，并可选继续跑本地 doctor。 会黑盒验证 这条本地闭环，不依赖真实企微网络。 会校验 root 包、installer CLI、manifest、运行时版本常量和 产物，适合作为发版前门禁。 如果当前配置更像官方插件 / sunnoy / 旧版 OpenClaw-Wechat，安装器会在 输出里直接给出 、来源说明、legacy 字段路径和回滚命令。 如果你想人工确认是否附带执行 ，可以加 ；要强制不附带 ，可加 ，自动确认则用 。 安装器的 现在还会直接输出 ，把来源审阅、迁移 patch、回滚和重跑 doctor 这些步骤结构化暴露出来。 如果你没有显式传 ，安装器还会按来源和现有能力自动选择 ，并在 里说明为什么这么选。 现在还会给出来源专属 和 。例如官方 / legacy 来源默认允许自动附带 ，而 sunnoy / mixed-source 来源默认只给修复建议，不会直接附带 。 仓库现在也自带两条 GitHub Actions 门禁： 跑本地安装闭环， 跑版本/打包一致性；tag 发布会走独立 release workflow，顺序发布插件包和 installer CLI。 输出会额外给出： • ：还有哪些模板占位项没替换 • ：下一步应该执行的管理台配置和自检命令 • ：可被 CLI / UI 直接消费的结构化 setup flow • ：当前是 fresh、legacy_config、stale_package、mixed_layout 还是 ready • ：当前更接近官方插件、sunnoy 配置、legacy-openclaw-wechat，还是 mixed-source • ：doctor 是否已提示、确认、落盘，以及真实 • ：quickstart 基于当前来源生成的推荐检查顺序、占位提示和 repair 默认值 • ：当前来源推荐的检查顺序，以及 installer 默认采用的修复策略 • ：当前 mode / group profile 下仍需确认的风险点 • ：推荐 selfcheck 的执行结果、阻塞原因或汇总状态 • ：把失败检查翻译成可执行的修复建议 • ：自动生成最小 和 模板，便于直接修复当前检查暴露的问题 • ：按项列出 repair patch 的配置变更、env 变更和会写出的文件 • ：当前 legacy 配置可直接迁移到的新布局建议 如果再加 ，quickstart 还会把这些修复产物直接落盘成： • • • • 如果加的是 ，则会在输出中额外看到 ，说明 repair patch 是否已实际写入目标配置。 如果加的是 ， 里还会带 ，方便区分“用户拒绝”与“自动执行”；真正写入的字段会出现在 。 5 分钟极速上手 适合“先跑起来再细调”的场景。 Step 1. 安装插件 最快入口： 它会复用仓库内的 quickstart / migrate / doctor 能力，把“安装插件 + 写 starter config + 跑本地体检”串成一次执行。 如果你只想单独安装插件包： > 最低建议版本： 。如果 里的 仍显示 ，请先升级或重装；旧包不会正确注册 channel 元数据，也不包含当前这套接入、迁移与可靠投递能力。 如果你是在本地开发或要直接跑仓库源码，再用下面这套： Step 2. 在 OpenClaw 里启用插件 如果你是通过 安装，在 增加： 如果你是源码路径加载，再使用下面这版（多一个 ）： Step 3. 选择一种模式配置 | 模式 | 回调路径 | 企业微信侧类型 | 最少需要的配置 | |---|---|---|---| | Agent（自建应用） | | 自建应用 API 接收 | | | Bot（智能机器人） | | 智能机器人 **API 模式** | | | Bot（智能机器人长连接） | 无需公网回调 | 智能机器人 **长连接模式** | | > Agent 模式补充（重要）：在企业微信自建应用后台请配置**可信 IP**，把 OpenClaw 网关实际出网 IP 加入白名单。否则可能出现“能收到消息但不回复”。 如果你希望私聊先审批，再开放会话，可以直接加： Step 4. 重启并自检 现在自检输出会先给出两行摘要： • : 当前是否能收、能回、能发 • : 当前是否启用 和 Step 5. 发一条消息验证 | 验证项 | 预期结果 | |---|---| | 文本消息 | 机器人返回文本 | | 图片消息（Bot） | 不再提示“图片接收失败”，可识别图像内容 | | | 且 WeCom 状态正常 | 功能概览 核心能力 | 能力 | 状态 | 说明 | |---|---|---| | 企业微信入站消息处理 | ✅ | 文本、图片、语音、链接、文件/视频（Agent + Bot） | | AI 自动回复 | ✅ | 接入 OpenClaw Runtime，自动路由 Agent | | Bot 原生 stream 协议 | ✅ | 刷新与增量回包 | | Bot 长连接（WebSocket） | ✅ | 原生 / / | | Bot 卡片回包 | ✅ | 支持 ，失败自动降级文本 | | 多账户 | ✅ | | | 发送者授权控制 | ✅ | + 账户级覆盖 | | 私聊策略（DM） | ✅ | + 账户级覆盖 | | 事件欢迎语（enter_agent） | ✅ | 可配置 | | 命令白名单 | ✅ | 等 | | 群聊触发策略 | ✅ | 支持 三种模式 | | 企业微信文档工具 | ✅ | 内置 工具：创建/重命名/分享/权限管理/收集表/表格属性 | | 文本防抖合并 | ✅ | 窗口期内多条消息合并投递 | | 异步补发（超时后） | ✅ | transcript 轮询补发最终回复 | | 观测统计 | ✅ | 入站/回包/错误计数 + 最近失败样本（ ） | | WeCom 出站代理 | ✅ | / | 媒体能力 | 能力 | 状态 | 说明 | |---|---|---| | 图片识别（入站） | ✅ | 支持 URL 下载、类型识别、必要时解密后识别 | | 图片发送（出站） | ✅ | Agent 模式支持 | | 语音/视频/文件发送（出站） | ✅ | 自动判型上传后发送（语音支持 AMR/SILK） | | 语音转写（本地） | ✅ | 企业微信 Recognition 优先，缺失时回退本地 whisper | | Bot 模式媒体回传 | ✅ | 优先 ；失败自动降级媒体链接， /Webhook Bot 继续兜底 | | Bot 思考过程展示 | ✅ | 识别 ，映射到原生 折叠区 | | Bot 文件入站 | ✅ | 支持 下载并注入会话上下文 | | Bot 引用消息上下文 | ✅ | 自动将 内容前置到本轮上下文 | 模式对比 | 维度 | Agent 模式（自建应用） | Bot 模式（智能机器人 API） | |---|---|---| | 回调数据格式 | XML | JSON | | 企业微信创建方式 | 应用管理 -> 自建应用 | 智能机器人 -> **API 模式** | | 回调路径默认值 | | | | 回复机制 | 主动调用 WeCom 发送 API | 回调响应 + 轮询刷新 | | 流式体验 | 多条消息模拟增量 | 原生 stream 协议 | | 思考展示 | 不适用 | 支持 标签映射到 | | 出站媒体（图/语音/视频/文件） | 支持 | 支持（ + 回包，video 自动按 file 回传） | | 典型场景 | 标准企业应用、菜单/回调体系 | 对话机器人、连续流式问答 | 回调路径规划建议 | 场景 | 建议 | |---|---| | 同时开 Agent + Bot | 使用不同路径： 与 | | 多账户 Agent | 每个账户独立路径（如 ） | | 与 Telegram/Feishu 并存 | 不复用任何 webhook path，避免路由冲突 | 前置要求 | 项目 | 说明 | |---|---| | OpenClaw | 已安装并可正常运行 Gateway | | 企业微信管理员权限 | 可创建应用或智能机器人并配置回调 | | 公网入口 | 企业微信需回调到可访问 URL（常见用 Cloudflare Tunnel） | | Node.js | 与 OpenClaw 运行环境一致 | | 本地语音识别（可选） | 或 | | ffmpeg（推荐） | AMR 等格式转码时需要 | 安装与加载 方式 A：通过 OpenClaw 安装（推荐） 安装后插件会进入 。这个目录主要用于 OpenClaw 运行时发现插件，通常**不建议**直接手改其中的 、 、 。 方式 B：本地路径加载（开发模式） 在 中配置插…