故障排查

​

命令阶梯

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：通道配置仍然存在，但插件在通道加载之前注册失败。
• 重新认证后的 Provider 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 的 100 万上下文 Claude 4.x 模型（Opus 4.6/4.7/4.8、Sonnet 4.6），或者模型配置仍然保留了旧版 params.context1m: true。
• 当前 Anthropic 凭据不符合长上下文使用资格。
• 请求仅在需要 100 万上下文路径的长会话/模型运行中失败。

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

​

上游 403 阻止响应

openclaw status
openclaw gateway status
openclaw logs --follow

• 同一提供方下的多个模型都以相同方式失败。
• 返回的是 HTML 或通用安全文案，而不是正常的提供方 API 错误。
• 同一请求时间点在提供方侧有安全事件记录。
• 一个很小的直接 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 使用相同的裸模型 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 网关静默停止响应，然后在你触碰控制面板时恢复

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 门控，在外部触发（例如交互式登录、控制面板连接或 launchctl kickstart）重新激活之前，可能不再响应 KeepAlive=true。

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

1. 如果你运行的是 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。

​

macOS launchd 监督循环，重复的 gateway/node LaunchAgents

for i in 1 2 3 4; do
  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
  sleep 10
done

openclaw gateway status --deep
openclaw node status
launchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'
tail -n 80 ~/Library/Logs/openclaw/gateway.log

• 在 30 秒采样期间出现多个 gateway PID，而不是一个稳定的进程。
• gateway.log 中出现 EADDRINUSE、another gateway instance is already listening，或者重复的 restart/handoff 日志行。
• 在一台本应只运行一个受管 gateway 服务的主机上，~/Library/LaunchAgents/ai.openclaw.gateway.plist 和 ~/Library/LaunchAgents/ai.openclaw.node.plist 两者同时被加载。

1. 如果这台主机只应该运行 Gateway 服务，请通过 OpenClaw 移除受管的 node 服务。如果你确实依赖 node 服务提供远程 node 功能，请跳过此步骤；卸载它会停止这台主机上的这些功能：
   openclaw node uninstall
   
2. 安装一个持久的 Gateway 包装器，在启动 OpenClaw 之前清除继承的 launchd 标记。请使用受支持的 --wrapper 选项；不要编辑 ~/.openclaw/service-env/ 下生成的文件，因为服务重装、更新和 doctor 修复都会重新生成该文件：
   mkdir -p ~/.local/bin
   cat >~/.local/bin/openclaw-launchd-workaround <<'EOF'
   #!/bin/sh
   set -eu
   unset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || true
   exec openclaw "$@"
   EOF
   chmod 700 ~/.local/bin/openclaw-launchd-workaround
   
   openclaw gateway install \
     --wrapper ~/.local/bin/openclaw-launchd-workaround \
     --force
   
   gateway install 会在强制重装、更新和 doctor 修复之间保留 wrapper 路径。
3. 验证 Gateway 是否稳定并且正在提供 RPC，而不仅仅是在监听：
   openclaw gateway status --deep --require-rpc
   
   for i in 1 2 3 4; do
     ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
     sleep 10
   done
   
   PID 采样应显示一个稳定的进程，而不是轮换的一组 PID，并且入站 channel 分发应该恢复。
4. 在升级到修复了底层双 LaunchAgent 循环的版本后，移除该 workaround，并重新安装正常的受管服务：
   OPENCLAW_WRAPPER= openclaw gateway install --force
   rm ~/.local/bin/openclaw-launchd-workaround
   

• macOS 平台说明
• Doctor
• Gateway CLI

​

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 检查它。
• memory pressure: level=critical 出现在 gateway 日志中 → OpenClaw 检测到严重内存压力，并记录了进程内可用的内存信息。
• Largest session files: 指向一个非常大的脱敏转录路径 → 减少保留的会话历史记录，检查会话增长情况，或在重启前将旧转录移出活动存储。
• V8 heap: 的已使用字节数接近堆限制 → 首先降低提示词／会话压力，或减少并发工作。对于托管服务，检查 openclaw gateway status 中的 Gateway heap:；如果显示 not set，请使用 openclaw gateway install --force 重新生成旧的服务元数据。环境 shell 中的 NODE_OPTIONS 会被有意忽略。只有在确认持续工作负载后，才使用明确的 supervisor 级堆覆盖设置，并为原生内存留出足够余量。
• Memory pressure: critical/rss_growth → 内存在一个采样窗口内快速增长。检查最新日志中是否存在大规模导入、失控的工具输出、重复重试或一批排队的 agent 工作。
• 日志中出现严重内存压力，但没有生成稳定性包 → 在事件发生后执行 openclaw gateway diagnostics export，以获取可用的运行证据。

• 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。

​

网关探测警告

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

• JSON 输出中的 warnings[].code 和 primaryTargetId。
• 警告是否与 SSH 回退、多网关、缺失的 scope，或未解析的身份验证引用有关。

• SSH tunnel failed to start; falling back to direct probes. → SSH 设置失败，但命令仍尝试了直接配置的/回环的目标。
• multiple reachable gateway identities detected → 不同的网关有响应，或者 OpenClaw 无法证明可达目标是同一个网关。SSH 隧道、代理 URL，或配置为指向同一个网关的远程 URL，会被视为一个具有多种传输方式的网关，即使传输端口不同也是如此。
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → 连接成功，但详细 RPC 受 scope 限制；请配对设备身份，或使用包含 operator.read 的凭据。
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → 连接成功，但完整的诊断 RPC 集超时或失败。将其视为一个可达但诊断受限的网关；在 --json 输出中对比 connect.ok 和 connect.rpcOk。
• Capability: pairing-pending 或 gateway closed (1008): pairing required → 网关已响应，但此客户端在获得正常 operator 访问权限前仍需要配对/批准。
• 未解析的 gateway.auth.* / gateway.remote.* SecretRef 警告文本 → 在此次命令路径中，失败目标的身份验证材料不可用。

• 网关
• 同一主机上的多个网关
• 远程访问

​

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

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）。

• 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 运行手册