企业微信智能机器人接入指南 - Webhook 方式 ​

通过 /gateway 命令，您可以将 CodeBuddy Code 接入企业微信生态。采用 HTTP Webhook 回调 方式，通过 Cloudflare Tunnel 暴露本地服务，接收企业微信推送的消息并自动回复。

支持两种接入方式：

  • 方式 A：腾讯客服（微信客服） — 通过微信客服账号对外提供 AI 服务，无需固定公网 IP
  • 方式 B：企业微信自建应用 — 在企业微信内部通过自建应用提供 AI 服务，需要公网固定 IP

如需更简便的接入方式（无需 Webhook 和 Tunnel），请参阅 企业微信智能机器人接入指南（WebSocket 长连接方式）。

前置条件 ​

  • 已注册企业微信账户
  • CodeBuddy Code 已安装：codebuddy --version
  • 已完成登录认证：codebuddy 后执行 /login
  • （Tunnel 模式）已安装 cloudflared（可选，未安装时回退到局域网模式）

方式 A：腾讯客服（微信客服） ​

1. 准备工作 ​

1.1 注册企业微信 ​

  1. 访问 企业微信官网 注册一个企业（可使用个人信息创建）
  2. 完成企业认证（基础功能无需认证，但未认证的企业累计仅可接待 100 位客户）
  3. 登录 企业微信管理后台，进入「我的企业」页面，在页面底部找到并记录 企业 ID

获取企业 ID

1.2 开通腾讯客服并配置回调 ​

  1. 访问 微信客服管理后台，使用企业微信管理员扫码登录
  2. 进入左侧菜单「开发配置」页面，在「回调配置」区域设定以下参数（后续配置到环境变量中）：
    • Token：用于回调签名验证的令牌（自定义字符串）
    • EncodingAESKey：消息加密密钥（43 个字符，可点击「随机获取」生成）

微信客服开发配置

注意：回调 URL 需要在步骤 2、3 中获取并配置。Secret 必须在回调 URL 验证通过后才能首次获取，因此先记录好 Token 和 EncodingAESKey，继续后续步骤。

2. 启动 Gateway 获取 Webhook 地址 ​

2.1 配置环境变量（首次启动） ​

首次启动时，由于尚未获取 Secret，先配置已有的 3 个环境变量：

bash
export CODEBUDDY_GATEWAY_WECHAT_KF_TOKEN="<你设定的 Token>"
export CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEY="<你设定的 EncodingAESKey，43 字符>"
export CODEBUDDY_GATEWAY_WECHAT_KF_CORP_ID="<企业 ID>"

2.2 启动 CLI 并执行 /gateway ​

bash
codebuddy

进入交互模式后，执行：

/gateway

启动成功后，终端会输出类似如下信息：

Gateway started

  ├─ Status    connected
  ├─ Mode      tunnel
  ├─ Local     http://127.0.0.1:8321
  ├─ Tunnel    https://xxx-yyy.trycloudflare.com
  └─ Webhook   https://xxx-yyy.trycloudflare.com/gateway/webhook/:platform

记录 Webhook 地址。

3. 配置回调地址并获取 Secret ​

将 Webhook 地址中的 :platform 替换为 wechat-kf，得到完整的回调 URL：

https://xxx-yyy.trycloudflare.com/gateway/webhook/wechat-kf

回到微信客服管理后台的「开发配置」页面：

  1. 在「回调配置」区域，将上述 URL 填入「回调 URL」
  2. 确认 Token 和 EncodingAESKey 与环境变量中配置的一致
  3. 点击「保存」，系统会发送 GET 验证请求，Gateway 会自动响应验证

验证通过后，微信客服的用户消息将通过此回调推送到 Gateway。

3.1 获取 Secret ​

回调验证通过后，在「开发配置」页面的「开发信息」区域即可获取 Secret。补充环境变量：

bash
export CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRET="<微信客服应用的 Secret>"

补充完成后，重新启动 Gateway 使 Secret 生效（后续正常启动时配置全部 4 个环境变量即可）。

4. 环境变量总览 ​

环境变量必填说明
CODEBUDDY_GATEWAY_WECHAT_KF_TOKEN是回调签名验证 Token
CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEY是消息加密密钥（43 字符）
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_ID是企业微信企业 ID
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRET是微信客服应用的 Secret
CODEBUDDY_GATEWAY_WECHAT_KF_ACCOUNT_NAME否自动创建的客服账号名称（默认 CodeBuddy）

5. 验证接入 ​

配置完成后，Gateway 会自动创建一个名为 CodeBuddy 的客服账号（可通过 CODEBUDDY_GATEWAY_WECHAT_KF_ACCOUNT_NAME 环境变量自定义名称）。你可以：

  1. 在微信客服管理页面查看新建的客服账号
  2. 获取客服账号对应的二维码或链接
  3. 通过微信扫码或链接发起客服对话，发送消息测试 Agent 是否正常响应

方式 B：企业微信自建应用 ​

1. 准备工作 ​

1.1 注册企业微信 ​

  1. 访问 企业微信官网 注册一个企业（可使用个人信息创建）
  2. 登录 企业微信管理后台，进入「我的企业」页面，在页面底部找到并记录 企业 ID

获取企业 ID

1.2 创建自建应用 ​

  1. 在管理后台，进入「应用管理」→ 页面底部「自建」区域 → 点击「创建应用」

创建自建应用

  1. 填写应用名称、Logo、可见范围等信息，完成创建
  2. 进入应用详情页，记录以下信息：
    • AgentId：应用的 ID
    • Secret：点击「查看」获取应用密钥（用于获取 access_token）

应用 AgentId 和 Secret

1.3 配置 IP 白名单 ​

企业微信自建应用调用 API（如发送消息）时，要求请求来源 IP 在白名单内。你需要将本地的公网固定 IP 配置到应用的「企业可信IP」列表中：

  1. 在应用详情页，找到「开发者接口」区域的「企业可信IP」
  2. 点击配置，将你的公网 IP 添加到白名单

配置 IP 白名单

注意：自建应用方式要求本地具备公网固定 IP。如果你没有固定公网 IP，可考虑使用方式 A（腾讯客服）。

1.4 配置接收消息 ​

  1. 在应用详情页，找到「功能」区域的「接收消息」卡片，点击「已启用API接收」进入配置页面

开启 API 接收消息

  1. 在「接收消息服务器配置」中设定以下参数（后续配置到环境变量中）：
    • Token：用于回调签名验证的令牌（自定义字符串）
    • EncodingAESKey：消息加密密钥（43 个字符，可点击「随机获取」生成）

注意：此时暂不填写 URL，先完成步骤 2 获取 Webhook 地址后再回来配置。

2. 启动 Gateway 获取 Webhook 地址 ​

2.1 配置环境变量 ​

在启动 CLI 前，设置以下环境变量：

bash
export CODEBUDDY_GATEWAY_WECOM_TOKEN="<你设定的 Token>"
export CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEY="<你设定的 EncodingAESKey，43 字符>"
export CODEBUDDY_GATEWAY_WECOM_CORP_ID="<企业 ID>"
export CODEBUDDY_GATEWAY_WECOM_CORP_SECRET="<自建应用的 Secret>"
export CODEBUDDY_GATEWAY_WECOM_AGENT_ID="<自建应用的 AgentId>"

2.2 启动 CLI 并执行 /gateway ​

bash
codebuddy

进入交互模式后，执行：

/gateway

启动成功后，终端会输出类似如下信息：

Gateway started

  ├─ Status    connected
  ├─ Mode      tunnel
  ├─ Local     http://127.0.0.1:8321
  ├─ Tunnel    https://xxx-yyy.trycloudflare.com
  └─ Webhook   https://xxx-yyy.trycloudflare.com/gateway/webhook/:platform

记录 Webhook 地址。

3. 配置回调地址 ​

将 Webhook 地址中的 :platform 替换为 wecom，得到完整的回调 URL：

https://xxx-yyy.trycloudflare.com/gateway/webhook/wecom

回到企业微信管理后台的自建应用「接收消息服务器配置」页面：

  1. 将上述 URL 填入「URL」
  2. 填入之前设定的 Token 和 EncodingAESKey
  3. 点击「保存」，系统会发送 GET 验证请求，Gateway 会自动响应验证

回调地址配置完成

验证通过后，企业微信用户发给该应用的消息将通过此回调推送到 Gateway。

4. 环境变量总览 ​

环境变量必填说明
CODEBUDDY_GATEWAY_WECOM_TOKEN是回调签名验证 Token
CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEY是消息加密密钥（43 字符）
CODEBUDDY_GATEWAY_WECOM_CORP_ID是企业微信企业 ID
CODEBUDDY_GATEWAY_WECOM_CORP_SECRET是自建应用的 Secret
CODEBUDDY_GATEWAY_WECOM_AGENT_ID是自建应用的 AgentId

5. 验证接入 ​

配置完成后：

  1. 打开企业微信客户端（桌面端或移动端）
  2. 在工作台找到你创建的自建应用
  3. 向应用发送消息，测试 Agent 是否正常响应

6. （可选）开通微信插件 ​

开通企业微信的「微信插件」后，可以直接在微信中与自建应用对话，无需打开企业微信客户端：

  1. 在企业微信管理后台，进入「我的企业」→「微信插件」
  2. 按指引开通微信插件功能

开通微信插件

开通后，企业成员在微信中即可收到自建应用的消息推送，并直接回复与 CodeBuddy Code 交互。

两种方式对比 ​

对比项腾讯客服（微信客服）企业微信自建应用
使用场景通过微信客服入口远程控制 CodeBuddy Code通过企业微信应用远程控制 CodeBuddy Code
用户入口微信扫码/客服链接企业微信工作台（开通微信插件后也可在微信中使用）
用户范围微信用户（外部客户）企业微信成员（内部员工）
所需环境变量4 个5 个（额外需要 AGENT_ID）
消息机制回调通知 + 主动拉取（sync_msg）回调直接推送完整消息
网络要求无需固定公网 IP需要公网固定 IP 并配置白名单
平台标识wechat-kfwecom

常见问题 ​

回调验证失败 ​

  • 确认环境变量已正确设置且 Gateway 已启动
  • 确认 Token 和 EncodingAESKey 与管理后台填写的一致
  • 确认 Tunnel URL 可从公网访问（本地模式仅适用于内网环境）

消息发送后无响应 ​

  • 检查 CLI 终端是否有错误日志输出
  • 确认 CORP_SECRET 正确（用于获取 access_token 调用 API）
  • 对于企业微信自建应用，确认 AGENT_ID 正确

Tunnel 地址变化 ​

每次执行 /gateway 会生成新的 Tunnel 地址（使用 Cloudflare Quick Tunnel），需要重新更新回调 URL。如需固定域名，可考虑使用 Cloudflare Named Tunnel 或自行配置反向代理。

使用 --port 参数指定固定端口（如 codebuddy --port 8321）可以在多次 CLI 重启之间保持 Tunnel 域名不变。详见 Remote Control 文档。

Gateway 默认端口 ​

Gateway 默认监听 8321 端口。如需修改，可在启动时通过 --port 参数指定。

相关文档 ​