本教程共 25 篇 · 第 21 篇 · 更新于 2026-07-26 · 约 18 分钟阅读

21. 语音模式、视觉与 Computer Use

本节目标：掌握 Hermes Agent 的全部多媒体能力——用嘴跟它对话、让它看懂图片、让它操控你的电脑、让它画图。学完你知道每种能力怎么开、用什么模型、踩什么坑。

前面二十章，你和 Hermes Agent 的交互都是打字。但人不是只会打字的动物——你会说话、会看图、会用手点鼠标。Hermes Agent 在 v2026.7.20 里把这些能力都补上了：语音对话、视觉理解、桌面操控、图片生成。

这一章把这四块一口气讲完。它们看起来各管一摊，但底层逻辑一样：主模型负责思考，辅助模型负责感官。

语音模式能做什么

Hermes Agent 的语音功能不是单一的”语音助手”，而是三种独立的体验：

模式	平台	干什么
交互式语音循环	CLI	按 Ctrl+B 说话，Agent 自动检测静默并回复
语音回复	Telegram / Discord	Agent 在文字回复之外，额外发一条语音消息
语音频道	Discord	Bot 加入语音频道，实时听你说、说给你听

三种模式可以叠加。你在 CLI 里用语音循环，同时在 Telegram 里开语音回复，互不冲突。

Note

语音功能不是开箱即用的。它需要额外安装 Python 包和系统依赖，下面每一步都会说清楚。

CLI 语音模式：对着终端说话

这是最直接的语音交互方式。你按一个键开始说话，说完停顿几秒，Hermes 自动转写、思考、回复。

安装依赖

CLI 语音需要两样东西：Python 的音频包和系统的音频库。

# Python 包：麦克风录音 + 音频播放
cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"

# 系统依赖
# macOS
brew install portaudio ffmpeg

# Ubuntu/Debian
sudo apt install portaudio19-dev ffmpeg

依赖	干什么
`portaudio`	麦克风输入和音频播放的底层库
`ffmpeg`	音频格式转换（MP3 转 Opus 等）
`sounddevice` + `numpy`	Python 层的录音和音频处理

开启语音模式

启动 CLI 后，用斜杠命令开启：

hermes          # 启动 CLI

在 CLI 里输入：

/voice on       # 开启语音模式
/voice tts      # 额外开启 TTS，让 Agent 说话

录音流程

整个交互循环是这样的：

按 Ctrl+B，一声 beep 响（880Hz），录音开始
你说话，屏幕上显示实时音量条：● [▁▂▃▅▇▇▅▂] ❯
说完停顿 3 秒，两声 beep 响（660Hz），录音自动停止
音频被 Whisper 转写成文字，发给 Agent
Agent 回复，如果开了 TTS 就逐句念给你听
录音自动重启，你直接继续说，不用再按键

这个循环会一直持续，直到你录音时再按一次 Ctrl+B 退出，或者连续 3 次没检测到语音。

Tip
录音键可以在 ~/.hermes/config.yaml 里改。如果你用 tmux，Ctrl+B 会冲突，建议改成别的：
voice:
  record_key: "ctrl+space"

静默检测：怎么知道你说完了

Hermes 用两阶段算法判断你什么时候说完：

语音确认——等音频超过 RMS 阈值（默认 200）至少 0.3 秒，容忍音节间的短暂停顿
结束检测——确认有语音后，连续 3 秒静默就触发停止

如果 15 秒内一个字都没说，录音自动取消。

两个参数都能调：

voice:
  silence_threshold: 200     # 越高越不敏感（安静环境调低，嘈杂环境调高）
  silence_duration: 3.0      # 静默多久算说完

打断（Barge-in）

Agent 正在说话时，你可以直接开口打断。语音活动监视器会实时监听，你一出声就立刻停止播放，切回录音模式。监视器会根据当前播放音量自动校准噪声底线，所以不会把 Agent 自己的声音误判成你在说话。

如果不想用这个功能：

voice:
  barge_in: false

幻觉过滤

Whisper 有个毛病：静音或背景噪声时它会”脑补”出文字，比如 “Thank you for watching”、“Subscribe” 之类的。Hermes 内置了 26 条多语言幻觉短语和一个正则模式来过滤这些假转录。

语音转写（STT）：把语音变成文字

不管你用 CLI 语音还是消息平台发语音消息，都需要先把音频转成文字。这就是 STT（Speech-to-Text）。

五个提供商

提供商	模型	费用	需要 API Key	速度
本地 Whisper	`base`（默认）	免费	不需要	取决于 CPU/GPU
Groq	`whisper-large-v3-turbo`	免费额度	`GROQ_API_KEY`	极快（~0.5 秒）
OpenAI	`whisper-1`	付费	`VOICE_TOOLS_OPENAI_KEY`	快（~1 秒）
Mistral	`voxtral-mini-latest`	付费	`MISTRAL_API_KEY`	快
xAI	`grok-stt`	付费	`XAI_API_KEY`	快

Tip

如果你装了 faster-whisper，语音模式零 API Key 就能跑。模型（base 约 150MB）首次使用时自动下载。

本地 Whisper 有五个模型大小可选：

模型	大小	速度	质量
`tiny`	~75 MB	最快	基础
`base`	~150 MB	快	够用（默认）
`small`	~500 MB	中	更好
`medium`	~1.5 GB	慢	很好
`large-v3`	~3 GB	最慢	最好

配置方式

# ~/.hermes/config.yaml
stt:
  provider: "local"          # local | groq | openai | mistral | xai
  local:
    model: "base"            # tiny / base / small / medium / large-v3

API Key 写在 ~/.hermes/.env：

# 本地 Whisper 不需要任何 Key
GROQ_API_KEY=your-key                    # Groq
VOICE_TOOLS_OPENAI_KEY=your-key          # OpenAI

自动降级

你配的提供商不可用时，Hermes 自动按优先级降级：local > groq > openai。比如你配了 Groq 但 Key 过期了，它会自动切到本地 Whisper，你不会感觉中断。

消息平台的语音转写

在 Telegram、Discord、WhatsApp 等平台发语音消息，适配器会自动下载音频、转写、把文字塞进消息里。Agent 收到的永远是文字，不知道原来是语音。这个设计让 Agent 的核心循环不用关心音频格式差异。

文字转语音（TTS）：让 Agent 开口说话

TTS（Text-to-Speech）让 Agent 的回复变成语音。v2026.7.20 支持 10 个提供商。

提供商一览

提供商	质量	费用	需要 API Key	延迟
Edge TTS（默认）	好	免费	不需要	~1 秒
ElevenLabs	最好	付费	`ELEVENLABS_API_KEY`	~2 秒
OpenAI TTS	好	付费	`VOICE_TOOLS_OPENAI_KEY`	~1.5 秒
MiniMax	最好	付费	`MINIMAX_API_KEY`	—
Mistral (Voxtral)	最好	付费	`MISTRAL_API_KEY`	—
Google Gemini	最好	免费额度	`GEMINI_API_KEY`	—
xAI	最好	付费	`XAI_API_KEY`	—
NeuTTS	好	免费（本地）	不需要	取决于 CPU
KittenTTS	好	免费（本地）	不需要	—
Piper	好	免费（本地）	不需要	—

Tip

最省钱的组合：本地 Whisper（STT）+ Edge TTS（TTS），一分钱不花。最求质量的组合：Groq Whisper + ElevenLabs。

配置方式

# ~/.hermes/config.yaml
tts:
  provider: "edge"                       # 默认，免费
  speed: 1.0                             # 全局语速倍率
  edge:
    voice: "en-US-AriaNeural"            # 322 个声音，74 种语言
    speed: 1.0                           # 覆盖全局语速

想换 ElevenLabs：

tts:
  provider: "elevenlabs"
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"     # Adam
    model_id: "eleven_multilingual_v2"

流式 TTS

Agent 说话不是等整段回复生成完再念，而是逐句实时播放。它把模型生成的文字按句子缓冲（最少 20 字），剥掉 markdown 和 emoji，然后一句一句念。支持 PCM 流式 API 的提供商（ElevenLabs、OpenAI）能做到最低的首字延迟。

平台投递格式

不同平台对语音消息的格式要求不同：

平台	格式	需要 ffmpeg 转换
Telegram	Opus/OGG	Edge/MiniMax/xAI/NeuTTS/KittenTTS/Piper 需要
Discord	Opus/OGG	同上
WhatsApp	MP3	不需要
CLI	MP3	不需要

OpenAI、ElevenLabs、Mistral 原生输出 Opus，不需要 ffmpeg。Edge TTS 输出 MP3，在 Telegram 上需要 ffmpeg 转成 Opus 才能显示为语音气泡，否则只能当文件发。

Warning

如果你用 Edge TTS 但没装 ffmpeg，Telegram 上的语音回复会变成普通文件附件，不是语音气泡。要么装 ffmpeg，要么换 OpenAI/ElevenLabs 提供商。

Gemini 人设提示

Gemini TTS 支持用自然语言描述声音风格。你可以写一个 Markdown 文件描述你想要的声音人设：

tts:
  provider: gemini
  gemini:
    voice: Algieba
    persona_prompt_file: ~/.hermes/tts/butler-voice.md

这个文件可以包含 AUDIO PROFILE、SCENE、DIRECTOR'S NOTES 等段落来指导声音表演。如果文件里有 {transcript} 占位符，Hermes 会替换成实际要念的文字。

自定义命令提供商

如果某个 TTS 引擎没有内置支持，但提供了命令行工具，你可以用 type: command 把它接进来，不用写 Python：

tts:
  provider: voxcpm
  providers:
    voxcpm:
      type: command
      command: "voxcpm --ref ~/voice.wav --text-file {input_path} --out {output_path}"
      output_format: mp3
      timeout: 180
      voice_compatible: true       # 尝试作为语音气泡投递

Hermes 把文字写入临时文件，跑你的命令，读取产出的音频文件。支持的占位符有 {input_path}、{output_path}、{voice}、{model}、{speed} 等。

消息平台语音回复

在 Telegram 和 Discord 里，你可以让 Agent 的回复带语音。

开启方式

先启动网关：

hermes gateway

然后在聊天里发命令：

/voice on       # 只在你发语音消息时，Agent 回语音
/voice tts      # 所有回复都带语音
/voice off      # 关闭语音回复
/voice status   # 查看当前状态

三种模式：

模式	命令	行为
`off`	`/voice off`	纯文字（默认）
`voice_only`	`/voice on`	你发语音才回语音
`all`	`/voice tts`	每条回复都带语音

设置会持久化，重启网关不丢。

Discord 的 DM 和频道

Discord 有两种交互方式：

私信（DM）——直接给 Bot 发消息，不需要 @提及
服务器频道——必须 @提及 Bot（如 @hermesbot 你好），否则不回复

如果嫌 @提及麻烦，可以在 ~/.hermes/.env 里关掉：

DISCORD_REQUIRE_MENTION=false

或者指定某些频道免提及：

DISCORD_FREE_RESPONSE_CHANNELS=123456789,987654321

Discord 语音频道：实时语音对话

这是最沉浸的语音体验。Bot 加入你的 Discord 语音频道，听你说话、思考、然后用语音回复。

额外要求

语音频道比文字语音回复多几样东西：

Bot 权限——在 Discord Developer Portal 给 Bot 加 Connect 和 Speak 权限
Opus 编解码器——系统装 opus 库
Privileged Gateway Intents——开启 Message Content Intent

# Opus 编解码器
# macOS
brew install opus

# Ubuntu/Debian
sudo apt install libopus0

使用方式

在 Bot 所在的文字频道里：

/voice join      # Bot 加入你当前所在的语音频道
/voice leave     # Bot 离开语音频道
/voice status    # 查看状态

Note

你必须先在语音频道里，再执行 /voice join。Bot 会加入你所在的那个频道。

工作流程

Bot 加入语音频道后：

独立监听每个用户的音频流
检测到 0.5 秒以上语音后，1.5 秒静默触发处理
用 Whisper 转写语音
走完整的 Agent 管线（会话、工具、记忆）
用 TTS 把回复念出来

转写文字会同步发到文字频道：[Voice] @user: 你说的话。Agent 回复也以文字 + 语音两种形式出现。

Bot 播放 TTS 时会暂停自己的音频监听，防止听到自己的声音形成回声。只有 DISCORD_ALLOWED_USERS 里的用户才能通过语音交互，其他人说话会被忽略。

视觉理解：让 Agent 看图片

Hermes Agent 支持多模态视觉——你给它一张图，它能看懂、描述、分析。

CLI 里粘贴图片

在 CLI 里，你可以直接把剪贴板里的图片粘进来：

截图或复制一张图片到剪贴板
在 CLI 里输入 /paste
图片以 [📎 Image #1] 标签出现在输入框上方
打字提问，回车发送

可以一次粘多张图，每张有自己的编号。按 Ctrl+C 清除所有已附加的图片。

Warning

终端是纯文本接口，如果你的剪贴板里只有图片（没有文字），Ctrl+V 不会有效果。必须用 /paste 命令显式触发图片附加。

平台兼容性

环境	`/paste`	Ctrl+V	备注
macOS Terminal / iTerm2	可以	可以	原生剪贴板 + 截图路径恢复
Linux X11	可以	可以	需要 `xclip`
Linux Wayland	可以	可以	需要 `wl-clipboard`
WSL2	可以	可以	用 `powershell.exe`，无需额外安装
VS Code / Cursor（本地）	可以	可以	推荐跑 `/terminal-setup`
SSH 远程	不行	不行	远程剪贴板不可访问

SSH 远程的替代方案：上传图片文件后用路径引用、用图片 URL、或通过 Telegram/Discord 发图片。

图片路由：视觉模型 vs 纯文本模型

Hermes 根据你当前用的主模型是否支持视觉，自动选择处理路径：

你的主模型	图片怎么处理
支持视觉（GPT-4V、Claude、Gemini 等）	图片以原始像素发送给主模型，不经过中间层
纯文本（DeepSeek V3 等）	走 `vision_analyze` 辅助工具——辅助视觉模型先描述图片，文字描述注入对话

你不需要配置这个——Hermes 自动查模型能力元数据来决定。实际效果：你可以在会话中途切换视觉和非视觉模型，图片处理”就是能用”。

辅助视觉模型

如果你用的是纯文本主模型，视觉分析由辅助模型完成。可以在 config 里显式配：

auxiliary:
  vision:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"
    timeout: 120

Hermes 的自动选择优先级：用户配置 > 主模型提供商 > OpenRouter（默认 Gemini Flash）> Nous Portal。

为什么不直接传 URL

图片 URL 可能过期（企业微信临时链接 1 小时就失效）、可能指向内网（SSRF 风险）。Hermes 的做法是先下载到本地、验证大小、转 base64，再发给模型。所有提供商都支持 base64，但不是所有都支持 URL。

Computer Use：让 Agent 操控你的电脑

这是最”科幻”的能力：Agent 能在你的电脑上点击、输入、滚动、拖拽——在后台完成，你的鼠标不动，你的窗口不切换。

工作原理

computer_use 工具集通过 MCP 协议跟 cua-driver（一个开源后台操控驱动）通信。每个平台用不同的底层技术：

平台	无障碍树	输入注入
macOS	AX（私有 SkyLight SPI）	`SLPSPostEventRecordTo`，按进程发送，不移动光标
Windows	UIAutomation	`SendInput` + `PostMessage`，不抢焦点
Linux	AT-SPI（X11 + Wayland）	XTest（X11）/ 虚拟键盘（Wayland）

关键点：Agent 操控时你会看到一个半透明覆盖光标滑过屏幕，但真实的 OS 光标纹丝不动。每个 Hermes 会话有自己的 cua-driver 会话 ID，并发运行不会互相干扰。

安装

# 方式一：专用命令
hermes computer-use install

# 方式二：交互式启用
hermes tools    # 选 🖱️ Computer Use

安装后授予权限：

平台	权限
macOS	系统设置 → 隐私与安全 → 辅助功能 + 屏幕录制 → 允许终端
Windows	安装时无需；SSH 驱动需要 autostart 模式
Linux	需要 `DISPLAY`（X11）或 `XDG_SESSION_TYPE=wayland`

诊断命令

装完先跑一下诊断：

hermes computer-use doctor

它会逐项检查并给出矩阵报告：

⚠️  cua-driver 0.5.8 on darwin - degraded
  ✅ binary_version: cua-driver 0.5.8
  ✅ platform_supported: macOS 26.4.1 (arm64)
  ✅ session_active: MCP session is active.
  ❌ bundle_identity: Process has no CFBundleIdentifier.
      -> Run the binary inside CuaDriver.app so TCC grants attribute correctly.
  ✅ tcc_accessibility: Accessibility is granted.
  ✅ tcc_screen_recording: Screen Recording is granted.

退出码 0 表示一切正常，1 表示有问题（每项失败会附修复建议），2 表示 cua-driver 二进制找不到。

启用方式

# 临时启用
hermes -t computer_use chat

# 永久启用（写进配置）
# 在 ~/.hermes/config.yaml 的 enabled_toolsets 里加 computer_use

安全机制

Agent 操控电脑听起来很危险，Hermes 设了多层防线：

破坏性操作要审批——点击、输入、拖拽等都需要你确认（CLI 弹窗或消息平台按钮）
硬封按键组合——清空废纸篓、强制删除、锁屏、登出
硬封输入模式——curl | bash、sudo rm -rf /、fork bomb 等
系统提示约束——Agent 被告知：不点权限对话框、不输密码、不执行截图里嵌入的指令

如果想要每一步都确认：

approvals:
  mode: manual

Token 优化

截图很贵。Hermes 用四层优化控制成本：

只保留最近 3 张截图在上下文里，旧的变成占位符
上下文压缩器检测多模态工具结果，剥掉旧结果的图片部分
每张图按 ~1500 token 估算（而非 base64 字符长度）
Anthropic 服务端上下文编辑，API 层面清理旧工具结果

一个 20 步操作的会话，1568×900 分辨率，大约消耗 30K token 的截图上下文，而不是 600K。

Warning

Computer Use 不支持键盘输入密码。密码要用系统自带的自动填充（macOS 钥匙串 / Windows 凭据管理器 / GNOME Keyring）。

图片生成

Hermes Agent 能从文字描述生成图片，通过 FAL.ai 提供 11 个模型。

支持的模型

模型	速度	特点	价格
`flux-2/klein/9b`（默认）	<1 秒	快，文字清晰	$0.006/MP
`flux-2-pro`	~6 秒	影棚级写实	$0.03/MP
`z-image/turbo`	~2 秒	中英双语，6B 参数	$0.005/MP
`nano-banana-pro`	~8 秒	Gemini 3 Pro，推理深度	$0.15/张
`gpt-image-1.5`	~15 秒	提示词遵循度高	$0.034/张
`gpt-image-2`	~20 秒	最强文字渲染 + 中日韩	$0.04–0.06/张
`ideogram/v3`	~5 秒	最佳排版	$0.03–0.09/张
`recraft/v4/pro`	~8 秒	设计、品牌系统	$0.25/张
`qwen-image`	~12 秒	LLM 式复杂文字	$0.02/MP
`krea/v2/medium`	~15-25 秒	插画、动漫	$0.030–0.035/张
`krea/v2/large`	~25-60 秒	写实、胶片质感	$0.060–0.065/张

配置

hermes tools    # 选 🎨 Image Generation → 选后端和模型

或者直接写配置：

image_gen:
  model: fal-ai/flux-2/klein/9b
  use_gateway: false          # true 则走 Nous Portal 订阅

API Key 写在 ~/.hermes/.env：

FAL_KEY=your-fal-api-key

Tip

如果你有 Nous Portal 付费订阅，不需要单独的 FAL Key。hermes setup --portal 一步搞定 LLM + TTS + 图片生成的全部认证。

图片编辑

同一个 image_generate 工具也能编辑现有图片——传入源图片，后端自动路由到编辑接口：

把这张照片改成东京雨夜街道 -> <图片>

不是所有模型都支持编辑。支持的包括 flux-2/klein/9b、flux-2-pro、nano-banana-pro、gpt-image-1.5、gpt-image-2、ideogram/v3、qwen-image。纯文生图模型（z-image/turbo、recraft、krea）会拒绝图片输入并给出错误提示。

宽高比

所有模型接受三种宽高比，Hermes 自动翻译成各模型的原生格式：

输入	效果
`landscape`	16:9 横向
`square`	1:1 正方形
`portrait`	9:16 纵向

多媒体能力的架构位置

把四种能力放在一起看，它们在架构中的位置不同：

入站（适配器层）：
  语音消息 → STT → 文字 → Agent
  图片消息 → 下载缓存 → 本地路径 → Agent

工具层（Agent 主动调用）：
  vision_analyze → 辅助视觉模型 → 文字描述
  text_to_speech → TTS 提供商 → MEDIA 标签
  computer_use → cua-driver → 桌面操作
  image_generate → FAL.ai → 图片 URL

出站（网关层）：
  MEDIA 标签 → 适配器 → 平台原生媒体消息

主模型全程只处理文字。 STT 在入口做（Agent 看到的是文字），视觉/操控/生成在工具层做（Agent 主动调用），TTS 在出口做（网关看到 MEDIA 标签后投递）。核心循环本身不碰任何多媒体格式。

这个设计意味着：不管你在 CLI、Telegram、Discord 还是 WhatsApp 上，Agent 的思考逻辑是一样的。平台差异全由适配器和网关吸收。

常见问题

CLI 语音提示 “No audio device found”

PortAudio 没装。brew install portaudio（macOS）或 sudo apt install portaudio19-dev（Linux）。

Discord Bot 加了语音频道但听不到我

检查三件事：

你的 Discord 用户 ID 在 DISCORD_ALLOWED_USERS 里
Bot 有 Connect 和 Speak 权限
你没静音，且加入后几秒内开始说话（Bot 需要收到 SPEAKING 事件才能映射你的音频）

Whisper 转出来全是乱码

幻觉过滤器能挡掉大部分，但如果还有问题：

换安静的环境
调高 silence_threshold（降低灵敏度）
换更高质量的 STT 模型

TTS 在 Telegram 上变成文件而不是语音气泡

你没装 ffmpeg，或者用的提供商不原生输出 Opus。要么装 ffmpeg，要么换成 OpenAI / ElevenLabs / Mistral（原生 Opus 输出）。

Computer Use 点了没反应

先跑 hermes computer-use doctor。最常见的原因是 macOS 上没给辅助功能权限，或者 Windows 上在 SSH 会话（Session 0）里跑而没有 autostart 模式。

图片粘贴在 SSH 里不工作

SSH 远程终端无法访问本地剪贴板。替代方案：上传图片文件用路径引用、用图片 URL、或通过 Telegram/Discord 发图片。