ClawCN - OpenClaw 中文站

主题

企业微信应用配置详解 ​

本文档详细介绍如何在企业微信管理后台创建和配置应用，以及企业微信通道的访问控制设置。这是 Docker Compose + 企业微信部署指南 的配套文档。

创建企业微信应用 ​

1. 登录企业微信管理后台 ​

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

如果您尚未注册企业微信，需先完成企业注册和认证。详情参阅 企业微信官方文档。

2. 创建智能机器人应用 ​

  1. 在左侧导航栏中点击 应用管理
  2. 在 应用 区域中点击 创建应用，选择 智能机器人
  3. 填写应用信息：
    • 应用 logo：上传应用图标
    • 应用名称：如 "OpenClaw Bot"
    • 应用介绍：如 "OpenClaw AI 助手"
    • 可见范围：选择哪些部门或成员可以看到该应用（可后续修改）
  4. 点击 创建应用

智能机器人：OpenClaw 插件使用企业微信的智能机器人类型，支持流式输出和丰富消息类型。

3. 了解凭据 ​

创建应用后，企业微信管理后台会提供以下凭据。这些凭据在管理后台内管理，不需要配置到 OpenClaw 插件中：

  • CorpID（企业 ID）：在「我的企业」→「企业信息」页面底部
  • AgentID：在应用详情页
  • Secret：在应用详情页

重要：OpenClaw 企业微信插件不需要 CorpID、AgentID 或 Secret。插件只需要接收消息回调的 Token 和 EncodingAESKey（在下一步配置）。

4. 配置接收消息回调 ​

企业微信通过 HTTP 回调将用户消息推送到您的服务器。与飞书的 WebSocket 长连接不同，您需要提供一个公网可访问的 URL。

⚠️ 重要：配置回调 URL 前，必须确保 OpenClaw 网关已启动且正在运行。企业微信会在保存时立即发送 GET 验证请求到回调 URL，如果服务器未响应，配置将失败。

验证网关状态：

bash
docker compose logs -f

确认日志中出现 [gateway] listening。

在应用详情页中：

  1. 点击 接收消息 下方的 设置API接收
  2. 填写以下信息：
    • URL：您的回调地址，格式为 https://<公网地址>:<端口>/webhooks/wecom
    • Token：可点击"随机获取"或自行填写，需与 .env 中的 WECOM_TOKEN 一致
    • EncodingAESKey：可点击"随机获取"或自行填写，需与 .env 中的 WECOM_ENCODING_AES_KEY 一致
  3. 点击 保存

验证流程 ​

保存时，企业微信会向您的回调 URL 发送一个 GET 请求进行验证，包含以下参数：

参数说明
msg_signature消息签名，用于验证请求来源
timestamp时间戳
nonce随机数
echostr加密的随机字符串，需解密后原样返回

您的服务器需要：

  1. 使用 Token 计算签名并验证 msg_signature
  2. 使用 EncodingAESKey 解密 echostr
  3. 将解密后的明文 echostr 作为响应体返回（HTTP 200）

以上验证逻辑由 @sunnoy/wecom 插件自动处理，您只需确保 Token 和 EncodingAESKey 配置正确。

将 Token 和 EncodingAESKey 填入 .env 文件：

bash
WECOM_TOKEN=your-callback-token-here
WECOM_ENCODING_AES_KEY=your-encoding-aes-key-here

5. 配置 API 权限 ​

在应用详情页中，部分 API 调用需要额外授权：

  1. 在左侧点击 API接口权限（或在应用详情中找到权限配置入口）
  2. 根据需要开启以下权限：
权限说明是否必须
消息推送发送应用消息到用户是
通讯录读取读取成员基本信息是
接收消息通过回调接收用户消息是
客户联系如需处理外部联系人消息否
媒体文件上传/下载处理图片、文件等多媒体消息推荐

注意：不同的 API 接口有各自独立的权限控制。如果调用某个 API 时返回权限错误，请检查对应的接口权限是否已开启。

6. 设置可信 IP（企业可信IP） ​

企业微信要求调用 API 的服务器 IP 必须在可信 IP 列表中。这是一个常见的配置遗漏，会导致 API 调用静默失败。

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

查看服务器公网 IP：

bash
curl ifconfig.me

常见问题：

  • 如果使用云服务器，填写弹性公网 IP（EIP），而非内网 IP
  • 如果使用 NAT 网关，填写 NAT 网关的出口 IP
  • 如果使用内网穿透工具（如 ngrok），填写穿透服务提供的出口 IP
  • IP 变更后需及时更新白名单，否则 API 调用会返回错误
  • 可信 IP 最多可配置 20 个

访问控制 ​

可见范围 ​

企业微信通过可见范围控制哪些成员可以看到和使用该应用：

  1. 在应用详情页中找到 可见范围
  2. 点击 修改
  3. 选择部门或成员：
    • 选择整个部门：该部门下所有成员可见
    • 选择个人：仅选中的成员可见
    • 选择"全体成员"：企业所有人可见

可见范围决定了谁能在企业微信中看到该应用入口。只有在可见范围内的成员才能向应用发送消息，否则会收到"无权限"的提示（错误码 60011）。

管理员用户（adminUsers） ​

管理员用户可绕过命令白名单限制，并跳过动态 Agent 路由（直接使用主 Agent）：

json5
{
  "channels": {
    "wecom": {
      "adminUsers": ["admin-userid"]
    }
  }
}

管理员用户 ID 不区分大小写，与企业微信的 userid 字段匹配。

动态 Agent 路由 ​

插件为每个私聊用户和群聊自动创建独立的 Agent，拥有独立的工作区和对话上下文：

  • 私聊：wecom-dm-<userId>
  • 群聊：wecom-group-<chatId>

可通过配置禁用：

json5
{
  "channels": {
    "wecom": {
      "dynamicAgents": { "enabled": false }
    }
  }
}

群聊配置 ​

默认情况下，群组中需要 @提及机器人才会响应。可通过 groupChat.requireMention 修改：

json5
{
  "channels": {
    "wecom": {
      "groupChat": {
        "enabled": true,
        "requireMention": true
      }
    }
  }
}

命令白名单 ​

防止普通用户通过企业微信消息执行敏感的网关管理命令：

json5
{
  "channels": {
    "wecom": {
      "commands": {
        "enabled": true,
        "allowlist": ["/new", "/status", "/help", "/compact"]
      }
    }
  }
}

安全提示：不要将 /gateway、/plugins 等管理命令加入白名单，以免普通用户获得网关管理权限。adminUsers 中的用户可绕过此限制。

获取用户/群组 ID ​

用户 ID（UserId）：

  1. 启动网关并向应用发送私聊消息
  2. 查看日志中的 UserId：docker compose logs -f
  3. 或查看配对请求：docker compose exec openclaw node /app/openclaw.mjs pairing list wecom

群组 ID：

  1. 启动网关并在群组中 @提及机器人
  2. 查看日志中的群组标识：docker compose logs -f

企业微信的用户标识（UserId）与飞书的 open_id 不同，UserId 由企业管理员在通讯录中设置，通常为工号或自定义字符串。

插件特性 ​

流式输出 ​

插件基于企业微信最新的 AI 机器人流式输出机制，实现打字机风格的实时响应。

消息防抖 ​

用户在短时间内（2 秒内）连续发送多条消息时，插件会自动合并为一个 AI 请求，避免多次并发 LLM 调用。以 / 开头的命令不受防抖影响。

图片处理 ​

  • 接收图片：插件自动使用 AES-256-CBC 解密企业微信加密的图片，传递给 AI 进行视觉分析
  • 发送图片：自动处理 OpenClaw 生成的图片（如浏览器截图），编码为 base64 通过 msg_item API 发送
  • 支持图文混合消息

语音和文件 ​

  • 语音消息：企业微信自动转写为文本，插件直接处理（仅私聊）
  • 文件消息：下载文件并传递给 AI 分析（PDF、代码文件等）

发布应用 ​

企业微信的自建应用创建后即可使用，无需像飞书那样经历版本审核发布流程。但需要确保：

  1. 可见范围已正确设置 — 目标用户必须在可见范围内
  2. 回调 URL 已配置并验证通过 — 否则无法接收消息
  3. 可信 IP 已配置 — 否则 API 调用会失败
  4. API 权限已开启 — 特别是消息推送和通讯录读取

设置完成后，可见范围内的成员即可在企业微信的"工作台"中看到该应用，点击即可开始对话。

返回 ​