1. 项目概述OpenClaw-Wechat 是一个面向 OpenClaw 的企业微信渠道插件。简单来说它就像一座桥把企业微信这个国内最主流的办公通讯工具和 OpenClaw 这个强大的 AI 对话引擎连接了起来。无论你是想在企业微信里部署一个智能客服助手还是想为团队打造一个能处理文档、回答问题的内部知识机器人这个插件都能帮你实现。我接触过不少团队他们想在企业微信里用上 AI 能力但往往卡在第一步如何让 AI 模型“听懂”企业微信的消息又如何把 AI 的回复“说”回企业微信。自己从零开发要处理回调加密、消息格式转换、会话管理、媒体文件处理等一系列繁琐问题耗时耗力。OpenClaw-Wechat 正是为了解决这个痛点而生它封装了企业微信官方 API 的所有复杂细节让你只需要关心业务逻辑和 AI 模型本身。这个插件支持两种主流的接入方式Agent 模式和Bot 模式。Agent 模式基于企业微信自建应用功能最全支持菜单、主动发送消息等高级能力Bot 模式则基于企业微信智能机器人主打轻量、原生流式对话体验。从 v2.2.0 版本开始插件还重点强化了“可靠投递”能力确保 AI 的回复能稳定送达并且提供了完善的工具链从安装、配置到诊断、排障都有一站式的命令支持。2. 核心能力与模式选择在深入配置之前我们必须先理清两种核心模式的区别这直接决定了后续的技术选型和配置复杂度。选择哪种模式取决于你的具体场景和需求。2.1 Agent 模式功能全面的“自建应用”Agent 模式对应的是在企业微信后台创建一个“自建应用”。你可以把它理解为你自己开发了一个小程序或服务号集成到了企业微信里。它的工作原理是用户在企微里向你的应用发送消息。企业微信服务器将这条加密的消息XML格式推送到你预先配置好的公网回调地址即你的 OpenClaw 网关。OpenClaw-Wechat 插件接收并解密消息将其转换为 OpenClaw 能理解的格式交给 AI 模型处理。模型生成回复后插件再调用企业微信的“发送消息”API将回复内容主动推送给用户。这种模式的优势在于功能完整支持几乎所有消息类型文本、图片、语音、视频、文件、链接的收发。主动触达可以随时向用户或群聊发送消息不依赖于用户先发起对话。支持应用菜单可以配置应用侧边栏菜单实现更丰富的交互。权限清晰可以精细控制哪些成员可以使用该应用。它的挑战在于配置稍复杂需要在企业微信管理后台配置可信 IP、回调 URL、Token、AESKey 等多个参数。依赖公网地址必须有一个能被企业微信服务器访问的公网回调地址。流式体验需模拟企业微信的“发送消息”API 本身不是流式的插件需要通过“快速回复多条消息”来模拟流式输出的效果。2.2 Bot 模式轻量敏捷的“智能机器人”Bot 模式对应的是在企业微信群里添加一个“智能机器人”并选择API 模式。它更像是群里的一个特殊成员。它的工作原理是用户在群里机器人并发送消息。企业微信服务器将这条消息JSON格式推送到你的回调地址。插件处理消息并调用 AI 模型。模型生成回复时插件通过企业微信提供的stream接口以“流”的形式逐步将回复内容推送回去用户能实时看到打字效果。从 v2.2.0 开始Bot 模式还支持了长连接WebSocket方式。这种方式下你的服务端会主动连接企业微信的 WebSocket 服务器并订阅消息。这带来了一个巨大优势你不再需要公网回调地址。消息通过长连接直接推送到你的服务回复也通过同一条连接发送非常适合部署在内网或没有固定公网 IP 的环境。这种模式的优势在于原生流式体验回复是逐字打出的体验更自然。配置相对简单尤其是长连接模式无需配置复杂的回调 URL 和 Token长连接模式。思考过程展示AI 模型的“内心独白”thinking标签可以映射到企业微信的原生“思考中”状态体验更佳。无需公网长连接极大降低了部署门槛。它的限制在于主要面向群聊虽然也支持私聊但触发和体验主要围绕群场景设计。功能相对精简相比 Agent 模式一些高级 API如主动推送非消息可能受限。平台限制企业微信官方规定群聊中的机器人通常只在被时才会收到回调。因此即使你在插件中配置了direct直接触发或keyword关键词触发模式在实际的 Bot 模式下也可能被强制按mention触发处理。2.3 模式对比与选型建议为了帮你快速决策我整理了一个对比表格特性维度Agent 模式自建应用Bot 模式API回调Bot 模式长连接创建方式应用管理 - 自建应用群聊 - 添加机器人 -API模式群聊 - 添加机器人 -API模式回调机制HTTP POST (XML)HTTP POST (JSON)WebSocket 长连接公网需求必需需配置回调URL必需需配置回调URL非必需服务端主动连接流式回复模拟多条消息原生支持(stream)原生支持(stream)思考过程展示不支持支持(thinking标签)支持(thinking标签)主动发送消息支持向用户/群/部门有限支持通常需先触发有限支持通常需先触发消息类型支持全类型文本、图片、文件等全类型图片/文件通过链接或附件回传全类型图片/文件通过链接或附件回传典型场景企业应用、客服助手、需要菜单和主动推送团队群聊助手、需要流式对话体验内网环境、无公网IP、追求最简部署我的选型建议如果你需要功能最全、最像“官方应用”的体验比如构建一个面向全公司的智能助手需要主动通知、应用菜单选Agent 模式。如果你主要服务于具体的项目群、部门群追求极致的流式对话体验和“思考过程”展示且具备公网条件选Bot 模式API回调。如果你的服务部署在内网、开发环境或者没有稳定的公网地址但依然想在企微群里用上 AI 助手Bot 模式长连接是你的不二之选。如果难以抉择插件支持多账户配置你完全可以同时启用一个 Agent 账户和一个 Bot 账户让它们服务于不同场景。3. 从零开始5分钟极速部署理论讲完我们直接上手。这里我以最快速、最推荐的Bot 长连接模式为例带你走通整个流程。这个模式免去了配置公网回调的麻烦最适合快速验证。3.1 第一步安装插件打开你的终端确保已经安装了 Node.js 和 OpenClaw。然后执行最简安装命令npx -y dingxiang-me/openclaw-wecom-cli install这个命令是一个“一站式”安装器它会自动完成三件事通过openclaw plugins install安装dingxiang-me/openclaw-wechat插件包。在你的 OpenClaw 主配置 (~/.openclaw/openclaw.json) 中写入一个基础的企业微信渠道配置。运行本地检查 (doctor)告诉你当前配置还缺什么下一步该做什么。注意确保你的 OpenClaw 版本较新并且openclaw命令行工具在 PATH 中可用。如果遇到权限问题可能需要使用sudo或在管理员模式下运行。3.2 第二步配置企业微信机器人现在需要去企业微信后台创建一个机器人。登录 企业微信管理后台 。进入目标群聊点击右上角...-添加群机器人-新建。给机器人起个名字例如“AI助手”。关键一步在创建方式中选择通过API配置有时也显示为“API模式”。创建成功后页面会展示Webhook地址、Bot ID和Secret。请立即复制保存Bot ID和Secret页面关闭后 Secret 将不可见。3.3 第三步修改 OpenClaw 配置安装器已经在你的~/.openclaw/openclaw.json里写入了基础配置。现在用文本编辑器打开这个文件找到channels.wecom部分将其修改为 Bot 长连接模式。你需要填入上一步获取的Bot ID和Secret。{ channels: { wecom: { enabled: true, bot: { enabled: true, longConnection: { enabled: true, botId: 你的Bot-ID, // 替换为实际值 secret: 你的Bot-Secret // 替换为实际值 } } } } }3.4 第四步重启网关并自检配置保存后需要重启 OpenClaw 网关来加载新配置。openclaw gateway restart重启后运行自检命令查看插件状态是否正常npm run wecom:doctor -- --json如果一切正常输出中会看到readiness: ok之类的成功状态。如果看到错误或警告请根据提示信息进行修复通常是Bot ID或Secret填写错误。3.5 第五步测试对话回到企业微信在你创建了机器人的群里你刚刚创建的机器人并发送一条消息比如“你好”。稍等片刻你应该就能看到机器人以流式打字的效果进行回复了恭喜至此一个最基本的企业微信 AI 机器人已经跑通了。整个过程如果顺利确实可以在5分钟内完成。但这只是开始接下来我们要深入配置细节让它变得更强大、更稳定。4. 深入配置解析与最佳实践极速上手让你看到了效果但要投入生产环境我们还需要关注稳定性、安全性和功能性。下面我拆解几个关键配置模块分享我的实操经验。4.1 多账户管理与路由策略一个 OpenClaw 实例完全可以同时服务多个企业微信应用或机器人。比如你们公司可能有“技术支持”、“销售咨询”、“内部问答”等多个不同的 AI 助手分别对应不同的企微应用或群聊。OpenClaw-Wechat 通过accounts配置项来支持多账户。每个账户可以独立配置 Agent 或 Bot 模式甚至混合配置。{ channels: { wecom: { enabled: true, defaultAccount: support, // 默认账户用于文档工具等未指定账户的场景 accounts: { support: { // 技术支持账户使用Agent模式 enabled: true, corpId: ww-support, corpSecret: secret-support, agentId: 1000001, callbackToken: token-support, callbackAesKey: aes-support, webhookPath: /wecom/support/callback, allowFrom: [*] // 允许所有成员 }, sales_bot: { // 销售群机器人使用Bot长连接模式 enabled: true, bot: { enabled: true, longConnection: { enabled: true, botId: bot-id-sales, secret: secret-sales } }, allowFrom: [sales_lead, wecom:alice] // 仅允许销售主管和Alice触发 } } } } }配置了多账户消息来了怎么知道该交给哪个 AI 模型Agent处理呢这里强烈推荐使用 OpenClaw 核心的bindings功能而不是在插件内部实现复杂的路由逻辑。bindings规则清晰优先级高。{ bindings: [ { match: { channel: wecom, accountId: support // 来自 support 账户的消息 }, agentId: tech_support_agent // 路由给名为 tech_support_agent 的AI助手 }, { match: { channel: wecom, accountId: sales_bot }, agentId: sales_assistant_agent }, { match: { channel: wecom // 不指定 accountId匹配所有 wecom 消息 }, agentId: default_agent // 默认路由 } ] }4.2 权限与安全控制让机器人在企业里乱跑可不行必须给它戴上“缰绳”。插件提供了多层级的权限控制。1. 发送者白名单 (allowFrom)这是最基础的防火墙。可以配置允许哪些用户或部门与机器人交互。*允许所有人默认生产环境慎用。[userid1, userid2]允许特定用户。[wecom:userid]使用wecom:前缀明确指定企业微信用户。[party:2]允许整个部门。这个配置可以在channels.wecom顶层设置全局生效也可以在accounts.id下为每个账户单独覆盖。2. 私聊策略 (dm)控制用户能否通过私聊方式联系机器人。mode: open允许所有私聊。mode: allowlist仅允许白名单内的用户私聊需配合dm.allowFrom使用。mode: pairing我强烈推荐这个模式。用户首次私聊时机器人会回复一条审批提示管理员在 OpenClaw 控制台或通过命令批准后该用户才能建立会话。这能有效防止无关人员骚扰机器人。mode: deny禁止所有私聊。3. 群聊触发策略 (groupChat)在群里你肯定不希望机器人对每句话都回应。可以精细控制触发条件triggerMode: direct任何群消息都触发。慎用可能刷屏triggerMode: mention只有机器人时才触发。最常用triggerMode: keyword当消息包含特定关键词时触发需配置triggerKeywords。一个重要限制对于 Bot 模式由于企业微信平台的限制即使在插件中配置了direct或keyword实际也会被当作mention处理。插件会记录警告日志。4. 命令白名单 (commands)机器人支持一些内置命令如/help,/status,/clear。你可以控制哪些命令可用。{ commands: { enabled: true, allowlist: [help, status], // 只允许 /help 和 /status 命令 rejectMessage: 此命令未被授权。 } }可以将adminUsers配置为管理员列表管理员可以绕过命令白名单限制。4.3 可靠投递与稳定性增强v2.2.0 的核心改进就在于此。AI 生成回复可能耗时较长网络也可能波动如何保证回复一定能送到用户手里1. Pending Reply待补发队列这是可靠投递的基石。当 AI 最终回复生成后如果因为网络超时、额度不足等原因首次投递失败插件不会直接丢弃而是将其放入一个“待补发队列”。定时重试插件会定期检查这个队列并重新尝试发送。下次入站补发更巧妙的是当同一个用户再次发送消息时插件会先检查是否有他未送达的回复并优先补发。用户感知上就是“机器人刚刚卡了一下现在把答案补上了”。持久化通过配置delivery.pendingReply.persist: true可以将这个队列保存到磁盘。即使网关重启未送达的回复也不会丢失重启后会继续尝试补发。2. 配额与状态感知插件现在能清晰区分失败原因窗口过期企业微信规定收到用户消息后必须在48小时内回复。超时后无法再主动发送。额度不足企业微信 API 有调用频率限制。传输失败网络问题导致发送请求失败。目标无效用户已不在群内或不存在。 在/status命令和自检输出中你可以直接看到这些状态便于快速定位问题。3. 推理过程展示 (delivery.reasoning)很多 AI 模型会在回复前输出一段think的思考过程。插件可以帮你优雅地处理它mode: separate将思考过程和最终回复分开显示。思考过程可能会被折叠或标记为“思考中”。mode: append将思考过程合并到最终回复的末尾。mode: hide完全隐藏思考过程。 这个功能在 Bot 模式下体验最佳可以原生地展示“思考中”状态。4.4 内置文档工具 (wecom_doc)这是一个非常实用的生产力工具。它允许 AI 助手直接操作企业微信文档微文档包括创建、重命名、分享、设置权限、创建收集表等。启用方式在配置中设置tools.doc: true即可。它会自动复用当前配置的企业微信账号凭证。使用示例用户“帮我创建一个名为‘项目周报’的文档。”AI调用wecom_doc工具创建成功并返回文档链接和 ID。用户“把文档doc_abc123分享给 Alice 和 Bob并给他们编辑权限。”AI调用工具执行权限修改。一个重要提示当前版本的wecom_doc主要专注于文档的元数据操作创建、权限、分享并不包含一个富文本编辑器来修改文档正文内容。它的定位是文档的“管理员”和“协作者”而不是“撰稿人”。如果你的需求是让 AI 直接撰写长篇文档内容可能需要结合其他方式如生成 Markdown 再粘贴。自动授权默认情况下当 AI 在企微会话中应请求创建一个新文档时插件会自动将请求者即发送消息的用户添加为该文档的协作者避免出现“文档创建了但我自己打不开”的尴尬情况。你可以通过docAutoGrantRequesterCollaborator: false关闭此行为。5. 高级部署与运维指南当你的机器人从 demo 走向生产就会遇到网络、监控、升级等实际问题。这部分分享一些进阶的实操经验。5.1 公网回调与网络架构对于 Agent 模式和 Bot API 模式公网可访问的回调地址 (URL) 是必须的。企业微信服务器会向这个 URL 发送 POST 请求。常见方案与避坑点本地开发/测试使用Cloudflare Tunnel或ngrok等内网穿透工具。这是最快的方式。但请注意免费隧道域名可能被企业微信安全策略拦截最好使用自定义域名。云服务器部署在云主机上部署 OpenClaw并配置域名和 HTTPS。这是生产环境的标准做法。反向代理配置这是最容易出错的地方。你的 Nginx/Apache/Caddy 配置必须确保路径正确将/wecom/callback(Agent) 或/wecom/bot/callback(Bot) 代理到 OpenClaw 网关的实际端口默认 3000。绕过认证如果你的网关前面有统一认证如 Gateway Auth、Zero Trust必须为这些 webhook 路径设置豁免否则企业微信的请求会被拦截返回 401/403 错误。超时设置适当调大代理的超时时间如proxy_read_timeout 90s;因为 AI 推理可能较慢。一个 Nginx 配置示例server { listen 443 ssl; server_name your-domain.com; location /wecom/ { # 重要如果网关有认证这里可能需要添加认证豁免头或者将 /wecom/ 路径排除在认证之外 proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 90s; } # 其他 location 规则... }5.2 使用环境变量管理敏感信息将corpSecret,callbackToken,callbackAesKey,bot.secret等敏感信息直接写在openclaw.json中是不安全的尤其是当配置文件需要纳入版本控制时。OpenClaw 支持通过环境变量注入配置。你可以在系统环境变量中设置也可以在 OpenClaw 的env.vars中配置。方法一系统环境变量export WECOM_CORP_IDwwxxxx export WECOM_CORP_SECRETyour_secret_here export WECOM_BOT_SECRETyour_bot_secret_here # 然后启动 openclaw gateway方法二OpenClawenv.vars配置在~/.openclaw/openclaw.json中{ env: { vars: { WECOM_CORP_ID: wwxxxx, WECOM_CORP_SECRET: your_secret_here, WECOM_BOT_SECRET: your_bot_secret_here } }, channels: { wecom: { corpId: ${WECOM_CORP_ID}, corpSecret: ${WECOM_CORP_SECRET}, bot: { longConnection: { secret: ${WECOM_BOT_SECRET} } } } } }更佳实践对于生产环境建议使用专业的密钥管理服务如 HashiCorp Vault, AWS Secrets Manager或至少使用.env文件通过dotenv等工具加载并确保.env文件被.gitignore排除。5.3 监控与排查机器人不回复了怎么办回复慢了怎么办你需要一些观察手段。查看网关状态openclaw gateway status关注RPC probe和 WeCom 相关组件的状态。使用自检命令# 检查所有账户 npm run wecom:selfcheck -- --all-accounts # 深度检查Agent模式 npm run wecom:agent:selfcheck -- --all-accounts # 深度检查Bot模式 npm run wecom:bot:selfcheck -- --all-accounts自检命令会验证配置完整性、网络连通性、API 权限等并给出明确的通过/失败指示和修复建议。查看运行日志 OpenClaw 的日志通常输出到标准输出或文件。你可以通过日志级别过滤信息。# 调整日志级别查看更多细节在 openclaw.json 中配置 # log: { level: debug }重点关注[wecom]前缀的日志。当消息投递失败时日志会记录具体原因如WINDOW_EXPIRED,QUOTA_EXCEEDED。使用/status命令 在企业微信里向机器人发送/status命令如果该命令在允许列表中它会返回当前运行状态摘要包括24小时回复窗口状态、待补发消息数量等。检查 Pending Reply 队列 如果启用了持久化待补发消息会存储在文件中默认在 OpenClaw 状态目录下。检查这些文件可以帮助你了解哪些消息发送失败了。5.4 版本升级与配置迁移插件的配置结构随着版本迭代可能会优化。从旧版本升级时可以使用内置的迁移工具来检查和更新你的配置。# 检查当前配置是否有需要迁移的遗留字段 npm run wecom:migrate -- --json这个命令会分析你的openclaw.json识别出过时的字段如旧的agent.corpId写法或混合布局问题并生成一个迁移补丁 (configPatch)。你可以选择手动应用或者使用--apply-repair参数让工具自动合并建议先备份原配置文件。一个我踩过的坑早期版本可能将 Bot 配置放在channels.wecom.botId和channels.wecom.secret。新版本推荐统一放在channels.wecom.bot.longConnection下。迁移工具能很好地处理这种变化。6. 常见问题与故障排查实录即使按照指南操作也难免会遇到问题。这里我整理了一些最常见的问题和解决方法希望能帮你快速排雷。6.1 消息能收到但机器人不回复这是最高频的问题。请按以下顺序排查检查 OpenClaw 网关和插件是否正常运行openclaw gateway status确保状态是running并且 WeCom 相关组件没有报错。检查企业微信后台配置Agent模式确认自建应用的“接收消息”已开启并且URL,Token,EncodingAESKey与 OpenClaw 配置中的webhookPath,callbackToken,callbackAesKey完全一致注意大小写和空格。Agent模式极其重要在企业微信后台找到自建应用的“企业可信IP”配置将你的 OpenClaw 服务器公网 IP 加入白名单。否则企业微信会拒绝来自你服务器的主动消息发送请求导致“只收不发”。Bot模式确认机器人是API 模式不是“Webhook模式”。检查回调 URL 配置是否正确。检查 OpenClaw 路由 (bindings) 消息收到了但有没有正确路由到某个 AI 助手 (Agent)检查bindings配置确保channel: wecom的消息有匹配的路由规则并且目标agentId确实存在且已启用。检查 AI 模型服务 消息路由到了 AI 助手但模型服务本身是否正常尝试通过 OpenClaw 的 WebUI 或其他渠道向同一个 AI 助手提问看是否有回复。查看日志 打开 debug 级别日志搜索[wecom]相关的错误信息。常见的错误有DECRYPTION_ERROR加密密钥错误、INVALID_SIGNATUREToken 校验失败、API_ERROR调用企业微信 API 失败。6.2 Bot 长连接模式连接失败检查botId和secret确保是从企业微信后台“API模式”机器人处复制的正确信息没有多余空格。检查网络连通性你的服务器需要能访问wss://openws.work.weixin.qq.com。可以尝试用curl或telnet测试。查看连接日志在日志中搜索WebSocket、aibot_subscribe等关键词。如果看到持续的重连通常是凭证错误或网络问题。6.3 媒体文件图片、语音处理异常图片发送失败Bot模式Bot 模式发送图片依赖response_url或webhook_bot接口。请确保配置中bot.card.responseUrlEnabled或bot.card.webhookBotEnabled为true。机器人的webhook地址配置正确且有权限。网络能访问企业微信的qyapi.weixin.qq.com。语音无法转写确认已安装ffmpeg插件依赖它进行音频格式转换。如果使用本地whisper转写确认已正确安装whisper-cli或whisperPython 包并且模型已下载。检查voiceTranscription相关配置是否启用以及command路径是否正确。6.4 性能与稳定性调优回复超时AI 模型生成较慢可能导致企业微信等待超时。可以适当调大bot.replyTimeoutMs例如设为120000即2分钟。但要注意企业微信服务器对回调也有超时限制通常30秒左右过长的超时可能无效。API 调用频率限制企业微信 API 有调用频率限制。如果机器人使用非常频繁可能会触发限流。插件内置的“可靠投递”机制Pending Reply和异步重试能在一定程度上缓解此问题。你也可以考虑在业务层做限流或队列。内存与存储如果启用了delivery.pendingReply.persist待补发队列会写入磁盘。确保 OpenClaw 的运行目录有足够的磁盘空间和写入权限。6.5 配置了不生效修改配置后务必重启网关openclaw gateway restart。检查配置语法openclaw.json必须是合法的 JSON 格式。一个多余的逗号都可能导致整个配置加载失败。可以使用在线 JSON 校验工具检查。环境变量优先级环境变量会覆盖配置文件中的值。如果你同时配置了文件和环境变量最终生效的是环境变量的值。检查是否有冲突的环境变量设置。使用自检命令npm run wecom:doctor -- --json是诊断配置问题最强大的工具。它能指出缺失的必填项、冲突的配置、以及网络连通性问题。