一、前置条件
·已注册企业微信账户
·CodeBuddy Code 已安装：codebuddy –version
·已完成登录认证：codebuddy 后执行 /login
三、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.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 有回复
20、方式二：群组对话
1. 将机器人添加到群聊
2. 在群组中通过 @机器人名称 发送消息
3. Bot 会响应被 @ 的消息
22、消息处理全流程
用户发送消息到 Bot 后的处理流程：
用户在企业微信发送消息 ↓ WebSocket 长连接实时推送消息CodeBuddy CLI 接收消息 ↓ 5 秒内回复（满足企微回调超时要求）发送流式消息 (stream finish=false)："正在处理，请稍候…" ↓ 企微客户端展示流式消息Agent 处理中…（处理时间可能 1 秒到 5+ 分钟） ↓处理完成，发送流式消息 (stream finish=true)：最终结果 ↓ 企微客户端用最终结果全量替换"正在处理…"企业微信用户看到最终回复（聊天记录中仅保留最终结果）
23、流式状态指示机制
利用企微流式消息（aibot_respond_msg stream 类型）的全量替换特性：
1. 立即回复：收到用户消息后，立即发送 finish=false 的流式消息，内容为“正在处理，请稍候…”
2. 原位替换：Agent 处理完成后，用同一个 stream.id 发送 finish=true + 最终结果
3. 企微客户端收到 finish=true 后，用全量内容替换之前显示的“正在处理…”
注意：说明：
注意：智能机器人长连接文档 —— stream.content 为全量内容，每次发送替换上一次的显示。
24、用户看到的效果
| 阶段 | 聊天窗口显示 | 说明 |
| 消息发送后 | “正在处理，请稍候…” | 流式消息占位，表示 Bot 正在处理 |
| 处理完成后 | 最终回复内容 | “正在处理…”被最终结果原位替换 |
25、与之前方案的区别
| 方面 | 旧方案（文本消息 ack） | 新方案（流式消息替换） |
| “正在处理…” | 永久保留在聊天记录 | 被最终结果原位替换 |
| 聊天记录 | 2 条消息（ack + 结果） | 1 条消息（仅最终结果） |
| 状态指示 | 有 | 有 |
26、超时处理
·流式消息超时：6 分钟（从首次发送 stream 开始计时）
·安全超时：5 分钟（预留 1 分钟余量）
·超时回退：如果 Agent 处理超过 5 分钟，自动回退到异步推送（aibot_send_msg，24 小时有效期）
·回调超时：收到消息回调后需在 5 秒内发送回复（流式占位消息满足此要求）
27、7. 工作原理
企业微信用户发送消息 ↓企业微信服务器（WebSocket 连接池） ↓ WebSocket 长连接实时推送CodeBuddy CLI（WecomBotClient） ↓CodeBuddy Agent 处理消息，生成回复 ↓通过同一 WebSocket 连接回复消息 ↓企业微信用户收到 Bot 回复
28、关键特性
·连接方式：WebSocket 长连接（客户端主动连接，无需公网 IP）
·认证机制：启动时发送 aibot_subscribe 帧，携带 bot_id + secret 完成鉴权
·消息接收：企业微信服务器通过 aibot_msg_callback 帧实时推送用户消息
·消息回复：通过 aibot_respond_msg 帧以流式方式返回 Agent 回复
·心跳保活：每 30 秒发送一次 ping 帧保持连接活跃
·自动重连：连接断开后按指数退避策略自动重连，最长延迟 60 秒
30、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 尝试连接
31、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 后保持在主界面，观察连接过程中的输出
32、Q3：连接后消息无响应
排查步骤：
1. 执行 /remote-control 确认 wecom-bot 状态为 connected
2. 如状态为 disconnected，重新连接
3. 检查 CLI 终端日志是否有错误信息
4. 确认 CodeBuddy CLI 进程仍在运行（未被中断或退出）
33、Q4：CLI 重启后需要重新连接
/remote-control 连接状态是临时的，不会持久化。每次重启 CodeBuddy CLI 后，需要重新执行 /remote-control 并选择 wecom-bot 建立连接。
自动连接方案（如需每次启动自动连接）：
将以下内容添加到启动脚本或 shell 配置文件中：
# ~/.zshrc 或 ~/.bashrcexport CODEBUDDY_WECOM_BOT_ID="<你的 Bot ID>"export CODEBUDDY_WECOM_BOT_SECRET="<你的 Bot Secret>"# 可选：创建别名快速启动并自动连接alias cbc-wecom='codebuddy -c "/remote-control"'
注意：说明：
注意：其中 -c 参数表示启动时自动执行指定命令。
34、Q5：应用提示“Token 过期”或“Secret 无效”
这通常表示 Bot 的 Secret 已失效或被重新生成。解决方案：
1. 登录企业微信管理后台，进入 Bot 详情页
2. 在“API 配置”区域重新生成 Secret
3. 更新环境变量 CODEBUDDY_WECOM_BOT_SECRET
4. 重启 CodeBuddy CLI 并重新连接
35、相关文档
·Remote Control（远程控制） – 了解 Remote Control 的完整功能和其他客户端
·斜杠命令 – 掌握所有内置命令
·设置配置 – 了解 CodeBuddy 配置选项