1. 为什么你的 Agent 还是个“哑巴”从 WorkBuddy 语音播报需求说起如果你已经在用 WorkBuddy、OpenCode 这类 AI 编程 Agent大概率经历过这样的场景跑完一轮自动化测试Agent 在终端里刷出几十行日志你盯着屏幕一行行找FAILED或者代码 Review 结束后它输出一大段中文解释你眼睛已经酸得不行还得硬着头皮读完。Agent 明明已经很聪明了但它只会“写字”不会“说话”也不会“听话”——这就是典型的“哑巴 Agent”。Voicebox 这个开源项目解决的就是这件事。它是一个本地优先的 AI 语音工作室把 TTS文本转语音和 STT语音转文本都放在你自己的机器上跑数据不出本地。更关键的是从 0.5.0 版本开始它内置了一个本地 MCP Server意味着任何支持 MCP 协议的 AgentWorkBuddy、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.1Localhost并且没有任何 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 就自动获得了两大能力。第一是自动播报TTSAgent 可以调用voicebox.speak工具主动为你朗读代码解释或运行结果。第二是全局听写STT遇到复杂需求懒得打字直接按住快捷键说话Voicebox 会在本地识别并输入到 Agent 对话框。这里要强调一个三件套的概念Base URL、Key、Model ID。Voicebox 的 MCP 接入里Base URL 就是http://127.0.0.1:17493/mcpKey 目前不需要0.5.0 无鉴权Model ID 对应的是你选的 TTS 引擎比如qwen3-tts或luxtts。如果你后面要接入 TaoToken 的模型对话或 Coding Plan 来做更复杂的 Agent 编排这三件套的对应关系要理清楚TaoToken 的 API 地址是https://taotoken.net/api模型对话入口在https://taotoken.net/modelsCoding Plan 在https://taotoken.net/coding-planAPI 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/modelsAPI 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。记得只在局域网内使用不要暴露到公网。