Adolanium/hermes-gadget-sdk · 上手攻略

  • 仓库：Adolanium/hermes-gadget-sdk
  • 链接：https://github.com/Adolanium/hermes-gadget-sdk
  • 分类：AI Agent 硬件 / 设备 SDK
  • 作者：Tom
  • 更新：2026-10-08

是什么

Hermes Gadget SDK 是一个为 Hermes Agent 配套的设备端开发包，让你把 ESP32-S3 开发板、Raspberry Pi 4/5，或者纯桌面模拟器，变成一个可以按住说话、放开发送、听到 AI 回答的实体对话设备。

它的核心设计哲学是设备保持轻薄：语音识别、语音合成、LLM 推理全部跑在主机侧（树莓派或电脑），设备只负责音频采集、屏幕渲染和播放。项目自称与 Nous Research 没有官方隶属关系，属于社区独立项目，但完整兼容 Hermes Agent 的工具、记忆和技能系统。

解决什么问题

如果你想做一个「能随时按住说话的 AI 设备」，面临的选择通常是：

  • 买现成产品，但无法定制工具或行为
  • 自己从头做，需要处理音频 Pipeline、WebSocket 协议、LLM 接口等复杂工作
  • 接 API，但要自己搞定语音识别和 TTS

Hermes Gadget SDK 把这些问题打包了：预编译固件直接 USB 刷入，支持 Wi-Fi 配网，配对后自动把设备的 LED、传感器、按钮暴露为 Agent 工具，无需刷固件的工具链。

快速安装

桌面模拟器（无需硬件）

# Python 3.10+, CMake 3.16+, C++17 编译器
python -m pip install -e ".[dev]"

# 终端 1：启动配对服务器
hermes-gadget build-sim --test
hermes-gadget devserver --pairing

# 终端 2：启动模拟器（在服务器终端输入 approve <CODE> 后）
hermes-gadget sim --url ws://127.0.0.1:8765/gadget --board sim-466x466-round

⚠️ 配对码在设备屏幕上显示，输入 approve <CODE> 完成配对。

物理板子（预编译固件，无需编译工具链）

  1. 打开浏览器访问 https://adolanium.github.io/hermes-gadget-sdk/installer.html
  2. 用 Chrome/Edge 连接 USB，选择板子型号
  3. 连接 2.4GHz Wi-Fi，配对 Hermes Agent

支持的硬件型号（截至本文）：ESP32-S3 系列（多种屏幕分辨率）、Raspberry Pi 4/5（64-bit Raspberry Pi OS Lite Trixie）。硬件端口仍为实验性，建议先查 hardware-validation.md 确认。

连接真实 Hermes Agent

# 在设备配对完成后，配置 Hermes 的 gadget 插件
# 参考：https://github.com/Adolanium/hermes-gadget-sdk/blob/main/docs/connect-hermes.md

核心用法

设备交互模式

  • 按住说话（Push-to-Talk）：按住 TALK 键说话，松开自动发送
  • 屏幕显示：实时展示设备状态（Ready / Listening / Thinking / Speaking）
  • 打断：对话中途可以再次按住键中断 AI 答复
  • 文本输入：也支持直接在模拟器打字

设备端暴露为 Agent 工具

一旦配对，设备的 LED、传感器、按钮等会自动暴露为 gadget_* 前缀的 Agent 工具，可以在 Hermes Agent 的 prompt 里直接调用。

OTA 固件更新

首次刷入后，后续固件更新通过 Wi-Fi 自动 OTA，不再需要 USB。更新失败会自动回滚。

远程访问（可选）

可以用 Tailscale Funnel 把本地 Hermes 暴露到外网，实现远程设备控制（参见 tailscale-funnel.md）。

典型适用场景

  1. 桌面对话终端：不想开电脑，用一个实体设备随时问 AI 问题
  2. 语音操控 Home Assistant：配合 Linux Gadget + MQTT，把设备变成家庭自动化控制面板
  3. AI 原型硬件：快速验证「语音 + 实体设备 + Agent 工具」组合的体验
  4. 开发者硬件调试：用模拟器跑自动化测试，不需要真机

坑与注意

  1. 语音识别/TTS 需额外配置：「Talk and listen」模式需要 speech recognition + TTS 配置好才能工作，裸固件只有脚本演示回复
  2. 硬件端口实验性：标为 experimental，不同板子 revision 可能表现不一致
  3. Wi-Fi 只支持 2.4GHz：很多开发板不支持 5GHz Wi-Fi
  4. Chrome/Edge 限定刷固件：浏览器安装器仅支持 Chrome 和 Edge
  5. 无 Wake-word：没有语音唤醒，需要按住物理键激活
  6. Linux 端 sudo 依赖：Linux gadget 安装需要 sudo 权限来运行 systemd oneshot
  7. 与 Hermes 解耦运行：模拟器 demo 模式下可以用脚本回复，不需要真实 Agent 连接

与同类对比

Hermes Gadget SDK Pipecat LiveKit Agents SDK
定位 实体硬件 + Agent 配套 语音 AI 框架 实时语音 Agent
硬件 ESP32 / Pi / 模拟器 任意设备 任意设备
协议 WebSocket + JSON/binary WebRTC WebRTC
依赖平台 Hermes Agent 多后端 LiveKit
固件编译 可选（dev） N/A N/A
工具暴露 gadget_* 工具自动暴露 手动 手动
上手门槛 中（硬件采购） 中 中

Hermes Gadget 的独特优势是绑定 Hermes Agent 的完整工具生态，以及预编译固件直接刷入的低门槛；缺点是依赖 Hermes，不像 Pipecat/LiveKit 那样支持多种后端。

一句话推荐结论

如果你是 Hermes Agent 用户，想要一个实体语音对话设备（而非纯软件），Hermes Gadget SDK 是目前门槛最低的方案——预编译固件 USB 刷入，Wi-Fi 配网，配对即用；如果你用的是其他 Agent 平台，它不适用。