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_ID=wwxxxx export WECOM_CORP_SECRET=your_secret_here export WECOM_BOT_SECRET=your_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 配置是否正确。
- Agent模式:确认自建应用的“接收消息”已开启,并且
检查 OpenClaw 路由 (
bindings): 消息收到了,但有没有正确路由到某个 AI 助手 (Agent)?检查bindings配置,确保channel: wecom的消息有匹配的路由规则,并且目标agentId确实存在且已启用。检查 AI 模型服务: 消息路由到了 AI 助手,但模型服务本身是否正常?尝试通过 OpenClaw 的 WebUI 或其他渠道向同一个 AI 助手提问,看是否有回复。
查看日志: 打开 debug 级别日志,搜索
[wecom]相关的错误信息。常见的错误有:DECRYPTION_ERROR(加密密钥错误)、INVALID_SIGNATURE(Token 校验失败)、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是诊断配置问题最强大的工具。它能指出缺失的必填项、冲突的配置、以及网络连通性问题。