18. 调试与排障：日志、doctor、status、常见错误怎么查

这篇解决什么问题

Hermes 出问题时，不要先猜。

先判断问题发生在哪一层：配置、模型、工具、Gateway、Cron、MCP、文件权限，还是项目代码本身。

先跑 doctor 和 status

最基础命令：

hermes doctor
hermes status
hermes config check

如果是工具不可用，再看：

hermes tools list

如果是模型或 provider 问题：

hermes model
hermes auth list

看配置路径

先确认 Hermes 读的是哪个配置：

hermes config path
hermes config env-path

Profile 场景下尤其重要。你以为改的是默认 profile，实际运行的是另一个 profile，就会出现“明明改了但不生效”。

Gateway 问题怎么查

Gateway 相关问题先看日志：

~/.hermes/logs/gateway.log

再看平台状态：

/platforms
/status

常见问题包括：

• 平台 token 失效；
• bot 没权限；
• gateway 没重启；
• home channel 没设置；
• 消息被平台限制；
• provider 错误被 gateway 过滤。

Cron 问题怎么查

先看：

hermes cron list
hermes cron status

再看输出目录：

~/.hermes/cron/output/<job_id>/

如果任务显示失败，先分清：

调度没触发
触发了但模型失败
模型成功但工具失败
任务完成但投递失败

不要一看到 cron 失败就改 schedule。

模型 401 / 429 / 402

这类错误一般不是任务逻辑问题。

401：API key / OAuth 失效
429：限流
402 或 billing：余额、订阅、额度问题
model not found：模型名或 provider 不匹配

处理顺序：

hermes auth list
hermes auth add <provider>
hermes model
hermes doctor

工具不可用

工具不出现，通常看三点：

toolset 是否启用
check_fn 是否通过
依赖环境变量或外部程序是否存在

例如 browser、tts、mcp、homeassistant 都可能因为依赖缺失而不出现在 schema。

MCP 连接问题

MCP 先看：

~/.hermes/logs/mcp-stderr.log

再检查：

mcp_servers 配置
command / args 是否能独立运行
env 是否传入
connect_timeout 是否太短
远程 url / headers 是否正确

如果 MCP server 启动时往 stderr 输出大量日志，Hermes 会把它重定向到日志文件，避免污染 TUI。

源码改动后怎么验证

如果改的是这个 future-observer-web 文档站：

npm run build

如果改 Hermes 本体，至少先跑相关测试或命令：

hermes doctor
hermes chat -q "hello"

具体测试命令要看改动范围。

一个排障原则

按层排：

配置 → 认证 → 模型 → 工具暴露 → 工具执行 → Agent loop → Gateway/Cron 投递

不要从最复杂的 Agent loop 开始猜。

下一篇看什么

下一篇看二开路线。

知道怎么排障后，就可以更稳地改功能。