奇链 奇链
← 教程库
进阶 约 25 分钟 2026-10-09 02:10:02 · 1 阅读

VoiceMode 实操：给 Claude Code 装上语音对话，converse 与 service 两工具用法

跟 AI 结对编程到深处，瓶颈常常不是脑子而是手：盯着重构了一半的代码，两只手都在键盘上，想问一句"这个异常该在哪层catch"得停下来打字。VoiceMode 解决的就是这个缝隙——它给 Claude Code（以及其他支持 MCP 的 AI 编程工具）加上语音对话：你说话，它听；它答完还能念出来。官方给的定位很克制，README 第一行写的是"Voice isn't about replacing typing - it's about being available when typing isn't"，走路去开会、做饭时盯日志、端着咖啡的时候，语音顶上。

这篇依据 VoiceMode 官方仓库 README（v8.12.0，GitHub 1389 星）与官方文档站整理，覆盖两条安装路径、converse 和 service 两个核心工具的用法、本地语音服务（Whisper/Kokoro）的选配。文中所有工具返回都附了一次真实端点会话的输出。

voicemode.dev 官网首页：Stop typing. Start talking. 大标题与平台徽章

voicemode.dev 官网首页：右侧是语音对话示例，徽章行标明 Linux/macOS/Windows(WSL)、Python 3.10+、MIT 协议

它是什么：一个 MCP 服务器，也是一套本地服务管理器

VoiceMode 的本体是一个 stdio 传输的 MCP 服务器，注册两个语音工具给 AI 客户端调用。同时它还自带一套本地语音服务的管理能力：语音识别（STT）和语音合成（TTS）既可以走 OpenAI 的云 API，也可以装成完全本地的 Whisper + Kokoro，官方文档明确这两种后端暴露相同的 API，VoiceMode 在其间无缝切换。在意隐私或想离线用的，选本地路线；要音色质量的，走 OpenAI。

兼容性方面官方列得很全：Linux、macOS、Windows（原生或 WSL）、NixOS，Python 3.10 到 3.14。前提只有一条——README 的 Quick Start 开头写着 Requirements: Computer with microphone and speakers，得有麦克风和扬声器。WSL2 用户还要额外装 pulseaudio 相关包才有麦克风访问，这点后面坑位表里还会出现。

路径一：Claude Code 插件（官方推荐）

用 Claude Code 的话四条命令搞定，README 原文如下：

# Add the VoiceMode marketplace
claude plugin marketplace add mbailey/voicemode

# Install VoiceMode plugin
claude plugin install voicemode@voicemode

## Install dependencies (CLI, Local Voice Services)
/voicemode:install

# Start talking!
/voicemode:converse

GitHub 仓库 README 的 Quick Start 与 Option 1 安装命令

GitHub README 的 Quick Start 一节：Option 1 是 Claude Code 插件路径，四条命令从加源到开口

/voicemode:install 这步装的是系统依赖（FFmpeg、PortAudio 等）和本地语音服务，官方文档说安装器会主动处理缺依赖的情况。

路径二：Python 安装器（任意 MCP 客户端）

不用 Claude Code 的走 Python 路线。先确保有 uv 包管理器，然后跑官方安装器，再把服务器注册进客户端。README 给的 Claude Code 注册命令长这样：

# Install UV package manager (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the installer (sets up dependencies and local voice services)
uvx voice-mode-install

# Add to Claude Code
claude mcp add --scope user voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcher

最后那条命令里的 voicemode-mcp-launcher 是个值得一提的设计。从 PyPI 包（voice-mode 8.12.0）的源码能看到，这个启动器是个"聪明"的 stdio 前门：默认不设 VOICEMODE_MCP_URL 环境变量时，它进程内直接启动内置的本地 stdio 服务器，不多开进程、不加代理层；设了这个变量，它就变成一个 stdio 到 Streamable-HTTP 的原生桥，接远端端点。也就是说想把它部署成 HTTP 服务远程访问时，不用换配置文件，一个环境变量切换。

装完用 claude mcp list 验证，列表里出现 voicemode 即接入成功。云服务路线记得配 OPENAI_API_KEY；没有 key 也没关系，先往下看本地服务。

权限：想不被每次询问，就写进 settings

默认情况下 Claude Code 每次调用 VoiceMode 工具都会弹权限确认。语音对话讲的就是流畅，一句一确认体验就碎了。官方 Permissions 文档给的免打扰配置是编辑 ~/.claude/settings.json：

{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse",
      "mcp__voicemode__service"
    ]
  }
}

两条 allow 正对应两个核心工具。只放开这两个是刻意收窄的口子——语音对话和服务管理放行，其他能力照旧走确认。

两个核心工具：converse 与 service

8.12.0 版的 VoiceMode 默认只注册三个工具（converse、pause_conversation、service），这是官方刻意为之——工具越少，占用的上下文越少。仓库源码里 tools/__init__.py 写得明白：默认模式只装载 essentials。要用全量工具（Whisper 模型管理、语音克隆、统计等），设 VOICEMODE_TOOLS_ENABLED 环境变量开白名单。日常对话场景，默认三个足够。

converse 是主角。工具描述原文："Have an ongoing voice conversation - speak a message and optionally listen for response."。在 Claude Code 里输入 converse，听到提示音后说话，说完自动停（静音检测），Claude 处理完用语音回答。参数面很宽，常用的几个： voice 选音色（OpenAI 的 alloy/echo/fable/onyx/nova/shimmer，或 Kokoro 的本地音色）；speed 调语速，0.25 到 4.0；vad_aggressiveness 调静音检测的严格度（0 宽松到 3 严格）；多轮播报可以用 turns 一次排好语音序列。还有个有意思的 skip_tts——只听不说，适合在图书馆里用。

service 管本地语音服务的生命周期，动作覆盖 status/start/stop/restart/enable/disable/logs。在 Claude Code 里说一句"看看 whisper 服务的状态"，它就会去调 service 工具。

下面是这两个工具的真实输出。在一次实际建立的 MCP 会话里（Python 包 8.12.0，streamable-http 传输），tools/list 返回三个工具，service 查询 voicemode 自身状态时如实报出版本与传输方式；查询未安装的 whisper 时也没有报错崩溃，而是返回一条明确的状态说明：

voicemode MCP 端点真实会话：tools/list 与两次 service status 调用的输出

真实端点会话输出：三工具清单 + service 两次 status（Voicemode running / Whisper not available）

顺带一提：源码里 converse 的参数文档写得相当细，比如 pause_after_ms 默认 150 毫秒、多轮序列里每轮可覆盖；wait_for_conch 这组参数是给多 agent 场景排队用的——几个 agent 同时想说话时按先来后到拿"话筒"（官方叫 conch，海螺）。单人使用不用管这组。

本地语音服务：隐私路线的账单

把语音识别和合成全放本地，是 VoiceMode 的一个主打卖点。安装就两条命令：

voicemode service install whisper   # Speech-to-text
voicemode service install kokoro    # Text-to-speech

# Start services
voicemode service start whisper
voicemode service start kokoro

下载体积官方文档给了明账：

服务下载量占用磁盘首次启动
Whisper (tiny)约 75MB约 150MB30 秒
Whisper (base)约 150MB约 300MB1-2 分钟
Whisper (small)约 460MB约 1GB2-3 分钟
Kokoro TTS约 350MB约 700MB2-3 分钟

官方推荐组合是 Whisper base + Kokoro，合计约 500MB 下载、1GB 磁盘。装完建议顺手 voicemode service enable whisper 把开机自启打开（macOS 走 launchd，Linux 走 systemd 用户服务），省得每次手动拉起。首次启动要下模型，官方文档给了两条 wait 循环（端口 2022 等 Whisper、8880 等 Kokoro），照抄即可。

配置层面日常最可能动的两项也能用环境变量解决：VOICEMODE_VOICES 选音色（如 "nova,shimmer" 或本地 "af_sky,am_adam"），语速 VOICEMODE_TTS_SPEED。项目级的差异化配置放项目根的 .voicemode.env，格式就是 export 语句。要系统级排查时 voicemode diag devices 列音频设备、VOICEMODE_SAVE_AUDIO=true 把每次录音存到 ~/.voicemode/audio/ 供回放调试。

四个常见坑（官方 Troubleshooting 表原文意译）

麦克风没声音——先查终端或应用有没有拿到麦克风权限；WSL2 下必须装 pulseaudio 系列包。uv 命令找不到——重跑那条 curl 安装命令。OpenAI 报 API 错——检查 OPENAI_API_KEY 是否设对。没有音频输出——查系统声音设置和可用设备。另外从系统依赖表看，Ubuntu/Debian 用户要先 apt install ffmpeg 加一堆 portaudio/pulseaudio 开发包，macOS 用户 brew install ffmpeg node portaudio。这些依赖没装齐时，服务器启动日志会给出明确提示而不是静默失败——源码里 FFmpeg 检查不通过且非 MCP 模式时直接打印安装指引退出。

动手前值得知道的三件事

其一，它是 MIT 协议的开源项目（作者 Mike Bailey，Failmode 项目成员），免费。其二，云端模式产生的 OpenAI API 用量走你自己的账单，官方文档没有给任何"每月大约多少钱"的估算，重度使用前自己看用量页。其三，默认三个工具的设计意味着上下文占用很小，但想要语音克隆（impressions）、Whisper 模型管理这些进阶能力就得显式开白名单，工具数量上去后 token 占用也随之上升——官方在 tools/__init__.py 的注释里把这层取舍写得很直白。

总的来说，VoiceMode 是个边界清晰的工具：它不试图替代打字，只在你腾不出手的时候补位。安装路径顺滑（尤其 Claude Code 插件路径），本地服务这条路给足了隐私选项，文档和源码注释的诚实度在同类项目里算高的——没装 Whisper 就如实说 not available，而不是含糊其辞。

本文步骤与图片依据 VoiceMode 官方 GitHub 仓库 README、docs 文档（getting-started/configuration/permissions）与 voicemode.dev 官网整理，工具会话输出为 Python 包 8.12.0 真实端点实测，版权归原作者所有。

评论 (0)