21. 故障排除

以症状为索引的参考。对每个问题:看到什么、最可能的原因、先试什么。

21.1 智能体不回复

可能 —— 网关挂了、通道 adapter 坏了、模型凭证丢失或被轮换走。

怎么查

  1. hermit doctor —— 看到网关的基本连通性。
  2. Manage → Channels —— 通道是否启用,有没有 missing-secret 警告?
  3. 试试 Web UI:如果 Web 能用、Telegram 不行,问题在通道而不是智能体。
  4. Observe 选项卡 —— 会话里是不是有模型错误?

21.2 工具调用反复失败

可能 —— 凭证过期、MCP 服务崩了、参数 schema 漂移、策略 deny。

怎么查

  1. 在 Observe 展开失败的调用。错误信息通常很具体。
  2. 与凭证有关 → 轮换密钥,重启 MCP 服务(hermit mcp disable + enable)。
  3. 与 schema 有关 → 看看 MCP 服务版本是不是变了。
  4. 与 deny 有关 → 看 Policy,可能有规则没明显提示地把它拦下了。

智能体 runner 在连续 15 次工具失败后会中止本轮以防止死循环;这次中止本身也会出现在 Observe 里。

21.3 记忆没记住

可能 —— 智能体没把它判断为可持久化事实,或者记忆工具被策略 deny。

怎么查

  1. 问智能体:“你记得关于 <主题> 的什么?” 空就是没存下。
  2. 显式重试:“请记住 <事实>。” 最可靠的强制写入方式。
  3. 看策略里有没有规则在拦 memory_* 工具。

21.4 新建的任务从不触发

可能 —— cron 时区不对、到点时网关挂了、任务建在了错的智能体上。

怎么查

  1. hermit schedules list --agent <id> —— 确认任务在对的智能体上。
  2. 看 cron —— UTC 是默认;如果你写的是本地时间表达式,它会按对应的 UTC 时间触发。
  3. 该智能体的 Observe —— 在预期时间出现过会话吗?

21.5 某人能做不该做的事

可能 —— 角色错了(误升级),或策略缺规则。

怎么查

  1. 管理界面 Users 选项卡,或以 owner 调 user_list —— 确认他的角色。
  2. hermit config --agent <id> policy list —— 对他角色的相应 deny 规则在不在?
  3. 用身份模拟来测:在 Web 上以他的身份登录(或用一个测试 guest 身份),复现。

21.6 Web UI 显示的是旧数据

可能 —— 浏览器缓存,或者网关重启后构建不匹配。

怎么查

  1. 强制刷新(Cmd-Shift-R / Ctrl-Shift-R)。
  2. 如果 UI 来自过时构建(运维刚升级),可能需要让运维重建静态资源。

21.7 CLI 说”未认证”

可能 —— 本地配置里没有这个网关的凭证,或者网关 URL 不对。

怎么查

  1. 再跑 hermit setup —— 重新填网关 URL 和 token。
  2. hermit doctor —— 应当全绿。

21.8 我上传的文件不见了

可能 —— 你上传到了另一个智能体,或者沙箱路径与你预期不一致。

怎么查

  1. 问智能体:“列出你工作区里的文件。”
  2. 确认你上传到的智能体和你现在问的是同一个。按智能体隔离是彻底的。

21.9 智能体在不同会话之间自相矛盾

可能 —— 一个会话里更新了记忆而另一个没,或者两条记忆条目冲突。

怎么查

  1. 问:“你关于 <主题> 记得什么?把所有相关条目都列出来。”
  2. 让它整合:“这两条冲突。正确的是 X。请相应更新。“

21.10 什么时候转交给运维

  • 跨智能体都持续存在的网关级错误。
  • 网关级密钥(模型 provider key)需要轮换。
  • 需要安装新的 MCP 服务。
  • 工作区存储满了。
  • 备份、升级、证书续签 —— 用户层之下的事。

21.11 指引

  • 上面提到的任何特性的具体章节都能通过 目录 找到。
  • 更高层的常见问题 → 第 22 章 · FAQ。