故障排查

这是深度排障手册。请先从 /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 身份验证影子副本，并移除旧副本，以便所有智能体都解析到当前共享配置文件。

安装版本分裂和较新配置保护机制

当 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 网关接受较新且不兼容的协议。协议版本升级用于保护线协议契约；回滚恢复是进程和版本清理问题。

因路径逃逸而跳过 Skill 符号链接

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

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

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

检查链接：

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

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

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

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

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

如果 Skill Workshop 的应用操作也应通过这些可信符号链接写入工作区 Skill 路径，请启用 skills.workshop.allowSymlinkTargetWrites。对于只读的共享 Skill 根目录，请保持禁用。

相关内容：

• 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 兼容后端通过直接探测，但智能体运行失败

适用于以下情况：

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

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

相关内容：

• 配置
• 本地模型
• 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 → 发送者/渠道已被策略过滤。

相关内容：

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

Dashboard Control UI 连接问题

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

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

检查：

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

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

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

如果 curl 返回 OpenClaw HTML，则 Gateway 网关工作正常，剩余问题可能是浏览器缓存、旧的深层链接或过期的标签页状态。直接打开 http://127.0.0.1:18789，然后从 Dashboard 中导航。如果重启后服务仍未保持运行，请运行 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 网关无提示地停止响应，操作 Dashboard 后又恢复

适用于 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，而不是一个稳定的 进程。
• gateway.log 中出现 EADDRINUSE、another gateway instance is already listening，或重复的 重启/交接行。
• 在一台本应只运行一个托管 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 ... memoryPressureSnapshot=disabled → OpenClaw 检测到严重内存压力，但 OOM 前稳定性快照已关闭。
• Largest session files: 指向一个非常大的已脱敏转录路径 → 减少保留的会话历史记录、检查会话增长情况，或在重启前将旧转录移出活动存储。
• V8 heap: 已用字节数接近堆限制 → 降低提示词/会话压力、减少并发工作，或仅在确认预期工作负载后提高 Node 堆限制。
• Memory pressure: critical/rss_growth → 内存在一个采样窗口内快速增长。检查最新日志中是否存在大型导入、失控的工具输出、重复重试或一批排队的智能体工作。
• 日志中出现严重内存压力但不存在稳定性包 → 这是默认行为。设置 diagnostics.memoryPressureSnapshot: true，以便在未来发生严重内存压力事件时捕获 OOM 前稳定性包。

稳定性包不含载荷。它包含运行内存证据和已脱敏的相对文件路径，不包含消息文本、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

Cron 和 Heartbeat 投递

如果 cron 或 Heartbeat 未运行或未投递，请先验证调度器状态，再检查投递目标。

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw 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 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 网关运行手册