WorkBuddy 专属接入指南

WorkBuddy 与 VOKO 有两个独立方向：WorkBuddy 通过 MCP 主动调用 VOKO；VOKO 通过已登录的独立 CodeBuddy CLI，在本机 HTTP/ACP 通道把新消息交给 WorkBuddy。配置其中一个方向不会自动打通另一个方向。

推荐顺序：先在 WorkBuddy 创建或选择专家，再配置 voko mcp；如需 VOKO 自动唤醒 WorkBuddy，再单独安装和登录 CodeBuddy CLI，最后在 VOKO 注册 WorkBuddy Agent。

1. 专家在哪里创建

个人版：WorkBuddy 左侧边栏 → 专家 → 我的专家在“我的专家”创建私有专家；也可从“专家中心”召唤已有专家或专家团。

企业版：WorkBuddy 企业管理后台 → 专家管理企业管理员可使用“+ 上传企业专家”，配置专家标识、资料、专家包和可见范围。

回到 VOKO：添加 Agent → WorkBuddyExpert 为可选绑定。不绑定时创建隔离会话；绑定已发现 Expert 时，资料建议和后续路由固定到该 Expert。不要手填未被 VOKO 枚举的 ID。

官方参考：WorkBuddy 专家中心。产品版本不同导致菜单名称变化时，以当前客户端“专家 / 我的专家”入口为准。

2. WorkBuddy → VOKO：一键配置 MCP

最快方式是在终端执行下面两条命令。点击按钮复制后，在安装 WorkBuddy/CodeBuddy 的同一用户终端运行：

codebuddy mcp add --scope user voko -- voko mcp
codebuddy mcp list

也可以打开 WorkBuddy 对话面板 → CodeBuddy Settings → MCP → Add MCP，复制下面的完整配置，点击 Try to Run 后保存：

{
  "mcpServers": {
    "voko": {
      "type": "stdio",
      "command": "voko",
      "args": ["mcp"],
      "description": "VOKO local Agent IM"
    }
  }
}

用户级文件优先使用 ~/.codebuddy/.mcp.json（Windows 为 %USERPROFILE%\.codebuddy\.mcp.json）。不要用示例覆盖已有 MCP Server，也不要同时维护多个同名 voko 条目。保存后完全重启 WorkBuddy，并确认工具列表出现 voko_whoami。

3. VOKO → WorkBuddy：准备自动投递

WorkBuddy Desktop 登录不能代替全局 CodeBuddy CLI 登录。自动投递前需要：

npm install -g @tencent-ai/codebuddy-code
codebuddy /login
codebuddy --version

VOKO 优先使用系统 PATH 中独立安装的新版 CLI；桌面内置旧版只作回退。发现可执行文件或成功启动本机服务都不等于可用，只有真实模型 loopback 精确返回后，注册预检才能将 http 标记为 ready。

4. 在 VOKO 注册

运行 voko start，打开 voko status --json 返回的实际端口。
在“添加 Agent”中选择 WorkBuddy，按需绑定已发现的 Expert。
只启用预检为 ready 的 http，并保留 pull。
真实回路验证会调用模型，可能产生费用，应由主人明确确认。
创建后分别确认 voko list_agents、voko_get_status 的 IM 连接和 automaticReadyModes。

推荐接收顺序：HTTP → Pull

5. 验证与排错

WorkBuddy 看不到 VOKO 工具：确认 GUI 进程能找到 voko，必要时在配置中使用 Get-Command voko 或 command -v voko 返回的绝对路径。
MCP 可用但不能自动收消息：MCP 是 WorkBuddy → VOKO；自动投递还需要全局 CLI 登录和真实 loopback。
Authentication required：执行 codebuddy /login，不要只重复登录 Desktop。
只有 Pull：消息不会丢失。修复 CLI/登录后重新预检，不要手工伪造 http ready。

当前已验证基线：macOS 全局 CodeBuddy CLI 2.139.0 已完成真实回路；Windows 同版本在未登录时能正确识别认证缺失，登录后的完整真实回路仍需按当前机器重新验收。Provider 服务只监听随机 127.0.0.1 端口，结果未知时不会重复提交任务。