# 附录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 守护进程与可用性验收](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/02_setup/2.4_gateway_service.md)
* [4.1 openclaw.json 结构与配置优先级](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/04_config_models/4.1_config_system.md)

## 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 --probe
openclaw logs --limit 200
```

关联阅读：

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

## C.3 工具异常检查

检查项：

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

常用命令示例：

```bash

# 按 traceId 回放工具链路

openclaw logs --limit 500 --json | jq -c 'select(.type=="log") | (.raw | fromjson? // {}) | select(.traceId=="t-...") | {ts:(.time // .ts), traceId, message, agent_id, session_id, channel}'
```

> **注**：`openclaw logs --json` 会输出 `type=="log"` 的包装事件，原始结构化 JSON 通常在 `.raw` 中；直接读取 `logging.file` 指向的 JSONL 文件时，每行通常就是日志对象，不要再套 `.type=="log"` 或解析 `.raw`。

关联阅读：

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

## C.4 模型异常检查

检查项：

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

常用命令示例：

```bash

# 统计错误分类占比

openclaw logs --limit 500 --json | jq -r 'select(.type=="log") | (.raw | fromjson? // {}) | select((.message // "") | test("model|provider|fallback|rate"; "i")) | (.error // .message)' | sort | uniq -c | sort -nr | head
```

> **注**：直接读取 `logging.file` 指向的 JSONL 文件时，把 jq 前半段改成 `select((.message // "") | test(...))`，不要使用 CLI JSON 包装字段。

关联阅读：

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

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

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

检查项：

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

常用命令示例：

```bash
openclaw status --deep
openclaw logs --limit 500 --json
openclaw logs --limit 500 --json | jq -c 'select(.type=="log") | (.raw | fromjson? // {}) | select((.session_id // "")!="") | {ts:(.time // .ts), traceId, session_id, message, error}' | tail
```

> **注**：`--follow` 适合最后持续观察；排查清单中的快照证据优先用 `--limit`，避免阻塞后续命令。

若要提交 Issue 或升级给维护者，优先导出受控诊断包，而不是散贴完整日志：

```bash
openclaw gateway diagnostics export --json
# 或在聊天窗口中使用：
/diagnostics [补充说明]
```

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

检查项：

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

关联阅读：

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/openclaw_guide/fu-lu/appendix/troubleshooting_checklist.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.