本文档介绍如何安装和配置企业微信 OpenClaw 插件,将 AI 助手接入企业微信。
前置要求
- 已安装 OpenClaw
- 企业微信管理后台权限,可创建自建应用
- 公网服务器 或 内网穿透工具(本机安装时需要)
重要说明
企业微信消息接收方式
企业微信自建应用不支持长连接,需要通过 HTTP 回调 方式接收消息:
- 企业微信将消息推送到你配置的回调 URL
- 你的服务器接收并处理消息
- 处理完成后调用企业微信 API 发送回复
内网穿透(重要)
注意:这里说的都是你在自己电脑本地安装的情况下才需要内网穿透,主要是让你本地127.0.0.1能在公网访问,如果你本身有云服务器,是不需要的,直接域名指向你的云服务器ip就行了,要简单很多,使用cloudflare一定要开启橙色云,会自动生成ssl证书,数据通过https传输,全程加密,保证数据不会泄露
如果你在本机或内网环境安装,需要使用内网穿透工具将本地服务暴露到公网。
| 方案 | 说明 | 推荐度 |
|---|---|---|
| Cloudflare Tunnel | 免费、稳定、HTTPS,需自有域名(本机安装推荐) | ⭐⭐⭐⭐⭐ |
| cpolar + 自有域名 | 速度快,通过 CNAME 中转(较繁琐,不推荐) | ⭐⭐⭐⭐ |
| 云服务器 | 阿里云/腾讯云等,直接部署 | ⭐⭐⭐⭐⭐ |
一、内网穿透方案(本机安装必选)
方案一:Cloudflare Tunnel(推荐)
前提:你需要有自己的域名(如 example.com),并需要先将域名托管到 Cloudflare(企微回调地址不认cf提供的临时域名,如果单纯做内网穿透,可以不注册账号,直接按下面方式就可以)
shellcloudflared tunnel --url http://localhost:8080
特点:
✅ 完全不需要注册/登录
✅ 自动生成随机临时域名(如 https://abcd-1234.trycloudflare.com )
❌ 每次重启域名会变
❌ 适合临时测试,不适合长期使用 ❌ 微信回调不支持
0. 将域名托管到 Cloudflare(首次使用必做)
步骤说明:如果域名在阿里云/腾讯云等注册商,需要将 DNS 服务器改为 Cloudflare 的。
-
在 Cloudflare 添加站点
- 访问 https://dash.cloudflare.com/
- 点击 添加站点
- 输入你的域名(如
example.com) - 选择 免费套餐
- Cloudflare 会扫描现有的 DNS 记录
-
获取 Cloudflare DNS 服务器地址
添加站点后,Cloudflare 会提供两个 DNS 服务器地址,如:
dotbob.ns.cloudflare.com lola.ns.cloudflare.com -
在域名注册商修改 DNS 服务器
阿里云示例:
- 登录阿里云 → 域名 → 找到你的域名
- 点击 DNS 修改 → 修改 DNS 服务器
- 删除原有的 DNS 服务器
- 添加 Cloudflare 提供的两个 DNS 服务器地址
- 确认修改
腾讯云示例:
- 登录腾讯云 → DNSPod DNS 解析 → 我的域名
- 点击 修改 DNS 服务器
- 改为 Cloudflare 提供的地址
-
等待 DNS 生效
通常需要 2min-24 小时生效,Cloudflare 会检测状态:
状态:生效中 → 活跃 -
验证域名已托管
返回 Cloudflare Dashboard,看到状态显示 活跃 即可。
1. 本地安装 cloudflared
bash# macOS brew install cloudflared # Linux wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb sudo dpkg -i cloudflared-linux-amd64.deb
2. 登录并授权域名
bashcloudflared tunnel login
浏览器会打开 Cloudflare 授权页面,选择你已托管的域名并授权。
3. 创建隧道
bashcloudflared tunnel create openclaw
记下返回的隧道 ID,如:a1b2c3d4-e5f6-7890-abcd-ef1234567890
4. 配置隧道
创建配置文件 ~/.cloudflared/config.yml:
bashcat > ~/.cloudflared/config.yml << EOF tunnel: <你的隧道ID> credentials-file: ~/.cloudflared/<你的隧道ID>.json ingress: - hostname: openclaw.你的域名.com service: http://localhost:18789 - service: http_status:404 EOF
示例:
yamltunnel: a1b2c3d4-e5f6-7890-abcd-ef1234567890 credentials-file: ~/.cloudflared/a1b2c3d4-e5f6-7890-abcd-ef1234567890.json ingress: - hostname: openclaw.example.com service: http://localhost:18789 - service: http_status:404
5. 配置 Cloudflare DNS
在 Cloudflare Dashboard 中:
- 登录 https://dash.cloudflare.com/
- 选择你的域名
- 进入 DNS → 记录
- 添加或修改
openclaw记录:
| 类型 | 名称 | 内容 | 代理状态 |
|---|---|---|---|
| CNAME | openclaw | 你的隧道ID.cfargotunnel.com | 🟠 已代理 |
示例:
dot类型: CNAME 名称: openclaw 内容: a1b2c3d4-e5f6-7890-abcd-ef1234567890.cfargotunnel.com 代理状态: 开启(橙色云朵)
6. 启动隧道
bashcloudflared tunnel run openclaw
7. 验证
bashcurl https://openclaw.你的域名.com/wecom/health
正常返回:
json{"status":"ok","channel":"wecom","timestamp":"..."}
8. 后台运行(可选)
bash# 使用 nohup nohup cloudflared tunnel run openclaw > /tmp/cloudflared.log 2>&1 & # 或使用 macOS launchd brew services start cloudflared
方案二:cpolar + 自有域名
原理:通过 Cloudflare DNS CNAME 将自己的域名指向 cpolar 隧道地址。
优势:cpolar 国内速度快,配置简单。
1. 安装 cpolar
bash# macOS brew tap cpolar/cpolar && brew install cpolar # Linux curl -L https://www.cpolar.com/static/downloads/release-release/cpolar-stable-linux-amd64.zip -o cpolar.zip unzip cpolar.zip sudo mv cpolar /usr/local/bin/
2. 注册并登录
访问 https://dashboard.cpolar.com/ 注册账号,获取 Authtoken。
bashcpolar authtoken <你的token>
3. 启动 cpolar 隧道
bashcpolar http 18789
会显示临时 URL,如:https://abc123.cpolar.cn
正常情况下到这一步内网穿透就完成了,你可以远程通过https://abc123.cpolar.cn访问你本地电脑,但是微信的回调地址不支持cpolar.cn域名,保存的时候验证无法通过,所以还需要cloudflare中转一下,这里主要讲解一下cpolar相关,实际不推荐这么做
4. 配置 Cloudflare DNS
在 Cloudflare Dashboard 中:
- 进入 DNS → 记录
- 添加或修改
openclaw记录:
| 类型 | 名称 | 内容 | 代理状态 |
|---|---|---|---|
| CNAME | openclaw | xxx.cpolar.cn | 🟠 已代理 |
5. 配置 Cloudflare Worker(必需)
原因:Cloudflare 代理到 cpolar 时,Host 头是 openclaw.你的域名.com,而 cpolar 隧道期望的是 xxx.cpolar.cn,需要通过 Worker 修改 Host 头,否则会报 404。
-
创建 Worker
- 在 Cloudflare Dashboard,进入 Workers & Pages
- 点击 创建应用程序 → 创建 Worker
- 命名为
openclaw-cpolar,点击 部署
-
编辑 Worker 代码
点击 快速编辑,替换为以下代码:
javascriptexport default { async fetch(request) { // 获取原始 URL const url = new URL(request.url); // 获取 cpolar 隧道地址(替换为你的实际地址) const cpolarHost = "abc123.cpolar.cn"; // 保留原始请求头,修改 Host const newHeaders = new Headers(request.headers); newHeaders.set("Host", cpolarHost); // 构建新请求 const newRequest = new Request(url, { method: request.method, headers: newHeaders, body: request.body, redirect: "manual" }); // 发送到 cpolar return fetch(newRequest); } }; -
部署 Worker
点击 保存并部署
-
绑定 Worker 到域名
- 在 Worker 页面,点击 触发器 → 添加路由
- 路由输入:
openclaw.你的域名.com/* - 域名选择:你的域名
- 点击 添加路由
- 删除或关闭 DNS 记录的代理(橙色云朵改为灰色),让流量走 Worker
-
验证
bashcurl https://openclaw.你的域名.com/wecom/health
6. 后台运行
bash# 使用 nohup nohup cpolar http 18789 > /tmp/cpolar.log 2>&1 &
方案三:云服务器部署
如果你有阿里云、腾讯云等服务器,直接在服务器上部署更简单。
bash# 1. SSH 登录服务器 ssh root@你的服务器IP # 2. 安装 Node.js 和 OpenClaw # ... # 3. 安装插件(步骤同本机) # 4. 启动网关 openclaw gateway # 5. 回调 URL # http://你的服务器IP:18789/wecom/callback
再补充一个内网穿透极简方案 Localtunnel(极简Node方案)
bash# 安装(需先装Node.js) npm install -g localtunnel # 使用(自动生成临时域名) lt --port 8080
缺点:稳定性一般,适合临时演示
注意:其实配置完内网穿透,相当于你可以远程浏览器打开openclaw的 对话框了,就没必要再去接入钉钉、微信、 飞书之类的了,不过为了教程完整性,还是继续一下,另外配置了内网穿透后,要注意权限控制,避免被其他人通过你的链接来访问操控
二、获取企业微信凭证
登录企业微信管理后台,进入 应用管理 → 应用 → 自建 → 创建应用:
| 配置项 | 获取位置 | 说明 |
|---|---|---|
| Corp ID | 我的企业 → 企业信息 | 企业 ID |
| Agent ID | 应用详情 → AgentId | 应用标识 |
| Secret | 应用详情 → Secret | 应用密钥,点击"查看"或"重置"获取 |
| Token | 应用详情 → 接收消息 → 生成 | 随机字符串,自定义 |
| EncodingAESKey | 应用详情 → 接收消息 → 生成 | 43 位 AES 密钥,随机生成或手动输入 |
三、安装插件
bash# 1. 克隆插件仓库 git clone https://github.com/11haonb/wecom-openclaw-plugin /tmp/wecom-plugin # 2. 复制到 OpenClaw 扩展目录 mkdir -p ~/.openclaw/extensions cp -r /tmp/wecom-plugin ~/.openclaw/extensions/wecom # 3. 安装依赖 cd ~/.openclaw/extensions/wecom npm install
四、配置 OpenClaw
编辑 ~/.openclaw/openclaw.json,添加以下配置:
json{ "env": { "WECOM_CORP_ID": "你的企业ID", "WECOM_CORP_SECRET": "你的应用Secret", "WECOM_AGENT_ID": "1000002", "WECOM_CALLBACK_TOKEN": "你的Token", "WECOM_CALLBACK_AES_KEY": "你的43位AES密钥" }, "plugins": { "entries": { "wecom-openclaw-integration": { "enabled": true } } } }
配置项说明
| 环境变量 | 必填 | 说明 |
|---|---|---|
WECOM_CORP_ID | ✅ | 企业 ID,如 ww1234567890abcdef |
WECOM_CORP_SECRET | ✅ | 应用 Secret |
WECOM_AGENT_ID | ✅ | 应用 AgentId |
WECOM_CALLBACK_TOKEN | ✅ | 消息回调验证 Token,自定义任意字符串 |
WECOM_CALLBACK_AES_KEY | ✅ | 消息加密密钥(43 位),随机生成 |
五、启动网关
bash# 启动 OpenClaw Gateway openclaw gateway
成功启动后会看到:
dot[WeCom] Plugin registered [WeCom] Corp ID: ww1234567890abcdef [WeCom] Agent ID: 1000002 [WeCom] Callback path: /wecom/callback [gateway] listening on ws://127.0.0.1:18789
保持网关运行,不要关闭终端。
六、配置回调 URL
1. 确定回调地址
根据你的穿透方案确定回调 URL:
| 方案 | 回调 URL |
|---|---|
| Cloudflare Tunnel | https://openclaw.你的域名.com/wecom/callback |
| cpolar + 自有域名 | https://openclaw.你的域名.com/wecom/callback |
| 云服务器 | http://服务器IP:18789/wecom/callback |
2. 在企业微信后台配置
进入 应用详情 → 接收消息:
| 配置项 | 值 |
|---|---|
| URL | 你的回调 URL |
| Token | 与 WECOM_CALLBACK_TOKEN 一致 |
| EncodingAESKey | 与 WECOM_CALLBACK_AES_KEY 一致 |
点击 保存。
3. 验证回调
保存后企业微信会自动验证回调 URL。验证通过后日志显示:
[WeCom] URL verification successful
七、测试
- 打开企业微信 App
- 找到你的应用
- 发送消息 "你好"
- AI 应该会回复
八、常见问题
8.1 URL 验证失败
- ✅ 检查 Token 和 AES Key 是否完全一致(区分大小写)
- ✅ 确保 Gateway 正在运行
- ✅ 确保内网穿透工具正在运行
- ✅ 测试公网 URL:
curl https://你的域名/wecom/health
8.2 消息无响应
- ✅ 检查应用可见范围是否包含你的账号
- ✅ 检查
WECOM_CORP_SECRET是否正确(注意后缀,如-EM) - ✅ 查看 Gateway 日志:
tail -f /tmp/openclaw/openclaw-*.log
8.3 回复发送失败 (errcode=60020)
服务器 IP 不在企业微信可信列表中。解决方法:
- 在应用详情中找到 开发配置
- 配置 企业可信 IP,添加服务器公网 IP
8.4 认证失败 (errcode=40001)
- ✅ 检查
WECOM_CORP_SECRET是否正确 - ✅ 在管理后台重新查看 Secret,注意复制完整内容
九、使用建议
9.1 推荐 AI 模型
json{ "agents": { "defaults": { "model": { "primary": "zai/glm-4.7" } } } }
9.2 群聊配置
插件默认支持群聊,机器人只在被 @ 时响应。
9.3 健康检查
bash# 本地检查 curl http://127.0.0.1:18789/wecom/health # 公网检查 curl https://openclaw.你的域名.com/wecom/health
正常返回:
json{"status":"ok","channel":"wecom","timestamp":"..."}
9.4 后台运行
生产环境建议使用 pm2:
bash# 安装 pm2 npm install -g pm2 # 启动网关 pm2 start "openclaw gateway" --name openclaw # 保存配置 pm2 save # 开机自启 pm2 startup