🎙️ VoxAgent

与你的编程智能体对话，它会回话。

面向 Claude Code、Cursor、OpenClaw 及任何 MCP 客户端的本地优先语音输入/输出。

English · 简体中文

为什么

编程智能体已经从自动补全进化成同事——但交互界面仍然是 一个键盘。VoxAgent 给你的智能体装上耳朵和嘴巴：

• 🎤 listen() — 口述指令、代码片段或代码审查反馈

• 🔊 speak() — 语音播报进度更新；趁你的智能体说话时去倒杯咖啡

• 🗣️ ask_user() — 智能体提问，你从房间另一头大声回答

• 🕹️ Push-to-talk — 在任何地方按住全局热键；你的话会直接 传入 claude -p，然后语音播报回复

一切都在你的机器上运行。STT 完全离线（faster-whisper）； TTS 从零配置的语音开始，可升级到本地 CosyVoice 服务器， 以获得生产级语音质量。无需 API 密钥。

快速开始

pip install 'voxagent[local]'
voxagent doctor        # check mic + deps
voxagent demo          # try the talk-loop standalone

# Register with Claude Code
claude mcp add voxagent -- voxagent serve

# Enable the agent skill (when to speak, how to behave)
mkdir -p ~/.claude/skills && cp -r skills/voice-control ~/.claude/skills/

# Push-to-talk daemon (optional): talk to Claude Code from any app
pip install 'voxagent[ptt]'
voxagent ptt --send 'claude -p'

然后只需说："voice mode on"——或按住 PTT 热键（默认 Ctrl+Shift+Space）开始说话。

可与任何 MCP 客户端配合使用——Cursor、OpenClaw、Codex 等都支持 MCP。

架构

        ┌─────────────┐     MCP (stdio)      ┌──────────────────┐
 mic ──▶│   listen()  │◀────────────────────▶│  Claude Code /   │
        │  (STT)      │                      │  Cursor / any    │
 spk ◀──│   speak()   │◀────────────────────▶│  MCP client      │
        │  (TTS)      │      tools+skill     └──────────────────┘
        └─────────────┘
          faster-whisper   edge-tts / CosyVoice (pluggable)
          ▲ fully offline           ▲ swap via env var

引擎是可插拔的——设置一个环境变量即可切换任意一侧：

查看 .env.example 了解所有选项。

MCP 工具

内置的 Agent Skill（skills/voice-control）会教智能体何时 使用它们：简短的语音回复、长任务前的语音播报、 语言镜像、优雅地回退到文本。

故障排除

模型下载失败（huggingface.co 网络错误）：请从镜像手动下载 模型，然后将 WHISPER_MODEL 指向该文件夹：

bash scripts/download_model.sh tiny            # or base / small
export WHISPER_MODEL="$HOME/.voxagent/models/tiny"

该脚本使用普通 curl 从 hf-mirror.com 拉取，完全绕过 huggingface_hub SDK。或者，如果 SDK 对你有用，可以在运行前设置 HF_ENDPOINT=https://hf-mirror.com 和 HF_HUB_DISABLE_XET=1。

按住热键会向当前聚焦的应用输入字符（例如 ctrl+j 会在终端中发送换行，导致你说话时终端滚动）：在 macOS 上， 守护进程会在组合键按住期间吞掉热键的字符键。如果 抑制器不可用，请优先使用不含字符的热键，如 --hotkey f6 或 --hotkey ctrl+cmd+j。

macOS 热键无响应：在系统设置 → 隐私与安全性中，为终端授予辅助功能 / 输入监控权限，然后重启守护进程。

路线图

• Push-to-talk 全局热键（voxagent ptt）

• 流式 STT（说话时实时生成部分转录文本）

• 语音记忆——克隆你自己的声音用于智能体回复

• OpenClaw / n8n 集成方案

• 内置 CosyVoice 的 Docker 镜像

参与贡献

欢迎提交 Issue 和 PR——尤其是新的引擎适配器（GPT-SoVITS、F5-TTS、 Piper...）。每个适配器约 ~40 行；请参阅 voxagent/tts/cosyvoice_engine.py 了解其模式。

许可证

MIT