附录C：故障排查检查单
本附录提供一套可直接照着执行的排查清单，目标是先用最少命令把故障定位到层级，再进入对应章节深挖。排查顺序建议遵循从外到内：进程与配置、网关与渠道、模型与工具、会话与记忆。
C.1 启动失败检查
检查项：
运行时与依赖是否满足要求（Node、Docker 等）。
配置文件路径与语法是否正确（尤其是 JSON5 注释与尾逗号）。
典型报错:
SyntaxError: JSON5: invalid character '}' at 12:4
端口是否被占用。
典型报错:
EADDRINUSE: address already in use :::18789
密钥与令牌是否注入且有效。
常用命令示例：
# 体检与诊断（以实际 CLI 为准）
openclaw doctor
# 查看最近日志
openclaw logs --tail 200
# 端口占用
lsof -nP -iTCP -sTCP:LISTEN | head关联阅读：
C.2 渠道异常检查
检查项：
渠道令牌与权限是否有效。
典型报错:
[Telegram] Polling error: 401 Unauthorized
配对关系是否正确，是否存在未审批的配对请求。
典型报错:
[Gateway] Connection rejected: device 9f8a not paired
路由是否命中目标 Agent，会话归属是否稳定。
渠道状态与日志是否一致。
常用命令示例：
关联阅读：
C.3 工具异常检查
检查项：
是否触发工具治理策略拒绝，或权限不足被拦截。
典型报错:
ToolError: execute_bash denied by default policy
参数格式是否符合预期，是否缺字段或类型不匹配。
典型报错:
SchemaValidationError: missing required property 'amount'
执行环境是否具备权限与网络访问条件（沙箱策略是否收紧）。
工具回执是否成功结构化回注，是否因上下文裁剪而丢失关键信息。
典型表现: 日志提示
Max context window exceeded, discarding output of tool 'search_web'
常用命令示例：
关联阅读：
10.3 工具执行链路与结果回注
C.4 模型异常检查
检查项：
主模型是否限流、超时或认证失败。
典型报错:
ProviderError: 429 Too Many Requests (OpenAI)或401 Invalid API Key
是否触发回退链路，回退是否有证据链。
典型表现:
[WARN] Model gpt-5 timed out. Falling back to claude-sonnet-4-5
冷却或禁用状态是否生效，是否出现重试放大。
认证档案与密钥是否过期或被吊销。
常用命令示例：
关联阅读：
C.5 记忆与上下文异常检查
现象：“模型遗忘刚刚提到的信息”或“连续要求重复输入参数”。
检查项：
会话归属是否漂移（同一用户被分配到不同 sessionKey）。
诊断手段 ：用结构化日志按
sessionKey和traceId回放链路。
上下文预算是否打满，导致近期信息被裁剪。
诊断手段 ：观察日志中的裁剪/压缩事件与占位符频率。
会话存储文件是否可读写，是否发生写入失败。
诊断手段 ：检查
~/.openclaw/agents/<agentId>/sessions/sessions.json的更新时间与权限。
常用命令示例：
C.6 复验与完整流程
检查项：
修复后是否完成同场景复验，并回放关键 trace 做回归对比。
是否更新 Runbook、告警阈值与回退策略。
是否记录原因、处理动作、回滚点与证据链，便于复盘与审计。
关联阅读：
最后更新于