VoiceMode

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

VoiceMode 让你能够与 Claude Code 进行自然的语音对话。语音并不是要取代打字——它是在无法打字时依然可以使用的工具。

非常适合：

• 去往下一个会议的路上
• 烹饪时调试代码
• 在长时间盯着屏幕后让眼睛休息一下
• 手里拿着咖啡（或抱着狗狗）
• 任何双手或眼睛被占用的时刻

实际演示

快速开始

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

方法 1：Claude Code 插件（推荐）

对于 Claude Code 用户来说，这是最快速的入门方式：

# 添加 VoiceMode 市场
claude plugin marketplace add mbailey/voicemode

# 安装 VoiceMode 插件
claude plugin install voicemode@voicemode

## 安装依赖项（CLI、本地语音服务）

/voicemode:install

# 开始对话！
/voicemode:converse

方法 2：Python 安装包

安装依赖项和 VoiceMode Python 包。

# 安装 UV 包管理器（如果需要）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 运行安装程序（设置依赖项和本地语音服务）
uvx voice-mode-install

# 添加到 Claude Code
claude mcp add --scope user voicemode -- uvx --refresh voice-mode

# 可选：添加 OpenAI API 密钥作为本地服务的备用
export OPENAI_API_KEY=your-openai-key

# 开始对话
claude converse

如需手动设置，请参阅 入门指南。

功能

• 自然对话——自然地说话，立即听到回应
• 离线可用——可选本地语音服务（Whisper STT、Kokoro TTS）
• 低延迟——速度快，感觉就像真实的对话
• 智能静音检测——当你停止说话时会自动停止录音
• 隐私选项——完全在本地运行，或使用云服务

兼容性

平台： Linux、macOS、Windows（WSL）、NixOS
Python： 3.10–3.14

配置

VoiceMode 无需额外配置即可使用。如需自定义：

# 设置 OpenAI API 密钥（如果使用云服务）
export OPENAI_API_KEY="your-key"

# 或通过文件进行配置
voicemode config edit

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

权限设置（可选）

若希望在不出现权限提示的情况下使用 VoiceMode，可在 ~/.claude/settings.json 中添加以下内容：

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

更多选项请参阅 权限指南。

本地语音服务

为保护隐私或在离线状态下使用，可安装本地语音服务：

• Whisper.cpp——本地语音转文本
• Kokoro——本地文本转语音，支持多种声音

这些服务提供与 OpenAI 相同的 API，因此 VoiceMode 可以无缝切换它们之间。

安装详情

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

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

brew install ffmpeg node portaudio

# 使用开发环境
nix develop github:mbailey/voicemode

# 或者系统级安装
nix profile install github:mbailey/voicemode

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

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

故障排除

保存音频用于调试

export VOICEMODE_SAVE_AUDIO=true
# 文件将保存到 ~/.voicemode/audio/YYYY/MM/

文档

• 入门指南——完整安装指南
• 配置——所有环境变量
• Whisper 设置——本地语音转文本
• Kokoro 设置——本地文本转语音
• 开发设置——贡献指南

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

链接

• 官网：getvoicemode.com
• GitHub：github.com/mbailey/voicemode
• PyPI：pypi.org/project/voice-mode
• YouTube：@getvoicemode
• Twitter/X：@getvoicemode
• 邮件列表：

许可证

MIT——Failmode 项目

mcp-name: com.failmode/voicemode

VoiceMode 快速上手指南

VoiceMode 是一款支持自然语音对话的 AI 工具，专为 Claude Code 及其他支持 MCP 协议的智能体设计。它让你在手忙眼累时（如走路、做饭、调试代码）也能通过语音与 AI 流畅交互。

环境准备

系统要求：

• 操作系统：Linux、macOS、Windows (WSL2)、NixOS
• Python 版本：3.10 - 3.14
• 硬件设备：需配备麦克风和扬声器

前置依赖（按平台安装）：

在安装主程序前，请先安装系统级依赖：

• Ubuntu/Debian (含 WSL2)

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

  注意：WSL2 用户必须安装 pulseaudio 相关包以获取麦克风权限。

• Fedora/RHEL

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

• macOS

  brew install ffmpeg node portaudio
  

• NixOS 可直接使用开发环境或全局安装：

  nix develop github:mbailey/voicemode
  # 或
  nix profile install github:mbailey/voicemode
  

安装步骤

推荐以下两种安装方式，任选其一即可。

方式一：作为 Claude Code 插件安装（推荐）

这是最快捷的启动方式，适合已在使用 Claude Code 的用户。

1. 添加插件市场并安装：

   claude plugin marketplace add mbailey/voicemode
   claude plugin install voicemode@voicemode
   

2. 在 Claude 会话中初始化依赖： 进入 Claude Code 后，运行以下命令安装本地语音服务依赖：

   /voicemode:install
   

方式二：使用 Python 安装包

此方式会安装 UV 包管理器、VoiceMode 核心包及本地语音服务。

1. 安装 UV 包管理器（如未安装）：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. 运行安装脚本：

   uvx voice-mode-install
   

3. 注册到 Claude Code：

   claude mcp add --scope user voicemode -- uvx --refresh voice-mode
   

4. 配置 API Key（可选）： 若不使用纯本地离线模式，需配置 OpenAI API Key 作为云端服务后备：

   export OPENAI_API_KEY=your-openai-key
   

基本使用

安装完成后，即可开始语音对话。

启动对话：

• 如果你使用的是插件模式（方式一）： 在 Claude Code 终端中输入：

  /voicemode:converse
  

• 如果你使用的是独立安装模式（方式二）： 直接在终端运行：

  claude converse
  

使用提示：

• 说话结束后，智能静音检测会自动停止录音并发送请求。
• 如需完全离线运行（保护隐私），请参考文档配置本地 Whisper (STT) 和 Kokoro (TTS) 服务。
• 可通过 voicemode config edit 自定义配置项。