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

25. 排障、FAQ 与版本升级

本节目标：掌握 Hermes Agent 常见问题的排查方法，学会用 hermes update 安全升级和回滚，了解 hermes doctor 诊断工具，拿到一份实用技巧合集和学习路径导航。

用了这么多章，你大概已经碰到过一些报错。这一章把常见问题集中起来，给你排查思路和修复方法，顺便讲讲怎么安全升级、怎么用诊断工具、以及一些能让你更高效的实用技巧。

常见问题 FAQ

Hermes 支持哪些模型提供商？

任何兼容 OpenAI API 的服务都行。主流选择：

OpenRouter：一个 Key 访问几百个模型（灵活性最高）
Nous Portal：Nous Research 的订阅网关，300+ 模型加搜索/图像/TTS/浏览器，一次 OAuth 登录搞定
OpenAI：GPT-5.4、GPT-4o 等
Anthropic：Claude 系列
Google：Gemini 系列
本地模型：Ollama、vLLM、llama.cpp、SGLang 等兼容 OpenAI API 的本地服务

用 hermes model 设置，或直接编辑 ~/.hermes/.env。

我的数据会发送到哪里？

API 调用只发往你配置的 LLM 提供商。Hermes Agent 不收集遥测、使用数据或分析数据。你的对话、记忆和技能都存在本地 ~/.hermes/。

能离线用吗？能用本地模型吗？

能。用 hermes model 选 Custom endpoint，填本地服务器 URL：

hermes model
# 选 Custom endpoint
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 64000

配置文件方式：

model:
  default: qwen3.5:27b
  provider: custom
  base_url: http://localhost:11434/v1

Tip

Hermes 自动检测本地端点并放宽流式超时（读超时从 120 秒提到 1800 秒）。大上下文还超时就设 HERMES_STREAM_READ_TIMEOUT=1800。

要花钱吗？

Hermes Agent 本身免费开源（MIT 协议）。你只为 LLM API 用量付费。本地模型完全免费。

多人能用同一个实例吗？

能。消息网关让多个用户通过 Telegram、Discord、Slack、WhatsApp 等跟同一个 Hermes Agent 实例交互。通过允许列表和 DM 配对控制访问。

记忆和技能有什么区别？

记忆存事实—关于你、你的项目、你的偏好的信息，按相关性自动检索
技能存流程—怎么做事的分步指令，遇到类似任务时调用

两者都跨会话持久化。

常见报错与解决

安装类

`hermes: command not found`

原因：shell 没重新加载 PATH。

source ~/.bashrc    # bash
source ~/.zshrc     # zsh

# 或开个新终端

还不行就检查安装位置：

which hermes
ls ~/.local/bin/hermes

Tip

安装器把 ~/.local/bin 加到 PATH。如果你用非标准 shell 配置，手动加 export PATH="$HOME/.local/bin:$PATH"。

Python 版本太旧

Hermes 需要 Python 3.11 或更新。

python3 --version

sudo apt install python3.12   # Ubuntu/Debian
brew install python@3.12      # macOS

终端命令报 `node: command not found`

原因：Hermes 启动时跑一次 bash -l 建环境快照。bash 登录 shell 读 /etc/profile、~/.bash_profile、~/.profile，但不读 ~/.bashrc—所以装在 ~/.bashrc 里的工具（nvm、asdf、pyenv、cargo）对快照不可见。

解决：列出要额外 source 的文件：

terminal:
  shell_init_files:
    - ~/.zshrc                     # zsh 用户
    - ~/.nvm/nvm.sh                # 直接 nvm 初始化
    - /etc/profile.d/cargo.sh      # 系统级 rc 文件

模型类

`/model` 只显示一个提供商

原因：/model（会话内）只能切换已配置的提供商。只配了 OpenRouter 就只显示 OpenRouter。

解决：退出会话，用终端里的 hermes model 添加新提供商：

# 先退出 Hermes 会话（Ctrl+C 或 /quit）

# 跑完整的提供商设置向导
hermes model

想做什么	用什么
添加新提供商	`hermes model`（终端）
输入/改 API Key	`hermes model`（终端）
会话内切模型	`/model <name>`（会话内）
切到其他已配置提供商	`/model provider:model`（会话内）

API Key 不工作

# 检查配置
hermes config show

# 重新配置提供商
hermes model

# 或直接设置
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx

Warning

确保密钥和提供商匹配。OpenAI 的 Key 不能用在 OpenRouter 上，反过来也不行。检查 ~/.hermes/.env 里有没有冲突的条目。

模型不可用 / model not found

# 列出提供商可用模型
hermes model

# 设置有效模型
hermes config set HERMES_MODEL anthropic/claude-opus-4.7

# 或按会话指定
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct

速率限制（429 错误）

等一会重试。持续使用考虑：升级提供商套餐、换模型或提供商、用 hermes chat --provider <alternative> 路由到其他后端。

上下文长度超限

# 压缩当前会话
/compress

# 或开新会话
hermes chat

# 用更大上下文窗口的模型
hermes chat --model openrouter/google/gemini-3-flash-preview

如果第一次长对话就超限，可能是 Hermes 检测到了错误的上下文长度。检查启动行显示的 Context limit，手动设：

model:
  default: your-model-name
  context_length: 131072

终端类

命令被标记为危险

这是安全功能。看到提示时审查命令，输 y 批准。也可以让 Agent 用更安全的替代方案。

Note

这是设计行为—Hermes 永远不会静默执行危险命令。审批提示会显示确切要执行什么。

Docker 后端连不上

# 检查 Docker 是否运行
docker info

# 把用户加入 docker 组
sudo usermod -aG docker $USER
newgrp docker

# 验证
docker run hello-world

消息类

Bot 不回消息

# 检查网关是否运行
hermes gateway status

# 启动网关
hermes gateway start

# 查看日志
cat ~/.hermes/logs/gateway.log | tail -50

网关启动失败

# 安装消息网关依赖
cd ~/.hermes/hermes-agent && uv pip install -e ".[messaging]"

# 检查端口冲突
lsof -i :8080

# 验证配置
hermes config show

WSL 网关不断断开

原因：WSL 的 systemd 支持不可靠。

用前台模式代替 systemd：

# 方式 1：直接前台（最简单）
hermes gateway run

# 方式 2：tmux 保持（关终端不死）
tmux new -s hermes 'hermes gateway run'
# 重连：tmux attach -t hermes

# 方式 3：nohup 后台
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

macOS 网关找不到 Node.js / ffmpeg

原因：launchd 服务继承的 PATH 很小，不含 Homebrew 目录。

# 重新捕获当前 PATH
hermes gateway install
hermes gateway start

性能类

响应慢

试更快的模型：hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct
减少活跃工具集：hermes chat -t "terminal"
检查到提供商的网络延迟
本地模型确保 GPU 显存够

Token 消耗高

# 压缩对话减少 Token
/compress

# 检查会话 Token 用量
/usage

Tip

长会话里定期用 /compress。它总结对话历史，显著减少 Token 用量同时保留上下文。

版本升级

一键升级

hermes update

这条命令拉取 main 分支最新代码、更新依赖、提示你配置新增选项。

升级时发生的事：

预升级快照：默认保存轻量状态快照（配对数据、cron 任务、config.yaml、.env、auth.json 等）。受 updates.pre_update_backup 控制（quick 默认，full 完整 zip，off 关闭）
Git pull：拉取 main 分支最新代码并更新子模块
语法验证 + 自动回滚：拉取后编译八个关键文件。如果任何一个解析失败，自动 git reset --hard <pre-pull-sha> 回滚，保证 shell 可启动
依赖安装：跑 uv pip install -e ".[all]" 拿新依赖
配置迁移：检测新增配置项并提示设置
网关自动重启：运行中的网关更新后自动刷新

Note

升级忽略 SIGHUP，关 SSH 会话或终端窗口不会中断升级。所有输出同时写入 ~/.hermes/logs/update.log。终端断了可以重连后查看日志确认升级是否完成。

预览是否有更新

hermes update --check

只获取并比较提交，不修改文件，不重启网关。适合脚本和 cron 里判断”有没有更新”。

完整备份后升级

高价值 Profile（生产网关、团队共享安装）可以选完整备份：

hermes update --backup

或设为默认：

updates:
  pre_update_backup: full

从消息平台升级

在 Telegram、Discord、Slack、WhatsApp 或 Teams 里发：

/update

会拉取最新代码、更新依赖、重启网关。Bot 重启期间短暂离线（通常 5-15 秒）。

Windows 上的特殊情况

Windows 上如果检测到另一个 hermes.exe 在跑，升级会拒绝执行：

✗ Another hermes.exe is running:
    PID 12345  hermes.exe

  Close Hermes Desktop, exit any open `hermes` REPLs, and
  stop the gateway (`hermes gateway stop`) before retrying.

关掉列出的进程后重试。确认不冲突可以 hermes update --force 跳过检查。

升级后验证

git status --short—如果树意外脏了，先检查
hermes doctor—检查配置、依赖和服务健康
hermes --version—确认版本号如预期更新
如果用网关：hermes gateway status
如果 doctor 报 npm audit 问题：在标记的目录跑 npm audit fix

回滚

如果升级引入问题：

cd /path/to/hermes-agent

# 查看最近的版本
git log --oneline -10

# 回到之前的提交
git checkout <commit-hash>

# 重新安装依赖
uv pip install -e ".[all]"

# 检查配置
hermes config check

hermes doctor 诊断

hermes doctor 是内置的诊断工具，检查配置、依赖和服务健康：

hermes doctor

加 --fix 尝试自动修复能修的问题：

hermes doctor --fix

hermes dump：可分享的配置摘要

报 bug 或求助时，用 hermes dump 输出一份纯文本的配置摘要，方便粘贴到 Discord、GitHub Issue 或 Telegram：

hermes dump

输出包含：

部分	内容
Header	Hermes 版本、发布日期、git 提交
Environment	OS、Python 版本、OpenAI SDK 版本
Identity	活跃 Profile、HERMES_HOME 路径
Model	配置的默认模型和提供商
Terminal	后端类型（local、docker、ssh 等）
API keys	22 个提供商/工具 API Key 的存在性检查
Features	启用的工具集、MCP 服务器数、记忆提供商
Services	网关状态、配置的消息平台
Workload	cron 任务数、已安装技能数
Config overrides	任何偏离默认值的配置

加 --show-keys 显示密钥的脱敏前缀（首尾各 4 字符）：

hermes dump --show-keys

实用技巧合集

提问要具体

“修代码”太模糊。说”修 api/handlers.py 第 47 行的 TypeError—process_request() 函数从 parse_body() 收到 None”。给的上下文越多，来回越少。

用 AGENTS.md 存重复指令

发现自己总在重复”用 tab 不用空格""我们用 pytest""API 在 /api/v2”—放进 AGENTS.md。Agent 每次会话自动读，设完就不用管了。

# Project Context
- 这是 FastAPI 后端 + SQLAlchemy ORM
- 数据库操作一律用 async/await
- 测试放 tests/，用 pytest-asyncio
- 永远不提交 .env 文件

让 Agent 用工具

别手把手指挥每一步。说”找到并修复失败的测试”而不是”打开 tests/test_foo.py，看第 42 行，然后…”。Agent 有文件搜索、终端、代码执行—让它自己探索。

CLI 快捷键

Alt+Enter / Ctrl+J / Shift+Enter：换行不发送
Ctrl+V：粘贴剪贴板图片，Agent 用视觉分析
Ctrl+C（按一次）：中断响应，可以输新消息重定向
Ctrl+C（2 秒内按两次）：强制退出
/ + Tab：斜杠命令自动补全

别破坏提示缓存

大多数 LLM 提供商缓存对话前缀（系统提示 + 历史）。保持系统提示稳定（相同上下文文件、相同记忆），后续消息命中缓存显著更便宜。切模型、提供商回退、凭据池轮换都会强制下一轮重新读整个对话，全价输入。

定期压缩和检查用量

/compress    # 压缩对话历史
/usage       # 查看 Token 用量
/insights    # 查看 30 天用量模式

用 delegate_task 做并行

同时研究三个主题？让 Agent 用 delegate_task 跑并行子任务。每个子 Agent 独立运行，只把摘要带回来，大幅减少主对话的 Token 消耗。

给会话起名字

/title auth-refactor

命名后容易找到和恢复：hermes -r "auth-refactor"。不命名的会话会堆成无法区分的一坨。

学习路径与资源

按经验等级

等级	目标	推荐阅读	时间
入门	跑起来、基本对话、用内置工具	安装 -> 快速开始 -> CLI 用法 -> 配置	~1 小时
进阶	设置消息 Bot、记忆、cron、技能	会话 -> 消息 -> 工具 -> 技能 -> 记忆 -> Cron	~2-3 小时
高级	自定义工具、创建技能、RL 训练、贡献项目	架构 -> 添加工具 -> 创建技能 -> 贡献	~4-6 小时

按使用场景

“我要 CLI 编程助手”：安装 -> 快速开始 -> CLI 用法 -> 代码执行 -> 上下文文件 -> 技巧

“我要 Telegram/Discord Bot”：安装 -> 配置 -> 消息概览 -> Telegram 设置 -> Discord 设置 -> 语音模式 -> 安全

“我要自动化任务”：快速开始 -> Cron 调度 -> 批处理 -> 委托 -> Hooks

“我要做自定义工具/技能”：插件 -> 构建插件 -> 工具概览 -> 技能概览 -> MCP -> 架构 -> 添加工具 -> 创建技能

“我要当 Python 库用”：安装 -> 快速开始 -> Python 库指南 -> 架构 -> 工具 -> 会话

关键资源

GitHub 仓库：github.com/NousResearch/hermes-agent
官方文档：Hermes Agent 官方文档站
GitHub Releases：查看最新版本和更新日志
Nous Research Discord：社区交流，#plugins-skills-and-skins 频道分享插件

常用诊断命令速查

命令	用途
`hermes doctor`	诊断配置和依赖问题
`hermes doctor --fix`	自动修复能修的问题
`hermes dump`	输出可分享的配置摘要
`hermes config show`	查看当前配置
`hermes config check`	检查缺失的配置项
`hermes config migrate`	交互式添加缺失配置
`hermes version`	查看当前版本
`hermes gateway status`	检查网关状态
`hermes update --check`	检查是否有更新
`hermes prompt-size`	查看系统提示大小分解

这是教程的最后一章。25 章从认识 Hermes Agent 开始，经过安装、配置、核心机制、工具系统、记忆、技能、消息平台，到委托编排、MCP 扩展、检查点、语音视觉、部署进阶、可视化管理、安全，最后回到排障和升级—形成了一个完整的知识闭环。

Hermes Agent 是一个在快速迭代中的开源项目。这篇教程以 v2026.7.20 为基准，但具体功能细节可能会随版本更新而变化。遇到跟教程描述不一致的地方，优先参考官方文档和 hermes --help 的最新输出。祝你和你的 Agent 合作愉快。

排障、FAQ 与版本升级

25. 排障、FAQ 与版本升级

常见问题 FAQ

Hermes 支持哪些模型提供商？

我的数据会发送到哪里？

能离线用吗？能用本地模型吗？

要花钱吗？

多人能用同一个实例吗？

记忆和技能有什么区别？

常见报错与解决

安装类

hermes: command not found

Python 版本太旧

终端命令报 node: command not found

模型类

/model 只显示一个提供商

API Key 不工作

模型不可用 / model not found

速率限制（429 错误）

上下文长度超限

终端类

命令被标记为危险

Docker 后端连不上

消息类

Bot 不回消息

网关启动失败

WSL 网关不断断开

macOS 网关找不到 Node.js / ffmpeg

性能类

响应慢

Token 消耗高

版本升级

一键升级

预览是否有更新

完整备份后升级

从消息平台升级

Windows 上的特殊情况

升级后验证

回滚

hermes doctor 诊断

hermes dump：可分享的配置摘要

实用技巧合集

提问要具体

用 AGENTS.md 存重复指令

让 Agent 用工具

CLI 快捷键

别破坏提示缓存

定期压缩和检查用量

用 delegate_task 做并行

给会话起名字

学习路径与资源

按经验等级

按使用场景

关键资源

常用诊断命令速查

`hermes: command not found`

终端命令报 `node: command not found`

`/model` 只显示一个提供商