使用说明

语音模式

与Claude Code（和其他支持MCP的代理）进行自然语音对话

VoiceMode允许与Claude Code进行自然的语音对话。语音不是要取代打字，而是要在打字不可用时提供帮助。

非常适合：

步行去参加下一次会议
调试时烹饪
在数小时的屏幕时间后让你的眼睛休息一下
拿着咖啡（或狗）
当你的手或眼睛忙碌的时候

实施状态

仓库现在有两个活动的VoiceMode界面：

已建立的MCP/服务器路径以 voicemode chat / voicemode converse
较新的本地/混合运行时以 voicemode voice

当前推出状态：

第一阶段：完成
- 显式状态机
- 取消并替换回合所有权
- 运行时启动器/诊断/控制路径
- 按键通话界面
- mpv支持的可取消播放
第二阶段：完成
- 会话式Silero VAD路径
- 用于确认/摘要/路由提示的本地Ollama语音shell
- 食品法典升级桥梁
- Pipecat适配器表面和依赖路径
第三阶段：完成
- 朗读控件被首尾相连地覆盖，用于继续/重复/跳过/总结/停止
- 弹性硬化包括显式超时/故障恢复到就绪状态
- 诊断程序在中公开SQLite支持的运行时摘要 status 和 diag
- Hammerspoon菜单栏抛光包括更清晰的状态标签和运行时工具提示
- 文档和实时测试现在覆盖了已完成的第3阶段运行时界面

规范运行时文档和审计工件：

在行动中看到它

快速开始

要求： 带麦克风和扬声器的电脑

选项1:克劳德代码插件（推荐）

Claude Code用户入门的最快方法：

# 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

选项2:Python安装包

安装依赖项和VoiceMode Python包。

# 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 voice-mode

# Optional: Add OpenAI API key as fallback for local services
export OPENAI_API_KEY=your-openai-key

# Start a conversation
claude converse

安装程序现在还检查本地运行时Ollama助手模型并提示当配置的模型丢失时，您可以提取它。默认情况下，运行时预期 phi4-mini 除非 VOICEMODE_OLLAMA_MODEL 被覆盖。

选项3：食品法典委员会（建议回购MCP）

当您希望直接在Codex中使用VoiceMode工具而不使用Claude插件时，请使用此功能。

# 1) Install system dependencies (macOS)
brew install ffmpeg node portaudio

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

# 3) Install VoiceMode + local voice service dependencies
uvx voice-mode-install

安装程序在安装过程中检查本地运行时Ollama助手模型。如果配置的模型丢失，它会提示您将其拉取。默认值运行时助手模型是 phi4-mini 除非被覆盖 VOICEMODE_OLLAMA_MODEL.

将此添加到 ~/.codex/config.toml:

[mcp_servers.voicemode]
command = "bash"
args = ["-lc", "mkdir -p /Volumes/Data/_ai/_mcp/mcp-data/voicemode && cd /Volumes/Data/_ai/_mcp/mcp_stuff/voicemode && exec uv run voicemode"]
startup_timeout_sec = 120

[mcp_servers.voicemode.env]
VOICEMODE_DATA_DIR = "/Volumes/Data/_ai/_mcp/mcp-data/voicemode"
VOICEMODE_LOG_DIR = "/Volumes/Data/_ai/_mcp/mcp-data/voicemode/logs"
VOICEMODE_CACHE_DIR = "/Volumes/Data/_ai/_mcp/mcp-working-cache/voicemode/cache"
VOICEMODE_PREFER_LOCAL = "true"
# OPENAI_API_KEY = "your-openai-key"

然后：

# 4) Restart Codex and verify MCP registration
codex mcp list

# 5) Install/start local services (one-time install, then start)
cd /Volumes/Data/_ai/_mcp/mcp_stuff/voicemode
uv run voicemode service install whisper
uv run voicemode service install kokoro
uv run voicemode service start whisper
uv run voicemode service start kokoro

在Codex中，测试工具调用：

mcp__voicemode__service 和 service_name="whisper" 和 action="status"
mcp__voicemode__service 和 service_name="kokoro" 和 action="status"
mcp__voicemode__converse 和 message="VoiceMode test" 和 wait_for_response="true"

如果STT/TTS在macOS上失败，请在以下位置检查终端应用程序的麦克风权限： System Settings -> Privacy & Security -> Microphone

uvx MCP变体（而不是固定回购）：

[mcp_servers.voicemode]
command = "bash"
args = ["-lc", "mkdir -p /Volumes/Data/_ai/_mcp/mcp-data/voicemode && exec uvx --refresh voice-mode"]
startup_timeout_sec = 120

已知问题（首次运行）：

Kokoro可以住在 starting up 在第一次启动时，在准备模型资产时花几分钟时间。
在该窗口期间， mcp__voicemode__converse 可能无法通过TTS，除非 OPENAI_API_KEY 设置为回退。
解决方法：
- 等候 mcp__voicemode__service (service_name="kokoro", action="status")报告跑步。
- 或致电 mcp__voicemode__converse 和 skip_tts="true" 立即测试STT仅流动。

有关手动设置，请参阅入门指南.

稳定的多客户端设置（Codex、Claude Code、本地LLM MCP客户端）

当您从多个MCP客户端运行VoiceMode并希望有一个稳定的运行时/数据布局时，请使用此选项。

使用一个共享数据根：

/Volumes/Data/_ai/_mcp/mcp-data/voicemode

保持主路径与符号链接的兼容性：

mkdir -p /Volumes/Data/_ai/_mcp/mcp-data/voicemode
if [ -d "$HOME/.voicemode" ] && [ ! -L "$HOME/.voicemode" ]; then
  mv "$HOME/.voicemode" "/Volumes/Data/_ai/_mcp/mcp-data/voicemode-home-backup-$(date +%Y%m%d-%H%M%S)"
fi
ln -sfn /Volumes/Data/_ai/_mcp/mcp-data/voicemode "$HOME/.voicemode"

在每个客户端配置中使用显式的env路径：

VOICEMODE_DATA_DIR=/Volumes/Data/_ai/_mcp/mcp-data/voicemode
VOICEMODE_LOG_DIR=/Volumes/Data/_ai/_mcp/mcp-data/voicemode/logs
VOICEMODE_CACHE_DIR=/Volumes/Data/_ai/_mcp/mcp-working-cache/voicemode/cache
VOICEMODE_PREFER_LOCAL=true

在所有地方使用相同的MCP服务器命令：

bash -lc "mkdir -p /Volumes/Data/_ai/_mcp/mcp-data/voicemode && cd /Volumes/Data/_ai/_mcp/mcp_stuff/voicemode && exec uv run voicemode"

选项4：本地/混合语音运行时

当您想要一个带有按键通话功能的专用桌面语音堆栈时，请使用此功能，对话突然闯入，可打断地大声朗读：

voicemode voice run
voicemode voice status
voicemode voice diag
voicemode voice export-hammerspoon

这个运行时现在包括什么：

显式状态转换和事件日志记录
取消和更换行为中的驳船
对讲机和对话模式
可中断标记/大声朗读文本
SQLite支持的会话和事件历史记录
本地Ollama语音外壳平滑和总结
Codex升级以实现更深入的编码/仓库转换
Silero支持对话式VAD，但有退路
Pipecat作为可选适配器依赖项提供

运行时记录在 docs/guides/voice-runtime.md，并在中跟踪实施轨迹 docs/reports/index.md.

对于以任务为导向的示例，如一次性对话、连续对话来回、大声朗读文件、对讲机模式和闯入行为，请参阅这使用表.

Codex/Claude终端使用的最快共享CLI快捷方式：

voicemode chat
voicemode chat --continuous
voicemode read README.md
voicemode mode walk
voicemode mode convo
voicemode stop

Claude代码配置片段：

{
  "mcpServers": {
    "voicemode": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-lc",
        "mkdir -p /Volumes/Data/_ai/_mcp/mcp-data/voicemode && cd /Volumes/Data/_ai/_mcp/mcp_stuff/voicemode && exec uv run voicemode"
      ],
      "env": {
        "VOICEMODE_DATA_DIR": "/Volumes/Data/_ai/_mcp/mcp-data/voicemode",
        "VOICEMODE_LOG_DIR": "/Volumes/Data/_ai/_mcp/mcp-data/voicemode/logs",
        "VOICEMODE_CACHE_DIR": "/Volumes/Data/_ai/_mcp/mcp-working-cache/voicemode/cache",
        "VOICEMODE_PREFER_LOCAL": "true"
      }
    }
  }
}

通用本地LLM MCP客户端代码段（JSON样式）：

{
  "mcpServers": {
    "voicemode": {
      "command": "bash",
      "args": [
        "-lc",
        "mkdir -p /Volumes/Data/_ai/_mcp/mcp-data/voicemode && cd /Volumes/Data/_ai/_mcp/mcp_stuff/voicemode && exec uv run voicemode"
      ],
      "env": {
        "VOICEMODE_DATA_DIR": "/Volumes/Data/_ai/_mcp/mcp-data/voicemode",
        "VOICEMODE_LOG_DIR": "/Volumes/Data/_ai/_mcp/mcp-data/voicemode/logs",
        "VOICEMODE_CACHE_DIR": "/Volumes/Data/_ai/_mcp/mcp-working-cache/voicemode/cache",
        "VOICEMODE_PREFER_LOCAL": "true"
      }
    }
  }
}

操作员偏好捕获（连续会话模式）

如果您希望长时间运行语音会话，而无需手动重新触发每个回合，请将代理保持在重复调用的循环中 converse 和 wait_for_response=true 直到你明确地说 stop voice 或 exit.

示例操作模式：

代理发送一个 converse 打电话给 wait_for_response=true.
用户通过语音进行响应。
代理执行请求的工作。
代理发送下一个 converse 呼叫并再次等待。
循环仅在明确的停止命令下结束。

这避免了在单一 converse 呼叫在一个响应周期后结束。

推荐的本地配置文件值（存储在 VOICEMODE_DATA_DIR/voicemode.env):

VOICEMODE_DISABLE_SILENCE_DETECTION=false
VOICEMODE_DEFAULT_LISTEN_DURATION=300.0
VOICEMODE_VAD_AGGRESSIVENESS=1
VOICEMODE_SILENCE_THRESHOLD_MS=1200

这些值经过调整，以获得更长的用户响应和更少的过早中断。

特性

自然对话 -说话自然，立即听到回应
离线工作 -可选的本地语音服务（Whisper STT、Kokoro TTS）
低延迟 -足够快，感觉像是一场真正的对话
智能静音检测 -当你停止说话时停止录音
隐私选项 -完全在本地运行或使用云服务

MCP能力

VoiceMode公开了以下MCP工具功能：

对话： mcp__voicemode__converse
快捷方式别名： mcp__voicemode__chat, mcp__voicemode__read, mcp__voicemode__mode, mcp__voicemode__stop
服务管理： mcp__voicemode__service
连接状态： mcp__voicemode__connect_status
诊断： mcp__voicemode__python_voicemode_info, mcp__voicemode__check_audio_dependencies
设备/语音： mcp__voicemode__voice_status, mcp__voicemode__check_audio_devices, mcp__voicemode__list_tts_voices
提供商注册表： mcp__voicemode__refresh_provider_registry, mcp__voicemode__get_provider_details, mcp__voicemode__voice_registry
统计数据： mcp__voicemode__voice_statistics, mcp__voicemode__voice_statistics_summary, mcp__voicemode__voice_statistics_recent, mcp__voicemode__voice_statistics_export, mcp__voicemode__voice_statistics_reset
配置管理： mcp__voicemode__show_config_files, mcp__voicemode__list_config_keys, mcp__voicemode__config_reload, mcp__voicemode__update_config
本地服务安装程序： mcp__voicemode__whisper_install, mcp__voicemode__whisper_uninstall, mcp__voicemode__whisper_model_install, mcp__voicemode__kokoro_install, mcp__voicemode__kokoro_uninstall

操作行为：

在可用时使用当地Whisper/Kokoro（默认首选项）。
当本地服务不可用且存在凭据时，可以退回到与OpenAI兼容的云提供商。
支持仅STT验证 skip_tts=true 在TTS预热/故障排除期间。

兼容性

平台： Linux、macOS、Windows（WSL）、NixOS python 3.10-3.14

配置

VoiceMode开箱即用。自定义：

# Set OpenAI API key (if using cloud services)
export OPENAI_API_KEY="your-key"

# Or configure via file
voicemode config edit

看配置指南对于所有选项。

权限设置（可选）

要在没有权限提示的情况下使用VoiceMode，请添加到 ~/.claude/settings.json:

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

看权限指南更多选择。

本地语音服务

为了保护隐私或离线使用，请安装本地语音服务：

Whisper.cpp -本地语音转文本
心 -具有多种语音的本地文本转语音

它们提供与OpenAI相同的API，因此VoiceMode在它们之间无缝切换。

安装细节

System Dependencies by Platform

Ubuntu/Debian

sudo apt update
sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev

WSL2用户：麦克风访问需要上述脉冲音频包。

Fedora/RHEL

sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel

macOS

brew install ffmpeg node portaudio

NixOS 系统

# Use development shell
nix develop github:mbailey/voicemode

# Or install system-wide
nix profile install github:mbailey/voicemode

Alternative Installation Methods

来源

git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .

NixOS系统范围

# In /etc/nixos/configuration.nix
environment.systemPackages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];

故障排除

问题	解决方案
无麦克风访问权限	检查终端/应用程序权限。WSL2需要脉冲音频包。
未找到UV	运行 `curl -LsSf https://astral.sh/uv/install.sh \| sh`
OpenAI API错误	验证 `OPENAI_API_KEY` 设置正确
无音频输出	检查系统音频设置和可用设备
`service status voicemode` 显示“不可用”，但Whisper/Kokoro已打开	检查 `~/.voicemode/logs/serve/serve.err.log`；如果它说 `exec: voicemode: not found`，修复启动路径（如下）。

启动代理PATH修复程序（macOS）

如果 com.voicemode.serve 发射代理崩溃循环 exec: voicemode: not found，申请：

mkdir -p "$HOME/.local/bin"
ln -sfn /Volumes/Data/_ai/_mcp/mcp_stuff/voicemode/.venv/bin/voicemode "$HOME/.local/bin/voicemode"

SCRIPT="$HOME/.voicemode/services/voicemode/bin/start-voicemode-serve.sh"
sed -i '' 's#exec voicemode serve#exec /Volumes/Data/_ai/_mcp/mcp_stuff/voicemode/.venv/bin/voicemode serve#' "$SCRIPT"

launchctl bootout gui/$(id -u) "$HOME/Library/LaunchAgents/com.voicemode.serve.plist" 2>/dev/null || true
launchctl bootstrap gui/$(id -u) "$HOME/Library/LaunchAgents/com.voicemode.serve.plist"

验证：

uv run voicemode service status voicemode
lsof -nP -iTCP:8765 -sTCP:LISTEN

保存音频以进行调试

export VOICEMODE_SAVE_AUDIO=true
# Files saved to /Volumes/Data/_ai/_mcp/mcp-data/voicemode/audio/YYYY/MM/

文档

入门指南 -完整设置指南
配置 -所有环境变量
Whisper设置 -本地语音转文本
Kokoro设置 -本地文本转语音
Codex语音预填充规范 -起草语音合成流程的预填充UX实施计划
开发设置 -贡献指南

完整文档： voice-mode.readdocs.io

链接

网站: getvoicemode.com
GitHub: github/mbailey/voicemode
PyPI: pypi.org/project/voice-mode
油管: @getvoicemode
推特/X: @getvoicemode
通讯:

许可证

麻省理工学院-A 文件模式项目

mcp名称：com.failmode/voicemode

本地定制跟踪

在外部数据根下跟踪本地机器特定的集成、客户端接线和操作状态。
本地元数据路径： /Volumes/Data/_ai/_mcp/mcp-data/<name>/meta
回购方能力合同已签订 docs/local-capability/.
秘密永远不会存储在repo文档中；只记录了变量名和加载位置。

外部化.vev

回购路径“.venv”是指向“/Volumes/Data/_ai/_mcp/mcp工作缓存/voicemode/.venv”下规范缓存位置的符号链接，用于减少回购本地可变环境状态。

本地增强功能捕获（2026-03-13）

为GitHub发布捕获了当前的本地更改、配置更新和操作增强。
包括在适用的情况下与子回购链接更新同步。
交叉引用此存储库中添加的本地文档和功能说明。