# 3.2 常用诊断命令与日志排障
排障核心思路：先确认进程与网关是否存活，再逐层验证渠道、模型依赖，最后通过日志定位具体错误。
> 完整命令参数与进阶排障流程见[附录 E 命令速查表](/openclaw_guide/fu-lu/appendix/command_cheatsheet.md)和[附录 C 排障检查清单](/openclaw_guide/fu-lu/appendix/troubleshooting_checklist.md)。
## 3.2.1 四层诊断顺序与辅助动作
本章建议把排障主链路固定为“四层诊断”：**进程/网关 → 渠道 → 模型 → 日志**。其中 `status --deep` 与 `doctor --repair` 为两个关键辅助动作：前者用于补充全局视图，后者用于在证据明确后做修复，而不是一上来就盲修。
| 诊断层级 | 命令 | 检查目标 |
| --------------- | ------------------------------------ | ---------------------- |
| **第一层：进程与网关** | `openclaw doctor` + 启动日志 | 进程能否拉起、配置是否损坏、依赖是否缺失 |
| **第二层：渠道** | `openclaw channels status --probe` | 渠道运行状态与 live probe |
| **第三层：模型** | `openclaw models status` / `--probe` | 认证状态与 live provider 探针 |
| **第四层：日志** | `openclaw logs --follow --json` | 定位具体错误、trace 与上下文 |
| **辅助动作 1：全局视图** | `openclaw status --deep` | 当前状态加渠道 live probe |
| **辅助动作 2：修复工具** | `openclaw doctor --repair` | 在确认问题后执行引导式修复 |
```mermaid
flowchart TD
Start["症状：不回复/卡住/报错"] --> S1["openclaw doctor + 启动日志
进程与启动自检"]
S1 --> S1a["openclaw status --deep
全局状态总览"]
S1a --> S2["openclaw channels status --probe
渠道运行状态与live probe"]
S2 --> S3["openclaw models status / --probe
认证状态与live探针"]
S3 --> S4["openclaw logs --follow --json
日志定位"]
S4 --> Fix["openclaw doctor --repair
确认后再修复"]
Fix --> End["定位：进程/凭据/限流/认证/配置"]
```
图 3-4：四层诊断顺序与辅助命令
## 3.2.2 命令示例
**命令 1：健康检查**
```bash
openclaw health --json
```
`openclaw health --json` 通常会返回顶层 `ok` 与若干嵌套健康信息；不同版本字段结构会变化，不要把 `status: "ok"`、`errors` 等字段当成固定契约。验收时重点看整体是否健康、是否还有关键错误即可。
**命令 2：状态总览**
```bash
openclaw status --deep
```
一次性查看状态并对渠道做 live probe。它适合作为第二步的总览入口：如果这里已经显示渠道掉线，就不应先去改提示词或工作流；供应商用量与配额快照应使用 `openclaw status --usage`。
**命令 3：渠道探针**
```bash
openclaw channels status --probe
```
`channels status --probe` 是当前更稳妥的渠道 live 检查入口，用来确认 Gateway 可达时各渠道账号的运行状态、传输状态和探针结果。`channels capabilities` 更适合后续查看渠道能力、权限范围和联调提示；若需要更深的端到端验证，应结合结构化日志和实际渠道消息一起判断，而不要把单一探针命令写成固定契约。
**命令 4：模型探针**
```bash
openclaw models status
openclaw models status --probe
```
`--check` 用于发现缺失、过期或即将过期的认证档案；`--probe` 会实际探测已配置 provider 的 live auth。若探针返回认证或限流错误，再结合供应商后台配额与结构化日志判断是密钥失效、额度耗尽还是上游故障。
**命令 5：跟踪日志**
```bash
openclaw logs --json --limit 500
```
结构化输出便于用 `jq` 过滤。优先用有界快照按 `level` 与 `message` 判断是认证、限流、超时还是 allowlist 类故障：
```bash
openclaw logs --json --limit 500 \
| jq -r 'select(.type=="log") | select((.level=="error") or (.message|test("auth|rate|timeout|blocked|allowlist";"i"))) | .message'
```
**命令 6：自动修复与诊断配置**
```bash
openclaw doctor --repair
```
自动检测并修复常见配置问题。建议配合脱敏配置使用：
```javascript
{
logging: {
level: "info",
redactSensitive: "tools",
redactPatterns: ["sk-[A-Za-z0-9]{16,}"],
}
}
```
## 3.2.3 快速判断路径
* `health` 失败 → 检查进程与端口，查配置语法与权限。
* `status --deep` / `channels status --probe` 发现渠道异常 → 检查渠道凭据、网络连接与网关可达性；再用 `channels capabilities` 查看能力与权限提示。
* `models status` 显示认证或模型配置异常 → 检查 API Key、OAuth 过期或缺失；需要 live provider 证据时再运行 `models status --probe`。
排障时不建议先改提示词或工作流；先把依赖与证据链确认下来。
> **踩坑实录：健康检查 “ok” 但消息不通**
>
> `openclaw health --json` 返回 `ok: true`，但 Telegram 消息始终无回复。原因是渠道链路与进程健康不是同一层：进程仍在跑，不代表消息已经真正送达。对渠道问题，先用 `channels status --probe` 查看 live 状态，再用 `channels capabilities` 确认能力与权限提示，最后结合实际消息回放和结构化日志做端到端排查，才是更稳妥的诊断路径。
---
# 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/di-yi-bu-fen-ji-chu-ru-men/03_minimal_loop/3.2_diagnostics.md?ask=
```
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.