# 附录C：故障排查检查单

本附录提供一套可直接照着执行的排查清单，目标是先用最少命令把故障定位到层级，再进入对应章节深挖。排查顺序建议遵循从外到内：进程与配置、网关与渠道、模型与工具、会话与记忆。

## C.1 启动失败检查

检查项：

1. 运行时与依赖是否满足要求（Node、Docker 等）。
2. 配置文件路径与语法是否正确（尤其是 JSON5 注释与尾逗号）。
   * **典型报错**: `SyntaxError: JSON5: invalid character '}' at 12:4`
3. 端口是否被占用。
   * **典型报错**: `EADDRINUSE: address already in use :::18789`
4. 密钥与令牌是否注入且有效。

常用命令示例：

```bash
# 体检与诊断（以实际 CLI 为准）
openclaw doctor

# 查看最近日志
openclaw logs --limit 200

# 端口占用
lsof -nP -iTCP -sTCP:LISTEN | head
```

关联阅读：

* [2.4 守护进程与可用性验收](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/02_setup/2.4_gateway_service)
* [4.1 openclaw.json 结构与配置优先级](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/04_config_models/4.1_config_system)

## C.2 渠道异常检查

检查项：

1. 渠道令牌与权限是否有效。
   * **典型报错**: `[Telegram] Polling error: 401 Unauthorized`
2. 配对关系是否正确，是否存在未审批的配对请求，或 Control UI 设备身份尚未建立。
   * **典型报错**: `[Gateway] Connection rejected: device 9f8a not paired`
3. 路由是否命中目标 Agent，会话归属是否稳定。
4. 渠道状态与日志是否一致。

常用命令示例：

```bash
openclaw channels status
openclaw logs --limit 200
```

关联阅读：

* [3.2 常用诊断命令与日志排障](https://yeasy.gitbook.io/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/03_minimal_loop/3.2_diagnostics)
* [9.5 渠道配对与本地信任建立](https://yeasy.gitbook.io/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/09_gateway_protocol/9.5_pairing_trust)

## C.3 工具异常检查

检查项：

1. 是否触发工具治理策略拒绝，或权限不足被拦截。
   * **典型报错**: `ToolError: execute_bash denied by default policy`
2. 参数格式是否符合预期，是否缺字段或类型不匹配。
   * **典型报错**: `SchemaValidationError: missing required property 'amount'`
3. 执行环境是否具备权限与网络访问条件（沙箱策略是否收紧）。
4. 工具回执是否成功结构化回注，是否因上下文裁剪而丢失关键信息。
   * **典型表现**: 日志提示 `Max context window exceeded, discarding output of tool 'search_web'`

常用命令示例：

```bash

# 按 trace_id 回放工具链路

cat /tmp/openclaw/openclaw-YYYY-MM-DD.log | jq -c 'select(.type=="log") | .log | select(.trace_id=="t-...") | {ts,event,tool,err_type,cost_ms}'
```

> **注**：实际日志路径由 `logging.file` 配置决定，默认为 `/tmp/openclaw/openclaw-YYYY-MM-DD.log`

关联阅读：

* [5.2 工具策略：允许、拒绝与分层策略](https://yeasy.gitbook.io/openclaw_guide/di-er-bu-fen-jin-jie-shi-yong/05_tools_skills/5.2_tool_policy)
* [10.5 工具执行与结果回注](https://yeasy.gitbook.io/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/10_agent_loop/10.5_tool_execution)

## C.4 模型异常检查

检查项：

1. 主模型是否限流、超时或认证失败。
   * **典型报错**: `ProviderError: 429 Too Many Requests (OpenAI)` 或 `401 Invalid API Key`
2. 是否触发回退链路，回退是否有证据链。
   * **典型表现**: `[WARN] Model gpt-5.4 timed out. Falling back to claude-sonnet-4-6`
3. 冷却或禁用状态是否生效，是否出现重试放大。
4. 认证档案与密钥是否过期或被吊销。

常用命令示例：

```bash

# 统计错误分类占比

cat /tmp/openclaw/openclaw-YYYY-MM-DD.log | jq -r 'select(.type=="log") | .log | select(.stage=="model_call_end" and .err_type!="") | .err_type' | sort | uniq -c | sort -nr | head
```

> **注**：实际日志路径由 `logging.file` 配置决定，默认为 `/tmp/openclaw/openclaw-YYYY-MM-DD.log`

关联阅读：

* [11.1 多密钥治理：keys、keyId 与认证档案](https://yeasy.gitbook.io/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security/11.1_auth_profiles)
* [11.2 冷却与禁用：故障窗口内的止血机制](https://yeasy.gitbook.io/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security/11.2_rotation_cooldown)
* [11.3 模型回退链路与错误分流](https://yeasy.gitbook.io/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security/11.3_fallback_rules)

## C.5 记忆与上下文异常检查

现象：“模型遗忘刚刚提到的信息”或“连续要求重复输入参数”。

检查项：

1. 会话归属是否漂移（同一用户被分配到不同 sessionKey）。
   * **诊断手段**：用结构化日志按 `sessionKey` 和 `traceId` 回放链路。
2. 上下文预算是否打满，导致近期信息被裁剪。
   * **诊断手段**：观察日志中的裁剪/压缩事件与占位符频率。
3. 会话存储文件是否可读写，是否发生写入失败。
   * **诊断手段**：检查 `~/.openclaw/agents/<agentId>/sessions/sessions.json` 的更新时间与权限。

常用命令示例：

```bash
openclaw status --deep
openclaw logs --follow --json
cat /tmp/openclaw/openclaw-YYYY-MM-DD.log | jq -c 'select(.type=="log") | .log | select(.sessionKey!="") | {ts,trace_id,sessionKey,event,err_type}' | tail
```

> **注**：实际日志路径由 `logging.file` 配置决定，默认为 `/tmp/openclaw/openclaw-YYYY-MM-DD.log`

## C.6 复验与完整流程

检查项：

1. 修复后是否完成同场景复验，并回放关键 trace 做回归对比。
2. 是否更新 Runbook、告警阈值与回退策略。
3. 是否记录原因、处理动作、回滚点与证据链，便于复盘与审计。

关联阅读：

* [12.3 测试与调试：把扩展做成可回放的工程完整流程](https://yeasy.gitbook.io/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/12_extension_engineering/12.3_testing_debugging)