Question 1

Windows 一定要装 WSL2 吗？（原生系统能直接跑吗？）

Accepted Answer

能。原生 Windows 目前不受支持，官方文档明确推荐通过 WSL2 运行 Hermes。安装 WSL2 后，在 Ubuntu 终端内执行官方的 curl | bash 一键安装脚本即可。如果有 Termux/Android 设备，也可以尝试在移动端运行。

Question 2

`官方一键安装脚本会做什么？需要手动装 Python 和 Node.js 吗？`

Accepted Answer

不需要。官方脚本会自动安装 Python 3.11、Node.js v22、ripgrep、ffmpeg、uv 等所有依赖，并创建虚拟环境、设置全局 hermes 命令。唯一前置条件是系统已安装 Git。

Question 3

`curl 安装脚本下载失败或中断怎么办？`

Accepted Answer

首先检查网络是否能访问 GitHub。也可以手动下载脚本后本地运行：curl -o install.sh https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh 然后 bash install.sh。脚本支持幂等安装，中断后重新运行即可。

Question 4

`hermes setup` 卡住了怎么办？

Accepted Answer

某些终端输入法可能与交互式向导不兼容。你可以按 Ctrl+C 退出后，手动编辑 ~/.hermes/config.yaml 创建初始配置，然后 Day 2 再补 API key。

Question 5

Fast Mode 是什么？

Accepted Answer

v0.9 新增的 hermes --fast 参数。开启后 Hermes 会绕过闲聊式对话，直接尝试执行你的第一个任务，适合快速验证安装和配置是否正常。

Question 6

Android 上运行 Hermes 会不会被杀后台？

Accepted Answer

可能会。建议将 Termux 设为无限制电池策略，并在运行 gateway 时执行 termux-wake-lock 保持唤醒。

Question 7

没有 OpenAI API key 怎么办？（国产模型接入方案）

Accepted Answer

Hermes 支持多种模型提供商，你可以使用 Anthropic Claude、OpenRouter、阿里通义千问、智谱 AI 等国产模型。只需在 config.yaml 中更换对应的 base_url 和 api_key。v0.9 推荐使用 hermes auth add <provider> 存储密钥。

Question 8

API key 迁移后无法调用是什么原因？

Accepted Answer

可能是 key 格式不兼容或 base_url 丢失。运行 hermes auth list 查看是否导入成功，并手动检查 ~/.hermes/config.yaml 补全 base_url。

Question 9

回复为空或报错 429 怎么办？

Accepted Answer

表示遇到速率限制，建议换 provider 或在 config.yaml 中设置 fallback_model。

Question 10

迁移后 Telegram bot 为什么不回复？

Accepted Answer

请检查 webhook 地址是否更新为 Hermes 的服务地址，并确认 BotFather 中的 token 仍然有效。如果是轮询方式，请确保没有其他服务在占用该 token。也可以用 /debug 查看连接状态。

Question 11

飞书机器人配置时 webhook 报错怎么办？

Accepted Answer

检查事件订阅里是否已正确勾选“消息”事件，确认 webhook 地址使用 HTTPS，并且服务器能够正常访问飞书的推送服务。

Question 12

v0.9 新增了哪些平台？

Accepted Answer

除了 Telegram 和飞书，还支持 Discord、Slack、WhatsApp、Signal、Matrix、Email、Home Assistant、Mattermost、钉钉、企业微信、BlueBubbles、SMS 等。

Question 13

`hermes backup` 会备份我的代码仓库吗？

Accepted Answer

不会。hermes backup 会自动跳过 hermes-agent 源码目录和 __pycache__，只备份配置、状态、技能和记忆。

Question 14

`watch_patterns` 支持正则吗？

Accepted Answer

支持子串匹配和部分正则。如果日志输出频繁，系统会自动限流（每 10 秒最多 8 条通知），持续过载会关闭 watch 以保护性能。

Question 15

`/debug` 能看到什么？

Accepted Answer

当前 session 使用的模型、provider 连接状态、各平台 gateway 是否在线、最近 5 条错误摘要和推荐修复命令。

Question 16

如何从 v0.8.x 升级到 v0.9.x？

Accepted Answer

三步：1) 运行 hermes update；2) hermes --version 确认版本；3) 如配置文件格式有变化，运行 hermes setup 自动迁移。

Question 17

如何更新 Hermes 到最新版本？

Accepted Answer

使用 hermes update 即可一键更新到最新版本。更新后建议检查 hermes --version 确认版本。

常见问题

安装与启动

模型与 API

平台与机器人

迁移与升级