OpenClaw 企业微信 (WeCom) 插件配置指南

本文档详细介绍 OpenClaw 企业微信插件的安装和配置流程。

目录

  1. 环境要求
  2. 插件安装
  3. 企业微信后台配置
  4. OpenClaw 配置
  5. 内网穿透配置
  6. 启动和验证
  7. 常见问题排查
  8. 安全建议
  9. 配置文件参考

1. 环境要求

1.1 系统要求

项目 要求
操作系统 Linux (Ubuntu 22.04+ 推荐)
Node.js 18.x 或更高版本
npm 9.x 或更高版本
内存 至少 2GB
磁盘 至少 10GB

1.2 网络要求

  • 服务器需要能访问互联网
  • 如需公网访问，需要配置内网穿透或公网 IP
  • 企业微信回调需要 HTTPS（生产环境）或 HTTP（测试环境）

1.3 账号要求

  • 企业微信管理员权限
  • 可创建智能机器人应用或自建应用

2. 插件安装

2.1 安装方式一：npm 安装（推荐）

# 进入 OpenClaw 扩展目录
cd ~/.openclaw/extensions

# 使用 npm 安装插件
npm install @sunnoy/wecom

# 复制插件到扩展目录（重要步骤！）
cp -r node_modules/@sunnoy/wecom ./wecom

2.2 安装方式二：OpenClaw 命令安装

# 使用 OpenClaw 插件命令安装
openclaw plugins install @sunnoy/wecom

2.3 验证安装

# 检查插件文件是否存在
ls -la ~/.openclaw/extensions/wecom/

# 应该看到以下文件：
# openclaw.plugin.json  - 插件清单文件
# index.js              - 插件入口
# package.json          - npm 包配置
# crypto.js             - 消息加解密模块
# webhook.js            - Webhook 处理器
# wecom/                - 核心模块目录

2.4 插件目录结构

~/.openclaw/extensions/wecom/
├── openclaw.plugin.json     # 插件清单文件
├── index.js                 # 插件入口
├── package.json             # npm 包配置
├── crypto.js                # 消息加解密模块 (AES-256-CBC)
├── webhook.js               # Webhook 处理器
├── stream-manager.js        # 流式消息管理
├── image-processor.js       # 图片处理
├── dynamic-agent.js         # 动态 Agent 管理
├── logger.js                # 日志模块
├── utils.js                 # 工具函数
└── wecom/                   # 核心模块
    ├── channel-plugin.js    # 频道插件
    ├── http-handler.js      # HTTP 处理器
    ├── agent-api.js         # Agent API
    ├── agent-inbound.js     # Agent 入站处理
    ├── inbound-processor.js # 入站消息处理
    ├── outbound-delivery.js # 出站消息投递
    ├── media.js             # 媒体文件处理
    ├── commands.js          # 指令处理
    ├── state.js             # 状态管理
    └── ...

3. 企业微信后台配置

3.1 方式一：创建 AI 机器人（Bot 模式）

AI 机器人模式适用于简单的问答场景，支持流式输出。

步骤 1：登录管理后台

访问 企业微信管理后台 并使用管理员账号登录。

步骤 2：创建智能机器人
  1. 进入「应用管理」→「应用」
  2. 下拉找到「智能机器人」区域
  3. 点击「创建应用」
步骤 3：选择 API 模式（关键！）

⚠️ 重要：必须选择 API 模式创建

模式 回调消息格式 本插件支持
标准模式 XML 格式 ❌ 不支持
API 模式 JSON 格式 ✅ 支持

在创建页面底部，选择 「API 模式创建」，而非「标准模式创建」。

步骤 4：获取凭证

创建完成后，在机器人详情页获取以下凭证：

凭证 说明 长度 用途
Token 消息签名验证令牌 可自定义 验证消息来源
EncodingAESKey 消息加密密钥 43位字符 消息加解密

获取方法：

  1. 在机器人详情页找到「接收消息」区域
  2. 点击「设置」按钮
  3. 可以看到或生成 Token 和 EncodingAESKey
  4. 复制这两个值备用
步骤 5：配置回调 URL

在「接收消息」设置页面配置：

配置项 值
URL https://你的域名/webhooks/wecom
Token 与步骤 4 相同的 Token
EncodingAESKey 与步骤 4 相同的 EncodingAESKey

URL 格式说明：

  • 生产环境：https://your-domain.com/webhooks/wecom
  • 测试环境（花生壳）：http://your-domain.oray.com/webhooks/wecom

3.2 方式二：创建自建应用（Agent 模式）

自建应用模式提供更完整的消息收发能力，支持主动推送、媒体文件处理等。

步骤 1：创建应用
  1. 进入「应用管理」→「应用」
  2. 点击「创建应用」
  3. 填写应用信息：
    • 应用名称：如 “AI 助手”
    • 应用头像：上传图标
    • 可见成员：选择可使用的成员
步骤 2：获取应用凭证

创建完成后，在应用详情页记录：

凭证 说明 位置
AgentId 应用 ID 应用详情页顶部
Secret 应用凭证密钥 点击「查看」获取
步骤 3：获取企业凭证

在「我的企业」页面获取：

凭证 说明
CorpID 企业 ID
步骤 4：配置 API 接收

在应用详情页的「接收消息」区域：

  1. 点击「设置 API 接收」
  2. 配置以下信息：
配置项 值
URL https://你的域名/webhooks/app
Token 点击「随机生成」
EncodingAESKey 点击「随机获取」

3.3 配置企业可信 IP

⚠️ 重要：企业微信 API 调用需要配置可信 IP

获取服务器公网 IP
# 方法一
curl -s ifconfig.me

# 方法二
wget -qO- ifconfig.me

# 方法三
curl -s ipinfo.io/ip
添加可信 IP
  1. 在应用详情页找到「企业可信IP」
  2. 点击「配置」
  3. 前置条件：需要先设置可信域名或接收消息服务器 URL
  4. 添加你的服务器公网 IP

3.4 配置应用权限

在应用详情页的「企业可信IP」下方，配置以下权限：

权限 说明
发送应用消息 允许应用发送消息
接收消息 允许应用接收用户消息
获取用户信息 获取用户基本信息

4. OpenClaw 配置

4.1 基础配置

# 启用 wecom 插件
openclaw config set plugins.entries.wecom.enabled true

# 启用 wecom 频道
openclaw config set channels.wecom.enabled true

# 配置 Token（Bot 模式必填）
openclaw config set channels.wecom.token "你的Token"

# 配置 EncodingAESKey（Bot 模式必填）
openclaw config set channels.wecom.encodingAesKey "你的43位EncodingAESKey"

4.2 Agent 模式配置

如果使用自建应用模式，需要额外配置：

# 配置企业 ID
openclaw config set channels.wecom.agent.corpId "你的企业CorpID"

# 配置应用 Secret
openclaw config set channels.wecom.agent.corpSecret "应用Secret"

# 配置应用 AgentId
openclaw config set channels.wecom.agent.agentId 1000002

# 配置 Agent 模式的 Token（如果与 Bot 模式不同）
openclaw config set channels.wecom.agent.token "Agent模式的Token"

# 配置 Agent 模式的 EncodingAESKey
openclaw config set channels.wecom.agent.encodingAesKey "Agent模式的EncodingAESKey"

4.3 动态 Agent 配置

动态 Agent 功能可以为每个用户/群聊创建独立的 Agent 会话：

# 启用动态 Agent
openclaw config set channels.wecom.dynamicAgents.enabled true

# 私聊时为每个用户创建独立 Agent
openclaw config set channels.wecom.dm.createAgentOnFirstMessage true

# 启用群聊处理
openclaw config set channels.wecom.groupChat.enabled true

# 群聊需要 @ 提及才响应（推荐开启）
openclaw config set channels.wecom.groupChat.requireMention true

4.4 指令白名单配置

# 启用指令白名单过滤
openclaw config set channels.wecom.commands.enabled true

# 设置允许的指令列表
openclaw config set channels.wecom.commands.allowlist '["/new","/status","/help","/compact"]'

内置指令说明：

指令 说明
/new 开始新对话
/status 查看状态
/help 显示帮助
/compact 压缩对话历史

4.5 管理员配置

管理员用户可以绕过指令白名单限制：

# 设置管理员用户列表
openclaw config set channels.wecom.adminUsers '["admin_userid1","admin_userid2"]'

获取用户 userid 的方法：

  1. 在企业微信管理后台
  2. 进入「通讯录」
  3. 点击用户查看详情
  4. 在 URL 中可以看到 userid 参数

4.6 Webhook 配置（可选）

配置 Webhook Bot 用于群通知：

# 配置 Webhook URL 映射
openclaw config set channels.wecom.webhooks.ops-group "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
openclaw config set channels.wecom.webhooks.dev-group "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=yyy"

4.7 工作区模板配置（可选）

为动态创建的 Agent 预置初始化文件：

# 创建模板目录
mkdir -p ~/.openclaw/templates/wecom

# 创建 bootstrap 文件
echo "# AI 助手\n\n我是你的智能助手，有什么可以帮助你的？" > ~/.openclaw/templates/wecom/BOOTSTRAP.md

# 配置模板路径
openclaw config set channels.wecom.workspaceTemplate "~/.openclaw/templates/wecom"

5. 内网穿透配置

如果服务器没有公网 IP，需要使用内网穿透工具。

5.1 花生壳内网穿透

安装花生壳客户端
# 下载花生壳
wget https://down.oray.com/hsk/linux/hsk_5.2.0_amd64.deb

# 安装
sudo dpkg -i hsk_5.2.0_amd64.deb

# 或使用 snap
sudo snap install hsk
配置映射
  1. 登录 花生壳管理后台
  2. 添加内网映射：
    • 内网地址：192.168.31.164:18789
    • 映射类型：HTTP
  3. 记录分配的外网域名
配置回调 URL

使用花生壳域名配置企业微信回调：

http://你的花生壳域名/webhooks/wecom

5.2 Tailscale（推荐）

OpenClaw 内置支持 Tailscale：

# 安装 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# 启动并认证
sudo tailscale up

# 配置 OpenClaw 使用 Tailscale
openclaw config set gateway.tailscale.mode "serve"

# 重启 Gateway
openclaw gateway restart

5.3 frp 内网穿透

安装 frp
# 下载 frp
wget https://github.com/fatedier/frp/releases/download/v0.52.0/frp_0.52.0_linux_amd64.tar.gz

# 解压
tar -xzf frp_0.52.0_linux_amd64.tar.gz
cd frp_0.52.0_linux_amd64
配置 frpc
# frpc.ini
[common]
server_addr = 你的frp服务器地址
server_port = 7000

[wecom]
type = http
local_ip = 127.0.0.1
local_port = 18789
custom_domains = 你的域名
启动 frpc
./frpc -c frpc.ini

6. 启动和验证

6.1 启动 Gateway

# 启动 Gateway
openclaw gateway start

# 或使用 systemd 服务
systemctl --user start openclaw-gateway

# 设置开机自启
systemctl --user enable openclaw-gateway

6.2 检查状态

# 查看 Gateway 状态
openclaw gateway status

# 查看完整状态
openclaw status

# 深度检查（包含频道探测）
openclaw status --deep

6.3 成功状态示例

Channels
┌───────────────────┬─────────┬────────┬──────────────────────────┐
│ Channel           │ Enabled │ State  │ Detail                   │
├───────────────────┼─────────┼────────┼──────────────────────────┤
│ Enterprise WeChat │ ON      │ OK     │ token configured         │
└───────────────────┴─────────┴────────┴──────────────────────────┘

6.4 查看日志

# 实时查看日志
openclaw logs --follow

# 查看 systemd 日志
journalctl --user -u openclaw-gateway.service -f

# 查看文件日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 查看最近 100 行日志
journalctl --user -u openclaw-gateway.service -n 100 --no-pager

6.5 测试消息收发

  1. 在企业微信中找到创建的机器人应用
  2. 发送一条消息
  3. 检查日志是否收到消息
  4. 等待 AI 回复

7. 常见问题排查

7.1 插件未找到

错误信息：

plugins.entries.wecom: plugin not found: wecom

原因分析：

  • 插件未正确安装
  • 插件目录结构不正确
  • openclaw.plugin.json 文件缺失

解决方案：

# 1. 检查插件目录
ls -la ~/.openclaw/extensions/wecom/

# 2. 检查插件清单文件
cat ~/.openclaw/extensions/wecom/openclaw.plugin.json

# 3. 如果目录不存在，重新安装
cd ~/.openclaw/extensions
npm install @sunnoy/wecom
cp -r node_modules/@sunnoy/wecom ./wecom

# 4. 重启 Gateway
openclaw gateway restart

7.2 频道未识别

错误信息：

channels.wecom: unknown channel id: wecom

原因分析：

  • 插件未加载
  • 插件清单中缺少 channels 定义

解决方案：

# 1. 检查插件清单中的 channels 定义
cat ~/.openclaw/extensions/wecom/openclaw.plugin.json | grep -A2 channels

# 应该看到：
# "channels": ["wecom"]

# 2. 检查插件是否被加载
openclaw plugins list

# 3. 重启 Gateway
openclaw gateway restart

7.3 Token 未配置

错误信息：

State: SETUP - no token

解决方案：

# 检查当前配置
openclaw config get channels.wecom.token
openclaw config get channels.wecom.encodingAesKey

# 重新设置
openclaw config set channels.wecom.token "正确的Token"
openclaw config set channels.wecom.encodingAesKey "正确的43位Key"

# 重启生效
openclaw gateway restart

7.4 回调 URL 验证失败

可能原因：

原因 解决方案
URL 无法访问 检查网络连通性
Token 不匹配 确保企业微信后台和 OpenClaw 配置一致
EncodingAESKey 不匹配 确保企业微信后台和 OpenClaw 配置一致
签名验证失败 检查时间同步

排查步骤：

# 1. 检查 Gateway 是否运行
openclaw gateway status

# 2. 检查端口是否监听
netstat -tlnp | grep 18789
# 或
ss -tlnp | grep 18789

# 3. 测试本地访问
curl http://localhost:18789/

# 4. 测试 Webhook 端点
curl "http://localhost:18789/webhooks/wecom?msg_signature=test&timestamp=123&nonce=456&echostr=test"

# 5. 查看错误日志
openclaw logs --follow

7.5 IP 白名单问题

错误信息：

error: 60020 - IP not in whitelist

解决方案：

  1. 获取服务器公网 IP：

    curl -s ifconfig.me

  2. 在企业微信后台添加可信 IP：

    • 进入应用详情页
    • 找到「企业可信IP」
    • 点击「配置」
    • 添加服务器公网 IP

7.6 权限不足

错误信息：

error: 48002 - api forbidden

解决方案：

  1. 检查应用权限配置
  2. 确保应用已发布（非开发中状态）
  3. 确保用户在应用的可见范围内
  4. 检查是否配置了可信域名

7.7 残留配置清理

如果之前安装失败，需要清理残留：

# 1. 停止 Gateway
openclaw gateway stop

# 2. 删除残留目录
rm -rf ~/.openclaw/extensions/wecom-simple
rm -rf ~/.openclaw/extensions/wecom

# 3. 清理配置中的无效引用
openclaw config unset plugins.entries.wecom
openclaw config unset plugins.installs.wecom

# 4. 重新安装
cd ~/.openclaw/extensions
npm install @sunnoy/wecom
cp -r node_modules/@sunnoy/wecom ./wecom

# 5. 重新配置
openclaw config set plugins.entries.wecom.enabled true
openclaw config set channels.wecom.enabled true
openclaw config set channels.wecom.token "你的Token"
openclaw config set channels.wecom.encodingAesKey "你的EncodingAESKey"

# 6. 启动 Gateway
openclaw gateway start

7.8 消息加解密错误

错误信息：

Decrypt failed / Invalid PKCS7 padding

解决方案：

  1. 确认 EncodingAESKey 长度为 43 位
  2. 确认 EncodingAESKey 配置正确（无多余空格）
  3. 确认企业微信后台和 OpenClaw 配置完全一致
# 检查 EncodingAESKey 长度
openclaw config get channels.wecom.encodingAesKey | wc -c

8. 安全建议

8.1 配置文件权限

# 设置配置文件权限（仅所有者可读写）
chmod 600 ~/.openclaw/openclaw.json

# 验证权限
ls -la ~/.openclaw/openclaw.json
# 应显示：-rw------- 1 root root

8.2 配置认证限速

防止暴力破解认证：

# 配置认证限速
openclaw config set gateway.auth.rateLimit.maxAttempts 10
openclaw config set gateway.auth.rateLimit.windowMs 60000
openclaw config set gateway.auth.rateLimit.lockoutMs 300000

参数说明：

参数 说明 建议值
maxAttempts 最大尝试次数 10
windowMs 时间窗口（毫秒） 60000 (1分钟)
lockoutMs 锁定时间（毫秒） 300000 (5分钟)

8.3 配置插件白名单

# 设置允许加载的插件（只允许可信插件）
openclaw config set plugins.allow '["wecom"]'

8.4 使用 HTTPS

生产环境强烈建议使用 HTTPS：

方式一：Nginx 反向代理 + Let’s Encrypt
# /etc/nginx/sites-available/wecom
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location /webhooks/wecom {
        proxy_pass http://127.0.0.1:18789;
        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;
    }
}
方式二：使用 Tailscale HTTPS
openclaw config set gateway.tailscale.mode "serve"

8.5 定期更新

# 检查 OpenClaw 更新
openclaw update --check

# 执行更新
openclaw update

# 更新 wecom 插件
cd ~/.openclaw/extensions
npm update @sunnoy/wecom
cp -r node_modules/@sunnoy/wecom ./wecom

# 重启 Gateway
openclaw gateway restart

8.6 日志安全

# 确保日志目录权限正确
chmod 700 /tmp/openclaw

# 定期清理旧日志
find /tmp/openclaw -name "*.log" -mtime +7 -delete

9. 配置文件参考

9.1 完整配置示例

{
  "meta": {
    "lastTouchedVersion": "2026.2.25"
  },
  "models": {
    "providers": {
      "volcengine": {
        "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "apiKey": "你的API密钥",
        "api": "openai-completions",
        "models": [
          {
            "id": "ark-code-latest",
            "name": "ark-code-latest",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "volcengine/ark-code-latest"
      },
      "workspace": "/root/.openclaw/workspace"
    }
  },
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "你的BotToken",
      "encodingAesKey": "你的43位EncodingAESKey",
      "dmPolicy": "pairing",
      "adminUsers": ["admin_userid"],
      "commands": {
        "enabled": true,
        "allowlist": ["/new", "/status", "/help", "/compact"]
      },
      "dynamicAgents": {
        "enabled": true
      },
      "dm": {
        "createAgentOnFirstMessage": true
      },
      "groupChat": {
        "enabled": true,
        "requireMention": true
      },
      "agent": {
        "corpId": "wwxxxxxxxxxxxxxx",
        "corpSecret": "应用Secret",
        "agentId": 1000002,
        "token": "Agent模式Token",
        "encodingAesKey": "Agent模式EncodingAESKey"
      },
      "webhooks": {
        "ops-group": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "allowedOrigins": ["*"]
    },
    "auth": {
      "mode": "token",
      "token": "你的GatewayToken"
    }
  },
  "plugins": {
    "entries": {
      "wecom": {
        "enabled": true
      }
    },
    "installs": {
      "wecom": {
        "source": "npm",
        "spec": "@sunnoy/wecom",
        "installPath": "/root/.openclaw/extensions/wecom",
        "version": "1.3.0"
      }
    },
    "allow": ["wecom"]
  }
}

9.2 最小配置示例

{
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "你的Token",
      "encodingAesKey": "你的43位EncodingAESKey"
    }
  },
  "plugins": {
    "entries": {
      "wecom": {
        "enabled": true
      }
    }
  }
}

9.3 配置项说明

基础配置
配置项 类型 必填 说明
plugins.entries.wecom.enabled boolean 是 启用插件
channels.wecom.enabled boolean 是 启用频道
channels.wecom.token string 是* Bot 模式必填
channels.wecom.encodingAesKey string 是* Bot 模式必填，43位
Agent 模式配置
配置项 类型 必填 说明
channels.wecom.agent.corpId string 是 企业 ID
channels.wecom.agent.corpSecret string 是 应用 Secret
channels.wecom.agent.agentId number 是 应用 ID
channels.wecom.agent.token string 是 Agent 模式 Token
channels.wecom.agent.encodingAesKey string 是 Agent 模式 Key
动态 Agent 配置
配置项 类型 默认值 说明
dynamicAgents.enabled boolean true 启用动态 Agent
dm.createAgentOnFirstMessage boolean true 私聊创建独立 Agent
groupChat.enabled boolean true 启用群聊
groupChat.requireMention boolean true 需要 @ 才响应

附录

A. 命令速查表

命令 说明
openclaw gateway start 启动 Gateway
openclaw gateway stop 停止 Gateway
openclaw gateway restart 重启 Gateway
openclaw gateway status 查看 Gateway 状态
openclaw status 查看完整状态
openclaw status --deep 深度检查
openclaw logs --follow 实时查看日志
openclaw config get <path> 获取配置值
openclaw config set <path> <value> 设置配置值
openclaw config unset <path> 删除配置值
openclaw plugins list 列出插件
openclaw plugins install <package> 安装插件
openclaw plugins info <id> 查看插件信息
openclaw doctor --fix 修复问题
openclaw update 更新 OpenClaw

B. 端口说明

端口 说明
18789 Gateway 默认端口
19001 Gateway 开发模式端口

C. Webhook 路径

路径 说明
/webhooks/wecom Bot 模式回调地址
/webhooks/app Agent 模式回调地址

D. 错误码参考

错误码 说明 解决方案
40014 不合法的 access_token 检查 corpSecret 配置
42001 access_token 已过期 自动刷新，检查系统时间
48002 API 禁止调用 检查应用权限和可信 IP
60020 IP 不在白名单 添加服务器 IP 到可信列表
60028 应用未发布 发布应用

E. 相关链接

文档版本： 1.0
最后更新： 2026-03-01
适用版本： OpenClaw 2026.2.25+, wecom 插件 1.3.0+

# python
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

Claude Code 远程控制功能详解：手机秒变编程神器

avatar 2048 AI社区
cover

企业级米家商城设计与实现abo管理系统源码｜SpringBoot+Vue+MyBatis架构+MySQL数据库【完整版】

avatar 2048 AI社区

(1) Policy Gradient & Actor-Critic Explained

∗argθmax​Jθ​​whereJθ​Eτ∼pθ​τ​t1∑H​rst​at​N1​i∑​t∑​rsti​ati​∫pθ​τrτdτ​​•τs1​a1​s2​a2​sH​aH​•pθ​τρs1​∏t1H​πθat​∣st​Pst1​∣st​at​Jθ​∫∇。

avatar 2048 AI社区