> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/fu-lu/appendix/troubleshooting_checklist.md).

# 附录 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)