Hermes Agent 语音不工作：一步步修复
Hermes Agent 语音模式没有声音、拒收音频或丢文件？走完这八种故障和对应修复。
语音模式突然安静时，问题几乎从来不在 Hermes 本身
你发了一条语音给机器人，什么也没回。或者你明明配置成语音回复，它却用文字回你。或者昨天还好好的，今天文件就那样躺着无人处理。语音模式无声无息地失效，是 Hermes Agent 上最常见的问题，几乎总是麦克风到模型之间那八件具体事之一在作怪。
如果你更想直接跳过整条管线，用一台已经接好语音的托管 Hermes Agent，就从 Hermify 开始。否则，按顺序走下面这份清单，每一项检查都很便宜，且都能一口气排除一整类故障。
1. 机器人在 Telegram 上无法访问语音消息
如果你的智能体运行在 Telegram 上，但语音消息压根收不到，文字能收，语音被无视，第一件事要看的是机器人的隐私设置。默认情况下，群组里的机器人只能看到 @ 到它的消息或以斜杠命令开头的消息，所以语音会被悄悄丢弃。
在 BotFather 里调整：
- 打开
@BotFather，发送/mybots。 - 选中你的机器人，进入 Bot Settings → Group Privacy。
- 设为 Disabled。
私聊机器人的消息不受这个设置影响。如果机器人私聊能用、只在群里失效，那就是群组隐私在作祟。
还有一种更隐蔽的情况：发送者账户把语音消息隐私设成了“仅联系人”。当机器人试图回发音频时，Telegram 会返回一个 VOICE_MESSAGES_FORBIDDEN 错误，尽管入向的语音一切正常。如果你的机器人能收到语音、但在回发音频时安静地失败，先检查一下自己 Telegram 的隐私设置。
2. 没有配置任何语音转写（STT）服务商
Hermes 需要一个语音转写（STT）后端把入向音频转成提示词。如果没配置任何一个，语音消息就完全不会被处理，智能体只读文字，忽略语音。
检查配置里的 STT 段：
voice:
stt:
provider: openai
api_key: ${OPENAI_API_KEY}
常见疏漏：
OPENAI_API_KEY（或ELEVENLABS_API_KEY，或你选择的服务商对应的 API 密钥）没有被导出到进程环境。在启动 Hermes 的同一个 shell 里用printenv OPENAI_API_KEY确认一下。- 密钥存在但填错了，或者已经被吊销。被吊销的密钥会返回 401，某些 Hermes 版本会在启动时记录一次日志，之后就默默吞掉。
- 你把
provider设成了whisper（本地 Whisper），却没有安装对应的 extra。本地 Whisper 需要pip install "hermes-agent[voice]"，加上首次运行时真正下载模型。
如果你不确定当前用的是哪个服务商，跑一下 hermes voice test，或去 hermes gateway logs 里找启动时的一行 stt.provider=。
3. 容器里缺少 FFmpeg
这是自托管部署里最常见的语音故障，且从日志里看不出来。Telegram 将语音消息以 .ogg 文件配合 OPUS 编码下发，而大多数 STT 服务商（包括本地 Whisper）都需要 FFmpeg 来解码。如果 FFmpeg 不在系统 PATH 中，音频到了却解不开，管线以一条看起来像网络问题的编解码错误退出。
在裸金属或 VPS 安装上：
# Debian/Ubuntu
sudo apt update && sudo apt install -y ffmpeg
# Alpine（常见于精简版 Docker 镜像）
apk add --no-cache ffmpeg
在基于 python:3.11-slim 构建的 Docker 容器里，FFmpeg 默认不会被包含。官方 Hermes 镜像自带 FFmpeg，自定义的 Dockerfile 可能没有。用下面这条命令确认：
docker exec <container> which ffmpeg
如果什么也不返回，就在你的 Dockerfile 里加上 apt-get install -y ffmpeg，然后重新构建。
4. 语音消息太大或格式不对
Telegram 自己对语音消息的限制很宽松，但并非无限。机器人可以发送最大 50 MB 的语音消息，超过 20 MB 的文件会以普通附件而不是可播放的语音气泡形式送达。用户发来的语音消息一定是 OGG/OPUS 格式，但如果你有把其他来源的录音（例如 Whisper 转写过的播客音频）经由机器人推送出去的流程，格式就很关键了。
如果你回发的语音以附件而不是音频气泡出现，说明文件要么太大，要么不是 audio/ogg。把它重新编码成 1 MB 以下的单声道 OGG/OPUS：
ffmpeg -i input.wav -c:a libopus -b:a 32k -ac 1 output.ogg
Whisper 还要求单声道输入，立体声文件会抛出一个通道不匹配的错误，表现就是“没有转写结果”。
5. 容器内存耗尽，STT worker 被杀
本地 Whisper 模型对内存很饥饿。whisper-base 大约需要 1 GB 内存才能跑起来，whisper-large-v3 接近 10 GB。在 1 GB 的 VPS 上，一收到语音消息容器几乎肯定会被 OOM 杀掉，然后 Docker 悄悄重启。
先看退出码：
docker inspect <container> --format='{{.State.ExitCode}}'
退出码 137 就是 SIGKILL，在内存吃紧的主机上几乎总是意味着 OOM killer。在宿主机上用 dmesg -T | grep -i "killed process" 进一步确认。
修复方法要么换一台更大的机器，要么用云端 API 替代本地 Whisper。如果你在 1 GB 的 droplet 上又想保留语音，把 stt.provider 切成 openai 或 elevenlabs，STT 调用会走网络，内存留给推理循环。
如果容器是因为其他原因（不是 OOM）反复重启，查看我们的 Hermes Agent Docker 指南 中的完整排查清单。
6. TTS 配好了，却始终不返回音频
反过来的故障：智能体正常转写你的语音、生成了文字回复，但没有音频回来。这几乎总是文本转语音（TTS）问题，而不是 STT。
三个常见嫌疑：
- TTS 密钥撞到了速率限制。 尤其是 ElevenLabs，对并发和每秒调用都有严格的上限。超限时 API 会返回错误，而不是给一段无声响应；但如果你的 Hermes 版本没把 TTS worker 收到的上游错误往上抛，你就得到一条纯文字回复，没有任何解释。去服务商的控制台看看是不是有一波速率限制。
- 合成超时。 对于长回复，ElevenLabs 标准接口会等整段音频都生成完再返回。大概超过 500 词的回复就可能超过默认的 HTTP 超时。如果你的 Hermes 版本支持流式合成就打开它，否则让智能体把回复写得更短。
- 音频生成了，但上传失败。 Telegram Bot API 的
sendVoice有 1 MB 的大小限制，超过之后就不会以可播放气泡呈现，而是变成文件。如果生成的 MP3 超过 1 MB，就在 TTS 配置里降低比特率，或者把回复切成多段。
7. 网关连上了，但语音管线没启动
Hermes 把 STT 与 TTS 管线作为独立于主网关的 worker 运行。有些环境下，网关干净地启动了，但语音 worker 没能起来，通常是因为语音 extra 中的某个 Python 依赖在安装阶段编译失败。
诊断：
hermes voice status
如果管线没有运行，显式重启：
hermes voice start
如果启动时报导入错误，重新安装语音 extra：
pip install --force-reinstall "hermes-agent[voice]"
在 Android/Termux 上，请用 Termux 专用的 extra：
pip install "hermes-agent[termux]"
8. 本地一切正常，但生产环境不行
如果语音在你本地笔记本上没问题，一到线上就坏，罪魁祸首几乎总是三个之一：生产镜像里没有 FFmpeg、环境变量没有传给容器、或者容器以非 root 用户运行且没有权限写音频临时目录。
最后一种情况里，Hermes 在转写过程中会在 /tmp（或你配置的 voice.temp_dir）写入短暂的 WAV 文件。如果容器用户在那里没有写权限，STT 调用会在创建文件时失败。挂一个可写的卷来解决：
volumes:
- hermes_tmp:/tmp
或者把 voice.temp_dir 指到一个你确认可写的路径。
什么时候更划算的是直接交出去
上面这八个故障都能修，如果你有二十分钟且乐意调编解码器，你就能修好。如果你更想让整条管线直接就能用，Hermify 在 Telegram 上运行托管的 Hermes Agent，FFmpeg、STT、TTS、记忆和网关全部替你打理好。语音模式默认开启，记忆文件始终归你所有，上线大约需要一分钟。
想深入了解，可以看我们的语音模式设置指南，它把顺畅路径讲得很细；如果你还在第一次选型，我们对 TTS 服务商的对比文章比较了 OpenAI、ElevenLabs 和本地方案。