🚀 語音模式
語音模式為AI助手帶來自然的語音對話體驗。它通過模型上下文協議(MCP),為Claude、ChatGPT等大語言模型(LLM)賦予類人的語音交互能力。
🚀 快速開始
📖 使用其他工具? 查看我們為Cursor、VS Code、Gemini CLI等工具編寫的集成指南!
npm install -g @anthropic-ai/claude-code
curl -LsSf https://astral.sh/uv/install.sh | sh
claude mcp add --scope user voice-mode uvx voice-mode
export OPENAI_API_KEY=your-openai-key
claude converse
✨ 主要特性
- 🎙️ 語音對話:與Claude進行語音交互,提問並聽取回答。
- 🔄 多種傳輸方式:支持使用本地麥克風或基於LiveKit房間的通信方式。
- 🗣️ 兼容OpenAI:可與任何語音轉文本(STT)/文本轉語音(TTS)服務(本地或雲端)配合使用。
- ⚡ 實時交互:低延遲語音交互,自動選擇傳輸方式。
- 🔧 MCP集成:與Claude Desktop和其他MCP客戶端無縫集成。
- 🎯 靜音檢測:當您停止說話時,自動停止錄音(無需再等待!)
🎯 簡單要求
開始使用所需的全部條件:
- 🔑 OpenAI API密鑰(或兼容服務):用於語音轉文本和文本轉語音。
- 🎤 配備麥克風和揚聲器的計算機 或 ☁️ LiveKit服務器(LiveKit Cloud 或 自建)
🎬 演示
觀看語音模式與Claude Code的實際運行效果:

語音模式與Gemini CLI
查看語音模式與Google的Gemini CLI(Claude Code的實現版本)的配合使用效果:

💻 使用示例
配置完成後,可嘗試向Claude發送以下提示:
👨💻 編程與開發
"讓我們一起調試這個錯誤"
- 口頭描述問題,粘貼代碼,並討論解決方案。
"逐步講解這段代碼"
- 讓Claude解釋複雜代碼,同時您可以提問。
"讓我們一起構思架構"
- 通過自然對話設計系統。
"幫我為這個函數編寫測試"
- 描述需求並進行口頭迭代。
💡 通用生產力
"進行每日站會"
- 練習演示或整理思路。
"就[主題]對我進行面試"
- 通過問答為面試做準備。
"做我的橡皮鴨調試夥伴"
- 大聲解釋問題以找到解決方案。
🎯 語音控制功能
"朗讀這條錯誤信息"
(Claude朗讀後等待您的回應)
"給我一個快速總結"
(Claude直接朗讀,無需等待)
- 使用
converse("message", wait_for_response=False)
進行單向播報。
converse
函數使語音交互自然流暢 - 默認情況下會自動等待您的回應,營造真實的對話流程。
📦 安裝指南
前提條件
- Python >= 3.10
- Astral UV - 包管理器(使用
curl -LsSf https://astral.sh/uv/install.sh | sh
進行安裝)
- OpenAI API密鑰(或兼容服務)
系統依賴
Ubuntu/Debian
sudo apt update
sudo apt install -y python3-dev libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev ffmpeg pulseaudio pulseaudio-utils
⚠️ 重要提示
WSL2用戶需要額外的音頻包(pulseaudio、libasound2-plugins)才能訪問麥克風。如果遇到問題,請查看我們的 WSL2麥克風訪問指南。
Fedora/RHEL
sudo dnf install python3-devel alsa-lib-devel portaudio-devel ffmpeg
macOS
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install portaudio ffmpeg
Windows (WSL)
在WSL中遵循上述Ubuntu/Debian的安裝說明。
NixOS
語音模式包含一個flake.nix文件,其中包含所有必需的依賴項。您可以選擇以下兩種方式之一:
- 使用開發環境(臨時):
nix develop github:mbailey/voicemode
- 系統級安裝(見下面的安裝部分)
快速安裝
claude mcp add --scope user voice-mode uvx voice-mode
claude mcp add voice-mode nix run github:mbailey/voicemode
uvx voice-mode
pip install voice-mode
nix run github:mbailey/voicemode
AI編碼助手的配置
📖 尋找詳細的設置說明? 查看我們全面的集成指南,獲取每個工具的分步說明!
以下是快速配置片段。完整的安裝和設置說明,請參閱上述集成指南。
Claude Code (CLI)
claude mcp add voice-mode -- uvx voice-mode
或者使用環境變量:
claude mcp add voice-mode --env OPENAI_API_KEY=your-openai-key -- uvx voice-mode
Claude Desktop
macOS:~/Library/Application Support/Claude/claude_desktop_config.json
Windows:%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"voice-mode": {
"command": "uvx",
"args": ["voice-mode"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
Cline
添加到您的Cline MCP設置中:
Windows:
{
"mcpServers": {
"voice-mode": {
"command": "cmd",
"args": ["/c", "uvx", "voice-mode"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
macOS/Linux:
{
"mcpServers": {
"voice-mode": {
"command": "uvx",
"args": ["voice-mode"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
Continue
添加到您的 .continue/config.json
文件中:
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "uvx",
"args": ["voice-mode"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
]
}
}
Cursor
添加到 ~/.cursor/mcp.json
文件中:
{
"mcpServers": {
"voice-mode": {
"command": "uvx",
"args": ["voice-mode"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
VS Code
添加到您的VS Code MCP配置中:
{
"mcpServers": {
"voice-mode": {
"command": "uvx",
"args": ["voice-mode"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
Windsurf
{
"mcpServers": {
"voice-mode": {
"command": "uvx",
"args": ["voice-mode"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
Zed
添加到您的Zed settings.json文件中:
{
"context_servers": {
"voice-mode": {
"command": {
"path": "uvx",
"args": ["voice-mode"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
}
Roo Code
- 打開VS Code設置 (
Ctrl/Cmd + ,
)
- 在設置搜索欄中搜索 "roo"
- 找到 "Roo-veterinaryinc.roo-cline → settings → Mcp_settings.json"
- 點擊 "在settings.json中編輯"
- 添加語音模式配置:
{
"mcpServers": {
"voice-mode": {
"command": "uvx",
"args": ["voice-mode"],
"env": {
"OPENAI_API_KEY": "your-openai-key"
}
}
}
}
其他安裝選項
使用Docker
docker run -it --rm \
-e OPENAI_API_KEY=your-openai-key \
--device /dev/snd \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e DISPLAY=$DISPLAY \
ghcr.io/mbailey/voicemode:latest
使用pipx
pipx install voice-mode
從源代碼安裝
git clone https://github.com/mbailey/voicemode.git
cd voicemode
pip install -e .
NixOS安裝選項
1. 使用nix profile進行用戶級安裝:
nix profile install github:mbailey/voicemode
2. 添加到NixOS配置(系統級):
environment.systemPackages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
3. 添加到home-manager:
home.packages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
4. 不安裝直接運行:
nix run github:mbailey/voicemode
📚 詳細文檔
工具說明
屬性 |
詳情 |
converse |
進行語音對話 - 說話並可選擇聽取回復 |
listen_for_speech |
監聽語音並轉換為文本 |
check_room_status |
檢查LiveKit房間狀態和參與者 |
check_audio_devices |
列出可用的音頻輸入/輸出設備 |
start_kokoro |
啟動Kokoro TTS服務 |
stop_kokoro |
停止Kokoro TTS服務 |
kokoro_status |
檢查Kokoro TTS服務的狀態 |
install_whisper_cpp |
安裝whisper.cpp以實現本地語音轉文本 |
install_kokoro_fastapi |
安裝kokoro-fastapi以實現本地文本轉語音 |
⚠️ 重要提示
converse
工具是語音交互的主要接口,它將說話和傾聽自然地結合在一起。
💡 使用建議
install_whisper_cpp
和 install_kokoro_fastapi
工具可幫助您在本地設置免費、私密、開源的語音服務。詳細用法請參閱 安裝工具文檔。
配置說明
快速設置
唯一需要的配置是您的OpenAI API密鑰:
export OPENAI_API_KEY="your-key"
可選設置
export STT_BASE_URL="http://127.0.0.1:2022/v1"
export TTS_BASE_URL="http://127.0.0.1:8880/v1"
export TTS_VOICE="alloy"
export LIVEKIT_URL="wss://your-app.livekit.cloud"
export LIVEKIT_API_KEY="your-api-key"
export LIVEKIT_API_SECRET="your-api-secret"
export VOICEMODE_DEBUG="true"
export VOICEMODE_SAVE_AUDIO="true"
export VOICEMODE_AUDIO_FORMAT="pcm"
export VOICEMODE_TTS_AUDIO_FORMAT="pcm"
export VOICEMODE_STT_AUDIO_FORMAT="mp3"
export VOICEMODE_OPUS_BITRATE="32000"
export VOICEMODE_MP3_BITRATE="64k"
音頻格式配置
語音模式默認使用 PCM 音頻格式進行TTS流式傳輸,以實現最佳實時性能:
- PCM(TTS默認):零延遲,最佳流式傳輸性能,未壓縮。
- MP3:廣泛兼容,上傳時壓縮效果好。
- WAV:未壓縮,適合本地處理。
- FLAC:無損壓縮,適合存檔。
- AAC:壓縮效果好,適用於蘋果生態系統。
- Opus:文件小,但不建議用於流式傳輸(存在質量問題)。
音頻格式會根據提供商的能力自動驗證,如果需要,會回退到支持的格式。
本地STT/TTS服務
為了保護隱私或離線使用,語音模式支持本地語音服務:
這些服務提供與OpenAI相同的API接口,允許在雲端和本地處理之間無縫切換。
OpenAI API兼容性優勢
通過嚴格遵循OpenAI的API標準,語音模式實現了強大的部署靈活性:
- 🔀 透明路由:用戶可以在語音模式之外實現自己的API代理或網關,根據自定義邏輯(成本、延遲、可用性等)將請求路由到不同的提供商。
- 🎯 模型選擇:部署路由層,為每個請求選擇最佳模型,而無需修改語音模式配置。
- 💰 成本優化:構建智能路由器,在昂貴的雲端API和免費的本地模型之間進行平衡。
- 🔧 無鎖定:只需更改
BASE_URL
即可切換提供商 - 無需更改代碼。
示例:只需將 OPENAI_BASE_URL
設置為指向您的自定義路由器:
export OPENAI_BASE_URL="https://router.example.com/v1"
export OPENAI_API_KEY="your-key"
OpenAI SDK會自動處理這些操作 - 無需對語音模式進行配置!
🔧 技術細節
┌─────────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ Claude/LLM │ │ LiveKit Server │ │ Voice Frontend │
│ (MCP Client) │◄────►│ (Optional) │◄───►│ (Optional) │
└─────────────────────┘ └──────────────────┘ └─────────────────────┘
│ │
│ │
▼ ▼
┌─────────────────────┐ ┌──────────────────┐
│ Voice MCP Server │ │ Audio Services │
│ • converse │ │ • OpenAI APIs │
│ • listen_for_speech│◄───►│ • Local Whisper │
│ • check_room_status│ │ • Local TTS │
│ • check_audio_devices └──────────────────┘
└─────────────────────┘
📚 詳細文檔
常見問題解決
- 無法訪問麥克風:檢查終端/應用程序的系統權限。
- 未找到UV:使用
curl -LsSf https://astral.sh/uv/install.sh | sh
進行安裝。
- OpenAI API錯誤:驗證您的
OPENAI_API_KEY
是否設置正確。
- 無音頻輸出:檢查系統音頻設置和可用設備。
調試模式
啟用詳細日誌記錄和音頻文件保存:
export VOICEMODE_DEBUG=true
調試音頻文件將保存到:~/voicemode_recordings/
音頻診斷
運行診斷腳本以檢查您的音頻設置:
python scripts/diagnose-wsl-audio.py
該腳本將檢查所需的軟件包和音頻服務,並提供具體建議。
音頻保存
保存所有音頻文件(TTS輸出和STT輸入):
export VOICEMODE_SAVE_AUDIO=true
音頻文件將保存到:~/voicemode_audio/
,文件名包含時間戳。
完整文檔
📚 在voice-mode.readthedocs.io閱讀完整文檔
入門指南
開發文檔
服務指南
故障排除
鏈接
社區
相關鏈接
- 🚀 集成指南 - 所有支持工具的設置說明。
- 🔧 配置參考 - 環境變量和選項。
- 🎤 本地服務設置 - 為保護隱私,在本地運行TTS/STT服務。
- 🐛 故障排除 - 常見問題和解決方案。
📄 許可證
本項目採用MIT許可證,由 Failmode 開發。
項目統計