OpenClaw企微接入教程

本文档介绍如何安装和配置企业微信 OpenClaw 插件，将 AI 助手接入企业微信。

前置要求

• 已安装 OpenClaw
• 企业微信管理后台权限，可创建自建应用
• 公网服务器 或 内网穿透工具（本机安装时需要）

重要说明

企业微信消息接收方式

企业微信自建应用不支持长连接，需要通过 HTTP 回调 方式接收消息：

• 企业微信将消息推送到你配置的回调 URL
• 你的服务器接收并处理消息
• 处理完成后调用企业微信 API 发送回复

内网穿透（重要）

注意：这里说的都是你在自己电脑本地安装的情况下才需要内网穿透，主要是让你本地127.0.0.1能在公网访问，如果你本身有云服务器，是不需要的，直接域名指向你的云服务器ip就行了，要简单很多，使用cloudflare一定要开启橙色云，会自动生成ssl证书，数据通过https传输，全程加密，保证数据不会泄露

如果你在本机或内网环境安装，需要使用内网穿透工具将本地服务暴露到公网。

一、内网穿透方案（本机安装必选）

方案一：Cloudflare Tunnel（推荐）

前提：你需要有自己的域名（如 example.com），并需要先将域名托管到 Cloudflare（企微回调地址不认cf提供的临时域名，如果单纯做内网穿透，可以不注册账号，直接按下面方式就可以）

shell
复制
cloudflared tunnel --url http://localhost:8080

特点：

✅ 完全不需要注册/登录

✅ 自动生成随机临时域名（如 https://abcd-1234.trycloudflare.com ）

❌ 每次重启域名会变

❌ 适合临时测试，不适合长期使用 ❌ 微信回调不支持

0. 将域名托管到 Cloudflare（首次使用必做）

步骤说明：如果域名在阿里云/腾讯云等注册商，需要将 DNS 服务器改为 Cloudflare 的。

1. 在 Cloudflare 添加站点

   • 访问 https://dash.cloudflare.com/
   • 点击 添加站点
   • 输入你的域名（如 example.com）
   • 选择 免费套餐
   • Cloudflare 会扫描现有的 DNS 记录

2. 获取 Cloudflare DNS 服务器地址

   添加站点后，Cloudflare 会提供两个 DNS 服务器地址，如：

   dot
   复制
   bob.ns.cloudflare.com
   lola.ns.cloudflare.com

3. 在域名注册商修改 DNS 服务器

   阿里云示例：

   • 登录阿里云 → 域名 → 找到你的域名
   • 点击 DNS 修改 → 修改 DNS 服务器
   • 删除原有的 DNS 服务器
   • 添加 Cloudflare 提供的两个 DNS 服务器地址
   • 确认修改

   腾讯云示例：

   • 登录腾讯云 → DNSPod DNS 解析 → 我的域名
   • 点击 修改 DNS 服务器
   • 改为 Cloudflare 提供的地址

4. 等待 DNS 生效

   通常需要 2min-24 小时生效，Cloudflare 会检测状态：

   状态：生效中 → 活跃
   

5. 验证域名已托管

   返回 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. 登录并授权域名

bash
复制
cloudflared tunnel login

浏览器会打开 Cloudflare 授权页面，选择你已托管的域名并授权。

3. 创建隧道

bash
复制
cloudflared tunnel create openclaw

记下返回的隧道 ID，如：a1b2c3d4-e5f6-7890-abcd-ef1234567890

4. 配置隧道

创建配置文件 ~/.cloudflared/config.yml：

bash
复制
cat > ~/.cloudflared/config.yml << EOF
tunnel: <你的隧道ID>
credentials-file: ~/.cloudflared/<你的隧道ID>.json

ingress:
  - hostname: openclaw.你的域名.com
    service: http://localhost:18789
  - service: http_status:404
EOF

示例：

yaml
复制
tunnel: 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 中：

1. 登录 https://dash.cloudflare.com/
2. 选择你的域名
3. 进入 DNS → 记录
4. 添加或修改 openclaw 记录：

示例：

dot
复制
类型: CNAME
名称: openclaw
内容: a1b2c3d4-e5f6-7890-abcd-ef1234567890.cfargotunnel.com
代理状态: 开启（橙色云朵）

6. 启动隧道

bash
复制
cloudflared tunnel run openclaw

7. 验证

bash
复制
curl 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。

bash
复制
cpolar authtoken <你的token>

3. 启动 cpolar 隧道

bash
复制
cpolar http 18789

会显示临时 URL，如：https://abc123.cpolar.cn

正常情况下到这一步内网穿透就完成了，你可以远程通过https://abc123.cpolar.cn访问你本地电脑，但是微信的回调地址不支持cpolar.cn域名，保存的时候验证无法通过，所以还需要cloudflare中转一下，这里主要讲解一下cpolar相关，实际不推荐这么做

4. 配置 Cloudflare DNS

在 Cloudflare Dashboard 中：

1. 进入 DNS → 记录
2. 添加或修改 openclaw 记录：

5. 配置 Cloudflare Worker（必需）

原因：Cloudflare 代理到 cpolar 时，Host 头是 openclaw.你的域名.com，而 cpolar 隧道期望的是 xxx.cpolar.cn，需要通过 Worker 修改 Host 头，否则会报 404。

1. 创建 Worker

   • 在 Cloudflare Dashboard，进入 Workers & Pages
   • 点击 创建应用程序 → 创建 Worker
   • 命名为 openclaw-cpolar，点击 部署

2. 编辑 Worker 代码

   点击 快速编辑，替换为以下代码：

   javascript
   复制
   export 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);
     }
   };

3. 部署 Worker

   点击 保存并部署

4. 绑定 Worker 到域名

   • 在 Worker 页面，点击 触发器 → 添加路由
   • 路由输入：openclaw.你的域名.com/*
   • 域名选择：你的域名
   • 点击 添加路由
   • 删除或关闭 DNS 记录的代理（橙色云朵改为灰色），让流量走 Worker

5. 验证

bash
复制
   curl 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的 对话框了，就没必要再去接入钉钉、微信、 飞书之类的了，不过为了教程完整性，还是继续一下，另外配置了内网穿透后，要注意权限控制，避免被其他人通过你的链接来访问操控

二、获取企业微信凭证

登录企业微信管理后台，进入 应用管理 → 应用 → 自建 → 创建应用：

三、安装插件

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
      }
    }
  }
}

配置项说明

五、启动网关

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：

2. 在企业微信后台配置

进入 应用详情 → 接收消息：

点击 保存。

3. 验证回调

保存后企业微信会自动验证回调 URL。验证通过后日志显示：

[WeCom] URL verification successful

七、测试

1. 打开企业微信 App
2. 找到你的应用
3. 发送消息 "你好"
4. 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

十、参考

• OpenClaw 官方文档
• 企业微信 API 文档
• 插件源码
• Cloudflare Tunnel 文档
• cpolar 文档