【Hermes入门11讲】第十一讲：故障排查与最佳实践

最后一讲，把我踩过的坑和总结的经验全倒出来。看完这讲，你基本上能独立解决90%的问题。

故障排查顺序

遇到问题不要慌，按这个顺序排查：

复制代码

hermes doctor → hermes model → hermes setup → hermes sessions list

第一步：hermes doctor

复制代码

hermes doctor

这条命令会自动检查：

• 安装是否完整
• 配置有没有问题
• 模型提供商是否正常
• 工具是否能用
• 磁盘空间够不够

出问题了它会给出明确的修复建议，跟着做就行。

第二步：hermes model

如果doctor没发现问题，大概率是模型配置不对：

复制代码

hermes model

重新选一下模型，确认：

• 提供商选对了
• API key有效（没过期、没用完额度）
• 模型名称正确

常见坑：API key前面多了个空格、复制的时候少了一个字符、key被重置了。重新复制粘贴一遍往往就好了。

第三步：hermes setup

前两步都不行，重新跑设置向导：

复制代码

hermes setup

这会重新走一遍配置流程，把可能配错的地方重置。

第四步：hermes sessions list

如果之前能聊，突然不能了：

复制代码

hermes sessions list

看看会话状态是否正常。有时候会话文件损坏，恢复不了，用 hermes --new 新开一个就好。

常见问题速查

问题1：Hermes回复空内容或报错

原因：模型提供商配置有问题（key错误、模型不可用、网络不通）

解决：

复制代码

hermes model    # 重新选择

如果用的是国内模型，检查能不能直连。Claude/OpenAI这些国外模型，国内需要代理。

问题2：工具不工作（比如不能搜索网页）

原因：

1. 工具集没启用：hermes tools 检查
1. API key没配：web工具需要 FIRECRAWL_API_KEY 或 TAVILY_API_KEY
1. key用完了或过期了

解决：

复制代码

hermes tools                    # 确认工具集启用了
hermes config set FIRECRAWL_API_KEY xxx   # 重新配key

问题3：上下文满了，开始忘事

现象：聊到一半，Hermes突然忘了前面的内容；或者回复质量明显下降。

解决：

复制代码

❯ /compress          # 压缩上下文
❯ /usage             # 查看具体占用

长期解决：换个大上下文模型，或者调低压缩阈值：

复制代码

compression:
  threshold: 0.40    # 更早触发压缩

问题4：网关启动但收不到消息

原因：

1. Bot Token配错了
1. 平台设置不完整（比如Telegram的webhook）
1. 防火墙挡住了
1. Hermes没权限访问平台API

解决：

复制代码

hermes gateway setup    # 重新配置
hermes gateway status   # 查看状态

问题5：Hermes执行危险命令前不问我

原因：审批模式关掉了

解决：

复制代码

hermes config set approvals.mode manual

问题6：定时任务不执行

原因：

1. 网关没运行
1. 任务被暂停了
1. 时间格式写错了

解决：

复制代码

hermes gateway status    # 确认网关运行中
hermes cron list         # 检查任务状态
hermes cron run 任务名    # 手动触发测试

问题7：装了技能但调不出来

原因：

1. 技能没安装成功
1. 技能名记错了
1. 技能有平台限制（比如macOS专用）

解决：

复制代码

hermes skills list       # 看看到底装上了没
❯ /skills               # 在对话里列出可用技能

问题8：恢复会话失败

原因：

1. 切换了profile（配置集）
1. 会话文件损坏
1. 换了一台机器

解决：

复制代码

hermes sessions list                    # 列出所有会话
hermes --resume 20260225_143052_a1b2c3  # 用ID恢复

成本控制技巧

用久了账单会涨，几个省钱方法：

1. 按场景选模型

场景	推荐模型	原因
日常闲聊	DeepSeek / GLM	便宜够用
写代码	Kimi / Claude	代码能力强
复杂分析	Claude Opus	推理能力最强
辅助任务	Gemini Flash	又快又便宜

2. 用Fallback降成本

主模型用贵的，fallback配便宜的：

复制代码

fallback_providers:
  - provider: deepseek
    model: deepseek-chat

3. 精简工具集

只开需要的工具，减少每次请求的token消耗：

复制代码

hermes tools    # 关掉不用的

4. 定时任务用便宜的模型

在config.yaml里给辅助任务单独配模型：

复制代码

auxiliary:
  compression:
    provider: openrouter
    model: google/gemini-2.5-flash   # 压缩用便宜的

安全最佳实践

1. API key别泄露

.env 文件里的key是敏感信息：

• 别上传到GitHub
• 别截图发朋友圈（打码也不安全）
• 定期轮换key

2. 远程操作开审批

复制代码

approvals:
  mode: manual    # 或 smart

3. 网关配白名单

复制代码

gateway:
  allowed_users:
    - telegram:你的ID

4. 容器隔离

不信任的命令用Docker后端执行：

复制代码

hermes config set terminal.backend docker

5. 定期备份

复制代码

hermes backup    # 备份配置、记忆、会话

进阶技巧

同时开多个Hermes

用profile隔离不同场景：

复制代码

hermes -p work     # 工作profile
hermes -p personal # 个人profile

每个profile有独立的配置、记忆、会话。

工作树隔离

复制代码

hermes -w    # 在独立的git worktree里运行

适合让Hermes做代码改动，不影响主分支。

批量查询

复制代码

hermes chat -q "你的问题"    # 单轮查询，非交互式

适合脚本里调用，或者快速问个问题。

查看日志

复制代码

hermes logs      # 查看日志
hermes logs -f   # 实时跟踪

日志里的API key会自动打码，可以放心分享。

社区资源

遇到问题自己搞不定？

• GitHub Issues：https://github.com/NousResearch/hermes-agent/issues
• Discord社区：https://discord.gg/NousResearch
• 官方文档：https://hermes-agent.nousresearch.com/docs/

发issue的时候带上 hermes doctor 的输出，维护者能更快定位问题。