首页 >> 帮助中心 >> 腾讯云国际 > 企业微信智能机器人接入指南

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

2026-10-13 访问量：0

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

前置条件

已注册企业微信账户

CodeBuddy Code 已安装：codebuddy --version

已完成登录认证：codebuddy 后执行 /login

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

1.1 打开创建页面

1.1.1 打开企业微信客户端，进入“工作台”。

1.1.2 单击智能机器人 > 创建 > 选择手动创建。

说明：

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

1.2 填写基本信息

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

1.3 切换到 API 模式

在页面底部点击“API 模式创建”。

1.4 选择长连接方式

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

1.5 获取 Bot ID 和 Secret

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

Bot ID：机器人的唯一标识（示例：aibVGv7I...）

Secret：点击“获取”或“点击获取”获取访问密钥

注意：

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

1.6 保存机器人

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

2. 配置环境变量

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

export CODEBUDDY_WECOM_BOT_ID="<您的 Bot ID>"export CODEBUDDY_WECOM_BOT_SECRET="<您的 Bot Secret>"

可选配置

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

持久化配置（可选）

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

# ~/.zshrc 或 ~/.bashrcexport CODEBUDDY_WECOM_BOT_ID="<您的 Bot ID>"export CODEBUDDY_WECOM_BOT_SECRET="<您的 Bot Secret>"

3. 启动 CodeBuddy 并连接

3.1 启动交互模式

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` / `k`	Vim 风格导航（等同于上下方向键）
`Enter`	连接（`disconnected` 状态）或断开（`connected`/`connecting` 状态）
`Esc`	退出面板（操作进行中时不响应）

5. 验证接入

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

方式一：直接对话

打开企业微信客户端（桌面端或移动端）

在消息列表中找到您创建的机器人

发送测试消息（如“您好”），确认 Bot 有回复

方式二：群组对话

将机器人添加到群聊

在群组中通过 @机器人名称发送消息

Bot 会响应被 @ 的消息

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

消息处理全流程

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

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

流式状态指示机制

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

立即回复：收到用户消息后，立即发送 finish=false 的流式消息，内容为“正在处理，请稍候...”

原位替换：Agent 处理完成后，用同一个 stream.id 发送 finish=true + 最终结果

企微客户端收到 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. 常见问题

Q1：环境变量未配置

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

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

解决方案：

确认已设置 CODEBUDDY_WECOM_BOT_ID 和 CODEBUDDY_WECOM_BOT_SECRET

执行 echo $CODEBUDDY_WECOM_BOT_ID 验证环境变量是否生效

重新启动 CodeBuddy CLI

再次执行 /remote-control 尝试连接

Q2：连接失败

可能原因及排查：

Bot ID 或 Secret 错误

确认从企业微信后台复制的值完全一致（注意末尾是否有空格）

确认 AI Bot 应用状态正常，未被停用

网络连接问题

检查是否能访问 wss://openws.work.weixin.qq.com

如使用私有化部署，确认 CODEBUDDY_WECOM_BOT_WS_URL 设置正确

尝试在浏览器中测试网络连接：curl -v wss://openws.work.weixin.qq.com

CLI 日志查看

查看终端输出的错误日志

执行 codebuddy 后保持在主界面，观察连接过程中的输出

Q3：连接后消息无响应

排查步骤：

执行 /remote-control 确认 wecom-bot 状态为 connected

如状态为 disconnected，重新连接

检查 CLI 终端日志是否有错误信息

确认 CodeBuddy CLI 进程仍在运行（未被中断或退出）

Q4：CLI 重启后需要重新连接

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

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

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

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

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

说明：

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

Q5：应用提示“Token 过期”或“Secret 无效”

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

登录企业微信管理后台，进入 Bot 详情页

在“API 配置”区域重新生成 Secret

更新环境变量 CODEBUDDY_WECOM_BOT_SECRET

重启 CodeBuddy CLI 并重新连接