故障排查

这是深度运行手册。请先从 /help/troubleshooting 开始，完成快速分诊流程。

命令执行顺序

按以下顺序运行：

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

健康状态信号：

• openclaw gateway status 显示 Runtime: running、Connectivity probe: ok 和一行 Capability: ...。
• openclaw doctor 报告没有阻塞性的配置或服务问题。
• openclaw channels status --probe 显示各账户的实时传输状态，并在支持时显示 works 或 audit ok。

更新后

当更新已完成，但 Gateway 网关已关闭、渠道为空或模型调用因 401 错误而失败时使用。

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw 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 都解析到当前的共享配置文件。

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

当 Gateway 网关服务在更新后意外停止，或日志显示某个 openclaw 二进制文件比最后写入 openclaw.json 的版本更旧时使用。

OpenClaw 使用 meta.lastTouchedVersion 标记配置写入。只读命令可以检查由较新版本 OpenClaw 写入的配置，但使用较旧的二进制文件时，进程和服务变更会被拒绝执行。被阻止的操作包括：启动、停止、重启或卸载 Gateway 网关服务，强制重新安装服务，以服务模式启动 Gateway 网关，以及清理 gateway --force 端口。

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

回滚后的协议不匹配

当降级或回滚后日志持续输出 protocol mismatch 时使用。旧版 Gateway 网关正在运行，但较新的本地客户端进程仍在使用旧版 Gateway 网关无法支持的协议范围重新连接。

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw 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 已消失。

不要让旧版 Gateway 网关接受不兼容的新版协议。协议版本升级用于保护线路协议契约；回滚恢复属于进程和版本清理问题。

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

当日志包含以下内容时使用：

正在跳过配置根目录之外的逃逸技能路径：... reason=symlink-escape

每个技能根目录都是一个包含边界。当 ~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills 或 ~/.openclaw/skills 下的符号链接的真实目标解析到该根目录之外时，除非明确将目标设为可信，否则会跳过该链接。

检查链接：

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

如果目标是有意设置的，请同时配置直接技能根目录和允许的符号链接目标：

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

然后启动新会话，或等待技能监视器刷新。如果运行中的进程早于配置更改，请重启 Gateway 网关。

不要使用 ~、/ 或整个已同步项目文件夹等宽泛目标。将 allowSymlinkTargets 限定为包含可信 SKILL.md 目录的实际技能根目录。

如果还需要让 Skill Workshop 的应用操作写入这些可信的符号链接工作区技能路径，请启用 skills.workshop.allowSymlinkTargetWrites。对于只读共享技能根目录，请保持禁用状态。

相关内容：

• Skills 配置
• 配置示例

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

当日志或错误包含 HTTP 429: rate_limit_error: Extra usage is required for long context requests 时使用。

openclaw logs --followopenclaw models statusopenclaw 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 阻止响应

当上游 LLM 提供商返回 Your request was blocked 等通用 403 时使用。

不要假定这始终是 OpenClaw 配置问题。该响应可能来自 OpenAI 兼容端点之前的上游安全层，例如 CDN、WAF、机器人管理规则或反向代理。

openclaw statusopenclaw gateway statusopenclaw logs --follow

检查以下内容：

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

当证据指向 WAF/CDN 阻止时，先修复提供商侧的过滤规则。优先为 OpenClaw 使用的 API 路径设置范围有限的允许或跳过规则，避免禁用整个站点的保护。

相关内容：

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

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

在以下情况下使用：

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

curl http://127.0.0.1:1234/v1/modelscurl 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" --jsonopenclaw 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 statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

检查：

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

常见特征：

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

相关内容：

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

仪表板 Control UI 连接

当仪表板/Control UI 无法连接时，请验证 URL、身份验证模式和安全上下文假设。

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

检查：

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

如果更新后本地浏览器无法连接到 127.0.0.1:18789，请先恢复本地 Gateway 网关服务，并确认它正在提供仪表板：

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

如果 curl 返回 OpenClaw HTML，则 Gateway 网关正常工作，剩余问题可能是浏览器缓存、旧的深层链接或过时的标签页状态。请直接打开 http://127.0.0.1:18789，然后从仪表板进行导航。如果重启后服务未保持运行，请运行 openclaw gateway start，然后重新检查 openclaw gateway status。

身份验证详细代码速查表

使用失败的 connect 响应中的 error.details.code 来选择下一步操作：

设备身份验证 v2 迁移检查：

openclaw --versionopenclaw doctoropenclaw gateway status

如果日志显示 nonce/签名错误，请更新正在连接的客户端并进行验证：

如果 openclaw devices rotate / revoke / remove 意外被拒绝：

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

相关内容：

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

Gateway 网关服务未运行

适用于服务已安装但进程无法保持运行的情况。

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # 同时扫描系统级服务

检查：

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

相关内容：

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

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

当 macOS 主机上的渠道（Telegram、WhatsApp 等）会一次静默数分钟到数小时，并且你一打开 Control UI、通过 SSH 登录或以其他方式与主机交互，Gateway 网关似乎就立即恢复时，请使用以下方法。openclaw status 中通常没有明显症状，因为等你查看时，Gateway 网关已经恢复运行。

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl 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 或 LaunchAgentstate=$(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.gatewayfi

   关键在于从外部重新激活重生门控；在 macOS 上短时间连续崩溃后，仅靠 KeepAlive=true 并不足够。

相关内容：

• macOS 平台说明
• 日志
• Doctor

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

当 macOS 安装每隔几秒就不断重启、openclaw 健康检查在健康和不可用之间反复切换，并且渠道分发停滞， 即使服务看似正在运行，也可使用以下方法。

在同时启用了 ai.openclaw.gateway 和 ai.openclaw.node LaunchAgent，且两者都注入了 OPENCLAW_LAUNCHD_LABEL 的旧版安装中曾观察到此问题。在这种状态下，OpenClaw 可能检测到 launchd 监管，尝试将重启交回 launchd，并陷入快速 EADDRINUSE/重生循环，而不是维持一个稳定的 Gateway 网关进程。

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl 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/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 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 10done

   PID 样本应显示一个稳定的进程，而不是一组不断轮换的 PID，并且入站渠道分发应恢复。

4. 升级到已修复底层双 LaunchAgent 循环的版本后， 移除该临时解决方案并重新安装正常的托管服务：

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

相关内容：

• macOS 平台说明
• Doctor
• Gateway CLI

Gateway 网关在高内存使用期间退出

当 Gateway 网关在负载下消失、监管程序报告类似 OOM 的重启，或日志提到 critical memory pressure bundle written 时，请使用以下方法。

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw 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，以获取可用的运行证据。

稳定性包不包含负载数据。它包含运行内存证据和已脱敏的相对文件路径，不包含消息文本、webhook 正文、凭据、令牌、Cookie 或原始会话 ID。请将诊断导出附加到错误报告中，而不是复制原始日志。

相关内容：

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

Gateway 网关拒绝了无效配置

当 Gateway 网关启动因 Invalid config 而失败，或热重载日志显示跳过了无效编辑时，请使用以下方法。

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw 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 | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

相关内容：

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

Gateway 网关探测警告

当 openclaw gateway probe 可以访问目标，但仍输出警告块时使用。

openclaw gateway probeopenclaw gateway probe --jsonopenclaw 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 --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

请查找：

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

常见特征：

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

相关内容：

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

定时任务和 Heartbeat 投递

如果定时任务或 Heartbeat 未运行或未投递，请先验证调度器状态，再验证投递目标。

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

请查找：

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

相关内容：

• Heartbeat
• 定时任务
• 定时任务：故障排查

节点已配对，但工具失败

如果节点已配对但工具失败，请分别排查前台状态、权限和审批状态。

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

请查找：

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

常见特征：

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

相关内容：

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

浏览器工具失败

当浏览器工具操作失败，但 Gateway 网关本身运行正常时使用。

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

请查找：

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

相关内容：

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

如果升级后某些功能突然出现故障

大多数升级后故障是由配置漂移或现在开始强制执行的更严格默认值导致的。

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

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

如果检查后服务配置与运行时仍不一致，请从同一配置文件/状态目录重新安装服务元数据：

openclaw gateway install --forceopenclaw gateway restart

相关内容：

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

相关内容

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