把CodeBuddy接入多智能体网络

一、背景：为什么要把CodeBuddy塞进"运维网络"

我们维护着一套跑在自有内网的多节点 AI Agent 协作网络：一台主控负责调度，若干节点分别承担网关隔离、模型推理、记忆检索、桌面自动化等角色，节点之间靠 SSH、文件通道和定时任务协同。

腾讯公司QClaw已发布停运公告后，我们决定提前启动迁移准备 —— 把原本由它承担的职能（定时派活、GUI 测试调度、深度研究任务）逐步转移到替代方案上，避免临期被动。

评估下来，腾讯的 CodeBuddy Code（CLI，@tencent-ai/codebuddy-code）是合适的候选：

• 内核是完整的 Agent Runtime（工具调用、多轮、子 Agent、MCP）
• 自带 headless 模式、HTTP 网关、Web UI、ACP 协议
• 有桌面版（WorkBuddy），具备窗口/截图/鼠标操作能力

但"能装"和"能无人值守地被调度"是两回事。 下面的排查过程，记录了我们从"桌面能用、脚本跑不通"到"完全本地化落地"的完整路径。

二、现象：

第一轮验证就出现了桌面侧和脚本侧的对照：

桌面侧：在 WorkBuddy 桌面里发消息，Agent 正常执行、正常回复。

脚本侧：用同样的网关接口发任务，返回 202 accepted 并给出 runId，但任务永远停在"进行中"：

{"data":{"runId":"<runId>","status":"accepted"}}
# 之后无论等多久，查询状态始终 active:true

日志里最先暴露的是一行不起眼的报错：

[Error] Failed to read settings file for scope user: ENOENT

继续追，发现状态机走了一半就停住：

RUN_PREPARING → RUN_ACCEPTED → AGENT_STARTED → ...（此后没有任何输出）
[WorkflowMemProbe] tick runId=(none)

任务被受理了、Agent 被拉起来了，但模型调用从未发生。

三、根因：两套认证体系，一道会话隔离墙

3.1 第一层：凭据根本不在 CLI 手里

我们把范围缩小到认证。关键日志：

[FileAuthenticationStorage] [AtRestEncryption] unavailable
    adapter=credential-fields resource=auth/<desktop>.info
[CliDispatcher] [CredentialBootstrap] CBC receiver
    {"route":"standalone","policy":"unspecified",...}
[ExternalLinkAuthenticationProvider] fetch auth accounts error: 401
[AuthenticationManager] Failed to refresh token: account list is empty

三条信息拼起来就是答案：

1. CredentialBootstrap 的 route 是 standalone —— 说明这个进程没有拿到宿主注入的凭据，是"野生"启动的。
2. AtRestEncryption unavailable —— 凭据存储采用了静态加密（在 Windows 平台，这类静态加密通常会走系统的 DPAPI，但这里只是我们的推断），而当前进程无法解密。
3. fetch auth accounts error: 401 —— 于是它去问服务端，服务端说你没凭据。

3.2 第二层：为什么"桌面 spawn 的进程"也没用

这里有个容易踩的坑：我们一度认为"只要用桌面自己拉起的 sidecar 就能借用登录态"，于是去接管了桌面的 prewarm 预热进程池（见第五节）。结果拿到了一个免密、状态为"已认证"的网关：

{"authEnabled":false,"authenticated":true}

但发任务依然卡在 AGENT_STARTED。 authenticated:true 只表示"这个进程认为自己是登录态"——我们理解，真正的凭据注入发生在桌面进程与它 spawn 的子进程之间，一旦从外部（比如 WSL）通过 IPC 接管，这条注入链就断了。（与 §3.3 同理，此为推断，我们未做对照实验。）

3.3 第三层：跨系统的会话隔离

我们还试过从 WSL 直接启动 Windows 侧的进程去跑 CLI，甚至用交互式计划任务在用户会话里启动。结果一致：Authentication required。

日志里能确定的只有一件事：静态加密模块在该进程内不可用（[AtRestEncryption] unavailable），随后凭据刷新失败。

我们推测，这类静态加密通常依赖当前登录会话持有的用户凭据材料（密钥派生自用户口令），而由 WSL 侧拉起的 Windows 进程往往处在非交互式上下文，因此可能拿不到解密所需的那部分材料。但这只是推测——我们没有做对照实验去证实这一层机制，就不在本文下结论了。

不过，真正有实操价值的一点是确定的：绕开这个问题的正确做法，不是去改造登录会话（换启动方式、调计划任务参数），而是换一条路——让 CLI 自己完成一次登录。 这正是下一节的内容。

3.4 关键转折：CLI 有它自己的认证，而且完全独立

排查到这里，我们做了一次思路切换：不要试图复用桌面的登录态，而是让 CLI 自己登录。

验证发现——CodeBuddy CLI 在 Linux 侧的认证是纯文件存储（~/.codebuddy/），不涉及任何操作系统级加密，自然也没有会话隔离问题。

这一步是整个问题的解。

四、解法：三步走通独立 CLI

4.1 安装（公网可得，无需内部源）

npm i -g @tencent-ai/codebuddy-code --registry=https://registry.npmmirror.com
codebuddy --version

提示 1：包名是 @tencent-ai/codebuddy-code。桌面端里内置的那份走的是另一条路径，不要混淆 —— 前者是公开发行渠道，后者是桌面私有集成。 提示 2：上面用 --registry 参数只影响本次安装。若写成 npm config set registry ... 会全局覆盖 npm 源，装完记得改回，或改用前者。

4.2 登录（这一步有个大坑）

CLI 提供 /login 交互命令，但我们实测发现：

用 pty 驱动 TUI 注入按键极不稳定 —— 菜单时好时坏，登录 URL 会因终端宽度不够被折行截断（state= 参数只取到一半）。折腾了几轮之后我们换了条路：

# 仅绑本机回环；仅为打通登录流程，完成登录后请改回启用鉴权（见 §6.3）
codebuddy --serve --port 8322 --auth none

然后在同机浏览器打开 http://localhost:8322/。

环境说明：本文 CLI 装在 Linux 侧的开发机（WSL 环境），浏览器在 Windows 侧。WSL2 默认会把 localhost 转发到 Windows，所以直接访问即可，无需额外配置。如果在纯远程服务器上操作，用 SSH 端口转发（ssh -L 8322:127.0.0.1:8322）也能达到同样效果 —— 不要把该端口直接暴露到网络上（见 §6.3 安全边界）。

Web UI 里有完整的登录入口，点一下、扫码/SSO 走完，凭据就落到用户目录（~/.codebuddy/）了。整个过程不需要和 TUI 搏斗。

补充：如果你确实需要走 TUI 拿登录链接，先把终端宽度设到 200 列以上（stty cols 220），否则 URL 必被截断。

4.3 验证

$ codebuddy -p "reply with exactly: PONG"
PONG
​
$ codebuddy -p "run the shell command 'echo HELLO' and tell me its output" -y
Output: `HELLO` (exit code 0)

工具调用（Bash）通了 —— 这是 Agent 能力的核心，也是后面一切的基础。

五、进阶：prewarm 进程池能接管吗？

CodeBuddy 有一个"预热进程"机制：提前冷启动若干进程待命，需要时唤醒，省掉冷启动时间。该机制由产品官方提供（具体行为请查阅官方文档）。

我们做了一次边界验证：外部程序能否激活这些预热进程、并借它拿到可用的 Agent 能力？

结论是"能接管，但不能绕过认证"：

• 能拿到的：一个仅绑本机回环地址的 HTTP 网关（端口由系统分配）。从进程控制的角度看，预热进程确实可以被外部激活并转为服务形态。
• 拿不到的：它不具备可用的登录凭据。用它提交任务，状态机同样会停在 AGENT_STARTED，模型调用永远不会发出（原因见 3.2）。

所以这条路不能作为认证的替代方案。 想打通，还是要让 CLI 自己完成一次登录。我们把它记在这里，是为了给同样想"少走一步"的人省下一次尝试 —— 这个方向看起来很像捷径，实际是死路。

说明：本文不展开该机制的具体协议与调用细节。若你需要了解，请以官方文档为准。

六、落地：把它变成调度网络里的一个执行节点

认证通了之后，我们把 CLI 封装成常驻网关 + 命令行客户端，接入现有的调度体系。

6.1 两种调用形态

形态 A：一次性调用（适合低频、独立任务）

codebuddy -p "任务文本"          # 只读问答
codebuddy -p "任务文本" -y       # 允许工具调用

形态 B：常驻网关（适合高频、多任务复用）

# 仅绑本机回环；生产环境请按官方文档启用鉴权（见下方安全边界）
codebuddy --serve --port 8322
​
curl -s -H "<标识头名>: <值>" \
     http://127.0.0.1:8322/api/v1/health
​
curl -s -X POST http://127.0.0.1:8322/api/v1/runs \
  -H "<标识头名>: <值>" -H "Content-Type: application/json" \
  -d '{
    "id":"<uuid>",
    "type":"message",
    "source":{"platform":"generic","sender":{"id":"scheduler"},
              "conversation":{"id":"<uuid>","type":"direct"}},
    "payload":{"text":"任务文本"}
  }'
# → {"data":{"runId":"...","status":"accepted"}}

6.2 两个必须知道的接口细节

坑一：网关要求携带产品自身的请求标识头。 缺了它，请求直接 403，而且错误信息不会告诉你原因 —— 对着 403 排查半天才发现是缺头。具体头字段名与取值请以官方文档为准。

坑二：任务正文不在 REST 响应里。 /api/v1/runs/{id} 只返回 active 状态，流式接口在任务完成后会直接 404。正文要从会话记录里取：

ls -t ~/.codebuddy/projects/*/*.jsonl | head -1
# 逐行 JSON，过滤 type=message && role=assistant 的 text 字段

这一条官方文档没写，但对接时不解决它就没法拿到结果。

6.3 网关的能力面

从运行日志看，这个网关的能力远不止"发任务"：它同时还暴露了会话管理、统计、追踪、常驻服务状态、定时任务、IM 通道接入等一组接口。

其中几个值得注意：

• IM 通道：接口层面声明支持 generic / wecom / wechat-kf（企业微信、微信客服）—— 意味着它自带 IM 通道接入能力，可以直接对接到群聊/客服工作流
• 常驻服务：可注册为系统服务、开机自启，并查询运行状态
• 定时任务：自带调度能力
• ACP：Agent Client Protocol 长连接，适合需要流式交互的场景

⚠️ 安全边界（重要） 这个网关能执行本机 shell 工具调用（见 §4.3 的验证），因此它实质上等同于一条本机命令执行入口。无论用哪种方式启动，都请守住三条底线：

1. 只绑回环地址（127.0.0.1）。切勿改为 0.0.0.0，也不要通过端口转发、反向代理把端口服到内网或公网。
2. 生产环境务必启用鉴权。本文为聚焦认证排查问题，示例中使用了关闭鉴权的参数；那仅适用于完全隔离的本机调试。长期运行请按官方文档启用访问控制。
3. 一旦实例挂上了 IM 通道（企业微信等），访问控制的要求会成倍上升 —— 因为消息入口本身就是外部输入源。此时应叠加网络隔离与反代鉴权，而不是依赖网关自身的单层防护。

七、成本归零：接到本地 GPU

真正让这套方案"值得长期跑"的，是模型侧的调整。

CodeBuddy 支持通过 ~/.codebuddy/models.json 注入自定义模型（OpenAI 兼容协议）：

{
  "models": [{
    "id": "local-model",
    "name": "local-model",
    "vendor": "Custom",
    "url": "http://<本地推理服务地址>:8000/v1",
    "supportsToolCall": true,
    "supportsImages": false,
    "supportsReasoning": false,
    "maxInputTokens": 128000,
    "maxOutputTokens": 16384
  }]
}

配好之后，整个 Agent 的推理就跑在内网的 GPU 节点上了。

实测数据

采集环境：本地 GPU 节点（内网 HTTP 服务，OpenAI 兼容接口），客户端与服务端同网段；单并发、无其他负载。数字为观察值，非严格基准测试。

两个观察：

1. 固定开销不小。CodeBuddy 本体的系统提示约 29K tokens，即便只回一句"OK"，也要先吃掉这个上下文。本地推理免费，但延迟由这部分决定（TTFT 约 0.5–1.5s）。
2. 调用成本为零。相比走云端 API 按 token 计费，本地接管后只有电费和 GPU 折旧。对于"高频、短输出"的调度类任务，这是关键的经济性优势。

八、经验总结

五条最值得记的结论：

1. 桌面能跑 ≠ 脚本能跑。桌面应用把凭据注入子进程时，注入链绑定在桌面进程上下文里（此为我们的推断，见 §3.2/§3.3）；一旦你从外部接管进程，这条链就断了。
2. OS 级加密可能依赖登录会话上下文。我们观察到的现象是"能读到加密文件、但解不开"，日志只证明静态加密模块不可用。与其在这条路上死磕（改造启动方式、换计划任务参数），不如换条路 —— 让程序自己完成一次认证，往往更快。
3. 遇到"认证拿不到"，先想"能不能让它自己登录"，而不是死磕"怎么复用别人的登录态"。我们绕了三层才走到这一步，而它是最短路径。
4. 自动化登录优先走 Web UI。用 pty 驱动 TUI 注入按键，在真实项目里是不稳定源；有 Web UI 就用 Web UI。
5. 官方文档没写的东西，往往才是集成时最耗时的：REST 不返回任务正文、必需的请求标识头不出现在错误信息里、预热进程接管后拿不到凭据 —— 这些只能靠实测。

适用场景建议：

九、写在最后

这套方案的实质，是把一个面向"编码"的 Agent，改造成面向"调度"的通用执行节点：它不再需要人坐在 IDE 前面，而是作为一个可编程的进程，被上层网络按需唤醒、派活、回收。

对我们来说，这是在原工具停运前完成的职能承接准备；对更广泛的场景来说，它提供了一个思路 —— 当下主流的编码 Agent，其内核能力（工具调用、多轮推理、MCP）已经足够通用，缺的往往只是"如何把它安全地接入你自己的自动化体系"这一层封装。

而这一层，官方文档通常只讲到一半。

声明：本文所有操作均在自有测试环境完成，不涉及任何未授权访问。文中内网地址、主机名、凭据、进程号与身份信息均已做脱敏处理；涉及的产品接口行为基于特定版本实测，后续版本可能变化，请以官方文档为准。文中所述为个人技术实践，不代表任何组织立场；实际部署请遵守产品许可协议与所在组织的信息安全规定。