网关

故障排除

此页面是深度运行手册。如果你想先使用快速排查流程，请从 /help/troubleshooting 开始。

命令阶梯

先按此顺序运行这些命令：

bash

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 网关服务在更新后意外停止，或日志显示某个 openclaw 二进制文件旧于最后写入 openclaw.json 的版本时，使用此部分。

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

bash

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

修复 PATH

修复 PATH，让 openclaw 解析到较新的安装，然后重新运行该操作。

重新安装 Gateway 网关服务

从较新的安装重新安装目标 Gateway 网关服务：

bash

openclaw gateway install --forceopenclaw gateway restart

移除过时包装器

移除仍指向旧 openclaw 二进制文件的过时系统包或旧包装器条目。

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

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

text

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

OpenClaw 将每个 skill 根目录视为一个包含边界。位于 ~/.agents/skills、<workspace>/.agents/skills、<workspace>/skills 或 ~/.openclaw/skills 下的符号链接，如果其真实目标解析到该根目录之外，除非该目标被显式信任，否则会被跳过。

检查链接：

bash

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

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

json5

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

然后启动新会话，或等待 skills 观察器刷新。如果正在运行的进程早于配置变更，请重启 Gateway 网关。

不要使用 ~、/ 或整个同步项目文件夹这类宽泛目标。将 allowSymlinkTargets 限定到包含受信任 SKILL.md 目录的真实 skill 根目录。

相关：

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

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

bash

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

查找：

选中的 Anthropic Opus/Sonnet 模型带有 params.context1m: true。
当前 Anthropic 凭证不具备长上下文使用资格。
请求仅在需要 1M beta 路径的长会话/模型运行中失败。

修复选项：

禁用 context1m

为该模型禁用 context1m，以回退到普通上下文窗口。

使用符合条件的凭证

使用符合长上下文请求条件的 Anthropic 凭证，或切换到 Anthropic API key。

配置回退模型

配置回退模型，以便 Anthropic 长上下文请求被拒绝时运行仍可继续。

相关：

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

在以下情况使用：

curl ... /v1/models 可用
微型直接 /v1/chat/completions 调用可用
OpenClaw 模型运行仅在正常 agent 轮次中失败

bash

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 运行仅在较大 prompt 上失败
即使直接 /v1/chat/completions 使用相同的裸模型 ID 可用，仍出现 model_not_found 或 404 错误
后端报错称 messages[].content 需要字符串
使用 OpenAI 兼容本地后端时，间歇性出现 incomplete turn detected ... stopReason=stop payloads=0 警告
仅在较大 prompt-token 数量或完整 agent 运行时 prompt 下出现的后端崩溃

常见特征

本地 MLX/vLLM 风格服务器出现 model_not_found → 验证 baseUrl 包含 /v1，对于 /v1/chat/completions 后端，api 为 "openai-completions"，并且 models.providers.<provider>.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 内容片段。修复：设置 models.providers.<provider>.models[].compat.requiresStringContent: true。
validation.keys 或类似 ["role","content"] 的允许消息键 → 后端拒绝 Chat Completions 消息上的 OpenAI 风格重放元数据。修复：设置 models.providers.<provider>.models[].compat.strictMessageKeys: true。
incomplete turn detected ... stopReason=stop payloads=0 → 后端完成了 Chat Completions 请求，但该轮次没有返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常表示后端正在发出空/非文本内容，或抑制最终答案文本。
直接微型请求成功，但 OpenClaw agent 运行因后端/模型崩溃而失败（例如某些 inferrs 构建上的 Gemma）→ OpenClaw 传输很可能已经正确；失败的是后端无法处理更大的 agent 运行时 prompt 形态。
禁用工具后故障减少但没有消失 → 工具 schema 是压力的一部分，但剩余问题仍然是上游模型/服务器容量或后端 bug。

修复选项

对仅支持字符串的 Chat Completions 后端设置 compat.requiresStringContent: true。
对只接受每条消息上的 role 和 content 的严格 Chat Completions 后端设置 compat.strictMessageKeys: true。
对无法可靠处理 OpenClaw 工具 schema 表面的模型/后端设置 compat.supportsTools: false。
尽可能降低 prompt 压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用具有更强长上下文支持的后端。
如果直接微型请求持续通过，而 OpenClaw agent 轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并在那里提交带有已接受 payload 形态的复现。

相关：

无回复

如果渠道已启动但没有任何应答，请先检查路由和策略，再重新连接任何内容。

bash

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

相关：

仪表盘控制 UI 连接

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

bash

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

查找：

正确的探测 URL 和仪表盘 URL。
客户端和 Gateway 网关之间的认证模式/token 不匹配。
在需要设备身份时使用 HTTP。

连接/认证特征

device identity required → 非安全上下文或缺少设备认证。
origin not allowed → 浏览器 Origin 不在 gateway.controlUi.allowedOrigins 中（或你正在从非 loopback 浏览器源连接，且没有显式允许列表）。
device nonce required / device nonce mismatch → 客户端未完成基于挑战的设备认证流程（connect.challenge + device.nonce）。
device signature invalid / device signature expired → 客户端为当前握手签署了错误 payload（或过期时间戳）。
AUTH_TOKEN_MISMATCH 且 canRetryWithDeviceToken=true → 客户端可以用缓存的设备 token 执行一次受信任重试。
该缓存 token 重试会复用与配对设备 token 一起存储的缓存 scope 集。显式 deviceToken / 显式 scopes 调用方会保留其请求的 scope 集。
AUTH_SCOPE_MISMATCH → 设备 token 已被识别，但其已批准 scope 不覆盖此次连接请求；重新配对或批准请求的 scope 契约，而不是轮换共享 Gateway 网关 token。
在该重试路径之外，连接认证优先级是先显式共享 token/password，再显式 deviceToken，再已存储设备 token，最后 bootstrap token。
在异步 Tailscale Serve Control UI 路径上，同一 {scope, ip} 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端的两次错误并发重试可能会让第二次尝试显示 retry later，而不是两个普通不匹配。
浏览器源 loopback 客户端出现 too many failed authentication attempts (retry later) → 来自同一规范化 Origin 的重复失败会被临时锁定；另一个 localhost 源会使用独立的桶。
该重试后仍重复出现 unauthorized → 共享 token/设备 token 漂移；刷新 token 配置，并在需要时重新批准/轮换设备 token。
gateway connect failed: → 主机/端口/url 目标错误。

认证详情代码快速映射

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

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

设备认证 v2 迁移检查：

bash

openclaw --versionopenclaw doctoropenclaw gateway status

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

等待 connect.challenge

客户端等待 Gateway 网关发出的 connect.challenge。

签署载荷

客户端签署与质询绑定的载荷。

发送设备 nonce

客户端使用同一个质询 nonce 发送 connect.params.device.nonce。

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

已配对设备令牌会话只能管理自己的设备，除非调用方同时拥有 operator.admin
openclaw devices rotate --scope ... 只能请求调用方会话已经持有的 operator 作用域

相关内容：

配置（Gateway 网关认证模式）
控制 UI
设备
远程访问
可信代理认证

Gateway 网关服务未运行

在服务已安装但进程无法持续运行时使用此项。

bash

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # also scan system-level services

查找：

带退出提示的 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 网关认证路径（令牌/密码，或已配置的可信代理）。
another gateway instance is already listening / EADDRINUSE → 端口冲突。
Other gateway-like services detected (best effort) → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数设置应在每台机器上只保留一个 Gateway 网关；如果确实需要多个，请隔离端口 + 配置/状态/工作区。参见 /gateway#multiple-gateways-same-host。
Doctor 输出 System-level OpenClaw gateway service detected → 存在 systemd 系统单元，而用户级服务缺失。在允许 Doctor 安装用户服务之前，移除或禁用重复项；如果该系统单元是预期的 supervisor，请设置 OPENCLAW_SERVICE_REPAIR_POLICY=external。
Gateway service port does not match current gateway config → 已安装的 supervisor 仍固定旧的 --port。运行 openclaw doctor --fix 或 openclaw gateway install --force，然后重启 Gateway 网关服务。

相关内容：

Gateway 网关拒绝无效配置

当 Gateway 网关启动因 Invalid config 失败，或热重载日志表示已跳过无效编辑时，使用此项。

bash

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 拥有的写入期间未通过验证。
Gateway 网关启动以失败关闭方式终止，而不是重写 openclaw.json。
热重载会跳过无效的外部编辑，并保持当前运行时配置处于活动状态。
OpenClaw 拥有的写入会在提交前拒绝无效/破坏性载荷，并保存 .rejected.*。
openclaw doctor --fix 负责修复。它可以移除非 JSON 前缀，或恢复最后已知良好的副本，同时将被拒绝的载荷保留为 .clobbered.*。

检查并修复

bash

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

常见特征

.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 → 候选内容包含已脱敏的密钥占位符，例如 ***。

修复选项

运行 openclaw doctor --fix，让 Doctor 修复带前缀/被覆盖的配置，或恢复最后已知良好配置。
仅从 .clobbered.* 或 .rejected.* 复制预期键名，然后使用 openclaw config set 或 config.patch 应用它们。
重启前运行 openclaw config validate。
如果手动编辑，请保留完整 JSON5 配置，而不是只保留你想更改的局部对象。

相关内容：

Gateway 网关探测警告

当 openclaw gateway probe 能够访问到某些目标，但仍打印警告块时，使用此项。

bash

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 设置失败，但命令仍尝试了直接配置目标/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 网关已响应，但此客户端在正常 operator 访问前仍需要配对/批准。
未解析的 gateway.auth.* / gateway.remote.* SecretRef 警告文本 → 此命令路径无法为失败目标取得认证材料。

相关内容：

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

如果频道状态为已连接但消息流已停止，请重点检查策略、权限和频道特定的投递规则。

bash

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 → 频道认证/权限问题。

相关：

Cron 和 Heartbeat 投递

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

bash

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

Common signatures

cron: scheduler disabled; jobs will not run automatically → cron 已禁用。
cron: timer tick failed → 调度器计时器 tick 失败；检查文件/日志/运行时错误。
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 → Heartbeat 投递目标的账号 ID 无效。
heartbeat skipped 且 reason=dm-blocked → Heartbeat 目标解析为私信风格目标，而 agents.defaults.heartbeat.directPolicy（或每个智能体的覆盖配置）设置为 block。

相关：

节点已配对，但工具失败

如果节点已配对但工具失败，请隔离前台、权限和批准状态。

bash

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw 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 statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

检查：

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

Plugin / executable signatures

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 使用了不受支持的 scheme，例如 file: 或 ftp:。
browser.cdpUrl has invalid port → 配置的 CDP URL 端口错误或超出范围。
Playwright is not available in this gateway build; '<feature>' is unsupported. → 当前 Gateway 网关安装缺少核心浏览器运行时依赖；重新安装或更新 OpenClaw，然后重启 Gateway 网关。ARIA 快照和基本页面截图仍可工作，但导航、AI 快照、CSS 选择器元素截图和 PDF 导出仍不可用。

Chrome MCP / existing-session signatures

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 "<name>" is not reachable → 配置的远程 CDP 端点无法从 Gateway 网关主机访问。
Browser attachOnly is enabled ... not reachable 或 Browser attachOnly is enabled and CDP websocket ... is not reachable → 仅附加配置文件没有可达目标，或 HTTP 端点已响应但 CDP WebSocket 仍无法打开。

Element / screenshot / upload signatures

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 上传钩子需要快照引用，而不是 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 配置文件。
附加-only 或远程 CDP 配置文件上的过期视口 / 深色模式 / 语言区域 / 离线覆盖 → 运行 openclaw browser stop --browser-profile <name> 以关闭活动控制会话，并释放 Playwright/CDP 仿真状态，而无需重启整个 Gateway 网关。

相关：

如果你升级后某些内容突然损坏

大多数升级后的故障来自配置漂移，或现在被强制执行的更严格默认值。

1. Auth and URL override behavior changed

bash

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

要检查的内容：

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

常见特征：

gateway connect failed: → URL 目标错误。
unauthorized → 端点可达但认证错误。

2. Bind and auth guardrails are stricter

bash

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw 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. Pairing and device identity state changed

bash

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

要检查的内容：

dashboard/nodes 的待处理设备批准。
策略或身份变更后的待处理私信配对批准。

常见特征：

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

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

bash

openclaw gateway install --forceopenclaw gateway restart

相关：