voicemode

首次设置

如果 VoiceMode 无法正常工作，或 MCP 连接失败，请运行：

/voicemode:install

安装后，重新连接 MCP：/mcp → 选择 voicemode → “Reconnect”（或重启 Claude Code）。

如果 Claude Code 就 voicemode:converse 或 voicemode:service 向你请求权限，请参阅 references/permissions.md，了解一次性允许列表设置。

---

VoiceMode

使用语音转文本（STT）和文本转语音（TTS），与 Claude Code 进行自然的语音对话。

注意： Python 包名为 voice-mode（带连字符），但 CLI 命令为 voicemode（不带连字符）。

何时使用 MCP 与 CLI

任务	使用	原因
语音对话	MCP voicemode:converse	更快——服务已在运行
启动/停止服务	MCP voicemode:service	可在 Claude Code 中使用
安装	CLI voice-mode-install	一次性设置
配置	CLI voicemode config	直接编辑设置
诊断	CLI voicemode diag	管理任务

用法

使用 converse MCP 工具与用户交谈并听取他们的回复：

# Speak and listen for response (most common usage)
voicemode:converse("Hello! What would you like to work on?")

# Speak without waiting (for narration while working)
voicemode:converse("Searching the codebase now...", wait_for_response=False)

对于大多数对话，只需传入你的消息即可——默认设置会处理其他所有事项。 除非有充分理由，否则请使用 converse 工具的默认参数。时间参数（listen_duration_max、listen_duration_min）会使用带静音检测的智能默认值——除非用户提出要求或你发现明确的必要性，否则不要覆盖。用户可以通过 ~/.voicemode/voicemode.env 配置默认值。

参数	默认值	说明
message	必填	要朗读的文本
wait_for_response	true	朗读后进行监听
voice	auto	TTS 语音——必须使用小写（例如 af_river，而非 AF_River）

语音名称规则： 如果指定 voice，必须使用小写并以 下划线分隔。Kokoro 会拒绝 AF_River 这类包含大写字母的名称，并返回 400 错误。有效示例：af_river、af_sky、bm_daniel、bf_emma。 前缀表示语言和性别：af_ = 美式英语女性，am_ = 美式英语男性，bf_ = 英式英语女性，bm_ = 英式英语男性。

如果不确定，请完全省略 voice——自动选择会挑选一个可用的 默认值。

应用和 Agent 的语音发现： 读取 voice://voices MCP 资源，获取可用语音的结构化 JSON 列表（使用 voice://voices/{provider} 按后端筛选）。voice_registry 工具会在 对话过程中向大模型返回相同的数据，以自然语言呈现。两者共用底层枚举器，因此数据始终保持一致。请参阅语音资源参考。

角色设定发现： voice://voices 中的语音 ID 对应磁盘上的角色档案，路径为 ~/.voicemode/voices/<name>/README.md（分组语音：<group>/<name>/README.md；索引位于 ~/.voicemode/voices/PERSONAS.md）。以角色身份发言前，请先阅读对应的 README，了解角色身份、说话方式和示例台词。目前并非每种语音都有角色档案；若没有，请直接使用语音本身。

所有参数请参阅 Converse Parameters。

最佳实践

1. 不必等待，直接讲述 - 宣布操作时使用 wait_for_response=False
2. 一次只问一个问题 - 不要在同一轮语音中打包多个问题。例外是问卷（turns 参数）：它会在一次调用中提出多个问题，但仍会逐轮进行，每轮结束后倾听——详见问卷（多轮提问）。
3. 先检查状态 - 开始对话前，确认服务正在运行
4. 让 VoiceMode 自动选择 - 除非用户有偏好，否则不要硬编码提供方
5. 首次运行较慢 - 模型会在首次启动时下载（2-5 分钟），之后即可即时运行

问卷（多轮提问）

converse 的 turns 参数会运行一份问卷：在一次调用中提出多个问题， 逐轮进行（说话、倾听、记录、继续），并以流水线方式处理，因此第 N+1 轮会在第 N 轮播放时进行合成——不会出现合成等待空档。 这是“一次只问一个问题”的特许例外：你仍然是在每个语音轮次中只问一个问题，只是预先编排了整个问题序列。

由于问卷会自动进入下一个预设问题，不会根据每个回答作出反应，用户无法通过其他方式判断自己是否被听见，或只是脚本继续执行了。要让多轮流程清晰易懂：

1. 一开始就说明问题数量。 用一个开头的 say 轮次来启动问卷， 说明接下来有几个问题——例如 “我有 3 个简短问题。” 这表明正在进行多轮问卷。
2. 在下一次调用的开头确认回答。 在问卷过程中无法流水线处理基于内容的确认（例如“知道了——鸡肉、每周两次、没有过敏”），否则会重新引入等待空档，因此确认应放在下一次 converse 调用的开头，再继续后续操作。复述收集到的回答，让用户知道你已收到。
3. 保持简短。 每份问卷的提问轮次不超过约 7 轮；为每个问题设置合理的 listen_duration_max（普通问题为 30–45 秒）。

Voicemode 回声（默认开启）

一些宿主（例如较新的 Claude Code）会合并 MCP 工具调用——语音轮次会从可见转录中消失。除非另有要求，否则默认启用 voicemode 回声： 将每次 voicemode:converse 交互打印为 Markdown 引用块，使其在屏幕上清晰可读。

> **ASSISTANT (voicemode):** <message arg passed to converse>
[voicemode:converse tool call]
> **USER (voicemode):** <captured user message>

• 说话者名称置于开头并使用大写；(voicemode) 是频道标签。
• 顺序很重要。 在发出 voicemode:converse 工具调用的同一条响应中，先写 ASSISTANT 引用块，再调用工具——这样用户可以在音频播放时同步阅读（如果漏听部分内容，也能查看文字）。工具返回结果后，在你的下一条响应中写 USER 引用块。不要等调用完成后再一起输出两段回声。
• ASSISTANT 回声：始终输出，包括 wait_for_response=false（仅语音讲述也会生成可见内容，否则这些内容会消失）。
• USER 回声：仅当捕获到用户消息时输出（wait_for_response=false、结果为空或转录失败时跳过——没有内容可供回声）。
• 助手回声：默认逐字输出——使用传递给 message 的确切字符串，不要改写或重新格式化。原因：这最符合读者预期，也便于对照打印文本与语音内容进行诊断。
• 视觉辅助内容（列表、表格、代码）应放在引用块之后，而不是放在其中。 引用块应保持为所说内容的干净逐字副本；更丰富的格式可以作为单独的正文内容跟在后面。
• 不要重复回声：如果某句话已作为可见正文出现在同一条响应中，就不要再用引用块重复输出。
• 按要求停用——标准短语：“disable voicemode echo”。收到后，在本次会话剩余时间内停止输出回声；如果用户的启动上下文中出现相同短语，也应遵守（某些宿主已在行内显示语音工具调用，此时回声会造成重复）。

并行调用工具（零冷场）

在同一条回复中同时发送语音和操作调用，消除冷场：

# FAST: speak + act in parallel (all fire concurrently)
voicemode:converse("Checking that now.", wait_for_response=False)
Bash("git status")
Agent(prompt="Research X", run_in_background=True)

# SLOW: sequential — unnecessary delay between speech and action
voicemode:converse("Checking that now.", wait_for_response=False)
# ... waits for TTS to finish ...
Bash("git status")

然后在下一条回复中报告结果：

voicemode:converse("Here's what I found: ...", wait_for_response=True)

场景	方式	原因
宣布 + 执行工作	并行	语音与操作之间没有依赖关系
宣布 + 启动 Agent	并行	Agent 无论如何都会在后台运行
检查结果后再报告	顺序	需要先获得结果才能发言
等待回复	顺序	wait_for_response=True 会阻塞，直到用户发言

关键要点： 墙上时钟时间 = 最长调用的耗时，而不是各调用耗时之和。所有工具类型（MCP、Bash、Agent、Read）都可以在同一条回复中混用。

处理暂停和等待请求

当用户要求你等待或给他们一些时间时：

短暂停（最长 60 秒）： 如果用户说的话以“wait”结尾（例如“hang on”“give me a sec”“wait”），VoiceMode 会自动暂停 60 秒，然后恢复监听。这是内置功能。

较长暂停（2 分钟以上）： 使用 bash sleep N，其中 N 是秒数。例如，如果用户说“给我 5 分钟”：

sleep 300  # Wait 5 minutes

等待结束后，再次调用 converse：

voicemode:converse("Five minutes is up. Ready when you are.")

配置： 可通过 VOICEMODE_WAIT_DURATION 配置短暂停时长（默认值：60 秒）。

传输控制（媒体键和 Stream Deck）

converse 运行期间，VoiceMode 会公开一个控制通道——使用 voicemode control pause | resume | stop | skip-forward | skip-back 控制它。你可以将 这些命令连接到实体按钮，让用户无需输入即可暂停、插话或重播：

• Stream Deck（或任何能运行 shell 命令的工具）：将按钮直接绑定到 voicemode control skip-forward 等命令。无需额外依赖——它会直接通过 shell 调用 CLI。
• macOS 媒体键（▶❙❙ / ⏭ / ⏮）：通过 Hammerspoon eventtap （scripts/hammerspoon/voicemode-media-keys.lua）进行路由；它只会在 converse 运行期间捕获按键，因此其他时候不会影响音乐。

启用方法：

1. 在 ~/.voicemode/voicemode.env 中设置 VOICEMODE_CONTROL_CHANNEL_ENABLED=true （服务端会为本轮 converse 绑定 ~/.voicemode/control.sock）。
2. 对于媒体键：安装 Hammerspoon，从 ~/.hammerspoon/init.lua 加载配置， 授予辅助功能权限，并保持 Hammerspoon 运行——将其设为登录项。 eventtap 只有在 Hammerspoon 运行时才会存在；如果它没有运行，按键会静默传递给 Music/Spotify，VoiceMode 不会收到按键（不会报错—— 只是没有效果）。Stream Deck 正常工作但媒体键没反应 = Hammerspoon 没有运行。快速检查：pgrep -x Hammerspoon。

要为用户设置此功能？ 使用 媒体键 Agent 操作手册——其中提供了逐步操作流程， 帮助助手完成端到端设置，并标明了需要用户处理的唯一一步 （授予辅助功能权限）。

完整参考（所有权模型、向后跳转历史缓冲区、原始套接字协议）： docs/reference/control-channel.md。

STT 故障恢复——手动转录

如果 Whisper STT 失败，但音频已成功录制，你可以手动转录保存的音频文件：

# Transcribe the most recent recording
whisper-cli ~/.voicemode/audio/latest-STT.wav

# Or check if file exists first (safe for inclusion in automation)
if [ -f ~/.voicemode/audio/latest-STT.wav ]; then
  whisper-cli ~/.voicemode/audio/latest-STT.wav
fi

要求：

• 必须通过以下任一方式启用音频保存：
  • 在 ~/.voicemode/voicemode.env 中设置 VOICEMODE_SAVE_AUDIO=true
  • 设置 VOICEMODE_SAVE_ALL=true（保存所有音频和转录内容）
  • 设置 VOICEMODE_DEBUG=true（启用调试模式并保存音频）

工作原理：

• VoiceMode 会将所有 STT 录音保存到 ~/.voicemode/audio/，并附带时间戳
• 符号链接 latest-STT.wav 始终指向最新录音
• 如果 STT API 调用失败，录音仍会保存，以便手动恢复
• 这样，你无需让用户重复发言即可恢复其语音内容

适用情况：

• STT 服务超时或连接失败
• 转录结果为空，但用户确定说过话
• 需要核实用户实际说了什么，与转录内容是否一致

另请参阅：故障排查 - 未检测到语音

检查状态

voicemode service status          # All services
voicemode service status whisper  # Specific service

显示服务状态，包括运行状态、端口和健康状况。

会话中途断开后的重新连接

如果语音在会话中途断开（-32000 Connection closed），或者服务器在启动时未能注册其工具，voicemode MCP 工具就会消失，因此无法通过 MCP 工具恢复。Bash 和 tmux 仍可使用，所以可以通过一次 Bash 调用修复：

voicemode reconnect

此命令会在你自己的窗格（$TMUX_PANE）中执行完整的 /mcp 重新连接流程：打开菜单，按名称（而非依赖不可靠的 Down 按键次数）查找 voicemode 服务，读取光标位置并导航到该服务，仅在服务已失败时点击重新连接，然后轮询直至连接成功，最后输出用于重新加载对话模式架构的准确 ToolSearch 命令。若屏幕内容与预期不符，它会明确报错，而不会盲目发送按键。必须在 tmux 中运行（它会通过 tmux 操作窗格）。

在输出 RESULT: reconnected 后，运行它回显的 ToolSearch select:… 命令来重新加载工具架构，然后继续对话。

RESULT: reconnected            # exit 0  — was failed, now reconnected
RESULT: already-connected      # exit 10 — nothing to do (benign no-op)
                               # 11 not-found · 12 timeout · 13 not-in-tmux · 1 error

实用标志：--pane <id>（操作其他窗格）、--server <substr>（默认值为 voicemode）、--timeout <s>（默认值为 75）、--dry-run（仅报告，不发送按键）。

备用方案——手动操作 /mcp（适用于较旧版本的 Claude Code，或在不熟悉的菜单中 voicemode reconnect 明确报错时）：分步手动操作指南位于 ~/.slipbox/voice-self-reconnect.md——打开 /mcp，使用 capture-pane 读取列表，导航到 voicemode，点击重新连接，等待约 1 分钟，然后重新加载架构。

安装

# Install VoiceMode CLI and configure services
uvx voice-mode-install --yes

# Install local services (Apple Silicon recommended)
voicemode service install whisper
voicemode service install kokoro

详细步骤请参阅入门指南。

服务管理

# Start/stop services
voicemode:service("whisper", "start")
voicemode:service("kokoro", "start")

# View logs for troubleshooting
voicemode:service("whisper", "logs", lines=50)

服务	端口	用途
whisper	2022	语音转文本
kokoro	8880	文本转语音
voicemode	8765	HTTP/SSE 服务

**操作：**状态、启动、停止、重启、日志、启用、禁用

配置

voicemode config list                           # Show all settings
voicemode config set VOICEMODE_TTS_VOICE nova   # Set default voice
voicemode config edit                           # Edit config file

配置文件：~/.voicemode/voicemode.env

所有选项请参阅配置指南。

DJ 模式

在 VoiceMode 会话期间播放背景音乐，并可控制单首曲目。

# Core playback
voicemode dj play /path/to/music.mp3  # Play a file or URL
voicemode dj status                    # What's playing
voicemode dj pause                     # Pause playback
voicemode dj resume                    # Resume playback
voicemode dj stop                      # Stop playback

# Navigation and volume
voicemode dj next                      # Skip to next chapter
voicemode dj prev                      # Go to previous chapter
voicemode dj volume 30                 # Set volume to 30%

# Music For Programming
voicemode dj mfp list                  # List available episodes
voicemode dj mfp play 49               # Play episode 49
voicemode dj mfp sync                  # Convert CUE files to chapters

# Music library
voicemode dj find "daft punk"          # Search library
voicemode dj library scan              # Index ~/Audio/music
voicemode dj library stats             # Show library info

# Play history and favorites
voicemode dj history                   # Show recent plays
voicemode dj favorite                  # Toggle favorite on current track

**配置：**在 ~/.voicemode/voicemode.env 中设置 VOICEMODE_DJ_VOLUME，以自定义启动音量（默认值：50%）。

CLI 速查表

# Service management
voicemode service status            # All services
voicemode service start whisper     # Start a service
voicemode service logs kokoro       # View logs

# Diagnostics
voicemode deps                      # Check dependencies
voicemode diag info                 # System info
voicemode diag devices              # Audio devices

# DJ Mode
voicemode dj play <file|url>        # Start playback
voicemode dj status                 # What's playing
voicemode dj next/prev              # Navigate chapters
voicemode dj stop                   # Stop playback
voicemode dj mfp play 49            # Music For Programming

Agent 之间的语音交接

在 Claude Code Agent 之间转移语音对话，以支持多 Agent 工作流。

适用场景：

• 个人助手将任务转交给特定项目的工头
• 工头将任务分派给工人，以专注处理特定任务
• 工作完成后交还控制权

快速参考

# 1. Announce the transfer
voicemode:converse("Transferring you to a project agent.", wait_for_response=False)

# 2. Spawn with voice instructions (mechanism depends on your setup)
spawn_agent(path="/path", prompt="Load voicemode skill, use converse to greet user")

# 3. Go quiet - let new agent take over

交还控制权：

voicemode:converse("Transferring you back to the assistant.", wait_for_response=False)
# Stop conversing, exit or go idle

核心原则

1. **宣布转交：**转交前务必告知用户
2. **单一发言者：**同一时间只能有一个 Agent 使用 converse
3. **区分语音：**使用不同语音，让交接过程能被听出来
4. **提供上下文：**告知接收方转交用户的原因

说话时自动聚焦 tmux 面板（可选）

在不同的 tmux 面板中运行多个语音 Agent 时，设置 VOICEMODE_AUTO_FOCUS_PANE=true，即可让 tmux 跟随说话者切换焦点。焦点会在获取通话权后切换，因此等待通话权的 Agent 不会抢占焦点——只有即将说话的 Agent 才会切换焦点。它还会遵循 show-me 插件写入的 ~/.voicemode/focus-hold 哨兵文件，因此刚打开的文件会在保持窗口期内留在屏幕上。

# ~/.voicemode/voicemode.env
VOICEMODE_AUTO_FOCUS_PANE=true

默认关闭。在 tmux 外部静默无操作。

详细文档

请参阅通话路由，了解完整指南：

• 交接模式 - 完整的交接和交还流程
• 语音代理 - 为没有语音功能的 Agent 提供中继模式
• 通话路由概览 - 所有路由模式

通过 Tailscale 共享语音服务

通过 HTTPS 将本地 Whisper（STT）和 Kokoro（TTS）提供给 Tailnet 上的其他设备。

原因

• 浏览器需要 HTTPS 才能访问麦克风（例如，VoiceMode Connect Web 应用）
• Tailscale serve 为 *.ts.net 域名自动提供有效的 Let's Encrypt 证书
• 可通过 Tailnet 上的任何设备使用本地高性能机器的 GPU

设置

# Expose TTS (Kokoro on port 8880)
tailscale serve --bg --set-path /v1/audio/speech http://localhost:8880/v1/audio/speech

# Expose STT (Whisper on port 2022)
tailscale serve --bg --set-path /v1/audio/transcriptions http://localhost:2022/v1/audio/transcriptions

# Verify configuration
tailscale serve status

# Reset all serve config
tailscale serve reset

端点

设置完成后，可通过以下端点访问：

• TTS： https://<hostname>.<tailnet>.ts.net/v1/audio/speech
• STT： https://<hostname>.<tailnet>.ts.net/v1/audio/transcriptions

重要说明

• 路径映射： Tailscale 会在转发前移除传入路径，因此目标 URL 中必须包含完整路径
• 同机测试： 本地流量不会经由 Tailscale 路由——请从 Tailnet 上的另一台设备进行测试
• 多个路径： 你可以将不同路径配置到同一台或不同机器上的不同后端
• CORS： Kokoro 已配置 CORS，允许来自 https://app.voicemode.dev 的源

搭配 VoiceMode Connect 使用

在 VoiceMode Connect Web 应用的设置中（app.voicemode.dev/settings），设置：

• TTS 端点： https://<hostname>.<tailnet>.ts.net
• STT 端点： https://<hostname>.<tailnet>.ts.net

音效字体

Claude Code 使用工具时播放的音频反馈音。使用 voicemode soundfonts on/off 切换。请参阅音效字体指南。

通过 VoiceMode Connect 使用远程语音

当无法使用本地语音时——机器没有麦克风或扬声器、无法安装本地服务，或想使用手机——VoiceMode Connect 可通过 Web 应用或移动设备提供远程语音。

适合推荐 Connect 的情况：

• 用户无法在本地安装 Whisper/Kokoro（平台不受支持、权限受限或使用公司设备）
• 用户想通过手机或平板与 Agent 对话
• 用户使用没有音频硬件的远程/无头机器
• 本地语音服务出故障，且快速排查仍无法解决

工作原理： 将 VoiceMode MCP 服务添加到任意 Claude 产品，在手机或浏览器中打开 app.voicemode.dev，然后开始对话。无需在本地安装 TTS/STT——音频由客户端设备处理。

设置： 请参阅 VoiceMode Connect 技能，了解 MCP 配置和入门说明。

文档索引

主题	链接
对话参数	所有参数
安装	入门指南
配置	配置指南
Claude Code 插件	插件指南
Whisper 语音转文本	Whisper 设置
Kokoro 文本转语音	Kokoro 设置
macOS 媒体键	媒体键指南
发音	发音指南
故障排除	故障排除
音色库	音色库指南
CLI 参考	CLI 文档
DJ 模式	背景音乐

相关技能

• VoiceMode Connect - 通过移动端／网页客户端进行远程语音交互（无需本地语音转文本／文本转语音）
• Impressions - 通过本地 mlx-audio 添加自定义语音（仅限 Apple Silicon，目前为预览版）。当用户想要使用 voice="<name>" 指定基于音频片段的自定义语音，而不是 Kokoro 语音时使用。