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

本文档详细记录了 OpenClaw 企业微信插件的完整安装和配置流程，包括飞书和企业微信双频道的配置方法。

🔴 重要提醒： 把文档发给你的 OpenClaw，它自己可以学会。

目录

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

1. 环境要求

1.1 系统要求

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

1.2 网络要求

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

1.3 账号要求

  • 企业微信管理员权限
  • 飞书开发者权限（如需配置飞书）

2. OpenClaw 安装

2.1 安装 Node.js

# 使用 NodeSource 安装 Node.js 22.x
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node --version
npm --version

2.2 安装 OpenClaw

# 全局安装 OpenClaw
sudo npm install -g openclaw

# 验证安装
openclaw --version

2.3 初始化配置

# 运行初始化向导
openclaw setup

# 或运行完整配置向导
openclaw configure

3. 飞书频道配置

3.1 创建飞书应用

  1. 登录 飞书开放平台
  2. 进入「开发者后台」→「创建企业自建应用」
  3. 填写应用名称和描述
  4. 记录以下信息：
    • App ID
    • App Secret

3.2 配置应用权限

在飞书应用后台，添加以下权限：

权限名称 权限标识
获取用户基本信息 contact:user.base:readonly
获取用户统一ID contact:user.id:readonly
发送消息 im:message
接收消息 im:message:receive_as_bot

3.3 配置事件订阅

  1. 在「事件订阅」页面，添加事件：

    • im.message.receive_v1 - 接收消息

  2. 配置请求网址（需要公网地址）：

    https://你的域名/webhooks/feishu

3.4 OpenClaw 飞书配置

# 配置飞书频道
openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.accounts.main.appId "你的AppID"
openclaw config set channels.feishu.accounts.main.appSecret "你的AppSecret"
openclaw config set channels.feishu.accounts.main.botName "AI Assistant"

4. 企业微信插件安装

4.1 安装方式一：使用 npm 安装（推荐）

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

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

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

4.2 安装方式二：使用 OpenClaw 命令

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

4.3 验证插件安装

# 检查插件文件
ls -la ~/.openclaw/extensions/wecom/

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

4.4 插件目录结构说明

~/.openclaw/extensions/wecom/
├── openclaw.plugin.json    # 插件清单文件
├── index.js                # 插件入口
├── package.json            # npm 包配置
├── crypto.js               # 消息加解密模块
├── 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
    ├── inbound-processor.js # 入站消息处理
    └── ...

5. 企业微信后台配置

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

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

步骤 1：创建机器人
  1. 登录 企业微信管理后台
  2. 进入「应用管理」→「应用」→ 下拉找到「智能机器人」
  3. 点击「创建应用」
步骤 2：选择 API 模式（关键！）

⚠️ 重要：必须选择 「API 模式创建」，而非「标准模式创建」

  • 标准模式：回调消息为 XML 格式
  • API 模式：回调消息为 JSON 格式
  • 本插件 Bot 模式仅支持 JSON 格式
步骤 3：获取凭证

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

凭证 说明 长度
Token 消息签名验证令牌 可自定义或随机生成
EncodingAESKey 消息加密密钥 43位字符
步骤 4：配置回调 URL

在「接收消息」区域点击「设置」：

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

5.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 点击「随机获取」

5.3 配置企业可信 IP

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

  1. 在应用详情页找到「企业可信IP」
  2. 点击「配置」
  3. 添加你的服务器公网 IP

获取公网 IP 的方法：

# 方法一：使用 curl
curl -s ifconfig.me

# 方法二：使用 wget
wget -qO- ifconfig.me

6. OpenClaw 企业微信配置

6.1 基础配置

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

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

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

6.2 Agent 模式配置（可选）

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

# 配置企业信息
openclaw config set channels.wecom.agent.corpId "你的企业CorpID"
openclaw config set channels.wecom.agent.corpSecret "应用Secret"
openclaw config set channels.wecom.agent.agentId 1000002

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

6.3 高级配置

动态 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
指令白名单配置
# 启用指令白名单
openclaw config set channels.wecom.commands.enabled true

# 设置允许的指令
openclaw config set channels.wecom.commands.allowlist '["/new","/status","/help","/compact"]'
管理员配置
# 设置管理员用户（绕过指令白名单限制）
openclaw config set channels.wecom.adminUsers '["admin1","admin2"]'
Webhook 配置（可选）
# 配置 Webhook Bot 用于群通知
openclaw config set channels.wecom.webhooks.ops-group "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"

7. 内网穿透配置

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

7.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
    • 外网域名：自动分配或自定义
  3. 记录外网域名
配置回调 URL

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

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

7.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"

7.3 SSH 隧道

临时测试可使用 SSH 隧道：

# 在本地执行
ssh -N -L 18789:127.0.0.1:18789 user@服务器地址

8. 启动和验证

8.1 启动 Gateway

# 启动 Gateway
openclaw gateway start

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

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

8.2 检查状态

# 查看 Gateway 状态
openclaw gateway status

# 查看完整状态
openclaw status

# 深度检查
openclaw status --deep

8.3 查看日志

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

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

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

8.4 验证频道状态

成功配置后，状态应显示：

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

9. 常见问题排查

9.1 插件未找到

错误信息：

plugins.entries.wecom: plugin not found: wecom

解决方案：

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

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

# 3. 验证插件清单文件
cat ~/.openclaw/extensions/wecom/openclaw.plugin.json

9.2 频道未识别

错误信息：

channels.wecom: unknown channel id: wecom

解决方案：

# 1. 确保插件已正确安装
ls ~/.openclaw/extensions/wecom/openclaw.plugin.json

# 2. 检查插件清单中的 channel ID
cat ~/.openclaw/extensions/wecom/openclaw.plugin.json | grep -A5 channels

# 3. 重启 Gateway
openclaw gateway restart

9.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

9.4 回调 URL 验证失败

可能原因：

  1. URL 无法访问
  2. Token 不匹配
  3. EncodingAESKey 不匹配
  4. 签名验证失败

排查步骤：

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

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

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

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

9.5 IP 白名单问题

错误信息：

error: 60020 - IP not in whitelist

解决方案：

  1. 获取服务器公网 IP：

    curl -s ifconfig.me

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

9.6 权限不足

错误信息：

error: 48002 - api forbidden

解决方案：

  1. 检查应用权限配置
  2. 确保应用已发布
  3. 确保用户在可见范围内

9.7 残留配置清理

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

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

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

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

10. 安全建议

10.1 配置文件权限

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

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

10.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

10.3 配置插件白名单

# 设置允许加载的插件
openclaw config set plugins.allow '["feishu","wecom"]'

10.4 使用 HTTPS

生产环境建议使用 HTTPS：

  1. 使用 Nginx 反向代理 + Let’s Encrypt 证书
  2. 或使用 Tailscale 的 HTTPS 功能

10.5 定期更新

# 检查更新
openclaw update --check

# 执行更新
openclaw update

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

11. 配置文件参考

11.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": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxxxxxxxxxxx",
          "appSecret": "你的飞书AppSecret",
          "botName": "AI Assistant"
        }
      }
    },
    "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
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "controlUi": {
      "allowedOrigins": ["*"]
    },
    "auth": {
      "mode": "token",
      "token": "你的GatewayToken"
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      },
      "wecom": {
        "enabled": true
      }
    },
    "installs": {
      "feishu": {
        "source": "npm",
        "spec": "@openclaw/feishu",
        "installPath": "/root/.openclaw/extensions/feishu",
        "version": "2026.2.25"
      },
      "wecom": {
        "source": "npm",
        "spec": "@sunnoy/wecom",
        "installPath": "/root/.openclaw/extensions/wecom",
        "version": "1.3.0"
      }
    },
    "allow": ["feishu", "wecom"]
  }
}

11.2 最小配置示例

{
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "你的Token",
      "encodingAesKey": "你的43位EncodingAESKey"
    }
  },
  "plugins": {
    "entries": {
      "wecom": {
        "enabled": 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 plugins list 列出插件
openclaw plugins install <package> 安装插件
openclaw doctor --fix 修复问题
openclaw update 更新 OpenClaw

B. 端口说明

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

C. 相关链接

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

Logo
2048 AI社区

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

更多推荐

cover

Java SpringBoot+Vue3+MyBatis 农产品预售平台系统源码｜前后端分离+MySQL数据库

avatar 2048 AI社区
cover

企业级.js高校学生选课系统管理系统源码｜SpringBoot+Vue+MyBatis架构+MySQL数据库【完整版】

avatar 2048 AI社区
cover

web铁路订票管理系统信息管理系统源码-SpringBoot后端+Vue前端+MySQL【可直接运行】

avatar 2048 AI社区