Agnes Harness 是一个面向 Forward Deployed Engineering（FDE）场景的可插拔智能体运行框架。当 daemon 启动失败、模型调用报错或会话打开卡住时，这篇 Agnes Harness 故障排查指南带你用doctor诊断命令、错误码对照表和运行时审计日志三件套，快速完成 Troubleshooting 定位。

先判断问题位置：4 大故障场景

排错的第一步不是敲命令，而是先分辨问题发生在哪个环节。官方排错文档把问题归为四类：

💡 排查前先记下：当前 commit、Node 版本、执行的命令、错误码和所用的 home/profile——不要输出整个环境或凭据。

完整对照表见 troubleshooting.zh-CN.md 与 troubleshooting.md。

30 秒环境快照：doctor 诊断命令速查

doctor是 Agnes Harness 内置的只读体检命令，覆盖platform、provider、storage、credentials、profile、extensions、daemon、binary、code-runtime十个检查段（定义见 doctor.ts）。故障时的标准开场动作：

node packages/cli/dist/local/agnes.mjs --version node packages/cli/dist/local/agnes.mjs daemon status node packages/cli/dist/local/agnes.mjs doctor platform --json node packages/cli/dist/local/agnes.mjs doctor storage --json node packages/cli/dist/local/agnes.mjs doctor provider --json

几条容易踩坑的读法：

• doctor platform会在每个低于full的能力下方输出<能力>.reason=…。看到sandbox.l1=unavailable且原因是awaiting sandbox backend full-boundary probe，说明沙箱后端只是尚未探测，并非平台不支持；真正的探测失败文案是no runnable OS sandbox backend passed its full-boundary probe。
• doctor storage只建立并清理临时探测数据库，不会修复现有数据。
• doctor provider --probe会真实调用模型（可能计费），排错时不要随手加上。
• 凭据目录权限不合格时，用doctor credentials做只读检查，它会列出每个不合格路径并给出可直接执行的chmod命令（详见 security.zh-CN.md）。

高频错误码实战对照表

Agnes Harness 的错误码是闭集：host 层固定 25 个（见 errors.ts），AI 装配层固定 6 个（见 errors.ts）。遇到报错先认码，再对下表动手：

读懂运行时状态：两个审计日志文件

错误现场之外，daemon 会在所选 dataDir 下写两个脱敏日志，是运行时状态排查的核心：

• audit/daemon.jsonl—— 请求审计：记录失败的请求和每个发起的批次。没有失败请求的行只代表"没有请求失败"，不代表 daemon 没有日志。
• audit/runtime.jsonl—— 运行日志：工作进程退出/启动失败、会话中断、每次会话打开耗时、daemon 启动/停止/崩溃。超过 2 MiB 前轮转为runtime.jsonl.1。

🕵️ 意外错误常附带diagnosticId，用它匹配audit/daemon.jsonl中的记录即可还原失败请求；若返回diagnosticUnavailable，说明审计写入失败，不能据此断定没有错误。

一个实用技巧：audit/runtime.jsonl中的detail.session不是会话 ID，而是其 SHA-256 的前 16 位。找某会话的记录时，用同样方式对 ID 求哈希即可命中。

会话打开慢时，比较session.load的ms.open/ms.authorityReplay/ms.acpReplay三项，再看对应session.open的ms.read、ms.verify、ms.fold构成——checkpoint.used: false且ms.verify很大，说明正在完整核对很长的历史（原理见 sessions.zh-CN.md · 历史完整性校验）。

排障清单：该做的 8 件事与 4 条红线

✅该做

1. 先跑--version和daemon status，确认版本与后台状态
2. 用doctor <段名> --json输出机器可读的诊断结果
3. 记下错误码 +diagnosticId，对照审计日志
4. 用doctor provider --probe（明确愿意计费时）验证模型链路
5. 版本切换前：结束任务、停止对应 daemon、备份自有数据（见 install.zh-CN.md）
6. 浏览器断线后先查后台历史确认最终状态，而不是盲目重发
7. 导入失败时保留输入与错误，用脱敏最小夹具复现
8. 需要更细的命令行参考时查 cli.zh-CN.md 的命令总表

🚫红线（不会让问题消失，只会让证据消失）

• 不删除 owner、锁、SQLite 数据库或回滚快照来"消除"错误
• 不通过修改产品安全策略绕过listen EPERM
• 不为绕过慢打开去复制或编辑数据库
• 不复制其他平台的单文件二进制混用

延伸阅读

• 完整排错对照表：troubleshooting.zh-CN.md
• 支持范围与已知限制：limitations.zh-CN.md
• 会话导出与导入：sessions.zh-CN.md
• 命令参考：cli.zh-CN.md