故障排查

​

命令执行顺序

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 会检查过期的各 Agent OAuth 身份验证影子配置，并删除旧副本，以便所有 Agent 都解析到当前的共享配置文件。

​

脑裂安装和较新配置保护机制

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 已消失。

​

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

正在跳过配置根目录之外的逃逸技能路径：... 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"],
    },
  },
}

• Skills 配置
• 配置示例

​

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

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

• 所选 Anthropic 模型是支持正式版 1M 上下文的 Claude 4.x 模型（Opus 4.6/4.7/4.8、Sonnet 4.6），或者模型配置仍带有旧版 params.context1m: true。
• 当前 Anthropic 凭据不具备长上下文使用资格。
• 请求仅在需要使用 1M 上下文路径的长会话或模型运行中失败。

• Anthropic
• Token 使用和成本
• 为什么会看到来自 Anthropic 的 HTTP 429？

​

上游 403 阻止响应

openclaw status
openclaw gateway status
openclaw logs --follow

• 同一提供商下的多个模型以相同方式失败。
• 返回 HTML 或通用安全提示文本，而不是正常的提供商 API 错误。
• 同一请求时间出现提供商侧安全事件。
• 极小的直接 curl 探测成功，但常规 SDK 形式的请求失败。

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

​

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

• curl ... /v1/models 可以正常工作。
• 极小的直接 /v1/chat/completions 调用可以正常工作。
• OpenClaw 模型运行仅在正常 Agent 轮次中失败。

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 运行仅在提示词较大时失败。
• 出现 model_not_found 或 404 错误，尽管使用同一个裸模型 ID 直接调用 /v1/chat/completions 可以正常工作。
• 后端报告 messages[].content 需要字符串的错误。
• 使用 OpenAI 兼容本地后端时，间歇性出现 incomplete turn detected ... stopReason=stop payloads=0 警告。
• 仅在提示词 Token 数量较大或使用完整 Agent 运行时提示词时出现后端崩溃。

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

​

无回复

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

• 私信发送者的配对待处理。
• 群组提及限制（requireMention、mentionPatterns）。
• 渠道/群组允许列表不匹配。

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

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

​

仪表板 Control UI 连接

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

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

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

​

身份验证详细代码速查表

openclaw --version
openclaw doctor
openclaw gateway status

• 已配对设备令牌会话只能管理自己的设备，除非调用方还具有 operator.admin。
• openclaw devices rotate --scope ... 只能请求调用方会话已拥有的操作员权限范围。

• 配置（Gateway 网关身份验证模式）
• Control UI
• 设备
• 远程访问
• 可信代理身份验证

​

Gateway 网关服务未运行

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

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

• 后台 Exec 和进程工具
• 配置
• Doctor

​

macOS Gateway 网关悄然停止响应，但触碰仪表板后又恢复响应

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 包，其中 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 驱动程序进入状态 0；在此时间窗口内发生的任何出站 connect() 都可能因 ENETDOWN 而失败，即使该主机在其他时候具有完整的网络连接。
• launchctl print 输出显示 state = not running，并包含多个近期 runs 和一个退出代码，尤其是崩溃与下次启动之间的间隔约为一小时而非数秒时。macOS launchd 会在短时间内连续崩溃后应用一个未公开的重生保护门控，该门控可能会停止遵循 KeepAlive=true，直到交互式登录、控制面板连接或 launchctl kickstart 等外部触发器将其重新激活。

• 稳定性包的 error.code 为 ENETDOWN 或同类错误代码，并且调用堆栈指向 Node net 的 lookupAndConnect / Socket.connect。OpenClaw 2026.5.26 及更高版本会将这些错误归类为无害的临时网络错误，因此它们不再传播到顶层未捕获异常处理程序；如果你使用的是更早的版本，请先升级。
• 长时间静默，并在你连接到 Control UI 或通过 SSH 登录主机时立即结束：重新激活 launchd 重生门控的是用户可见的活动，而不是控制面板对 Gateway 网关执行了任何操作。
• runs 计数在一天内持续增加，但 ~/Library/Logs/openclaw/gateway.log 中没有对应的 received SIG*; shutting down 行：正常关闭会记录信号；临时崩溃不会。

1. 如果你运行的是 2026.5.26 之前的版本，请升级 Gateway 网关。升级后，未来的 ENETDOWN 错误将记录为警告，而不是终止进程。
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
   
   关键在于从外部重新激活重生门控；在 macOS 上短时间连续崩溃后，仅靠 KeepAlive=true 并不足够。

• macOS 平台说明
• 日志
• Doctor

​

存在重复 Gateway 网关/节点 LaunchAgent 时的 macOS launchd 监管循环

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，而不是一个稳定的 进程。
• EADDRINUSE、another gateway instance is already listening，或 gateway.log 中重复出现的重启/交接行。
• 在一台本应只运行一个托管 Gateway 网关服务的主机上， ~/Library/LaunchAgents/ai.openclaw.gateway.plist 和 ~/Library/LaunchAgents/ai.openclaw.node.plist 同时被加载。

1. 如果此主机只应运行 Gateway 网关服务，请通过 OpenClaw 移除托管节点 服务。如果你正在依赖节点服务提供远程节点功能，请跳过此步骤； 卸载节点服务会停止此主机上的这些功能：
   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 修复后保留包装器路径。
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，并且入站渠道分发应恢复。
4. 升级到已修复底层双 LaunchAgent 循环的版本后， 移除该临时解决方案并重新安装正常的托管服务：
   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 检查该包。
• Gateway 网关日志中出现 memory pressure: level=critical → OpenClaw 检测到严重内存压力，并记录了进程内可用的内存信息。
• Largest session files: 指向一个非常大的已脱敏转录记录路径 → 减少保留的会话历史记录、检查会话增长情况，或在重启之前将旧转录记录移出活动存储。
• V8 heap: 已用字节数接近堆限制 → 首先降低提示词/会话压力或减少并发工作。对于托管服务，请检查 openclaw gateway status 中的 Gateway heap:；如果其内容为 not set，请使用 openclaw gateway install --force 重新生成旧服务元数据。系统会有意忽略 shell 环境中的 NODE_OPTIONS。仅在确认持续工作负载并为原生内存保留足够余量后，才使用明确的监管程序级堆覆盖设置。
• Memory pressure: critical/rss_growth → 内存在一个采样窗口内快速增长。检查最新日志中是否存在大型导入、失控的工具输出、重复重试或一批排队的智能体工作。
• 日志中出现严重内存压力但不存在稳定性包 → 在事件发生后捕获 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

​

Gateway 网关探测警告

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

• JSON 输出中的 warnings[].code 和 primaryTargetId。
• 警告是否涉及 SSH 回退、多个 Gateway 网关、权限范围缺失或未解析的身份验证引用。

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

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

​

渠道已连接，但消息未流转

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

• 私信策略（pairing、allowlist、open、disabled）。
• 群组允许列表和提及要求。
• 缺失的渠道 API 权限或权限范围。

• mention required → 消息因群组提及策略而被忽略。
• pairing / 待审批跟踪信息 → 发送者尚未获批。
• missing_scope、not_in_channel、Forbidden、401/403 → 渠道身份验证或权限问题。

• 渠道故障排除
• Discord
• Telegram
• WhatsApp

​

定时任务和 Heartbeat 投递

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

• 定时任务已启用且存在下次唤醒时间。
• 任务运行历史状态（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

• 节点在线且具备预期能力。
• 相机、麦克风、位置和屏幕的操作系统授权。
• Exec 审批和允许列表状态。

• NODE_BACKGROUND_UNAVAILABLE → 节点应用必须处于前台。
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → 缺少操作系统权限。
• SYSTEM_RUN_DENIED: approval required → Exec 审批待处理。
• SYSTEM_RUN_DENIED: allowlist miss → 命令被允许列表阻止。

• Exec 审批
• 节点故障排查
• 节点

​

浏览器工具失败

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

• 身份验证
• 后台 Exec 和进程工具
• 节点配对

​

相关内容

• Doctor
• 常见问题
• Gateway 网关运行手册