Voice Mode

VoiceMode

使用 Claude Code（以及其他支持 MCP 的 Agent）进行自然语音对话

VoiceMode 支持与 Claude Code 进行自然语音对话。语音并非为了取代打字，而是在无法打字时也能随时使用。

适合以下场景：

• 走去参加下一个会议
• 一边做饭一边调试
• 长时间盯着屏幕后让眼睛休息
• 手里拿着咖啡（或抱着狗）
• 双手或双眼正忙碌的任何时刻

实际演示

快速开始

**要求：**配备麦克风和扬声器的计算机

选项 1：Claude Code 插件（推荐）

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 --from voice-mode voicemode-mcp-launcher

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

# Start a conversation
claude converse

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

功能

• 自然对话 - 自然地说话，即时听到回复
• 支持离线使用 - 可选本地语音服务（Whisper STT、Kokoro 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 - 本地语音转文本
• 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

# Use development shell
nix develop github:mbailey/voicemode

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

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

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

故障排除

保存音频以便调试

export VOICEMODE_SAVE_AUDIO=true
# Files saved to ~/.voicemode/audio/YYYY/MM/

文档

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

完整文档：voicemode.dev

Links

• Website: voicemode.dev
• GitHub: github.com/mbailey/voicemode
• PyPI: pypi.org/project/voice-mode
• YouTube: @getvoicemode
• Twitter/X: @getvoicemode
• Newsletter:

License

MIT - A Failmode Project

mcp-name: dev.voicemode/voicemode