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

下载

聚焦模式

字号

最后更新时间： 2026-09-30 18:41:46

通过 /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 或 ~/.bashrc
export 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 是否正常工作。
方式一：直接对话
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. 常见问题
Q1：环境变量未配置
症状：在 /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 尝试连接
Q2：连接失败
可能原因及排查：
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 后保持在主界面，观察连接过程中的输出
Q3：连接后消息无响应
排查步骤：
1. 执行 /remote-control 确认 wecom-bot 状态为 connected
2. 如状态为 disconnected，重新连接
3. 检查 CLI 终端日志是否有错误信息
4. 确认 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 已失效或被重新生成。解决方案：
1. 登录企业微信管理后台，进入 Bot 详情页
2. 在“API 配置”区域重新生成 Secret
3. 更新环境变量 CODEBUDDY_WECOM_BOT_SECRET
4. 重启 CodeBuddy CLI 并重新连接
相关文档
﻿Remote Control（远程控制） - 了解 Remote Control 的完整功能和其他客户端
﻿斜杠命令 - 掌握所有内置命令
﻿设置配置 - 了解 CodeBuddy 配置选项
﻿

帮助和支持

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

填写满意度调查问卷，共创更好文档体验。

文档反馈

tencent cloud

Tencent WorkBuddy Enterprise

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

前置条件

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

1.1 打开创建页面

1.2 填写基本信息

1.3 切换到 API 模式

1.4 选择长连接方式

1.5 获取 Bot ID 和 Secret

1.6 保存机器人

2. 配置环境变量

可选配置

持久化配置（可选）

3. 启动 CodeBuddy 并连接

3.1 启动交互模式

3.2 打开远程控制面板

3.3 连接 wecom-bot

3.4 查看连接状态

4. 面板操作说明

5. 验证接入

方式一：直接对话

方式二：群组对话

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

消息处理全流程

流式状态指示机制

用户看到的效果

与之前方案的区别

超时处理

7. 工作原理

关键特性

8. 常见问题

Q1：环境变量未配置

Q2：连接失败

Q3：连接后消息无响应

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

Q5：应用提示“Token 过期”或“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`

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

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

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