1. 为什么你的 Agent 还是个“哑巴”：从 WorkBuddy 语音播报需求说起
如果你已经在用 WorkBuddy、OpenCode 这类 AI 编程 Agent，大概率经历过这样的场景：跑完一轮自动化测试，Agent 在终端里刷出几十行日志，你盯着屏幕一行行找FAILED；或者代码 Review 结束后，它输出一大段中文解释，你眼睛已经酸得不行，还得硬着头皮读完。Agent 明明已经很聪明了，但它只会“写字”，不会“说话”，也不会“听话”——这就是典型的“哑巴 Agent”。
Voicebox 这个开源项目解决的就是这件事。它是一个本地优先的 AI 语音工作室，把 TTS（文本转语音）和 STT（语音转文本）都放在你自己的机器上跑，数据不出本地。更关键的是，从 0.5.0 版本开始，它内置了一个本地 MCP Server，意味着任何支持 MCP 协议的 Agent（WorkBuddy、OpenCode、Cursor 等）都能直接调用它的语音能力，不需要改一行 Agent 源码。
这篇文章面向两类人：一是想让 WorkBuddy / OpenCode 具备语音播报和语音输入能力的开发者；二是想用十几秒干声克隆出自己音色、给 Agent 配一个“专属人设”的折腾党。我会把 MCP 配置片段、Agent 侧接入步骤、声音克隆流程、以及连不上时的排查方法全部拆开讲，你跟着做就能把“哑巴”Agent 变成能听会说的语音助手。整篇内容围绕 Voicebox + MCP + WorkBuddy / OpenCode 这条链路展开，不涉及任何云端账号注册，全部在本地完成。
先明确一个认知：Voicebox 的架构是“客户端发指令，本地机器跑模型计算”。也就是说，算力瓶颈完全在你的电脑上。Mac M 系列芯片因为有统一内存加速，体验很好；Windows 轻薄本如果没有 N 卡，纯 CPU 跑大模型会吃力。这个前提决定了你后面选哪个 TTS 引擎、要不要走局域网共享算力。下面从环境准备开始，一步步来。
2. 前置准备：Voicebox 本地 MCP Server 与 Agent 接入环境
在动手改配置文件之前，先把几个基础概念和前置条件理清楚，否则后面遇到报错会不知道从哪查。
Voicebox 的 MCP Server 默认监听在http://127.0.0.1:17493/mcp，这个端口是固定的。它只在 Voicebox 桌面端 App 处于打开状态时才会监听，App 一关，服务就没了。这一点和很多常驻后台的服务不一样，也是后面“Connection Refused”报错的最常见原因。你不需要单独启动什么命令行服务，打开 App 就等于启动了 MCP Server。
关于鉴权：0.5.0 版本的 Voicebox MCP 服务端默认只绑定在127.0.0.1（Localhost），并且没有任何 Auth 机制。官方文档特别提醒，任何能访问你本地环回接口的进程都可以调用它。所以现阶段不要把它暴露到公网，跨设备调用需要你自己配反向代理转发端口，官方说未来版本会加入非环回接口的 Bearer Token 鉴权。这个安全边界心里要有数。
Agent 侧需要支持 MCP 协议。WorkBuddy 和 OpenCode 都支持在配置文件里声明mcpServers节点，通常是一个.mcp.json文件或者设置界面里的 JSON 编辑区。你需要在里面加入 Voicebox 的服务地址和一个自定义的X-Voicebox-Client-Id头。这个 Client-Id 是你自己起的名字，比如workbuddy或opencode，它的作用是在后面绑定专属音色时，让 Voicebox 知道是哪个客户端在调用，从而返回对应的声音配置。
声音克隆的前置条件：你需要一段干净的干声样本，建议 15 到 30 秒，安静环境下录制，不要有背景音乐和明显底噪。引擎选择上，必须选 Qwen3-TTS（支持多语言、保真度高）或 LuxTTS（极速、仅英文）。如果你选了 Kokoro 或 Qwen CustomVoice，克隆配置会被隐藏，因为这两个引擎不支持自定义音色。这是很多人第一次配的时候会踩的坑。
算力方面，Mac M1/M2/M3/M4 全系都没问题，16G 内存的入门款 MacBook Air 也能在 1 到 2 秒内完成语音生成。Windows 轻薄本如果只有 CPU 核显，纯 CPU 运算大模型会非常吃力，生成一句话可能卡顿 5 到 20 秒，内存占用也会飙升。破局方案有两个：一是降级用 Kokoro 极速引擎，放弃克隆音色，纯 CPU 也能秒出结果；二是局域网共享算力，在带 N 卡的台式机上跑 Voicebox，把笔记本上 Agent 的 MCP 地址从127.0.0.1改成台式机的局域网 IP。
把这些前提确认完，就可以进入具体的配置环节了。下一节给出可直接复制的配置片段。
3. 可复制配置：WorkBuddy / OpenCode 的 MCP 服务端 JSON 片段
这一节是整篇的核心操作部分，配置片段可以直接复制，但路径和字段名要和你本地的实际情况对齐。
先看 Voicebox 侧的 MCP 配置。打开 WorkBuddy 或 OpenCode 的 MCP 配置文件，通常是项目根目录下的.mcp.json，或者设置界面里的 JSON 编辑区。在mcpServers节点中加入以下内容：
{ "mcpServers": { "voicebox": { "url": "http://127.0.0.1:17493/mcp", "headers": { "X-Voicebox-Client-Id": "workbuddy" } } } }如果你用的是 OpenCode，把X-Voicebox-Client-Id的值改成opencode即可。这个值不是随便填的，它会在后面绑定专属音色时用到——Voicebox 的 Settings -> MCP 面板里会列出所有连接过的 Client-Id，你把某个音色的profile_id指向对应的 Client-Id，这个客户端调用voicebox.speak时就会用那个声音。
有些 Agent 的 MCP 配置用的是 TOML 格式，比如 Codex 的auth.json或类似配置文件。如果是 TOML，写法如下：
[mcp_servers.voicebox] url = "http://127.0.0.1:17493/mcp" [mcp_servers.voicebox.headers] X-Voicebox-Client-Id = "workbuddy"配置完成后，你的 Agent 就自动获得了两大能力。第一是自动播报（TTS）：Agent 可以调用voicebox.speak工具，主动为你朗读代码解释或运行结果。第二是全局听写（STT）：遇到复杂需求懒得打字，直接按住快捷键说话，Voicebox 会在本地识别并输入到 Agent 对话框。
这里要强调一个三件套的概念：Base URL、Key、Model ID。Voicebox 的 MCP 接入里，Base URL 就是http://127.0.0.1:17493/mcp，Key 目前不需要（0.5.0 无鉴权），Model ID 对应的是你选的 TTS 引擎，比如qwen3-tts或luxtts。如果你后面要接入 TaoToken 的模型对话或 Coding Plan 来做更复杂的 Agent 编排，这三件套的对应关系要理清楚：TaoToken 的 API 地址是https://taotoken.net/api，模型对话入口在https://taotoken.net/models，Coding Plan 在https://taotoken.net/coding-plan，API Keys 管理在https://taotoken.net/api-keys。Voicebox 负责语音层，TaoToken 负责模型层，两者通过 MCP 和 API 各司其职。
配置写完后，保存文件，重启 Agent 或重新加载 MCP 配置。如果 Agent 界面里有 MCP 工具列表，应该能看到voicebox.speak、voicebox.list_profiles等工具。看不到就说明配置没生效，先检查 JSON 格式有没有语法错误，再检查 Voicebox App 是否在运行。下一节用实际请求验证整条链路。
4. 验证请求：用 voicebox.speak 与 list_profiles 跑通端到端语音
配置写好了不代表链路通了，必须实际发一次请求验证。这一节给出两种验证方式：一种是在 Agent 里直接触发，一种是用 MCP Inspector 直连测试。
先说 Agent 侧触发。在 WorkBuddy 或 OpenCode 的对话框里输入一句会触发语音播报的指令，比如“帮我解释一下这段代码的作用，并用语音读出来”。Agent 会调用voicebox.speak工具，参数里包含要朗读的文本。如果一切正常，你应该能听到声音，同时在 Voicebox 的 Captures 面板里看到这条生成记录。Captures 面板是 Voicebox 记录所有语音生成历史的地方，能看到文本、使用的音色、生成时间，是验证链路是否真正跑通的关键证据。
如果 Agent 没有自动调用，你可以手动在支持工具调用的界面里选择voicebox.speak，填入文本参数，比如：
{ "text": "部署测试已完成，发现两处潜在的内存泄漏，请查看面板。", "profile_id": "your-profile-id" }profile_id是你在 Voicebox 里创建的音色配置 ID，不填的话会用默认回放声音。这个参数对应 Voicebox Settings -> MCP 里的capture_settings.default_playback_voice_id。
第二种验证方式是用 MCP Inspector 直连测试，这是官方推荐的调试工具。在终端运行：
npx @modelcontextprotocol/inspector http://127.0.0.1:17493/mcp启动后，Inspector 会打开一个 Web 界面，列出 Voicebox 暴露的所有工具。第一步，调用voicebox.list_profiles，如果能返回你的音色列表，说明 MCP 链路完全畅通。第二步，调用voicebox.speak进行端到端测试，填入文本和profile_id。如果正常，你不仅能听到声音，还能在 Voicebox 的 Captures 面板中看到这条生成的记录。
这里有个细节：voicebox.list_profiles返回的列表里，每个音色都有一个profile_id，这个 ID 就是你在 Agent 配置里要绑定的值。如果你在 Settings -> MCP 里把workbuddy这个 Client-Id 的profile_id指向了某个音色，那么 WorkBuddy 调用voicebox.speak时就会用那个声音，不需要每次传profile_id。
验证成功后，你可以进一步测试 STT 能力。按住 Voicebox 设置的全局快捷键，说一段话，Voicebox 会在本地识别并输入到当前焦点窗口。如果焦点在 Agent 对话框，识别结果就直接变成文字输入。这一步验证的是“能听”的能力，和 TTS 的“会说”能力合起来，Agent 才算真正活起来。
如果验证过程中听到的声音是机器音而不是你克隆的音色，检查引擎选择是不是 Qwen3-TTS 或 LuxTTS，以及profile_id有没有正确绑定。下一节集中讲常见报错和排查方法。
5. 常见错排查：401、local proxy failed、reading choices 与 OAuth 报错对照
接入过程中最容易卡住的就是报错排查。这一节把 Voicebox + MCP 链路上常见的几类报错对照着讲清楚，包括 401、local proxy failed、reading choices、OAuth 相关错误。
第一类：Connection Refused / Timeout。核心原因是 Voicebox 的服务端只在桌面端 App 打开时才会监听。如果你用的是 Stdio 模式连接，代理（Shim）会有 30 秒的健康检查等待时间，如果 Voicebox 后端没启动，客户端就会报 JSON-RPC 错误。排查方法很简单：确保 Voicebox 软件正在运行，然后重新加载 Agent 的 MCP 配置。如果还是连不上，用curl http://127.0.0.1:17493/mcp测试端口是否可达，返回非连接拒绝就说明服务在跑。
第二类：401 Unauthorized。0.5.0 版本的 Voicebox MCP 服务端没有鉴权机制，所以正常情况下不应该出现 401。如果你遇到了 401，大概率是你自己配了反向代理并加了鉴权，或者 Agent 侧配置里多写了Authorization头。检查.mcp.json里有没有多余的headers字段，把非X-Voicebox-Client-Id的头去掉。
第三类：local proxy failed。这个报错通常出现在 Agent 通过本地代理转发 MCP 请求时。核心原因是代理进程没有正确启动，或者代理配置的端口和 Voicebox 实际端口不一致。排查方法：确认 Voicebox 监听的是17493端口，确认代理配置里的目标地址是http://127.0.0.1:17493/mcp，确认代理进程本身在运行。如果你用的是局域网共享算力，把127.0.0.1改成台式机的局域网 IP，比如http://192.168.1.100:17493/mcp，同时确认防火墙没有拦截这个端口。
第四类：reading choices 相关报错。这类报错通常出现在 Agent 解析 Voicebox 返回结果时，核心原因是返回的 JSON 结构不符合 Agent 的预期。排查方法：用 MCP Inspector 直接调用voicebox.speak，看返回的原始 JSON 结构。如果 Inspector 里正常但 Agent 里报错，说明是 Agent 侧的解析问题，检查 Agent 版本是否支持 Voicebox 返回的 MCP 协议版本。
第五类：OAuth 相关报错。Voicebox 本身不走 OAuth，如果你在配置里看到了 OAuth 报错，大概率是 Agent 侧把 Voicebox 当成了需要 OAuth 的远程 MCP 服务。检查配置里有没有auth或oauth字段，把它们删掉。Voicebox 是本地服务，不需要 OAuth 流程。
第六类：Profile Not Found。核心原因是 Agent 尝试调用一个不存在的音色名称。Voicebox 在找不到匹配音色时不会静默降级，而是会直接抛出错误。你需要进入 Voicebox 的 Settings -> MCP，检查对应客户端（如opencode）绑定的profile_id是否拼写正确，或者是否将其设置为capture_settings.default_playback_voice_id默认回放声音。
第七类：局域网访问被拒。官方文档特别指出，0.5.0 版本 Voicebox 的 MCP 服务端默认只绑定在127.0.0.1，并且没有任何鉴权机制。如果你想跨设备通过局域网调用，现阶段需要自行配置反向代理（如 Nginx）来转发端口。配置反向代理时，注意不要暴露到公网，只在局域网内使用。
排查顺序建议：先确认 Voicebox App 在运行，再用 MCP Inspector 直连测试，确认 MCP 链路本身没问题，最后检查 Agent 侧配置。这样能把问题范围一步步缩小。如果你在排查过程中需要查 Voicebox 的官方文档，入口在https://taotoken.net/doc，里面有 MCP 接入的详细说明和最新版本变更。
6. 声音克隆与长期编排：从零样本复刻到 Coding Plan 接入
声音克隆是 Voicebox 最有意思的部分。Zero-shot 克隆只需要十几秒干声，就能复刻你的音色。操作路径是：进入 Voicebox 的 Profiles 面板，点击新增，上传一段干净的本地录音，或者在安静环境下直接用麦克风朗读 15 到 30 秒测试文本。建议多上传几段不同情绪的音频，这样克隆出来的音色更自然。
引擎选择是克隆成功的关键。必须选 Qwen3-TTS（支持多语言，保真度高）或 LuxTTS（极速，仅英文）。千万不要选 Kokoro 或 Qwen CustomVoice，否则你的克隆配置会被隐藏。这是很多人第一次配的时候会踩的坑，明明上传了音频却找不到克隆选项，就是因为引擎选错了。
克隆完成后，可以注入“灵魂”。在声音配置中开启 Voice Personalities，填入你的人设提示词，比如“用极其口语化的中文沟通，像个暴躁的架构师”。Agent 原本生硬的代码解释会经过本地 LLM 改写，以更具个性的语气读出来。这个功能让 Agent 不只是“会说话”，而是“有性格地说话”。
绑定到 Agent 的步骤：在 Settings -> MCP 中，找到刚刚配置的workbuddy或opencode，将其profile_id指向你新建的声音。这样这个客户端调用voicebox.speak时就会用你克隆的音色，不需要每次传profile_id。
如果你想把语音能力和更复杂的 Agent 编排结合起来，比如让 Agent 在完成一轮代码 Review 后自动语音汇报，同时调用模型做代码分析，可以把 Voicebox 的 MCP 和 TaoToken 的 Coding Plan 配合使用。Coding Plan 入口在https://taotoken.net/coding-plan，适合长期编码和 Agent 场景。模型对话入口在https://taotoken.net/models，API Keys 管理在https://taotoken.net/api-keys。Voicebox 负责语音输入输出，TaoToken 负责模型推理，两者通过 MCP 和 API 各司其职，Agent 就能从“哑巴”变成能听会说的语音助手。
最后给一个实用技巧：如果你在 Windows 轻薄本上跑，纯 CPU 生成语音很慢，可以把 Voicebox 装在带 N 卡的台式机上，笔记本上的 Agent 通过局域网 IP 调用。这样笔记本负责交互，台式机负责算力，体验会好很多。配置时把.mcp.json里的127.0.0.1改成台式机的局域网 IP 即可，比如http://192.168.1.100:17493/mcp。记得只在局域网内使用，不要暴露到公网。
