项目介绍
VoiceMode
安装方式:
uv tool install voice-mode| getvoicemode.com
通过模型上下文协议（MCP），VoiceMode为Claude Code等AI代码编辑器带来了类似人类的语音交互。
🖥️ 兼容性
运行于: Linux • macOS • Windows (WSL) • NixOS | Python: 3.10-3.14
✨ 特性
- 🎙️ 自然语音对话与Claude Code - 提问并听到回答
- 🗣️ 支持本地语音模型 - 适用于任何兼容OpenAI API的STT/TTS服务
- ⚡ 实时 - 低延迟语音交互，自动选择传输方式
- 🔧 MCP集成 - 无缝集成到Claude Code（及其他MCP客户端）
- 🎯 静音检测 - 当您停止说话时自动停止录音（无需等待！）
- 🔄 多种传输方式 - 本地麦克风或基于LiveKit房间的通信（可选）
🎯 简单需求
开始所需：
- 🎤 带有麦克风和扬声器的计算机
- 🔑 OpenAI API密钥（推荐，作为本地服务的备用方案）
快速入门
使用UV安装VoiceMode及依赖项（推荐）
- Linux (fedora, debian/ubuntu)
- macOS
- Windows WSL
# 安装VoiceMode MCP Python包及其依赖项
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx voice-mode-install
# 虽然本地语音服务可以自动安装，但我们建议提供一个OpenAI API密钥作为备用方案
export OPENAI_API_KEY=your-openai-key # 可选但推荐
# 将VoiceMode添加到Claude
claude mcp add --scope user voicemode -- uvx --refresh voice-mode
# 开始语音对话
claude converse
手动安装
对于手动设置步骤，请参阅入门指南。
🎬 演示
观看VoiceMode在Claude Code中的实际操作：
converse函数使语音交互自然化 - 默认情况下它会自动等待您的回应，创建真实的对话流程。
安装
预备条件
- Python 3.10-3.14
- Astral UV - 包管理器（使用
curl -LsSf https://astral.sh/uv/install.sh | sh安装） - OpenAI API密钥（或兼容的服务）
关于LiveKit的注意事项: LiveKit集成是可选的，并且需要Python 3.10-3.13（Python 3.14的支持取决于上游依赖）。使用
uv tool install voice-mode[livekit]进行安装。详情请参阅LiveKit集成指南。
系统依赖项
<details> <summary><strong>Ubuntu/Debian</strong></summary>sudo apt update
sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev
针对WSL2用户: WSL2需要额外的音频包（pulseaudio, libasound2-plugins）以访问麦克风。
</details> <details> <summary><strong>Fedora/RHEL</strong></summary>sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
# 如果尚未安装Homebrew，请先安装
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装依赖项
brew install ffmpeg node portaudio
按照上述Ubuntu/Debian指令在WSL中执行。
</details> <details> <summary><strong>NixOS</strong></summary>VoiceMode包含了一个带有所有必需依赖项的flake.nix。您可以：
- 使用开发shell（临时）：
nix develop github:mbailey/voicemode
- 系统范围安装（请参阅下面的安装部分）
快速安装
# 使用Claude Code（推荐）
claude mcp add --scope user voicemode uvx --refresh voice-mode
AI编码助手配置
📖 需要详细的设置说明吗？ 查看我们全面的入门指南，获取逐步说明！
以下是快速配置片段。完整的安装和设置说明，请参阅上面的集成指南。
<details> <summary><strong>Claude Code (CLI)</strong></summary>claude mcp add --scope user voicemode -- uvx --refresh voice-mode
或者使用环境变量：
claude mcp add --scope user --env OPENAI_API_KEY=your-openai-key voicemode -- uvx --refresh voice-mode
替代安装选项
<details> <summary><strong>从源码安装</strong></summary>git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .
1. 使用nix profile安装（用户范围）:
nix profile install github:mbailey/voicemode
2. 添加到NixOS配置（系统范围）:
# 在/etc/nixos/configuration.nix中
environment.systemPackages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
3. 添加到home-manager:
# 在home-manager配置中
home.packages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
4. 不安装运行:
nix run github:mbailey/voicemode
配置
快速设置
唯一需要的配置是您的OpenAI API密钥：
export OPENAI_API_KEY="your-key"
本地STT/TTS服务
为了隐私或离线使用，VoiceMode支持本地语音服务：
- Whisper.cpp - 具有OpenAI兼容API的本地语音转文本
- Kokoro - 具有多语音选项的本地文本转语音
这些服务提供了与OpenAI相同的API接口，允许在云处理和本地处理之间无缝切换。
故障排除
常见问题
- 无法访问麦克风: 检查终端/应用程序的系统权限
- WSL2 用户: 需要额外的音频包（pulseaudio, libasound2-plugins）以访问麦克风
- 未找到UV: 使用
curl -LsSf https://astral.sh/uv/install.sh | sh进行安装 - OpenAI API错误: 验证您的
OPENAI_API_KEY是否正确设置 - 无音频输出: 检查系统音频设置和可用设备
音频保存
要保存所有音频文件（包括TTS输出和STT输入）：
export VOICEMODE_SAVE_AUDIO=true
音频文件保存在：~/.voicemode/audio/YYYY/MM/，文件名中包含时间戳。
文档
📚 阅读完整的文档
入门
开发
- 开发设置 - 本地开发指南
服务指南
- Whisper.cpp 设置 - 本地语音转文本配置
- Kokoro 设置 - 本地文本转语音配置
- LiveKit 集成 - 实时语音通信
链接
- 网站: getvoicemode.com
- 文档: voice-mode.readthedocs.io
- GitHub: github.com/mbailey/voicemode
- PyPI: pypi.org/project/voice-mode
社区
- Twitter/X: @getvoicemode
- YouTube: @getvoicemode
参考
许可
MIT - 由Failmode项目提供
mcp-name: com.failmode/voicemode