语音与 TTS

Hermes Agent 支持在所有消息平台上进行文本转语音输出和语音消息转录。

文本转语音

通过四种提供商将文本转换为语音：

提供商	质量	成本	API 密钥
Edge TTS (默认)	良好	免费	无需
ElevenLabs	优秀	付费	`ELEVENLABS_API_KEY`
OpenAI TTS	良好	付费	`VOICE_TOOLS_OPENAI_KEY`
NeuTTS	良好	免费	无需

平台投递方式

平台	投递方式	格式
Telegram	语音气泡（内联播放）	Opus `.ogg`
Discord	语音气泡 (Opus/OGG)，回退为文件附件	Opus/MP3
WhatsApp	音频文件附件	MP3
CLI	保存至 `~/.hermes/audio_cache/`	MP3

配置

# 在 ~/.hermes/config.yaml 中
tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "neutts"
  edge:
    voice: "en-US-AriaNeural"   # 322 种语音，74 种语言
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"  # Adam
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # alloy, echo, fable, onyx, nova, shimmer
    base_url: "https://api.openai.com/v1"  # 用于覆盖 OpenAI 兼容的 TTS 端点
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

Telegram 语音气泡与 ffmpeg

Telegram 语音气泡需要 Opus/OGG 音频格式：

OpenAI 和 ElevenLabs 原生生成 Opus 格式 — 无需额外设置
Edge TTS (默认) 输出 MP3，需要 ffmpeg 进行转换
NeuTTS 输出 WAV，同样需要 ffmpeg 转换以用于 Telegram 语音气泡

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Fedora
sudo dnf install ffmpeg

如果没有安装 ffmpeg，Edge TTS 和 NeuTTS 的音频将作为普通音频文件发送（可播放，但显示为矩形播放器而非语音气泡）。

提示

如果你想在不安装 ffmpeg 的情况下使用语音气泡，请切换到 OpenAI 或 ElevenLabs 提供商。

语音消息转录 (STT)

在 Telegram、Discord、WhatsApp、Slack 或 Signal 上发送的语音消息会自动转录，并以文本形式注入到对话中。Agent 会将转录文本视为普通文本。

提供商	质量	成本	API 密钥
本地 Whisper (默认)	良好	免费	无需
Groq Whisper API	良好–最佳	免费额度	`GROQ_API_KEY`
OpenAI Whisper API	良好–最佳	付费	`VOICE_TOOLS_OPENAI_KEY` 或 `OPENAI_API_KEY`

零配置

当安装了 faster-whisper 时，本地转录功能开箱即用。如果不可用，Hermes 也可以从常见安装位置（如 /opt/homebrew/bin）调用本地的 whisper CLI，或通过 HERMES_LOCAL_STT_COMMAND 使用自定义命令。

配置

# 在 ~/.hermes/config.yaml 中
stt:
  provider: "local"           # "local" | "groq" | "openai"
  local:
    model: "base"             # tiny, base, small, medium, large-v3
  openai:
    model: "whisper-1"        # whisper-1, gpt-4o-mini-transcribe, gpt-4o-transcribe

提供商详情

本地 (faster-whisper) — 通过 faster-whisper 在本地运行 Whisper。默认使用 CPU，如果可用则使用 GPU。模型大小：

模型	大小	速度	质量
`tiny`	~75 MB	最快	基础
`base`	~150 MB	快	良好 (默认)
`small`	~500 MB	中等	更好
`medium`	~1.5 GB	较慢	优秀
`large-v3`	~3 GB	最慢	最佳

Groq API — 需要 GROQ_API_KEY。当你需要一个免费的云端 STT 备选方案时，这是一个很好的云端回退选项。

OpenAI API — 优先接受 VOICE_TOOLS_OPENAI_KEY，回退到 OPENAI_API_KEY。支持 whisper-1、gpt-4o-mini-transcribe 和 gpt-4o-transcribe。

自定义本地 CLI 回退 — 如果你希望 Hermes 直接调用本地转录命令，请设置 HERMES_LOCAL_STT_COMMAND。命令模板支持 {input_path}、{output_dir}、{language} 和 {model} 占位符。

回退行为

如果配置的提供商不可用，Hermes 会自动回退：

本地 faster-whisper 不可用 → 在尝试云端提供商之前，先尝试本地的 whisper CLI 或 HERMES_LOCAL_STT_COMMAND
未设置 Groq 密钥 → 回退到本地转录，然后是 OpenAI
未设置 OpenAI 密钥 → 回退到本地转录，然后是 Groq
都不可用 → 语音消息会原样传递，并向用户发送准确的说明

文本转语音​

平台投递方式​

配置​

Telegram 语音气泡与 ffmpeg​

语音消息转录 (STT)​

配置​

提供商详情​

回退行为​