> 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/di-si-bu-fen-shi-zhan-yu-you-hua-shen-du-zhi-nan/15_troubleshooting_trees/15.1_diagnostic_decision_trees.md).

# 15.1 常见故障的分层诊断

本节保留大量 Mermaid 决策树，但它们不是孤立的“流程合集”，而是同一套诊断框架的不同切面。阅读顺序应该是：**先理解分层模型，再按症状选树，再沿证据链逐层排除假设**。这样做的目的，是避免一看到症状就随机尝试命令，最后把真正的根因埋掉。

## 15.1.1 诊断总框架：先分层，再选树

OpenClaw 的常见故障可以先分成六层：

1. **启动层**：进程能否起来、配置能否加载、依赖是否齐全。
2. **消息入口层**：消息能否真正进入 Gateway，而不是停在渠道侧。
3. **模型调用层**：凭据、配额、供应商状态是否正常。
4. **工具执行层**：工具权限、参数、依赖服务是否正常。
5. **会话与记忆层**：上下文、压缩、会话隔离、记忆存储是否稳定。
6. **性能层**：在系统“能工作”的前提下，哪里开始变慢、堆积或级联退化。

```mermaid
flowchart TD
  S["用户观察到故障"] --> L1["启动层"]
  L1 --> L2["消息入口层"]
  L2 --> L3["模型调用层"]
  L3 --> L4["工具执行层"]
  L4 --> L5["会话与记忆层"]
  L5 --> L6["性能层"]
```

图 15-1：第十五章的分层诊断框架

这六层的意义在于：**前一层没通过，就不要急着跳到后一层**。例如进程都没起来，就不该先怀疑模型质量；渠道消息根本没进来，就不该先排工具执行。

## 15.1.2 证据链方法：命令的价值在于排除假设

本节里会出现很多命令，但命令不是目的，证据才是目的。每一层最该做的事，是先明确你要排除哪类假设。

| 层级     | 优先证据                                    | 主要排除的假设                               |
| ------ | --------------------------------------- | ------------------------------------- |
| 启动层    | `openclaw doctor`、启动日志                  | 进程没起来、配置坏了、依赖缺失                       |
| 消息入口层  | `openclaw channels status --probe`、渠道日志 | 消息未进入 Gateway、渠道门控未命中                 |
| 模型调用层  | `openclaw models status` / `--probe`    | 凭据缺失或过期、live provider 认证失败、配额耗尽、供应商故障 |
| 工具执行层  | 结构化日志、工具报错                              | 工具被拒绝、参数不合法、下游依赖异常                    |
| 会话与记忆层 | 会话日志、压缩/记忆痕迹                            | 会话串话、上下文丢失、记忆污染                       |
| 性能层    | 延迟、资源、队列指标                              | CPU/内存/IO 瓶颈或级联退化                     |

因此，下面的每一棵树都不是“万能排障流程”，而是解决对应层级问题的专项路径。

> \[!NOTE] 本章里的部分节点会引用 Linux、Kubernetes、Slack/飞书后台或特定供应商控制台的操作。这些都应理解为**常见部署示例**，不是所有环境都必须照做的固定路径。若你的平台不同，请保留“先取证、再改配置、最后验证恢复”的顺序，并替换成等价操作。

## 15.1.3 启动层：启动失败诊断流程

以下流程帮助诊断 OpenClaw 启动阶段遇到的各种故障。

```mermaid
graph TD
    A["启动OpenClaw"] --> B{"进程启动成功？"}
    B -->|否| C{"是否有错误日志？"}
    C -->|是| D["查看日志"]
    D --> E{"错误类型"}
    E -->|Port已占用| F["检查端口占用<br/>使用宿主机等价工具"]
    F --> G["更改端口号或停止占用进程"]
    E -->|配置文件格式错误| H["检查最近配置改动<br/>并回看启动日志"]
    H --> I["修复配置文件"]
    E -->|权限不足| J["先看服务/配置路径是否漂移<br/>openclaw gateway status"]
    J --> K["若是 Unix 主机再检查<br/>ls -la ~/.openclaw 等归属/权限"]
    E -->|缺少依赖| L["检查依赖<br/>openclaw doctor"]
    L --> M["安装缺失的依赖"]
    E -->|其他错误| L

    C -->|否| N["运行诊断命令"]
    N --> O["openclaw doctor"]
    O --> P{"诊断输出"}
    P -->|有警告| Q["按警告提示修复"]
    P -->|全部通过| R["检查系统资源"]
    R --> S{"内存/CPU充足？"}
    S -->|否| T["增加系统资源"]
    S -->|是| U["检查环境变量"]
    U --> V{"环境变量正确？"}
    V -->|否| W["更正环境变量"]
    V -->|是| X["开启debug模式<br/>OPENCLAW_LOG_LEVEL=debug"]
    X --> Y["重新启动并检查日志"]

    B -->|是| Z["启动成功"]
    G --> Z
    I --> Z
    K --> Z
    M --> Z
    Q --> Z
    T --> Z
    W --> Z
    Y --> AA{"问题解决？"}
    AA -->|是| Z
    AA -->|否| AB["收集日志并<br/>提交Issue"]
```

图 15-2：启动失败诊断决策树

## 15.1.4 消息入口层：消息无法接收诊断流程

当 OpenClaw 无法从各渠道接收消息时，按照此流程进行诊断。

```mermaid
graph TD
    A["消息无法接收"] --> B{"是哪个渠道？"}
    B -->|Lark/飞书| C["飞书渠道诊断"]
    B -->|Slack| D["Slack渠道诊断"]
    B -->|Google Chat / Webhook类| E["Webhook类渠道诊断"]
    B -->|其他| F["通用渠道诊断"]

    C --> C1{"飞书应用已发布？"}
    C1 -->|否| C2["前往飞书开放平台<br/>创建版本并发布"]
    C1 -->|是| C3{"事件订阅已启用？"}
    C3 -->|否| C4["在飞书平台启用事件订阅<br/>选择长连接方式"]
    C3 -->|是| C5{"Webhook URL正确？"}
    C5 -->|否| C6["更新飞书平台中的<br/>Webhook URL"]
    C5 -->|是| C7{"先跑 live probe<br/>openclaw channels status --probe"}
    C7 -->|probe 失败| C8["检查网络连接/账号状态<br/>再结合 openclaw logs --follow"]
    C7 -->|probe 正常仍无消息| C9["检查消息配置"]

    D --> D1{"Bot Token有效？"}
    D1 -->|否| D2["在当前部署的密钥系统中<br/>更新 Slack Token"]
    D1 -->|是| D3{"Event订阅URL正确？"}
    D3 -->|否| D4["在Slack应用配置中<br/>更新Event URL"]
    D3 -->|是| D5{"Bot已加入目标channel？"}
    D5 -->|否| D6["在Slack中邀请Bot进入Channel"]
    D5 -->|是| D7["检查 OpenClaw 与 Slack 相关日志<br/>openclaw channels logs --channel slack --lines 200<br/>openclaw logs --limit 500 --json"]

    E --> E1{"Webhook目标已配置？"}
    E1 -->|否| E2["用当前渠道命令配置<br/>例：channels add --channel googlechat --webhook-url ..."]
    E1 -->|是| E3{"渠道 probe 正常？"}
    E3 -->|否| E4["运行 channels status --probe<br/>并检查 Gateway URL/auth"]
    E3 -->|是| E5["检查渠道日志与通用日志<br/>openclaw channels logs<br/>openclaw logs --limit 500 --json"]

    F --> F1{"Webhook URL可访问？"}
    F1 -->|否| F2["检查 Gateway 是否在线<br/>用当前环境的健康检查方式验证"]
    F1 -->|是| F3{"消息格式正确？"}
    F3 -->|否| F4["按当前渠道 schema<br/>校验消息格式"]
    F3 -->|是| F5["检查消息路由规则"]

    C9 --> C10{"消息应该被发送到哪个Agent？"}
    C10 -->|未指定| C11["检查当前渠道默认目标<br/>或路由绑定"]
    C10 -->|已指定| C12["检查Agent是否启用<br/>openclaw agents list"]
    C9 --> Z
    D7 --> Z
    E5 --> Z
    F5 --> Z
    C2 --> Z
    C4 --> Z
    C6 --> Z
    C8 --> Z
    D2 --> Z
    D4 --> Z
    D6 --> Z
    E2 --> Z
    E4 --> Z
    F2 --> Z
    F4 --> Z
    C11 --> Z
    C12 --> Z

    Z["消息应该开始进入系统"]
```

图 15-3：消息无法接收诊断决策树

## 15.1.5 模型调用层：模型调用异常诊断流程

当与 LLM API 的通信出现异常时，使用此诊断流程快速定位问题。

```mermaid
graph TD
    A["模型调用失败"] --> B{"错误类型"}
    B -->|401/403 Unauthorized| C["API 密钥问题"]
    B -->|429 Rate Limited| D["速率限制"]
    B -->|500/502/503| E["API服务故障"]
    B -->|Timeout| F["超时问题"]
    B -->|其他错误| G["其他故障"]

    C --> C1{"密钥是否有效？"}
    C1 -->|不确定| C2["运行认证状态检查与provider探针<br/>models status / --probe"]
    C2 --> C3{"探针通过？"}
    C3 -->|是| C4["密钥有效"]
    C3 -->|否| C5["密钥已过期或无效<br/>更新密钥"]
    C1 -->|是| C6{"环境变量已设置？"}
    C6 -->|否| C7["按当前 provider 指南<br/>补齐凭据注入"]
    C6 -->|是| C8{"OpenClaw读取了密钥？"}
    C8 -->|检查日志| C9["查看初始化日志与<br/>models status 输出"]
    C9 --> C10{"密钥前缀匹配？"}
    C10 -->|是| C11["检查权限范围<br/>该密钥允许的模型?"]
    C10 -->|否| C12["更新密钥"]

    D --> D1{"当前请求速率"}
    D1 -->|查看日志| D2["检查日志中的速率限制警告<br/>openclaw logs"]
    D2 --> D3{"是否超过限制？"}
    D3 -->|是| D4{"是账户级限制还是<br/>IP级限制？"}
    D4 -->|账户级| D5["申请提升配额<br/>Anthropic/OpenAI 支持"]
    D4 -->|IP级| D6["检查是否有其他应用<br/>共用该IP的API 密钥"]
    D3 -->|否| D7["问题已解决"]

    E --> E1{"API服务状态"}
    E1 -->|检查官方状态| E2["查看当前 provider 的状态页面"]
    E2 --> E3{"显示服务故障？"}
    E3 -->|是| E4["等待服务恢复<br/>配置fallback模型"]
    E3 -->|否| E5["可能是网络问题"]
    E5 --> E6["检查 OpenClaw 到 provider 的网络连通性"]
    E6 --> E7["查看防火墙/代理配置"]

    F --> F1{"当前超时配置"}
    F1 -->|查看| F2["openclaw config get agents.defaults.timeoutSeconds"]
    F2 --> F3{"超时值合理？"}
    F3 -->|过低| F4["增加超时值<br/>特别是复杂查询"]
    F4 --> F5["agents.defaults.timeoutSeconds: 60"]
    F3 -->|合理| F6{"是API响应慢<br/>还是网络慢？"}
    F6 -->|API响应慢| F7["使用流式输出<br/>streaming: true"]
    F6 -->|网络慢| F8["检查到当前 provider 端点的网络延迟"]
    F8 --> F9["考虑使用就近的API端点"]

    G --> G1{"错误消息提示"}
    G1 -->|查看完整错误| G2["openclaw logs --limit 500 --json"]
    G2 --> G3{"是否为已知问题？"}
    G3 -->|是| G4["按知识库文章修复"]
    G3 -->|否| G5["导出诊断包<br/>openclaw gateway diagnostics export --json<br/>或聊天 /diagnostics [说明]"]
    G5 --> G6["提交Issue给支持团队"]

    C4 --> Z["密钥问题已解决"]
    C5 --> Z
    C7 --> Z
    C12 --> Z
    D5 --> Z
    D6 --> Z
    D7 --> Z
    E4 --> Z
    E6 --> Z
    E7 --> Z
    F5 --> Z
    F7 --> Z
    F9 --> Z
    G4 --> Z
    G6 --> Z

    Z["模型调用应该成功"]
```

图 15-4：模型调用异常诊断决策树

## 15.1.6 工具执行层：工具执行失败诊断流程

当工具执行出错时，按照此流程诊断是权限问题、执行错误还是无结果返回。

> \[!NOTE] 下图中带有 `profiles.*`、黑名单、清单权限等节点，适用于你已经启用对应治理配置的部署。如果你的环境并未定义这些字段，应把它们视为**可选分支**，优先回到工具策略、运行时权限和日志证据链本身排查，而不要把示意字段当成当前版本的固定 schema。

```mermaid
graph TD
    A["工具执行失败"] --> B{"失败时机"}
    B -->|Tool前置检查失败| C["权限检查"]
    B -->|Tool执行出错| D["执行错误"]
    B -->|Tool返回空| E["无结果"]

    C --> C1{"用户权限等级"}
    C1 -->|查看| C2["检查工具策略<br/>tools.profile / allow / deny"]
    C2 --> C3{"工具被策略拒绝？"}
    C3 -->|是| C4["检查渠道/群组/发送者策略<br/>以当前渠道 schema 为准"]
    C4 --> C5["按最小权限增加 allow 或 alsoAllow"]
    C3 -->|否| C6{"工具在黑名单中？"}
    C6 -->|是| C7["检查 deny 命中来源<br/>tools.deny 或渠道层 deny"]
    C6 -->|否| C8{"工具启用状态"}
    C8 -->|disabled| C9["检查插件/工具是否加载<br/>plugins list / /tools verbose"]
    C8 -->|enabled| C10["检查工具参数"]
    C10 -->|参数类型错误| C11["验证参数 Schema<br/>查阅工具定义文件 tools/*.json"]
    C10 -->|参数值无效| C12["修正参数值"]

    D --> D1{"错误信息"}
    D1 -->|Connection refused| D2["工具服务不可达<br/>例：GitHub API, Jira Server"]
    D2 --> D3["检查服务状态<br/>curl https://www.githubstatus.com/api/v2/status.json<br/>或用 curl -I https://api.github.com 检查 API 可达性"]
    D3 -->|在线| D4["检查网络连接<br/>telnet api.github.com 443"]
    D3 -->|离线| D5["等待服务恢复"]
    D1 -->|Authentication failed| D6["工具认证信息错误"]
    D6 -->|Token过期| D7["在当前部署的密钥系统中<br/>更新 GitHub Token"]
    D6 -->|权限不足| D8["检查Token权限范围<br/>重新生成高权限Token"]
    D1 -->|Timeout| D9["工具执行超时"]
    D9 -->|执行命令慢| D10["按层调整超时<br/>agents.defaults.timeoutSeconds / cron timeoutSeconds / 插件或单次工具 timeout"]
    D9 -->|网络慢| D11["检查网络性能"]
    D1 -->|业务逻辑错误| D12["阅读错误详情"]
    D12 -->|资源不存在| D13["检查传入的ID/Key<br/>如PR ID, Issue Key等"]
    D12 -->|权限限制| D14["检查OAuth范围<br/>需要仓库写权限?"]

    E --> E1{"无结果原因"}
    E1 -->|查询条件过严| E2["尝试放宽条件<br/>如日期范围、过滤器"]
    E1 -->|数据源为空| E3["检查插件或外部 API<br/>是否有相关数据"]
    E1 -->|缓存过期| E4["检查具体工具/插件缓存<br/>不要假设内置 Redis"]
    E1 -->|工具未返回| E5["检查工具输出格式"]
    E5 -->|格式错误| E6["查看工具文档<br/>验证输出schema"]

    C5 --> Z["权限问题解决"]
    C7 --> Z
    C9 --> Z
    C12 --> Z
    D5 --> Z
    D7 --> Z
    D8 --> Z
    D10 --> Z
    D11 --> Z
    D13 --> Z
    D14 --> Z
    E2 --> Z
    E3 --> Z
    E4 --> Z
    E6 --> Z

    Z["工具应该成功执行"]
```

图 15-5：工具执行失败诊断决策树

## 15.1.7 会话与记忆层：会话与内存异常诊断流程

当遇到上下文丢失、重复回答或内存溢出时，使用此诊断流程定位根因。

```mermaid
graph TD
    A["会话/内存异常"] --> B{"症状"}
    B -->|上下文丢失| C["消息历史丢失"]
    B -->|重复回答| D["记忆混乱"]
    B -->|内存溢出| E["OOM错误"]

    C --> C1{"什么时间点丢失？"}
    C1 -->|启动后立即丢失| C2["会话初始化问题"]
    C2 --> C3{"会话存储配置"}
    C3 -->|检查配置| C4["查看会话存储与作用域<br/>openclaw status<br/>openclaw sessions --json"]
    C4 --> C5{"session.dmScope / reset 是否符合预期？"}
    C5 -->|否| C6["调整会话作用域或重置策略<br/>session.dmScope / session.reset"]
    C5 -->|是| C7["检查会话文件与 transcript"]
    C7 -->|sessions.json| C8["openclaw sessions cleanup --dry-run"]
    C7 -->|jsonl| C9["检查对应 session transcript"]
    C1 -->|多轮对话中丢失| C10["上下文压缩过度"]
    C10 --> C11{"当前压缩策略"}
    C11 -->|查看配置| C12["检查 agents.defaults.compaction"]
    C12 -->|过于激进| C13["调整 compaction / keepRecentTokens"]
    C12 -->|合理| C14["检查模型上下文预算<br/>provider contextTokens"]
    C14 -->|过低| C15["调整模型上下文预算"]
    C14 -->|合理| C16["查看日志与会话上下文<br/>openclaw logs --limit 500 --json<br/>聊天内使用 /context detail"]

    D --> D1{"何时开始重复？"}
    D1 -->|新会话重复old答案| D2["会话隔离失败"]
    D2 -->|检查日志| D3["查看openclaw日志<br/>openclaw logs"]
    D3 -->|发现ID重复| D4["检查sessionId生成逻辑"]
    D3 -->|ID不同| D5["检查记忆存储隔离"]
    D5 -->|存储混淆| D6["检查 session key 与 dmScope"]
    D1 -->|同一会话中重复| D7["摘要生成过度"]
    D7 --> D8["检查 compaction 次数与摘要"]
    D8 -->|过频| D9["调高压缩阈值或保留近期上下文"]

    E --> E1{"内存占用情况"}
    E1 -->|检查| E2["用宿主机等价工具查看<br/>OpenClaw 进程资源占用"]
    E2 --> E3{"内存使用趋势"}
    E3 -->|持续增长| E4["内存泄漏"]
    E3 -->|峰值突增后降低| E5["GC正常工作"]
    E3 -->|峰值后无降低| E6["内存泄漏"]

    E4 --> E7["排查泄漏源"]
    E7 -->|缓存未清理| E8["检查具体插件/工具缓存配置"]
    E7 -->|外部连接未释放| E9["检查相关插件或下游 SDK"]
    E7 -->|会话文件过大| E10["检查 session.maintenance<br/>maxEntries / maxDiskBytes"]

    E6 --> E11["查阅已知泄漏<br/>或升级补丁版本"]

    C6 --> Z["内存问题解决"]
    C13 --> Z
    C15 --> Z
    C16 --> Z
    D4 --> Z
    D6 --> Z
    D9 --> Z
    E5 --> Z
    E8 --> Z
    E9 --> Z
    E10 --> Z
    E11 --> Z

    Z["会话和内存正常"]
```

图 15-6：会话与内存异常诊断决策树

## 15.1.8 性能层：性能退化诊断流程

当响应时间明显变慢时，按以下决策树收集性能指标并对比基线，定位退化根因。

```mermaid
graph TD
    A["响应时间变慢"] --> B["收集性能指标"]
    B --> C{"对比基线"}
    C -->|轻微上升| D["寻找最近变化"]
    C -->|严重上升| E["立即诊断"]

    D --> D1{"最近是否有变更？"}
    D1 -->|有| D2["回滚变更或恢复配置"]
    D1 -->|无| D3{"流量是否增加？"}
    D3 -->|是| D4["按需扩容"]
    D3 -->|否| D5["继续定位慢点"]

    E --> E1{"先看哪一项？"}
    E1 -->|CPU| E2{"CPU 超过 80%？"}
    E1 -->|内存| E3{"内存超过 85%？"}
    E1 -->|磁盘| E4{"磁盘 util 超过 90%？"}

    E2 -->|是| E5["排查 CPU 热点"]
    E3 -->|是| E6["检查内存泄漏或扩容"]
    E4 -->|是| E7["排查磁盘 IO 瓶颈"]
    E2 -->|否| F["检查网络与下游依赖"]
    E3 -->|否| F
    E4 -->|否| F

    F --> F1{"哪个环节最慢？"}
    F1 -->|请求准备| F2["检查上下文组装"]
    F1 -->|模型调用| F3["参考模型调用诊断"]
    F1 -->|工具调用| F4["参考工具执行诊断"]
    F1 -->|返回答案| F5["启用流式输出并检查网络"]

    D2 --> Z["性能恢复正常"]
    D4 --> Z
    D5 --> F
    E5 --> Z
    E6 --> Z
    E7 --> Z
    F2 --> Z
    F3 --> Z
    F4 --> Z
    F5 --> Z

    Z["性能恢复正常"]
```

图 15-7：性能退化诊断决策树

> \[!NOTE] 当前版本排查 Control UI 连接异常时，还应优先留意日志中的 `CONTROL_UI_ORIGIN_NOT_ALLOWED` 与 `CONTROL_UI_DEVICE_IDENTITY_REQUIRED`。这类错误通常说明问题在控制面来源校验或设备身份签名链，而不是简单的“端口不通”。

## 15.1.9 跨层故障与升级路径

实际排障时，常见的难点不是“不会跑树”，而是**一个症状可能跨越多层**。例如：

* 入口正常，但模型层 401，表现成“机器人不回复”。
* 模型正常，但工具层被拒绝，表现成“回答空泛”。
* 工具正常，但会话层串话，表现成“回答逻辑混乱”。

所以当你沿当前树走不通时，不要在同一层死磕，应该回到总框架，判断是不是已经跨层。一个简单原则是：

* 能证明“消息没进入系统”，就留在入口层。
* 能证明“消息进入了，但模型没回”，就切到模型层。
* 能证明“模型回了，但动作不对”，就切到工具层或会话层。
* 能证明“功能没坏，只是越来越慢”，就切到性能层，并准备进入 [15.2](/openclaw_guide/di-si-bu-fen-shi-zhan-yu-you-hua-shen-du-zhi-nan/15_troubleshooting_trees/15.2_high_concurrency_diagnosis.md) 的高并发诊断。

## 15.1.10 快速诊断命令参考

```bash
# 完整系统诊断
openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor

# 渠道/实时日志
openclaw channels status --probe
openclaw logs --follow

# 配置验证与查看
openclaw config
openclaw configure

# 健康检查
openclaw health

# 获取帮助信息
openclaw --help
openclaw --version
```

**注意**：

* 更多诊断命令和完整命令列表参见**附录 E - 命令速查表**（参考 [命令速查表](/openclaw_guide/fu-lu/appendix/command_cheatsheet.md)）
* 对于特定组件的深入诊断（如数据库、网络、API 密钥验证），请参考上述各个诊断决策树流程

这套决策树和基础诊断命令的价值，不在于让读者机械记住每一条命令，而在于建立“先分层、再取证、再选树”的诊断思路。