故障排查

​

命令阶梯

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

• openclaw gateway status 显示 Runtime: running、Connectivity probe: ok，以及一行 Capability: ...。
• openclaw doctor 报告没有阻塞性的配置/服务问题。
• openclaw channels status --probe 显示每个账户的实时传输状态，并在支持时显示探测/审计结果，例如 works 或 audit ok。

​

更新后

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

• 在 openclaw status / openclaw status --all 中出现 Update restart。待处理或失败的交接会包含下一条要运行的命令。
• 在 Channels 下出现 plugin load failed: dependency tree corrupted; run openclaw doctor --fix。这表示通道配置仍然存在，但插件注册在通道加载之前就失败了。
• 重新认证后出现提供方 401。openclaw doctor --fix 会检查过期的按代理 OAuth 认证影子副本，并删除旧副本，从而让所有代理解析到当前共享配置文件。

​

分裂脑安装与较新配置保护

which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

openclaw gateway install --force
openclaw gateway restart

​

回滚后协议不匹配

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow

• Gateway 日志中的 protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>。
• openclaw gateway status --deep 中的 Established clients:，或 openclaw doctor --deep 中的 Gateway clients。这会列出连接到 Gateway 端口的活动 TCP 客户端，包括操作系统允许时的 PID 和命令行。
• 命令行指向你回滚前所用的较新 OpenClaw 安装或包装器的客户端进程。

1. 停止或重启 gateway status --deep 中显示的陈旧 OpenClaw 客户端进程。
2. 重启嵌入 OpenClaw 的应用或包装器，例如本地仪表板、编辑器、应用服务器辅助进程，或长时间运行的 openclaw logs --follow shell。
3. 重新运行 openclaw gateway status --deep 或 openclaw doctor --deep，确认陈旧客户端 PID 已消失。

​

技能符号链接因路径逃逸而被跳过

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
openclaw config get skills.load

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

• 技能配置
• 配置示例

​

Anthropic 429 长上下文需要额外用量

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

• 所选 Anthropic 模型是支持 GA 的 1M Claude 4.x 模型，或者该模型具有旧版 params.context1m: true。
• 当前 Anthropic 凭据不具备长上下文用量资格。
• 请求只在需要 1M 上下文路径的长会话/模型运行中失败。

• Anthropic
• Token 使用与费用
• 为什么我从 Anthropic 看到了 HTTP 429？

​

上游 403 阻止响应

openclaw status
openclaw gateway status
openclaw logs --follow

• 同一提供方下多个模型以相同方式失败
• 普通提供方 API 错误之外的 HTML 或通用安全文本
• 相同请求时间点的提供方侧安全事件
• 一个很小的直接 curl 探测成功，而正常 SDK 形态请求失败

• OpenAI 兼容端点
• 提供方配置
• 日志

​

本地 OpenAI 兼容后端可通过直接探测，但代理运行失败

• curl ... /v1/models 可用
• 很小的直接 /v1/chat/completions 调用可用
• OpenClaw 模型运行只在正常代理轮次中失败

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

• 直接的小请求成功，但 OpenClaw 运行只在更大的提示词上失败
• 即使直接 /v1/chat/completions 使用相同的裸 model id 也可工作，仍出现 model_not_found 或 404 错误
• 后端关于 messages[].content 期望字符串的错误
• 带有 OpenAI 兼容本地后端时，偶发的 incomplete turn detected ... stopReason=stop payloads=0 警告
• 仅在更大的提示词 token 数或完整代理运行时提示词下才出现的后端崩溃

• 配置
• 本地模型
• OpenAI 兼容端点

​

没有回复

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

• DM 发送者处于待配对状态。
• 群组提及门控（requireMention、mentionPatterns）。
• 通道/群组允许列表不匹配。

• drop guild message (mention required → 群组消息在被提及之前会被忽略。
• pairing request → 发送者需要审批。
• blocked / allowlist → 发送者/通道被策略过滤。

• 通道故障排查
• 群组
• 配对

​

仪表板控制 UI 连接

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

• 正确的探测 URL 和仪表板 URL。
• 客户端与网关之间的认证模式/令牌不匹配。
• 需要设备身份时却使用了 HTTP。

openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

​

认证详情代码速查表

openclaw --version
openclaw doctor
openclaw gateway status

• 已配对设备 token 会话只能管理 它们自己的 设备，除非调用方还具有 operator.admin
• openclaw devices rotate --scope ... 只能请求调用方会话已经持有的操作员作用域

• 配置（网关认证模式）
• Control UI
• 设备
• 远程访问
• 受信任代理认证

​

Gateway 服务未运行

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # 也会扫描系统级服务

• Runtime: stopped 并带有退出提示。
• 服务配置不匹配（Config (cli) vs Config (service)）。
• 端口/监听冲突。
• 使用 --deep 时额外的 launchd/systemd/schtasks 安装。
• Other gateway-like services detected (best effort) 的清理提示。

• 后台执行和进程工具
• 配置
• Doctor

​

macOS gateway 静默停止响应，然后在你触碰 dashboard 时恢复

ls ~/.openclaw/logs/stability/ | tail -5
openclaw gateway stability --bundle latest
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -50
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

• ~/.openclaw/logs/stability/ 下存在一个或多个 *-uncaught_exception.json bundle，且 error.code 被设置为诸如 ENETDOWN、ENETUNREACH、EHOSTUNREACH 或 ECONNREFUSED 之类的瞬态网络错误码。
• pmset -g log 中有类似 Entering Sleep state due to 'Maintenance Sleep' 或 en0 driver is slow (msg: WillChangeState to 0) 的行，并且与崩溃时间戳对齐。Power Nap / Maintenance Sleep 会短暂将 Wi-Fi 驱动置于 state 0；在该窗口内发生的任何出站 connect() 都可能返回 ENETDOWN，即使主机其他方面具有完整的网络连接。
• launchctl print 输出显示 state = not running，并且有多次最近的 runs 和一个退出码，尤其是在崩溃与下一次启动之间的间隔大约是一小时而不是几秒钟时。macOS launchd 在一轮崩溃风暴后会应用一个未公开的 respawn-protection 门控，在外部触发（例如交互式登录、dashboard 连接或 launchctl kickstart）重新激活之前，可能不再响应 KeepAlive=true。

• 一个 error.code 为 ENETDOWN 或同类代码的稳定性包，调用栈指向 Node net 的 lookupAndConnect / Socket.connect。OpenClaw 2026.5.26 及更新版本会将这些视为良性的瞬态网络错误，因此不再将其传播到顶层未捕获处理器；如果你使用的是更早版本，请先升级。
• 漫长的静默期在你连接 Control UI 或通过 SSH 登录主机的瞬间结束：用户可见的活动是在重新为 launchd 的 respawn 门控上弦，而不是 dashboard 对 gateway 做了什么。
• runs 计数在一天内不断增加，但 ~/Library/Logs/openclaw/gateway.log 中没有对应的 received SIG*; shutting down 行：正常关闭会记录 signal；瞬态崩溃不会。

1. 升级 gateway，如果你运行的是 2026.5.26 之前的版本。升级后，未来的 ENETDOWN 错误会被记录为 warning，而不是终止进程。
2. 减少维护性睡眠活动，适用于作为常开服务器运行的 Mac mini / 桌面主机：
   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
   
   这会显著降低底层驱动抖动，但不能完全消除。系统仍可能为了 TCP keepalive 和 mDNS 维护而执行某些维护性睡眠，无论这些标志如何设置。
3. 添加一个存活监控，以便在未来由 launchd 暂停的崩溃风暴能被迅速捕获：
   # 示例 launchd 感知的存活检查，适合 5 分钟 cron 或 LaunchAgent
   state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')
   if [ "$state" != "running" ]; then
     launchctl kickstart -k gui/$UID/ai.openclaw.gateway
   fi
   
   关键在于从外部重新为 respawn 门控上弦；仅靠 KeepAlive=true 在 macOS 崩溃风暴后并不充分。

• macOS 平台说明
• 日志
• Doctor

​

Gateway 在高内存使用期间退出

openclaw gateway status --deep
openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export

• 最新稳定性包中的 Reason: diagnostic.memory.pressure.critical。
• Memory pressure:，以及 critical/rss_threshold、critical/heap_threshold 或 critical/rss_growth。
• 接近堆上限的 V8 heap: 数值。
• Largest session files: 条目，例如 agents/<agent>/sessions/<session>.jsonl 或 sessions/<session>.jsonl。
• 当 gateway 在容器或内存受限服务中运行时，Linux cgroup 内存计数器。

• critical memory pressure bundle written 出现在重启前不久 → OpenClaw 捕获了一个 OOM 前的稳定性包。使用 openclaw gateway stability --bundle latest 检查它。
• gateway 日志中出现 memory pressure: level=critical ... memoryPressureSnapshot=disabled → OpenClaw 检测到严重内存压力，但 OOM 前的稳定性快照未开启。
• Largest session files: 指向一个非常大的脱敏转录路径 → 在重启前减少保留的会话历史、检查会话增长，或将旧转录移出活动存储。
• V8 heap: 已用字节接近堆上限 → 降低提示/会话压力、减少并发工作，或仅在确认工作负载确实如此之后再提高 Node 堆限制。
• Memory pressure: critical/rss_growth → 内存在一个采样窗口内快速增长。检查最新日志中是否有大导入、失控的工具输出、重复重试，或一批排队的 agent 工作。
• 日志中出现严重内存压力，但没有 bundle → 这是默认行为。将 diagnostics.memoryPressureSnapshot: true 设为开启，以便在未来严重内存压力事件中捕获 OOM 前稳定性包。

• Gateway 健康状况
• 诊断导出
• 会话

​

Gateway 拒绝了无效配置

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• 活动配置旁边带时间戳的 openclaw.json.rejected.* 文件
• 如果 doctor --fix 修复了一个损坏的直接编辑，则会出现带时间戳的 openclaw.json.clobbered.* 文件
• OpenClaw 为每个配置路径保留最新的 32 个 .clobbered.* 文件，并轮转更旧的文件

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• 配置
• 配置：热重载
• 配置：严格验证
• Doctor

​

Gateway 探测警告

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

• JSON 输出中的 warnings[].code 和 primaryTargetId。
• 警告是否与 SSH 回退、多 gateway、缺失 scopes，或未解析的 auth 引用有关。

• SSH tunnel failed to start; falling back to direct probes. → SSH setup failed, but the command still tried direct configured/loopback targets.
• multiple reachable gateway identities detected → distinct gateways answered, or OpenClaw could not prove reachable targets are the same gateway. An SSH tunnel, proxy URL, or configured remote URL to the same gateway is treated as one gateway with multiple transports, even when transport ports differ.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → connect worked, but detail RPC is scope-limited; pair device identity or use credentials with operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → connect worked, but the full diagnostic RPC set timed out or failed. Treat this as a reachable Gateway with degraded diagnostics; compare connect.ok and connect.rpcOk in --json output.
• Capability: pairing-pending or gateway closed (1008): pairing required → the gateway answered, but this client still needs pairing/approval before normal operator access.
• unresolved gateway.auth.* / gateway.remote.* SecretRef warning text → auth material was unavailable in this command path for the failed target.

• Gateway
• 同一主机上的多个 gateway
• 远程访问

​

通道已连接，但消息未流动

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

• DM 策略（pairing、allowlist、open、disabled）。
• 群组 allowlist 和提及要求。
• 缺失的通道 API 权限/scopes。

• mention required → 消息因群组提及策略而被忽略。
• pairing / 待批准跟踪信息 → 发送方未获批准。
• missing_scope、not_in_channel、Forbidden、401/403 → 通道认证/权限问题。

• 通道故障排查
• Discord
• Telegram
• WhatsApp

​

Cron 和 heartbeat 投递

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

• 已启用 cron 且存在下一次唤醒。
• 作业运行历史状态（ok、skipped、error）。
• Heartbeat 跳过原因（quiet-hours、requests-in-flight、cron-in-progress、lanes-busy、alerts-disabled、empty-heartbeat-file、no-tasks-due）。

• Heartbeat
• 计划任务
• 计划任务：故障排查

​

节点已配对，但工具失败

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

• 节点在线且具备预期能力。
• 摄像头/麦克风/位置/屏幕的操作系统权限授予。
• 执行批准和 allowlist 状态。

• NODE_BACKGROUND_UNAVAILABLE → 节点应用必须在前台运行。
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → 缺少操作系统权限。
• SYSTEM_RUN_DENIED: approval required → 执行批准待处理。
• SYSTEM_RUN_DENIED: allowlist miss → 命令被 allowlist 阻止。

• 执行批准
• 节点故障排查
• 节点

​

浏览器工具失败

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

• plugins.allow 是否已设置并包含 browser。
• 浏览器可执行文件路径是否有效。
• CDP 配置文件是否可达。
• existing-session / user 配置文件的本地 Chrome 是否可用。

• 浏览器（OpenClaw 托管）
• 浏览器故障排查

​

如果你在升级后突然遇到故障

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

openclaw gateway install --force
openclaw gateway restart

• 认证
• 后台执行和进程工具
• Gateway 拥有的配对

​

相关

• 诊断
• 常见问题
• Gateway 运行手册