企业微信智能机器人接入指南 ​

通过 /remote-control 命令，您可以将 CodeBuddy Code 快速接入企业微信智能机器人，实现远程消息驱动。采用 WebSocket 长连接 主动连接方式，无需公网 IP，配置最为简洁。

如需通过企业微信自建应用或微信客服接入，请参阅企业微信智能机器人接入指南 - Webhook 方式。

对比：长连接 vs Gateway 方案 ​

在选择接入方式前，了解两种方案的差异：

对比项/remote-control（长连接）/gateway（Webhook 回调）
连接方式CLI 主动建立 WebSocket企业微信推送 HTTP 回调
网络要求无需公网 IP，仅需出站连接企业微信自建应用需要公网固定 IP
配置复杂度简单（2 个环境变量）较复杂（需配置 Webhook + 签名验证）
启动命令/remote-control/gateway
适用场景企业微信 AI Bot 场景企业微信自建应用 / 微信客服场景
响应延迟WebSocket 实时推送HTTP 回调 + 网络延迟
消息通道双向实时单向回调 + 主动消息

前置条件 ​

  • 已注册企业微信账户
  • CodeBuddy Code 已安装：codebuddy --version
  • 已完成登录认证：codebuddy 后执行 /login

1. 创建企业微信智能机器人 ​

1.1 打开创建页面 ​

  1. 打开企业微信客户端，进入「工作台」
  2. 点击「智能机器人」→ 点击「创建」→ 选择「手动创建」

如果在工作台中未找到「智能机器人」入口，请将企业微信更新到最新版本。

1.2 填写基本信息 ​

输入机器人名称、头像、应用简介等基本信息。

填写基本信息

1.3 切换到 API 模式 ​

在页面底部点击「API 模式创建」。

切换 API 模式

1.4 选择长连接方式 ​

在 API 模式创建页面，找到「API 配置」区域，将连接方式选择为「使用长连接」。

API 模式创建页面

1.5 获取 Bot ID 和 Secret ​

在「API 配置」区域中找到以下信息并妥善保存：

  • Bot ID：机器人的唯一标识（示例：aibVGv7I...）
  • Secret：点击「获取」或「点击获取」获取访问密钥

API 配置 - 获取 Bot ID 和 Secret

⚠️ 重要：Secret 仅显示一次。如丢失可在机器人详情页重新生成。

1.6 保存机器人 ​

确认 Bot ID 和 Secret 已记录后，点击「保存」完成创建。

2. 配置环境变量 ​

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

bash
export CODEBUDDY_WECOM_BOT_ID="<你的 Bot ID>"
export CODEBUDDY_WECOM_BOT_SECRET="<你的 Bot Secret>"

可选配置 ​

环境变量说明默认值
CODEBUDDY_WECOM_BOT_IDAI Bot ID（必填）—
CODEBUDDY_WECOM_BOT_SECRETAI Bot Secret（必填）—
CODEBUDDY_WECOM_BOT_WS_URLWebSocket 服务地址（私有化部署时使用）wss://openws.work.weixin.qq.com

持久化配置（可选） ​

将环境变量添加到 shell 启动文件中，每次启动时自动生效：

bash
# ~/.zshrc 或 ~/.bashrc
export CODEBUDDY_WECOM_BOT_ID="<你的 Bot ID>"
export CODEBUDDY_WECOM_BOT_SECRET="<你的 Bot Secret>"

3. 启动 CodeBuddy 并连接 ​

3.1 启动交互模式 ​

bash
codebuddy

3.2 打开远程控制面板 ​

/remote-control

此命令打开交互式面板，列出所有可用的连接客户端。

3.3 连接 wecom-bot ​

使用方向键选择 wecom-bot 条目，按 Enter 发起连接：

Remote Control Clients

  1. • wecom-bot  [disconnected]  (Press Enter to connect)
  2. • centrifugo [disconnected]
  3. Cancel

连接成功后面板会自动关闭。如果环境变量未配置，面板会停留并显示错误信息。

3.4 查看连接状态 ​

再次执行 /remote-control 可查看连接状态：

  1. • wecom-bot  [connected]  (Press Enter to disconnect)
  2. Cancel

状态说明：

  • disconnected — 未连接，可选择发起连接
  • connecting — 连接中，请稍候
  • connected — 已连接，可选择断开连接

4. 面板操作说明 ​

操作说明
↑ / ↓选择客户端条目
j / kVim 风格导航（等同于上下方向键）
Enter连接（disconnected 状态）或断开（connected/connecting 状态）
Esc退出面板（操作进行中时不响应）

5. 验证接入 ​

连接建立后，可通过以下方式验证 Bot 是否正常工作。

方式一：直接对话 ​

  1. 打开企业微信客户端（桌面端或移动端）
  2. 在消息列表中找到你创建的机器人
  3. 发送测试消息（如「你好」），确认 Bot 有回复

方式二：群组对话 ​

  1. 将机器人添加到群聊
  2. 在群组中通过 @机器人名称 发送消息
  3. Bot 会响应被 @ 的消息

6. 消息处理流程和状态指示 ​

消息处理全流程 ​

用户发送消息到 Bot 后的处理流程：

用户在企业微信发送消息
        ↓ WebSocket 长连接实时推送消息
CodeBuddy CLI 接收消息
        ↓ 5 秒内回复（满足企微回调超时要求）
发送流式消息 (stream finish=false)："正在处理，请稍候..."
        ↓ 企微客户端展示流式消息
Agent 处理中...（处理时间可能 1 秒到 5+ 分钟）
        ↓
处理完成，发送流式消息 (stream finish=true)：最终结果
        ↓ 企微客户端用最终结果全量替换"正在处理..."
企业微信用户看到最终回复（聊天记录中仅保留最终结果）

流式状态指示机制 ​

利用企微流式消息（aibot_respond_msg stream 类型）的全量替换特性：

  1. 立即回复：收到用户消息后，立即发送 finish=false 的流式消息，内容为"正在处理，请稍候..."
  2. 原位替换：Agent 处理完成后，用同一个 stream.id 发送 finish=true + 最终结果
  3. 企微客户端收到 finish=true 后，用全量内容替换之前显示的"正在处理..."

参考：智能机器人长连接文档 —— stream.content 为全量内容，每次发送替换上一次的显示。

用户看到的效果 ​

阶段聊天窗口显示说明
消息发送后"正在处理，请稍候..."流式消息占位，表示 Bot 正在处理
处理完成后最终回复内容"正在处理..."被最终结果原位替换

与之前方案的区别 ​

方面旧方案（文本消息 ack）新方案（流式消息替换）
"正在处理..."永久保留在聊天记录被最终结果原位替换
聊天记录2 条消息（ack + 结果）1 条消息（仅最终结果）
状态指示有有

超时处理 ​

  • 流式消息超时：6 分钟（从首次发送 stream 开始计时）
  • 安全超时：5 分钟（预留 1 分钟余量）
  • 超时回退：如果 Agent 处理超过 5 分钟，自动回退到异步推送（aibot_send_msg，24 小时有效期）
  • 回调超时：收到消息回调后需在 5 秒内发送回复（流式占位消息满足此要求）

7. 工作原理 ​

企业微信用户发送消息
        ↓
企业微信服务器（WebSocket 连接池）
        ↓ WebSocket 长连接实时推送
CodeBuddy CLI（WecomBotClient）
        ↓
CodeBuddy Agent 处理消息，生成回复
        ↓
通过同一 WebSocket 连接回复消息
        ↓
企业微信用户收到 Bot 回复

关键特性 ​

  • 连接方式：WebSocket 长连接（客户端主动连接，无需公网 IP）
  • 认证机制：启动时发送 aibot_subscribe 帧，携带 bot_id + secret 完成鉴权
  • 消息接收：企业微信服务器通过 aibot_msg_callback 帧实时推送用户消息
  • 消息回复：通过 aibot_respond_msg 帧以流式方式返回 Agent 回复
  • 心跳保活：每 30 秒发送一次 ping 帧保持连接活跃
  • 自动重连：连接断开后按指数退避策略自动重连，最长延迟 60 秒

8. 常见问题 ​

环境变量未配置 ​

症状：在 /remote-control 面板中选择 wecom-bot 后显示错误

Error: WeChat Work AI Bot is not configured.
Missing environment variables: CODEBUDDY_WECOM_BOT_ID, CODEBUDDY_WECOM_BOT_SECRET

解决方案：

  1. 确认已设置 CODEBUDDY_WECOM_BOT_ID 和 CODEBUDDY_WECOM_BOT_SECRET
  2. 执行 echo $CODEBUDDY_WECOM_BOT_ID 验证环境变量是否生效
  3. 重新启动 CodeBuddy CLI
  4. 再次执行 /remote-control 尝试连接

连接失败 ​

可能原因及排查：

  1. Bot ID 或 Secret 错误

    • 确认从企业微信后台复制的值完全一致（注意末尾是否有空格）
    • 确认 AI Bot 应用状态正常，未被停用

  2. 网络连接问题

    • 检查是否能访问 wss://openws.work.weixin.qq.com
    • 如使用私有化部署，确认 CODEBUDDY_WECOM_BOT_WS_URL 设置正确
    • 尝试在浏览器中测试网络连接：curl -v wss://openws.work.weixin.qq.com

  3. CLI 日志查看

    • 查看终端输出的错误日志
    • 执行 codebuddy 后保持在主界面，观察连接过程中的输出

连接后消息无响应 ​

排查步骤：

  1. 执行 /remote-control 确认 wecom-bot 状态为 connected
  2. 如状态为 disconnected，重新连接
  3. 检查 CLI 终端日志是否有错误信息
  4. 确认 CodeBuddy CLI 进程仍在运行（未被中断或退出）

CLI 重启后需要重新连接 ​

/remote-control 连接状态是临时的，不会持久化。每次重启 CodeBuddy CLI 后，需要重新执行 /remote-control 并选择 wecom-bot 建立连接。

自动连接方案（如需每次启动自动连接）：

将以下内容添加到启动脚本或 shell 配置文件中：

bash
# ~/.zshrc 或 ~/.bashrc
export CODEBUDDY_WECOM_BOT_ID="<你的 Bot ID>"
export CODEBUDDY_WECOM_BOT_SECRET="<你的 Bot Secret>"

# 可选：创建别名快速启动并自动连接
alias cbc-wecom='codebuddy -c "/remote-control"'

其中 -c 参数表示启动时自动执行指定命令。

应用提示"Token 过期"或"Secret 无效" ​

这通常表示 Bot 的 Secret 已失效或被重新生成。解决方案：

  1. 登录企业微信管理后台，进入 Bot 详情页
  2. 在「API 配置」区域重新生成 Secret
  3. 更新环境变量 CODEBUDDY_WECOM_BOT_SECRET
  4. 重启 CodeBuddy CLI 并重新连接

相关文档 ​