3.2 常用诊断命令与日志排障

本节把排障从“看报错猜原因”变成基于官方命令与日志证据的分层定位。核心思路是先用 health 与 status 判断系统是否可用，再用 channels status --probe 与 models status --check 分别验证渠道与模型依赖，最后通过 doctor 与诊断配置把敏感信息脱敏后采样留证。

3.2.1 分层定位顺序：先外后内

建议固定排障顺序。

1. 进程与健康：服务是否可用。

2. 网关与渠道：渠道是否连通、是否被策略拒绝。

3. 模型与配额：模型是否可用、是否限流或认证失败。

4. 会话与工具：是否串话、是否被工具策略拦截。

3.2.2 四个命令覆盖 80% 排障

操作示例：先跑一遍健康与状态探测，再分别验证渠道与模型依赖，把问题定界到可执行动作。

# 1) 健康检查，适合自动化探测

openclaw health --json

# 2) 状态总览，--deep 会触发更深的探测

openclaw status --deep

# 3) 渠道状态与探针

openclaw channels status --probe

# 4) 模型状态与探针

openclaw models status --check

3.2.3 日志与落盘位置：先找到证据

官方说明中，日志默认写入 /tmp/openclaw/openclaw-YYYY-MM-DD.log（以下示例中的 runtime.log 均指代该默认日志路径，实际路径以配置为准）。建议在排障时同时开启 follow 与结构化输出，便于 jq 过滤。

openclaw logs --follow --json

操作示例：统计某类错误类型的出现频率，快速判断是否为认证或限流类故障。字段名以实际日志为准。

jq -r 'select(.err_type!="") | .err_type' runtime.log | sort | uniq -c | sort -nr | head

3.2.4 doctor 与诊断配置：可修复、可脱敏、可留证

官方提供 doctor 用于诊断与修复常见问题，并提供诊断配置用于脱敏与控制日志落盘。

openclaw doctor --fix

配置示例（从官方示例改写，突出脱敏与落盘）：

{
  diagnostics: {
    redact: true,
    logPath: "/tmp/openclaw/openclaw-%DATE%.log",
    maskedEnv: ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
    dumpOnCrash: true,
    maxBytesPerLog: 10485760,
  },
}

3.2.5 典型场景：渠道不响应时如何快速判断

• 若 health 失败：先看进程与端口，再看配置语法与权限。

• 若 channels status --probe 失败：优先检查渠道凭据与登录状态。

• 若 models status --check 失败：优先检查认证、配额与供应商状态。

排障时不建议先改提示词或工作流；先把依赖与证据链确认下来。

3.2.6 斜杠命令速查：日常高频操作

除了上述系统级诊断命令，OpenClaw 还提供了一套可在聊天界面中直接使用的斜杠命令，用于快速控制智能体行为。以下是最常用的命令速查表：

命令	用途	典型场景
/status	查看当前运行状态	小龙虾卡住不回复时，先发这个定位问题
/stop	停止当前正在执行的任务	配合 /status 使用；发现任务卡住后强制终止
/compact	压缩当前会话上下文	token 快满时使用，压缩后仍保留核心记忆
/new	开启全新会话	切换话题时避免上下文污染
/model <名字>	切换当前使用的模型	简单任务用便宜模型，复杂任务切强模型，控制成本
/think <级别>	调整思考深度（off / low / high）	日常闲聊用 off 省 token，复杂推理开 high

[!TIP] /status + /stop 是排障第一步。当智能体长时间无响应时，先 /status 看状态，如果显示正在运行但无输出，多半是某个工具调用卡住了，发 /stop 让它恢复。

[!WARNING] 飞书渠道目前不支持斜杠命令系统。若主要接入渠道是飞书，建议优先使用 SSH 终端运行 openclaw CLI 命令来完成等效操作，或考虑切换到 Telegram 等支持斜杠命令的渠道。