openclaw-plugin-wecom

GitHub
676 82 简单 1 次阅读 今天ISC语言模型插件
AI 解读 由 AI 自动生成,仅供参考

openclaw-plugin-wecom 是一款专为 OpenClaw 框架打造的企业微信(WeCom)增强插件,旨在让 AI 机器人更深度、灵活地融入企业办公场景。它解决了官方插件在多账号管理、动态会话隔离及高级消息交互方面的局限,帮助团队构建更稳健的企业级 AI 应用。

该工具特别适合需要定制企业微信 AI 助手的开发者和技术团队使用。其核心亮点在于支持 WebSocket 长连接与流式输出,确保对话响应实时流畅;同时提供动态 Agent 路由功能,可按用户或群组自动隔离会话与工作区,实现精细化的权限管理。此外,它还具备指令白名单、运行时配额感知、自建应用主动推送(支持文本、图片、文件)以及消息去重等高级特性,有效防止资源滥用并提升系统稳定性。对于从传统 HTTP 回调模式迁移的用户,openclaw-plugin-wecom 提供了平滑的过渡方案,仅需配置 BotID 和密钥即可启用现代化的长连接模式,大幅降低了运维复杂度。无论是构建内部客服机器人还是团队协作助手,它都能提供强大的底层支撑。

使用场景

某中型互联网公司的运维团队希望将内部 AI 助手集成到企业微信群聊中,用于实时响应故障报警并自动执行排查指令,同时确保只有授权人员能触发高危操作。

没有 openclaw-plugin-wecom 时

  • 会话混乱难隔离:多个业务群的请求混杂在同一个 Agent 中,上下文互相干扰,导致 AI 经常“张冠李戴”,无法区分不同项目的故障现场。
  • 权限管控缺失:缺乏指令白名单机制,任何群成员都能发送 /restart-server 等高危命令,存在严重的安全隐患。
  • 消息触达受限:仅能被动回复群内消息,无法主动向特定部门或标签组推送紧急告警,且不支持流式输出,长文本生成时用户等待体验极差。
  • 运维黑盒无追踪:缺少详细的收发日志与配额感知,消息丢失后无法重试,也无法监控机器人是否因达到 24 小时被动回复限制而停摆。

使用 openclaw-plugin-wecom 后

  • 动态路由隔离:利用动态 Agent 管理功能,自动按群组隔离会话工作区,确保每个项目的故障排查上下文独立且精准。
  • 细粒度权限控制:通过指令白名单与管理者绕过机制,仅允许运维组长执行高危 Slash 命令,普通员工仅限查询类操作,筑牢安全防线。
  • 主动通知与流畅交互:支持基于部门/标签的主动消息推送,结合流式输出与思考占位符,让长报告生成过程透明流畅,显著提升响应体验。
  • 高可靠可观测:内置配额实时监控与断连自动重试机制,配合完整的出入站日志,确保关键告警必达,运维状态全程可视。

openclaw-plugin-wecom 将原本松散脆弱的群聊机器人升级为具备企业级隔离、安全管控与高可用性的智能运维中枢。

运行环境要求

操作系统
  • 未说明
GPU

不需要 GPU

内存

未说明

依赖
notes该工具是 OpenClaw 的 Node.js 插件,非 Python 项目。运行需安装 Node.js 环境及 OpenClaw (版本 2026.3.23-2+)。必须拥有企业微信管理后台权限以创建 AI 机器人或自建应用。网络方面,运行机器需能出站访问企业微信 WebSocket (wss://openws.work.weixin.qq.com) 及 API (https://qyapi.weixin.qq.com)。v2.0+ 版本主要采用 WebSocket 长连接模式,不再强制要求公网 HTTP 回调地址(除非使用可选的自建应用回调入站功能)。
python不适用 (基于 Node.js)
@sunnoy/wecom
@wecom/aibot-node-sdk
OpenClaw (>=2026.3.23-2)
openclaw-plugin-wecom hero image

快速开始

OpenClaw 企业微信(WeCom)增强插件

npm license

@sunnoy/wecomOpenClaw 企业微信渠道的社区增强插件,基于官方 @wecom/wecom-openclaw-plugin 的 WebSocket 长连接骨架,提供多账号管理、动态 Agent 隔离、Agent API / Webhook 增强出站、指令白名单、配额感知等企业级特性。

底层 SDK:@wecom/aibot-node-sdk — 企业微信智能机器人 Node.js SDK。

⚠️ 从 HTTP 回调迁移到长连接: 2.0 版本完全采用企业微信 AI 机器人 WebSocket 长连接模式。如果你之前使用 HTTP 回调(Token + EncodingAESKey + 回调 URL),需要在企业微信管理后台将机器人切换到长连接模式,然后删除旧的回调配置。切换后只需 botIdsecret 即可接入。

2.1 新增: 在 WS 长连接之外,2.1 版本新增了企业微信自建应用"接收消息"HTTP 回调作为可选入站通道。在 channels.wecom.agent 下配置 callback.tokencallback.encodingAESKeycallback.path 即可同时启用,与 WS 通道并行运行,互不影响。

相比官方插件的增强特性

下表列出了本插件相比 官方 WeCom OpenClaw 插件npm)额外提供的能力:

特性 官方插件 本插件
WebSocket 长连接 + 流式回复
私聊 / 群聊接收
DM 准入策略(pairing / open / allowlist / disabled)
群聊准入策略(open / allowlist / disabled)
按群配置发送者白名单
思考占位(<think> 占位符)
CLI 交互式配置向导
多账号管理(多 Bot 独立配置、共享字段继承)
动态 Agent 路由(按用户 / 群自动隔离会话与工作区)
Workspace 模板(自动为新 Agent 复制 AGENTS.md 等引导文件)
Agent API 增强出站(自建应用主动发送文本、图片、文件)
部门 / 标签目标发送party: / tag: 寻址)
Webhook Bot 群通知(命名 webhook 映射,markdown / 图片 / 文件)
指令白名单(限制普通用户可执行的 slash 命令)
管理员绕过(命令白名单 + 动态 Agent 路由)
运行时配额感知(被动回复 24h 窗口 + 主动发送额度追踪与告警)
Pending Reply 重试(WS 断连后自动通过 Agent API 补发未送达回复)
Reasoning 流式节流(800ms 节流防止 SDK 队列溢出)
<think> 标签规范化(兼容 <thinking> / <thought> 等变体)
Reply 媒体指令解析(自动提取 LLM 输出中的 MEDIA: / FILE: 路径)
出站代理network.egressProxyUrl
自定义 API 基础地址network.apiBaseUrl / WECOM_API_BASE_URL
Bindings 路由(固定绑定企业微信账号到指定 Agent)
消息去重(reqId + msgId 去重,防止重复处理)
入站图文混排mixed 消息拆解为文本 + 图片)
入站语音转写voice.content 自动提取)
入站引用消息quote 上下文透传)
自建应用回调入站(HTTP 回调作为独立入站通道,与 WS 并行)
Agent API Markdown 回复(回调入站回复默认 markdown 格式)
入站/出站信息日志(WS / CB 收发日志,便于追踪消息流)

目录

前置要求

  • 已安装 OpenClaw 2026.3.23-2+
  • 企业微信管理后台权限,可创建 AI 机器人或自建应用
  • 机器人已切换到长连接模式(参考官方文档
  • 运行 OpenClaw 的机器可以出站访问:
    • wss://openws.work.weixin.qq.com
    • https://qyapi.weixin.qq.com(启用 Agent / Webhook 时)

Bot 主链路不需要企业微信反向访问你的 HTTP 回调地址。

安装

openclaw plugins install @sunnoy/wecom

3.0 兼容性说明:3.0.0 开始,本插件仅支持 OpenClaw 2026.3.23-2+. 旧版 OpenClaw 请继续使用 2.x.

从官方插件迁移: 如果之前使用 openclaw plugins install @wecom/wecom-openclaw-plugin,请先卸载官方插件再安装本插件。channels.wecom 配置字段兼容,无需修改。

从 HTTP 回调迁移

如果之前使用 HTTP 回调模式(Token + EncodingAESKey + 回调 URL),迁移步骤如下:

  1. 企业微信后台:进入「应用管理」→「智能机器人」,将机器人切换到长连接模式(参考官方文档
  2. 记录凭证:切换后获取新的 BotIdSecret
  3. 更新配置:在 ~/.openclaw/openclaw.json 中:
    • 设置 channels.wecom.botIdchannels.wecom.secret
    • 删除旧的 tokenencodingAesKey、回调 URL 相关配置
  4. 安装插件openclaw plugins install @sunnoy/wecom
  5. 重启 Gatewayopenclaw gateway restart

迁移后不再需要公网可达的 HTTP 回调地址,插件会主动连接企业微信 WebSocket。

运行测试

npm test

配置

单账号示例

~/.openclaw/openclaw.json 中添加:

{
  "plugins": {
    "entries": {
      "wecom": {
        "enabled": true
      }
    }
  },
  "channels": {
    "wecom": {
      "enabled": true,
      "botId": "aibxxxxxxxxxxxxxxxx",
      "secret": "xxxxxxxxxxxxxxxx",
      "welcomeMessage": "你好,我是 AI 助手。",
      "sendThinkingMessage": true,
      "dmPolicy": "pairing",
      "allowFrom": [],
      "groupPolicy": "open",
      "groupAllowFrom": [],
      "adminUsers": ["admin-userid"],
      "commands": {
        "enabled": true,
        "allowlist": ["/new", "/compact", "/help", "/status"]
      },
      "dynamicAgents": {
        "enabled": true,
        "adminBypass": false
      },
      "dm": {
        "createAgentOnFirstMessage": true
      },
      "groupChat": {
        "enabled": true,
        "requireMention": true,
        "mentionPatterns": ["@"]
      },
      "workspaceTemplate": "/path/to/template-dir",
      "mediaLocalRoots": ["/tmp/openclaw"],
      "agent": {
        "corpId": "wwxxxxxxxxxxxxxxxx",
        "corpSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "agentId": 1000002
      },
      "webhooks": {
        "ops": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx",
        "dev": "yyy"
      },
      "network": {
        "egressProxyUrl": "http://proxy.internal:8080",
        "apiBaseUrl": "https://qyapi.weixin.qq.com"
      }
    }
  }
}

webhooks 的 value 既可以是完整 URL,也可以只写群机器人的 key.

核心配置

配置项 类型 必填 说明
plugins.entries.wecom.enabled boolean 启用插件
channels.wecom.enabled boolean 游道开关
channels.wecom.botId string 企业微信 AI 机器人 Bot ID
channels.wecom.secret string 企业微信 AI 机器人 Secret
channels.wecom.websocketUrl string WS 地址,默认 wss://openws.work.weixin.qq.com
channels.wecom.sendThinkingMessage boolean 是否先发送 <<think>> 占位,默认 true
channels.wecom.welcomeMessage string 进入会话欢迎语(非空时固定使用该字符串)
channels.wecom.welcomeMessagesFile string 欢迎语列表文件路径。支持:{ "messages": [ ... ] } 或顶层数组;每条欢迎语可为一行一个字符串的数组(推荐,易读),或单条字符串(可含 \\n)。相对路径基于 OpenClaw 状态目录(~/.openclawOPENCLAW_STATE_DIR)。未设置 welcomeMessage 时从该文件随机选取;修改文件后无需重启服务(按 mtime 自动重读)
channels.wecom.adminUsers string[] 管理员用户 ID,可绕过命令白名单
channels.wecom.defaultAccount string 多账号模式默认账号

准入与安全配置

配置项 类型 必填 说明
channels.wecom.dmPolicy string pairingallowlistopendisabled,默认 pairing
channels.wecom.allowFrom string[] 私聊 allowlist
channels.wecom.groupPolicy string openallowlistdisabled,默认 open
channels.wecom.groupAllowFrom string[] 允许触发的群聊 ID 列表
channels.wecom.groups object 按群覆盖配置,可为某个群单独设置 allowFrom
channels.wecom.commands.enabled boolean 是否启用命令白名单,默认 true
channels.wecom.commands.allowlist string[] 普通用户允许执行的命令

路由与工作区配置

配置项 类型 必填 说明
channels.wecom.dynamicAgents.enabled boolean 是否启用动态 Agent,默认 true
channels.wecom.dynamicAgents.adminBypass boolean 管理员是否绕过动态 Agent,默认 false
channels.wecom.dm.createAgentOnFirstMessage boolean 私聊是否按用户建独立 Agent,默认 true
channels.wecom.groupChat.enabled boolean 是否启用群聊处理,默认 true
channels.wecom.groupChat.requireMention boolean 群聊是否要求 @ 才响应,默认 true
channels.wecom.groupChat.mentionPatterns string[] 群聊触发前缀,默认 ["@"]
channels.wecom.workspaceTemplate string 动态 Agent 工作区模板目录
channels.wecom.mediaLocalRoots string[] 额外允许被动回复读取的宿主机目录列表。用于放行 MEDIA:/abs/pathFILE:/abs/path 指向的本地文件;默认只允许当前 Agent workspace 和浏览器产物目录。注意:浏览器工具返回的宿主机路径在 block reply 阶段仍可能被 core sandbox 校验拦下,建议先用 stage_browser_media 复制到 /workspace/... 后再回复。多账号模式下也可配置在 channels.wecom.<accountId>.mediaLocalRoots。修改后需重启 Gateway 生效

增强出站配置

配置项 类型 必填 说明
channels.wecom.agent.corpId string 自建应用 CorpID
channels.wecom.agent.corpSecret string 自建应用 Secret
channels.wecom.agent.agentId number 自建应用 AgentId
channels.wecom.agent.replyFormat string 回调入站回复格式,"markdown"(默认)或 "text"
channels.wecom.agent.callback.token string 回调验签 Token
channels.wecom.agent.callback.encodingAESKey string 回调消息解密密钥(43 位)
channels.wecom.agent.callback.path string 回调 HTTP 路由路径,如 "/webhooks/app"
channels.wecom.webhooks object 群机器人 webhook 映射
channels.wecom.network.egressProxyUrl string Agent / Webhook 出站代理
channels.wecom.network.apiBaseUrl string 企业微信 API 基础地址覆盖,默认官方地址

Agent 增强出站不需要 tokenencodingAesKey、回调 URL;只有需要同时启用回调入站时才需配置 agent.callback.*

多账号示例

{
  "channels": {
    "wecom": {
      "defaultAccount": "open",
      "adminUsers": ["admin-userid"],
      "commands": {
        "enabled": true,
        "allowlist": ["/new", "/compact", "/help", "/status"]
      },
      "open": {
        "botId": "aib-open-xxx",
        "secret": "secret-open-xxx",
        "dmPolicy": "open"
      },
      "support": {
        "botId": "aib-support-xxx",
        "secret": "secret-support-xxx",
        "dmPolicy": "pairing",
        "mediaLocalRoots": ["/tmp/openclaw"],
        "agent": {
          "corpId": "wwxxxxxxxxxxxxxxxx",
          "corpSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "agentId": 1000002
        },
        "webhooks": {
          "ops": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
        }
      }
    }
  }
}

多账号模式下:

  • 顶层共享字段会合并到各账号
  • channels.wecom.<accountId> 是每个账号自己的覆盖项
  • 动态 Agent ID 会自动带账号前缀
  • 旧的 v1 token / encodingAesKey 字段不再使用。

私聊与群聊准入策略

私聊 dmPolicy

含义
pairing 默认模式。陌生用户首次私聊会收到配对码,管理员执行 openclaw pairing approve wecom <code> 后放行
allowlist 只允许 allowFrom 中的用户私聊,不自动发配对码
open 允许所有能私聊机器人的企业微信成员直接进入会话
disabled 禁用私聊

open 的含义就是:如果机器人可见范围允许,企业内任何能私聊到这个 Bot 的成员都可以直接使用。

群聊策略

配置 说明
groupPolicy: "open" 所有群可触发
groupPolicy: "allowlist" + groupAllowFrom 只允许指定群
groupPolicy: "disabled" 禁用群聊
groupChat.requireMention 群聊是否必须 @ 才触发
groups.<chatId>.allowFrom 某个群里仅允许指定成员触发

企业微信侧配置

1. 创建 AI 机器人(Bot 主链路)

这是 v2 的主接入方式,使用 WebSocket 长连接。

  1. 登录企业微信管理后台
  2. 进入「应用管理」→「智能机器人」
  3. 创建机器人,选择长连接模式(参考官方文档
  4. 创建完成后记录 BotIdSecret
  5. 填入 OpenClaw 配置的 channels.wecom.botIdchannels.wecom.secret
  6. 启动 OpenClaw,插件会主动连接官方 WebSocket

长连接模式下不需要配置 HTTP 回调 URL、Token、EncodingAESKey。

2. 创建自建应用(Agent 增强出站 + 可选回调入站)

自建应用承担两个可选职责:

增强出站(主动推送消息):

  • 主动给用户 / 群 / 部门 / 标签发消息
  • 上传图片和文件
  • 当 WS 断连时作为回复后备通道

回调入站(可选,与 WS 并行):

  • 企业微信将用户消息以 HTTP POST 推送到你的服务器
  • 适合需要独立入站 URL 或不方便使用 WS 长连接的场景

创建步骤:

  1. 在企业微信后台创建自建应用
  2. 记录 CorpIDAgentIdSecret
  3. 填入配置:
    • channels.wecom.agent.corpId
    • channels.wecom.agent.agentId
    • channels.wecom.agent.corpSecret
  4. 仅启用回调入站时,额外在应用的「接收消息」中配置回调 URL,并填入对应的 agent.callback.* 配置(见自建应用回调入站

3. 配置群机器人(Webhook 增强出站,可选)

Webhook 只负责群通知。

  1. 在目标群添加群机器人
  2. 复制 webhook URL 或 key
  3. 配置到 channels.wecom.webhooks
  4. 发送目标使用 webhook:<name>

消息能力与投递策略

能力矩阵

能力 Bot(WS) Agent API Webhook
私聊接收 ✅(回调入站)
群聊接收(可配置 @ 触发) ✅(回调入站)
被动流式回复
被动最终帧图片
主动发送文本
主动发送图片 / 文件
发送到部门 / 标签
思考过程 <think>
欢迎语
WS 断连补发

入站消息

类型 说明
text 文本消息
image 图片(AES 加密下载 + 解密)
voice 语音(自动提取转写文本 voice.content
file 文件(AES 加密下载 + 解密)
mixed 图文混排(自动拆解为文本 + 图片)
quote 引用消息(上下文透传)

被动回复

被动回复统一走 WebSocket replyStream

  • 文本内容支持 Markdown
  • <thinking><thought> 等变体会被规范化为 <think>
  • 可先发送 <think></think> 占位(配置 sendThinkingMessage
  • 思考流式更新采用 800ms 节流,防止 SDK 队列溢出
  • 最终回复 finish=true 时可附带图片 msg_item
  • 若最终回复包含 WS 不支持的媒体(文件等),会先文本提示再通过 Agent API 补发

本插件会自动解析模型输出中的 MEDIA: / FILE: 指令,并在回复完成后上传对应文件:

  • 图片使用 MEDIA:/abs/path
  • PDF、音频、视频、压缩包、Office 文档等非图片文件使用 FILE:/abs/path
  • 沙箱内当前工作区文件可直接写成 MEDIA:/workspace/...FILE:/workspace/...
  • 浏览器生成的文件默认允许从 OpenClaw 状态目录下的浏览器媒体目录读取,但如果浏览器工具返回的是宿主机绝对路径,先调用 stage_browser_media,再使用它返回的 MEDIA:/workspace/...FILE:/workspace/...
  • 宿主机其他目录默认不放行;如果需要回复 /tmp/openclaw/report.pdf 这类文件,请把其父目录加入 channels.wecom.mediaLocalRoots,多账号模式可配在 channels.wecom.<accountId>.mediaLocalRoots
  • 更新 mediaLocalRoots 后需重启 Gateway 生效。

主动发送与后备策略

主动发送分层:

  1. 普通文本优先走 WS sendMessage
  2. 目标为 webhook:<name> 时走 Webhook
  3. 目标为用户 / 群 / 部门 / 标签,且配置了 Agent 时走 Agent API
  4. 发送图片 / 文件时,WS 侧给出文本提示,媒体交给 Agent / Webhook 通道
  5. 未配置 Agent / Webhook 时,只保留 WS 文本提示。

WS 断连自动重试

当 WS 断连导致最终回复发送失败时:

  1. 插件自动将未送达回复加入 pending 队列(TTL 5 分钟,最多 50 条)
  2. WS 重连并认证成功后,自动通过 Agent API 补发所有 pending 回复
  3. 过期条目自动丢弃,不会无限积压

运行时配额感知

插件会进行本地近似记账,并将状态暴露到账号快照/状态中:

  • 连接占线:当同一个 botId 被其他实例接管时,标记为 displaced
  • 24小时被动回复窗口:按会话追踪回复配额(限额30,告警24)。
  • 每会话每日主动发送额度:按会话追踪主动发送配额(限额10,告警8)。
  • 当接近上限或达到上限时,输出警告信息。

当前策略是“感知+告警”,不会进行硬性阻断。

支持的目标格式

格式 示例 说明
wecom:<userId> wecom:zhangsan 发送给企业微信用户
group:<chatId> group:wr123456 发送给群聊
party:<id> party:2 发送给部门
tag:<name> tag:Developers 发送给标签
webhook:<name> webhook:ops 发送给 webhook 群
<chatId> wr123456 直接写群ID也可识别

动态 Agent 与路由

动态 Agent

默认路由规则:

  • 私聊:wecom-dm-<userId>
  • 群聊:wecom-group-<chatId>
  • 多账号私聊:wecom-<accountId>-dm-<userId>
  • 多账号群聊:wecom-<accountId>-group-<chatId>

好处:

  • 每个用户/群聊拥有独立的上下文。
  • 每个动态 Agent 拥有独立的工作区。
  • 可以按账号进一步隔离。

Workspace 模板

workspaceTemplate 目录中的模板文件会在动态 Agent 首次创建时复制到工作区:

  • AGENTS.mdBOOTSTRAP.mdCLAUDE.mdSOUL.mdTOOLS.mdIDENTITY.mdUSER.mdHEARTBEAT.mdsystem-prompt.md

插件会在工作区里写入 .openclaw/wecom-template-state.json 文件,记录首次模板同步状态。已有状态的工作区后续只补缺,不覆盖已有文件。

BOOTSTRAP.md 只会在工作区还没有 memory/MEMORY.md 时参与同步;一旦工作区已经出现记忆痕迹,插件就不再回种 bootstrap,避免打断已完成 onboarding 的会话。

历史工作区如果还没有 state,插件会先补写 state,再按“只补缺、不覆盖”处理,避免存量工作区被重新整批同步。

Bindings

如果 OpenClaw 配置了 bindings,则优先按 binding 路由,不会被动态 Agent 覆盖。

自建应用回调入站

自建应用的「接收消息」HTTP 回调可作为额外的入站通道,与 WS 长连接并行运行,互不干扰。适合已有自建应用的场景,或需要独立回调 URL 的情况。

配置

channels.wecom.agent 下增加 callback 子对象:

{
  "channels": {
    "wecom": {
      "botId": "aib-xxx",
      "secret": "bot-secret-xxx",
      "agent": {
        "corpId": "wwxxxxxxxxxxxx",
        "corpSecret": "app-secret-xxx",
        "agentId": 1000002,
        "replyFormat": "markdown",
        "callback": {
          "token": "YourToken",
          "encodingAESKey": "43位密钥",
          "path": "/webhooks/app"
        }
      }
    }
  }
}
字段 说明
agent.callback.token 企业微信「接收消息」里配置的 Token
agent.callback.encodingAESKey 43位 EncodingAESKey
agent.callback.path Gateway监听的HTTP路径,需与企业微信后台填写的URL一致
agent.replyFormat 回复格式,"markdown"(默认)或 "text"

企业微信侧配置

  1. 进入自建应用 → 「接收消息」
  2. 填写URL:https://<your-gateway-host>:<port><path>(例如 https://example.com:18789/webhooks/app
  3. 填写Token和EncodingAESKey(与配置保持一致)
  4. 点击「保存」,企业微信将发送GET请求验证(gateway会自动回复echostr)
  5. 验证通过后,用户发给自建应用的消息将通过HTTP POST推送到gateway。

支持的消息类型

类型 说明
text 文本消息
image 图片(通过Agent API下载)
voice 语音文件
file 文件
video 视频文件

事件类消息(关注、进入会话等)会被静默忽略。

常见问题

Q: 2.0和之前最大的区别是什么?

2.0完全采用WebSocket长连接,不再使用HTTP回调。需要在企业微信后台将机器人切换到长连接模式

Q: 3.0为什么不能再装在旧OpenClaw上?

3.0开始直接适配OpenClaw 2026.3.23-2+的新版plugin SDK导出和媒体/runtime约定,旧版core缺少这些接口。旧环境请固定使用2.x

Q: 之前用的官方插件@wecom/wecom-openclaw-plugin,怎么迁移?

# 卸载官方插件
openclaw plugins uninstall wecom-openclaw-plugin
# 安装本插件
openclaw plugins install @sunnoy/wecom
# 重启
openclaw gateway restart

channels.wecom配置字段兼容,无需修改。

Q: dmPolicy: "open"是不是企业里任何人都能私聊?

是。前提是该成员对这个机器人可见,并且能在企业微信里私聊到它。

Q: pairing模式怎么放行用户?

用户第一次私聊会收到配对码。管理员执行:

openclaw pairing approve wecom <code>

Q: Agent还需要配置token/encodingAesKey吗?

不需要。Agent只做增强出站,保留corpIdcorpSecretagentId即可。

Q: 入站图片还依赖全局EncodingAESKey吗?

不依赖。WS消息体里的图片/文件自带独立aeskey,插件按image.aeskeyfile.aeskey下载与解密。

Q: 收到disconnected_event是什么情况?

通常表示同一个botId被另一个实例接管了。企业微信同一时刻只允许一个活跃长连接。

Q: 什么时候会走Agent或Webhook?

  • webhook:<name>目标固定走Webhook。
  • 发送部门/标签/媒体消息时优先走Agent。
  • WS断连后的pending回复通过Agent API补发。
  • WS文本主动发送失败时,尝试回退到Agent。

Q: 回复本地文件时提示“没有权限访问路径”怎么办?

先确认文件路径是否在允许目录里:

  • 当前Agent工作区文件默认允许,可直接用FILE:/workspace/...MEDIA:/workspace/...
  • 浏览器生成的文件默认允许,但浏览器工具返回的宿主机路径建议先用stage_browser_media转成/workspace/...
  • 宿主机其他目录需要把父目录加入channels.wecom.mediaLocalRoots
  • 多账号模式如果只想对某个账号生效,可配置channels.wecom.<accountId>.mediaLocalRoots

例如:

{
  "channels": {
    "wecom": {
      "mediaLocalRoots": ["/tmp/openclaw"]
    }
  }
}

修改后重启Gateway。v2.2.1+已支持把mediaLocalRoots并入被动回复文件允许目录。

Q: 60020 not allow to access from your ip是什么问题?

企业微信自建应用API的可信IP限制。把当前服务器出口IP加入企业微信应用的可信IP白名单即可。

项目结构

openclaw-plugin-wecom/
├── index.js                      # 插件入口、生命周期、onboarding
├── dynamic-agent.js              # 动态Agent路由判断
├── image-processor.js            # 图片格式检测、MD5、Base64
├── logger.js                     # 结构化日志
├── think-parser.js               # <think>标签规范化
├── utils.js                      # 工具函数
├── openclaw.plugin.json          # 插件元数据
├── wecom/
│   ├── accounts.js               # 多账号管理与配置继承
│   ├── agent-api.js              # Agent API(Token、发送、上传)
│   ├── allow-from.js             # allowlist规范化与匹配
│   ├── callback-crypto.js        # 回调AES解密与签名验证
│   ├── callback-inbound.js       # 自建应用回调入站处理
│   ├── callback-media.js         # 回调媒体下载
│   ├── channel-plugin.js         # 核心通道(sendNotice/sendMedia)
│   ├── commands.js               # 指令白名单与命令拦截
│   ├── constants.js              # 常量定义
│   ├── dm-policy.js              # 私聊准入策略
│   ├── group-policy.js           # 群聊准入策略
│   ├── http.js                   # HTTP请求+代理
│   ├── onboarding.js             # CLI交互式配置向导
│   ├── runtime-telemetry.js      # 运行时配额追踪
│   ├── sandbox.js                # 沙箱集成
│   ├── state.js                  # 插件状态管理
│   ├── target.js                 # 目标解析(user/group/party/tag/webhook)
│   ├── webhook-bot.js            # WebhookBot发送
│   ├── workspace-template.js     # 工作区模板同步
│   ├── ws-monitor.js             # WS消息处理、流式回复、节流、重试
│   └── ws-state.js               # WS状态+pending reply队列
└── tests/
    ├── accounts-reserved-keys.test.js
    ├── api-base-url.test.js
    ├── callback-crypto.test.js
    ├── callback-inbound.test.js
    ├── channel-plugin.media-type.test.js
    ├── channel-plugin.notice.test.js
    ├── dynamic-agent.test.js
    ├── image-processor.test.js
    ├── issue-fixes.test.js
    ├── reply-media-directive.test.js
    ├── runtime-telemetry.test.js
    ├── target.test.js
    ├── think-parser.test.js
    ├── workspace-template.test.js
    ├── ws-monitor.quote-mixed.test.js
    └── ws.e2e.test.js

自定义 Skills 配合沙箱使用实践

OpenClaw 支持自定义 Skills 并通过沙箱(Docker)隔离执行,下面保留一份生产环境常见配置示例:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "workspaceAccess": "rw",
        "scope": "agent",
        "docker": {
          "image": "your-registry.com/openclaw-agent:v2026.x.x",
          "readOnlyRoot": false,
          "network": "bridge",
          "extraHosts": [
            "your-domain.internal:xxx.xxx.xxx.xxx"
          ],
          "binds": [
            "/path/to/skills:/workspace/skills:ro"
          ],
          "dangerouslyAllowReservedContainerTargets": true,
          "dangerouslyAllowExternalBindSources": true
        },
        "prune": {
          "idleHours": 87600,
          "maxAgeDays": 3650
        }
      }
    }
  },
  "skills": {
    "allowBundled": ["_none_"],
    "load": {
      "extraDirs": ["/path/to/skills"],
      "watch": true,
      "watchDebounceMs": 250
    }
  }
}

关键点:

  • sandbox.mode: "all" 表示所有操作都走沙箱
  • sandbox.workspaceAccess: "rw" 允许 Agent 读写工作区
  • sandbox.scope: "agent" 表示每个 Agent 独立沙箱
  • sandbox.docker.binds 可把宿主机技能目录映射到容器内 /workspace/skills
  • skills.load.extraDirs 用于声明自定义 Skills 加载目录
  • skills.load.watch 改动 Skill 后自动热加载

相关链接

贡献与协议

  • 贡献说明见 CONTRIBUTING.md
  • 许可证为 ISC

版本历史

v3.0.12026/04/08
v3.0.02026/03/24
v2.4.02026/03/23
v2.3.02026/03/20
v2.2.12026/03/18
v2.2.02026/03/15
v2.1.02026/03/11
v2.0.22026/03/11
v2.0.12026/03/10
v2.0.02026/03/10
v1.9.02026/03/06
v1.8.02026/03/06
v1.7.12026/03/05
v1.7.02026/03/05
v1.6.22026/03/05
v1.6.02026/03/04
v1.5.12026/03/04
v1.5.02026/03/03
v1.4.12026/03/02
v1.4.02026/03/02

常见问题

相似工具推荐

everything-claude-code

everything-claude-code 是一套专为 AI 编程助手(如 Claude Code、Codex、Cursor 等)打造的高性能优化系统。它不仅仅是一组配置文件,而是一个经过长期实战打磨的完整框架,旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。 通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能,everything-claude-code 能显著提升 AI 在复杂任务中的表现,帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略,使得模型响应更快、成本更低,同时有效防御潜在的攻击向量。 这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库,还是需要 AI 协助进行安全审计与自动化测试,everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目,它融合了多语言支持与丰富的实战钩子(hooks),让 AI 真正成长为懂上

158.1k|★★☆☆☆|今天
开发框架Agent语言模型

opencode

OpenCode 是一款开源的 AI 编程助手(Coding Agent),旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件,而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码,还是排查难以定位的 Bug,OpenCode 都能通过自然语言交互高效完成,显著减少开发者在重复性劳动和上下文切换上的时间消耗。 这款工具专为软件开发者、工程师及技术研究人员设计,特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构,这意味着用户可以审查代码逻辑、自定义行为策略,甚至私有化部署以保障数据安全,彻底打破了传统闭源 AI 助手的“黑盒”限制。 在技术体验上,OpenCode 提供了灵活的终端界面(Terminal UI)和正在测试中的桌面应用程序,支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具,安装便捷,并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客,还是渴望提升产出的独立开发者,OpenCode 都提供了一个透明、可信

144.3k|★☆☆☆☆|今天
Agent插件

gemini-cli

gemini-cli 是一款由谷歌推出的开源 AI 命令行工具,它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言,它提供了一条从输入提示词到获取模型响应的最短路径,无需切换窗口即可享受智能辅助。 这款工具主要解决了开发过程中频繁上下文切换的痛点,让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用,还是执行复杂的 Git 操作,gemini-cli 都能通过自然语言指令高效处理。 它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口,具备出色的逻辑推理能力;内置 Google 搜索、文件操作及 Shell 命令执行等实用工具;更独特的是,它支持 MCP(模型上下文协议),允许用户灵活扩展自定义集成,连接如图像生成等外部能力。此外,个人谷歌账号即可享受免费的额度支持,且项目基于 Apache 2.0 协议完全开源,是提升终端工作效率的理想助手。

100.8k|★★☆☆☆|1周前
插件Agent图像

markitdown

MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具,专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片(含 OCR)、音频(含语音转录)、HTML 乃至 YouTube 链接等多种格式的解析,能够精准提取文档中的标题、列表、表格和链接等关键结构信息。 在人工智能应用日益普及的今天,大语言模型(LLM)虽擅长处理文本,却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点,它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式,成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外,它还提供了 MCP(模型上下文协议)服务器,可无缝集成到 Claude Desktop 等 LLM 应用中。 这款工具特别适合开发者、数据科学家及 AI 研究人员使用,尤其是那些需要构建文档检索增强生成(RAG)系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性,但其核心优势在于为机器

93.4k|★★☆☆☆|1周前
插件开发框架

LLMs-from-scratch

LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目,旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型(LLM)。它不仅是同名技术著作的官方代码库,更提供了一套完整的实践方案,涵盖模型开发、预训练及微调的全过程。 该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型,却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码,用户能够透彻掌握 Transformer 架构、注意力机制等关键原理,从而真正理解大模型是如何“思考”的。此外,项目还包含了加载大型预训练权重进行微调的代码,帮助用户将理论知识延伸至实际应用。 LLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API,而是渴望探究模型构建细节的技术人员而言,这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计:将复杂的系统工程拆解为清晰的步骤,配合详细的图表与示例,让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础,还是为未来研发更大规模的模型做准备

90.1k|★★★☆☆|1周前
语言模型图像Agent

NextChat

NextChat 是一款轻量且极速的 AI 助手,旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性,以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发,NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。 这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言,它也提供了便捷的自托管方案,支持一键部署到 Vercel 或 Zeabur 等平台。 NextChat 的核心亮点在于其广泛的模型兼容性,原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型,让用户在一个界面即可自由切换不同 AI 能力。此外,它还率先支持 MCP(Model Context Protocol)协议,增强了上下文处理能力。针对企业用户,NextChat 提供专业版解决方案,具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能,满足公司对数据隐私和个性化管理的高标准要求。

87.6k|★★☆☆☆|1周前
开发框架语言模型