古法编程

Appearance

OpenClaw Gateway 故障排查深度手册：适合在快速分诊后使用，覆盖更新后崩溃、协议不匹配、技能符号链接逃逸、Anthropic 长上下文 429、本地 OpenAI 兼容后端代理运行失败、频道无回复、Dashboard 连接不上、服务不运行、内存过高退出、配置拒绝、节点工具失败、浏览器工具故障等场景。按症状定位诊断命令，并给出常见错误特征和修复步骤。

OpenClaw Gateway 故障排查手册 ​

本页是深度排查手册。如果你想先走快速分诊流程，请访问 /openclaw/help/troubleshooting。

诊断命令梯队 ​

首先依次执行以下命令：

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

更新后 Gateway 崩溃或通道为空怎么解决 ​

更新完成但 Gateway 停止运行、通道为空，或模型调用返回 401 时，执行以下命令：

bash
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 认证副本并删除旧副本，使所有智能体都使用当前的共享配置。

脑裂安装与新版配置保护 ​

Gateway 服务在更新后意外停止，或日志显示当前 openclaw 二进制版本旧于最后写入 openclaw.json 的版本时，使用本节。

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

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

  1. 修复 PATH：调整 PATH 使 openclaw 解析到较新的安装，然后重新执行操作。

  2. 重新安装 gateway 服务：从较新安装重新安装目标 gateway 服务：

    bash
    openclaw gateway install --force
openclaw gateway restart

  3. 移除过时的包装器：删除仍指向旧 openclaw 二进制的系统包或旧包装器条目。

WARNING

仅用于故意的降级或紧急恢复：为单个命令设置 OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1。正常操作下保持未设置。

回滚后协议不匹配 ​

当降级或回滚后日志反复出现 protocol mismatch，表示旧版 Gateway 正在运行，但新的本地客户端进程仍试图使用旧版 Gateway 无法处理的协议范围重连。

bash
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 或 openclaw doctor --deep 中查找 Established 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 接受新的不兼容协议。协议升级保护了有线契约；回滚恢复是一个进程/版本清理问题。

技能符号链接被跳过（路径逃逸） ​

当日志包含以下内容时：

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

OpenClaw 将每个技能根目录视为一个安全边界。在 ~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills 或 ~/.openclaw/skills 下的符号链接，如果其目标解析到根目录之外，则会被跳过，除非目标被显式信任。

检查链接：

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

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

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

然后启动一个新会话或等待技能观察者刷新。如果配置变更是运行时前做的，重启 Gateway。

不要使用宽泛的目标，如 ~、/ 或整个同步的项目文件夹。将 allowSymlinkTargets 限定为真实技能根目录，其中包含受信任的 SKILL.md 目录。

相关文档：

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

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

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

排查要点：

  • 所选 Anthropic Opus/Sonnet 模型是否设置了 params.context1m: true。
  • 当前 Anthropic 凭据是否不具备长上下文使用权限。
  • 请求是否只在需要 1M beta 路径的长会话/模型运行时失败。

修复选项：

  1. 禁用该模型的 context1m，回退到普通上下文窗口。
  2. 使用具备长上下文使用资格的 Anthropic 凭据，或切换到 Anthropic API key。
  3. 配置备用模型，当 Anthropic 长上下文请求被拒绝时继续运行。

相关文档：

本地 OpenAI 兼容后端直连正常但智能体运行失败 ​

当以下情况出现时使用：

  • curl ... /v1/models 正常
  • 小尺寸直接 /v1/chat/completions 调用正常
  • OpenClaw 模型运行只在普通智能体轮次失败
bash
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 运行时只在较大 prompt 下失败。
  • 即使直接 /v1/chat/completions 使用相同裸模型 id 正常，仍出现 model_not_found 或 404。
  • 后端报错 messages[].content 期望字符串。
  • 间歇性 incomplete turn detected ... stopReason=stop payloads=0 警告。
  • 后端仅在较大 prompt token 量或完整智能体运行时 prompt 下崩溃。
常见特征
  • model_not_found 与本地 MLX/vLLM 风格服务器 → 验证 baseUrl 包含 /v1，api 为 "openai-completions"（针对 /v1/chat/completions 后端），models.providers.&lt;provider&gt;.models[].id 是纯粹的提供商本地 id。使用提供商前缀选择一次，例如 mlx/mlx-community/Qwen3-30B-A3B-6bit；保持目录条目为 mlx-community/Qwen3-30B-A3B-6bit。
  • messages[...].content: invalid type: sequence, expected a string → 后端拒绝结构化的 Chat Completions content parts。修复：设置 models.providers.&lt;provider&gt;.models[].compat.requiresStringContent: true。
  • validation.keys 或允许的消息键如 ["role","content"] → 后端拒绝 Chat Completions 消息上的 OpenAI 风格重放元数据。修复：设置 models.providers.&lt;provider&gt;.models[].compat.strictMessageKeys: true。
  • incomplete turn detected ... stopReason=stop payloads=0 → 后端完成了 Chat Completions 请求，但该轮次没有返回用户可见的助手文本。OpenClaw 会对安全的空回复重试一次；持续失败通常表示后端输出了空/非文本内容或抑制了最终答案文本。
  • 直连小请求正常，但 OpenClaw 智能体运行失败且后端/模型崩溃 → OpenClaw 传输很可能正确；后端在更大的智能体运行时 prompt 上失败。
  • 禁用工具后失败减少但未消失 → 工具 schema 是压力的一部分，但剩余问题仍是上游模型/服务器容量或后端 bug。
修复选项
  1. 设置 compat.requiresStringContent: true 针对仅字符串的 Chat Completions 后端。
  2. 设置 compat.strictMessageKeys: true 针对仅接受每条消息上 role 和 content 的严格 Chat Completions 后端。
  3. 设置 compat.supportsTools: false 针对无法可靠处理 OpenClaw 工具 schema 的模型/后端。
  4. 尽可能降低 prompt 压力：更小的工作区引导、更短的会话历史、更轻的本地模型，或更强长上下文支持的后端。
  5. 如果直连小请求正常但 OpenClaw 智能体轮次仍在后端内部崩溃，将其视为上游服务器/模型限制，并在那里提交包含已接受载荷形状的 bug 报告。

相关文档：

频道无回复 ​

频道正常但没有任何响应时，在重新连接任何东西之前先检查路由和策略。

bash
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 → 发送者/频道被策略过滤。

相关文档：

Dashboard 控制 UI 连接失败 ​

当 dashboard/控制 UI 无法连接时，验证 URL、认证模式和安全上下文假设。

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

排查要点：

  • 正确的探测 URL 和 dashboard URL。
  • 客户端和 gateway 之间认证模式/token 不匹配。
  • 在需要设备身份的情况下使用了 HTTP。
连接/认证特征
  • device identity required → 非安全上下文或缺少设备认证。
  • origin not allowed → 浏览器 Origin 不在 gateway.controlUi.allowedOrigins 中（或你从非 loopback 浏览器 origin 连接但没有配置显式允许列表）。
  • device nonce required / device nonce mismatch → 客户端未完成基于挑战的设备认证流（connect.challenge + device.nonce）。
  • device signature invalid / device signature expired → 客户端对当前握手签署了错误的载荷（或时间戳过期）。
  • AUTH_TOKEN_MISMATCH 且 canRetryWithDeviceToken=true → 客户端可以用缓存的设备 token 进行一次可信重试。
  • 该缓存 token 重试会复用与配对设备 token 一起存储的作用域集。显式传入 deviceToken / scopes 的调用方则保持其请求的作用域集。
  • AUTH_SCOPE_MISMATCH → 设备 token 被识别，但其批准的 scopes 未涵盖此连接请求；重新配对或批准请求的作用域契约，而不是轮换共享 gateway token。
  • 在此重试路径之外，connect 认证优先级依次为：显式共享 token/密码 > 显式 deviceToken > 存储的设备 token > bootstrap token。
  • 在 Tailscale Serve 控制 UI 的异步路径上，同一 {scope, ip} 的失败重试会在限速器记录失败前被串行化，因此同一客户端的两个并发错误重试，第二次可能返回 retry later 而非两次独立的 mismatch。
  • too many failed authentication attempts (retry later) 来自浏览器 loopback 客户端 → 同一归一化 Origin 多次失败后会被暂时锁定；来自其他 localhost origin 的请求使用独立桶。
  • 重试后仍出现 unauthorized → 共享 token/设备 token 漂移；刷新 token 配置并在需要时重新审批/轮换设备 token。
  • gateway connect failed: → 目标主机/端口/URL 错误。

认证详情代码快速映射 ​

使用失败 connect 响应中的 error.details.code 决定下一步操作：

详情代码含义建议操作
AUTH_TOKEN_MISSING客户端未发送必需的共享 token。在客户端粘贴/设置 token 并重试。Dashboard 路径：openclaw config get gateway.auth.token 然后粘贴到控制 UI 设置中。
AUTH_TOKEN_MISMATCH共享 token 与 gateway 认证 token 不匹配。如果 canRetryWithDeviceToken=true，允许一次可信重试。缓存 token 重试复用已批准的存储作用域集；显式传入 deviceToken / scopes 的调用方保持其请求作用域。仍然失败则运行 token 漂移恢复清单。
AUTH_DEVICE_TOKEN_MISMATCH每设备缓存 token 已过期或被撤销。使用 devices CLI 轮换/重新审批设备 token，然后重新连接。
AUTH_SCOPE_MISMATCH设备 token 有效，但其批准的角色/作用域不涵盖此连接请求。重新配对设备或批准请求的作用域契约；不要将此视为共享 token 漂移。
PAIRING_REQUIRED设备身份需要审批。检查 error.details.reason 中的 not-paired、scope-upgrade、role-upgrade 或 metadata-upgrade，并在存在时使用 requestId / remediationHint。审批待处理请求：openclaw devices list 然后 openclaw devices approve <requestId>。作用域/角色升级在审查请求的访问后使用相同流程。

::: note 使用共享 gateway token/password 认证的直接 loopback 后端 RPC 不应依赖于 CLI 的配对设备作用域基线。如果子智能体或其他内部调用仍返回 scope-upgrade，请验证调用方使用了 client.id: "gateway-client" 和 client.mode: "backend"，并且没有强制使用显式 deviceIdentity 或设备 token。 :::

设备认证 v2 迁移检查：

bash
openclaw --version
openclaw doctor
openclaw gateway status

如果日志显示 nonce/签名错误，更新连接客户端并验证它：

  1. 等待 gateway 发出的 connect.challenge。
  2. 客户端签署绑定挑战的载荷。
  3. 客户端发送带有相同挑战 nonce 的 connect.params.device.nonce。

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

  • 配对设备 token 会话只能管理自身的设备，除非调用方同时具有 operator.admin。
  • openclaw devices rotate --scope ... 只能请求当前调用方会话已持有的 operator 作用域。

相关文档：

Gateway 服务不运行 ​

当服务已安装但进程无法保持运行时使用：

bash
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) 清理提示。
常见特征
  • Gateway start blocked: set gateway.mode=local 或 existing config is missing gateway.mode → 本地 gateway 模式未启用，或配置文件被覆盖丢失了 gateway.mode。修复：在配置中设置 gateway.mode="local"，或重新运行 openclaw onboard --mode local / openclaw setup 来重建预期的本地模式配置。如果通过 Podman 运行 OpenClaw，默认配置路径为 ~/.openclaw/openclaw.json。
  • refusing to bind gateway ... without auth → 非 loopback 绑定但没有有效的 gateway 认证路径（token/密码，或已配置的 trusted-proxy）。
  • another gateway instance is already listening / EADDRINUSE → 端口冲突。
  • Other gateway-like services detected (best effort) → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数场景应在每台机器只运行一个 gateway；如果确实需要多个，请隔离端口 + 配置/状态/工作区。参见 /openclaw/gateway#multiple-gateways-same-host。
  • System-level OpenClaw gateway service detected from doctor → 存在 systemd 系统单元但用户级服务缺失。在允许 doctor 安装用户服务之前移除或禁用重复单元，或者如果系统单元是预期的监督者，则设置 OPENCLAW_SERVICE_REPAIR_POLICY=external。
  • Gateway service port does not match current gateway config → 安装的监督者仍然固定了旧版 --port。运行 openclaw doctor --fix 或 openclaw gateway install --force，然后重启 gateway 服务。

相关文档：

Gateway 内存过高退出 ​

当 Gateway 在负载下消失、监督者报告 OOM 风格重启，或日志提到 critical memory pressure bundle written 时使用：

bash
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/&lt;agent&gt;/sessions/&lt;session&gt;.jsonl 或 sessions/&lt;session&gt;.jsonl。
  • 当 Gateway 运行在容器或内存受限服务内时的 Linux cgroup 内存计数器。

常见特征：

  • critical memory pressure bundle written 在重启前不久出现 → OpenClaw 捕获了 OOM 前的稳定性包。用 openclaw gateway stability --bundle latest 检查。
  • memory pressure: level=critical ... memoryPressureSnapshot=disabled 出现在 gateway 日志中 → OpenClaw 检测到内存压力，但 OOM 前快照已关闭。
  • Largest session files: 指向非常大的已编辑对话路径 → 减少保留的会话历史，检查会话增长，或在重启前将旧对话移出活跃存储。
  • V8 heap: 已用字节接近堆限制 → 降低 prompt/会话压力，减少并发工作，或在确认负载预期后提高 Node 堆限制。
  • Memory pressure: critical/rss_growth → 内存在一个采样窗口内快速增加。检查最近的日志中是否有大型导入、失控的工具输出、重复的重试或一批排队的智能体工作。
  • 日志中出现内存压力但无包 → 这是默认行为。设置 diagnostics.memoryPressureSnapshot: true 以便在将来关键内存压力事件时捕获 OOM 前稳定性包。

稳定性包是无载荷的。它包含运行内存证据和已编辑的相对文件路径，但不包含消息文本、webhook 主体、凭据、token、cookies 或原始 session id。将诊断导出附加到 bug 报告中，而不是复制原始日志。

相关文档：

Gateway 拒绝无效配置 ​

当 Gateway 启动失败显示 Invalid config，或热重载日志显示它跳过了无效编辑时使用：

bash
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.* 文件，并轮换更早的文件
发生了什么
  • 在启动、热重载或 OpenClaw 拥有的写入期间配置未通过验证。
  • Gateway 启动失败关闭，而不是重写 openclaw.json。
  • 热重载跳过无效外部编辑，保持当前运行时配置活跃。
  • OpenClaw 拥有的写入在提交前拒绝无效/破坏性载荷，并保存 .rejected.*。
  • openclaw doctor --fix 拥有修复权。它可以删除非 JSON 前缀或从最后一个已知好副本恢复，同时将拒绝的载荷保留为 .clobbered.*。
  • 当许多修复发生在一个配置路径上时，OpenClaw 会轮换较旧的 .clobbered.* 文件，以便最新的修复载荷仍然可用。
检查和修复
bash
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
常见特征
  • .clobbered.* 存在 → doctor 保留了损坏的外部编辑，同时修复了活动配置。
  • .rejected.* 存在 → OpenClaw 拥有的配置写入在提交前失败 schema 或覆盖检查。
  • Config write rejected: → 写入试图删除必需形状、急剧缩小文件或持久化无效配置。
  • config reload skipped (invalid config): → 直接编辑未能通过验证，被运行中的 Gateway 忽略。
  • Invalid config at ... → 启动失败，Gateway 服务未启动。
  • missing-meta-vs-last-good、gateway-mode-missing-vs-last-good 或 size-drop-vs-last-good:* → OpenClaw 拥有的写入被拒绝，因为它与最后已知好备份相比丢失了字段或大幅缩减大小。
  • Config last-known-good promotion skipped → 候选包含已编辑的秘密占位符如 ***。
修复选项
  1. 运行 openclaw doctor --fix 让 doctor 修复前缀/损坏的配置或恢复最后已知好副本。
  2. 从 .clobbered.* 或 .rejected.* 仅复制预期键，然后使用 openclaw config set 或 config.patch 应用它们。
  3. 重启前运行 openclaw config validate。
  4. 如果手动编辑，保持完整的 JSON5 配置，而不是只想更改的部分对象。

相关文档：

Gateway 探测警告 ​

当 openclaw gateway probe 能够连接到目标，但仍然打印了警告块时使用：

bash
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 配置失败，但命令仍然尝试了直接配置/loopback 目标。
  • multiple reachable gateways detected → 多个目标响应了探测。通常意味着有意的多 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 警告文本 → 该命令路径在失败目标上无法获取认证材料。

相关文档：

频道已连接但消息不流动 ​

频道状态为已连接但消息流中断时，重点检查策略、权限和频道特定的交付规则：

bash
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）。
  • 群组允许列表和提及需求。
  • 缺少频道 API 权限/范围。

常见特征：

  • mention required → 群组提及策略忽略了消息。
  • pairing / 待审批跟踪 → 发送者未获批准。
  • missing_scope、not_in_channel、Forbidden、401/403 → 频道认证/权限问题。

相关文档：

定时任务和心跳投递 ​

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

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

排查要点：

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

常见特征：

  • cron: scheduler disabled; jobs will not run automatically → 定时任务已禁用。
  • cron: timer tick failed → 调度器计时器失败；检查文件/日志/运行时错误。
  • heartbeat skipped 且 reason=quiet-hours → 在活跃时间窗口之外。
  • heartbeat skipped 且 reason=empty-heartbeat-file → HEARTBEAT.md 存在但只包含空行/markdown 标题，OpenClaw 跳过了模型调用。
  • heartbeat skipped 且 reason=no-tasks-due → HEARTBEAT.md 包含 tasks: 块，但本次 tick 没有任何到期任务。
  • heartbeat: unknown accountId → 心跳投递目标的 account id 无效。
  • heartbeat skipped 且 reason=dm-blocked → 心跳目标解析到 DM 类目标，但 agents.defaults.heartbeat.directPolicy（或每个 agent 覆盖）设为 block。

相关文档：

节点已配对但工具失败 ​

节点已配对但工具失败时，隔离前台、权限和审批状态：

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

排查要点：

  • 节点在线且具有预期功能。
  • 摄像头/麦克风/位置/屏幕的 OS 权限授予。
  • Exec 审批和允许列表状态。

常见特征：

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

相关文档：

浏览器工具失败 ​

Gateway 本身健康但浏览器工具操作失败时使用：

bash
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 可用性。
插件/可执行文件特征
  • unknown command "browser" 或 unknown command 'browser' → 捆绑浏览器插件被 plugins.allow 排除。
  • 浏览器工具缺失/不可用但 browser.enabled=true → plugins.allow 排除了 browser，导致插件从未加载。
  • Failed to start Chrome CDP on port → 浏览器进程启动失败。
  • browser.executablePath not found → 配置的路径无效。
  • browser.cdpUrl must be http(s) or ws(s) → 配置的 CDP URL 使用了不支持的协议（如 file: 或 ftp:）。
  • browser.cdpUrl has invalid port → 配置的 CDP URL 端口无效或超出范围。
  • Playwright is not available in this gateway build; '&lt;feature&gt;' is unsupported. → 当前 gateway 安装缺少核心浏览器运行时依赖；重新安装或更新 OpenClaw，然后重启 gateway。ARIA 快照和基础页面截图仍然可用，但导航、AI 快照、CSS 选择器元素截图和 PDF 导出仍然不可用。
Chrome MCP / existing-session 特征
  • Could not find DevToolsActivePort for chrome → Chrome MCP existing-session 无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器打开，批准第一个附加提示，然后重试。如果不需要登录状态，优先使用托管的 openclaw 配置文件。
  • No Chrome tabs found for profile="user" → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
  • Remote CDP for profile "&lt;name&gt;" is not reachable → 配置的远程 CDP 端点从 gateway 主机不可达。
  • Browser attachOnly is enabled ... not reachable 或 Browser attachOnly is enabled and CDP websocket ... is not reachable → 仅附加配置文件没有可达目标，或 HTTP 端点响应但 CDP WebSocket 仍然无法打开。
元素/截图/上传特征
  • fullPage is not supported for element screenshots → 截图请求同时传入了 --full-page 和 --ref / --element。
  • element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP / existing-session 截图调用必须使用页面捕获或快照 --ref，而非 CSS --element。
  • existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome MCP 上传钩子需要快照 ref，而非 CSS 选择器。
  • existing-session file uploads currently support one file at a time. → 在 Chrome MCP 配置文件上每次调用只能上传一个文件。
  • existing-session dialog handling does not support timeoutMs. → Chrome MCP 配置文件上的对话框钩子不支持超时覆盖。
  • existing-session type does not support timeoutMs overrides. → 对 profile="user" / Chrome MCP existing-session 配置文件省略 act:type 上的 timeoutMs，或当需要自定义超时时使用托管/CDP 浏览器配置文件。
  • existing-session evaluate does not support timeoutMs overrides. → 对 profile="user" / Chrome MCP existing-session 配置文件省略 act:evaluate 上的 timeoutMs，或当需要自定义超时时使用托管/CDP 浏览器配置文件。
  • response body is not supported for existing-session profiles yet. → responsebody 仍然需要托管浏览器或原始 CDP 配置文件。
  • 仅附加或远程 CDP 配置文件上的过期 viewport / 深色模式 / 语言 / 离线覆盖 → 运行 openclaw browser stop --browser-profile &lt;name&gt; 关闭当前控制会话并释放 Playwright/CDP 仿真状态，而无需重启整个 gateway。

相关文档：

升级后突然出现问题 ​

大多数升级后的问题是配置漂移或更严格的默认值被强制执行。

1. 认证和 URL 覆盖行为变化
bash
openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

检查内容：

  • 如果 gateway.mode=remote，CLI 调用可能指向远端，而本地服务正常。
  • 显式 --url 调用不会回退到存储的凭据。

常见特征：

  • gateway connect failed: → URL 目标错误。
  • unauthorized → 端点可达但认证错误。
2. 绑定和认证防护更严格
bash
openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

检查内容：

  • 非 loopback 绑定（lan、tailnet、custom）需要有效的 gateway 认证路径：共享 token/密码认证，或已正确配置的非 loopback trusted-proxy 部署。
  • 旧密钥如 gateway.token 不能替代 gateway.auth.token。

常见特征：

  • refusing to bind gateway ... without auth → 非 loopback 绑定但没有有效的 gateway 认证路径。
  • Connectivity probe: failed 但运行时在运行 → gateway 存活但当前认证/URL 无法访问。
3. 配对和设备身份状态变化
bash
openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

检查内容：

  • dashboard/节点的待处理设备审批。
  • 策略或身份变更后的 DM 配对审批待处理。

常见特征：

  • device identity required → 设备认证未满足。
  • pairing required → 发送者/设备必须被审批。

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

bash
openclaw gateway install --force
openclaw gateway restart

相关文档：

常见问题 ​

更新后 Gateway 不运行怎么办？ ​

首先运行 openclaw status --all 和 openclaw update status --json 检查更新状态。如果显示 Update restart 待处理，则执行提示的下一步命令。接着运行 openclaw doctor --fix 修复可能损坏的依赖，然后 openclaw gateway restart 重启服务。如果问题依旧，检查是否有脑裂安装：用 which openclaw 确认当前二进制路径，用 openclaw --version 比较版本，并用 openclaw gateway status --deep 查看服务配置是否存在 Config (cli) 与 Config (service) 不一致。参考上文“脑裂安装与新版配置保护”部分。

浏览器工具报错 unknown command browser 怎么解决？ ​

这个错误表示浏览器插件被 plugins.allow 排除了。运行 openclaw doctor 和 openclaw config get plugins.allow 检查配置。如果 plugins.allow 中不包含 browser，需添加。也可以直接运行 openclaw doctor --fix 自动修复常见问题。确认后重启 Gateway 使配置生效。

频道有连接但没有回复，怎么排查？ ​

先运行 openclaw channels status --probe 查看每个渠道的连接状态。然后检查 openclaw pairing list --channel &lt;channel&gt; 看 DM 发送者是否处于待配对状态。查看日志中的 drop guild message (mention required 或 pairing request 等关键词。同时确认频道允许列表和群组提及策略是否正确。详情请参考上文“频道无回复”和“频道已连接但消息不流动”部分。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策