openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-28 20:58:30 +00:00
parent f87b2b7232
commit 5fb5e92c4f
2 changed files with 248 additions and 246 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
docs/zh-CN/cli/gateway.md
View File

@ -1,31 +1,31 @@
---
read_when:
- 从 CLI 运行 Gateway 网关（开发环境或服务器）
- 调试 Gateway 网关的身份验证、绑定模式和连接性
- 调试 Gateway 网关的凭证、绑定模式和连接性
- 通过 Bonjour 发现 Gateway 网关（本地 + 广域 DNS-SD）
sidebarTitle: Gateway
summary: OpenClaw Gateway 网关 CLI (`openclaw gateway`) — 运行、查询和发现 Gateway 网关
title: Gateway 网关
x-i18n:
generated_at: "2026-04-28T11:48:26Z"
generated_at: "2026-04-28T20:56:43Z"
model: gpt-5.5
provider: openai
source_hash: ea6cb28046bb9a29c9f308a951c5ff3d25f8ebea4edfeb91e4688ceab5a8bc78
source_hash: 25680abf3f6f32fe9a5eea846ce6223c0d82896b5ae0bc09ea6bd8403ac34cfd
source_path: cli/gateway.md
workflow: 16
---
Gateway 网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、钩子）。本页中的子命令都位于 `openclaw gateway …` 下。
Gateway 网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、钩子）。本页中的子命令位于 `openclaw gateway …` 下。
<CardGroup cols={3}>
<Card title="Bonjour 设备发现" href="/zh-CN/gateway/bonjour">
本地 mDNS + 广域 DNS-SD 设置。
</Card>
<Card title="设备发现概览" href="/zh-CN/gateway/discovery">
OpenClaw 如何公布和发现 Gateway 网关。
OpenClaw 如何通告和发现 Gateway 网关。
</Card>
<Card title="配置" href="/zh-CN/gateway/configuration">
顶层 Gateway 网关配置键。
顶层 gateway 配置键。
</Card>
</CardGroup>
@ -45,12 +45,12 @@ openclaw gateway run
<AccordionGroup>
<Accordion title="启动行为">
- 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 网关会拒绝启动。对于临时/开发运行，请使用 `--allow-unconfigured`。
- `openclaw onboard --mode local` 和 `openclaw setup` 预期会写入 `gateway.mode=local`。如果文件存在但缺少 `gateway.mode`，应将其视为损坏或被覆盖的配置并修复它，而不是隐式假定为本地模式。
- 如果文件存在且缺少 `gateway.mode`，Gateway 网关会将其视为可疑的配置损坏，并拒绝为你“猜测 local”。
- 未启用身份验证时禁止绑定到 loopback 之外（安全防护栏）。
- 授权后，`SIGUSR1` 会触发进程内重启（默认启用 `commands.restart`；设置 `commands.restart: false` 可阻止手动重启，同时仍允许 Gateway 网关工具/配置应用/更新）。
- `SIGINT`/`SIGTERM` 处理程序会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw-mode 输入包装 CLI，请在退出前恢复终端。
- 默认情况下，除非在 `~/.openclaw/openclaw.json` 中设置了 `gateway.mode=local`，否则 Gateway 网关会拒绝启动。仅将 `--allow-unconfigured` 用于临时/开发运行。
- `openclaw onboard --mode local` 和 `openclaw setup` 应写入 `gateway.mode=local`。如果文件存在但缺少 `gateway.mode`，应将其视为损坏或被覆盖的配置并修复，而不是隐式假定为本地模式。
- 如果文件存在且缺少 `gateway.mode`，Gateway 网关会将其视为可疑的配置损坏，并拒绝替你“猜测为本地”。
- 绑定到回环地址以外且没有身份验证会被阻止（安全护栏）。
- `SIGUSR1` 在获得授权时会触发进程内重启（默认启用 `commands.restart`；设置 `commands.restart: false` 可阻止手动重启，而 Gateway 网关工具/配置的应用/更新仍会允许）。
- `SIGINT`/`SIGTERM` 处理程序会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或原始模式输入包装 CLI，请在退出前恢复终端。
</Accordion>
</AccordionGroup>
@ -67,7 +67,7 @@ openclaw gateway run
身份验证模式覆盖。
</ParamField>
<ParamField path="--token <token>" type="string">
令牌覆盖（也会为进程设置 `OPENCLAW_GATEWAY_TOKEN`）。
令牌覆盖（也会为该进程设置 `OPENCLAW_GATEWAY_TOKEN`）。
</ParamField>
<ParamField path="--password <password>" type="string">
密码覆盖。
@ -91,7 +91,7 @@ openclaw gateway run
重置开发配置 + 凭据 + 会话 + 工作区（需要 `--dev`）。
</ParamField>
<ParamField path="--force" type="boolean">
启动前终止所选端口上任何现有监听器。
启动前终止选定端口上的任何现有监听器。
</ParamField>
<ParamField path="--verbose" type="boolean">
详细日志。
@ -100,7 +100,7 @@ openclaw gateway run
仅在控制台显示 CLI 后端日志（并启用 stdout/stderr）。
</ParamField>
<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
Websocket 日志样式。
WebSocket 日志样式。
</ParamField>
<ParamField path="--compact" type="boolean">
`--ws-log compact` 的别名。
@ -118,8 +118,8 @@ openclaw gateway run
### 启动性能分析
- 设置 `OPENCLAW_GATEWAY_STARTUP_TRACE=1` 可在 Gateway 网关启动期间记录各阶段耗时，包括每个阶段的 `eventLoopMax` 延迟，以及已安装索引、清单注册表、启动规划和 owner-map 工作的插件查找表耗时。
- 运行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 来基准测试 Gateway 网关启动。该基准测试会记录首次进程输出、`/healthz`、`/readyz`、启动追踪耗时、事件循环延迟，以及插件查找表耗时详情。
- 设置 `OPENCLAW_GATEWAY_STARTUP_TRACE=1` 可在 Gateway 网关启动期间记录阶段耗时，包括每阶段 `eventLoopMax` 延迟，以及已安装索引、清单注册表、启动规划和 owner-map 工作的插件查询表耗时。
- 运行 `pnpm test:startup:gateway -- --runs 5 --warmup 1` 可对 Gateway 网关启动进行基准测试。该基准测试会记录首个进程输出、`/healthz`、`/readyz`、启动跟踪耗时、事件循环延迟，以及插件查询表耗时详情。
## 查询正在运行的 Gateway 网关
@ -128,7 +128,7 @@ openclaw gateway run
<Tabs>
<Tab title="输出模式">
- 默认：人类可读（TTY 中带颜色）。
- `--json`：机器可读的 JSON（无样式/spinner）。
- `--json`：机器可读 JSON（无样式/加载指示器）。
- `--no-color`（或 `NO_COLOR=1`）：禁用 ANSI，同时保留人类可读布局。
</Tab>
@ -143,7 +143,7 @@ openclaw gateway run
</Tabs>
<Note>
设置 `--url` 时，CLI 不会回退到配置或环境凭据。请显式传入 `--token` 或 `--password`。缺少显式凭据会报错。
设置 `--url` 时，CLI 不会回退到配置或环境凭据。请显式传入 `--token` 或 `--password`。缺少显式凭据是错误。
</Note>
### `gateway health`
@ -152,11 +152,11 @@ openclaw gateway run
openclaw gateway health --url ws://127.0.0.1:18789
```
HTTP `/healthz` 端点是存活探针：一旦服务器可以响应 HTTP 就会返回。HTTP `/readyz` 端点更严格，在启动 sidecar、渠道或已配置钩子仍在稳定期间会保持红色。本地或经过身份验证的详细就绪响应包含一个 `eventLoop` 诊断块，其中包含事件循环延迟、事件循环利用率、CPU 核心比例和 `degraded` 标志。
HTTP `/healthz` 端点是存活探测：服务器能够响应 HTTP 后就会返回。HTTP `/readyz` 端点更严格，在启动边车、渠道或配置的钩子仍在稳定时会保持红色。本地或已认证的详细就绪响应包含一个 `eventLoop` 诊断块，其中包括事件循环延迟、事件循环利用率、CPU 核心比例和 `degraded` 标志。
### `gateway usage-cost`
从会话日志获取使用成本摘要。
从会话日志获取用量成本摘要。
```bash
openclaw gateway usage-cost
@ -184,13 +184,13 @@ openclaw gateway stability --json
要包含的最近事件最大数量（最大 `1000`）。
</ParamField>
<ParamField path="--type <type>" type="string">
按诊断事件类型过滤，例如 `payload.large` 或 `diagnostic.memory.pressure`。
按诊断事件类型筛选，例如 `payload.large` 或 `diagnostic.memory.pressure`。
</ParamField>
<ParamField path="--since-seq <seq>" type="number">
仅包含某个诊断序列号之后的事件。
仅包含诊断序列号之后的事件。
</ParamField>
<ParamField path="--bundle [path]" type="string">
读取持久化的稳定性包，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅使用 `--bundle`）读取状态目录下最新的包，或直接传入包 JSON 路径。
读取持久化的稳定性包，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅使用 `--bundle`）读取状态目录下的最新包，也可以直接传入包 JSON 路径。
</ParamField>
<ParamField path="--export" type="boolean">
写入可共享的支持诊断 zip，而不是打印稳定性详情。
@ -201,15 +201,15 @@ openclaw gateway stability --json
<AccordionGroup>
<Accordion title="隐私和包行为">
- 记录会保留运行元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie、密钥值、主机名或原始会话 ID。设置 `diagnostics.enabled: false` 可完全禁用记录器。
- 在致命 Gateway 网关退出、关闭超时和重启启动失败时，如果记录器中有事件，OpenClaw 会将同一个诊断快照写入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。使用 `openclaw gateway stability --bundle latest` 检查最新包；`--limit`、`--type` 和 `--since-seq` 也适用于包输出。
- 记录会保留运行元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、Cookie、秘密值、主机名或原始会话 ID。设置 `diagnostics.enabled: false` 可完全禁用记录器。
- 在 Gateway 网关致命退出、关闭超时和重启启动失败时，如果记录器中有事件，OpenClaw 会将相同的诊断快照写入 `~/.openclaw/logs/stability/openclaw-stability-*.json`。使用 `openclaw gateway stability --bundle latest` 检查最新包；`--limit`、`--type` 和 `--since-seq` 也适用于包输出。
</Accordion>
</AccordionGroup>
### `gateway diagnostics export`
写入本地诊断 zip，设计用于附加到错误报告。有关隐私模型和包内容，请参阅 [诊断导出](/zh-CN/gateway/diagnostics)。
写入本地诊断 zip，设计用于附加到 bug 报告。有关隐私模型和包内容，请参阅 [诊断导出](/zh-CN/gateway/diagnostics)。
```bash
openclaw gateway diagnostics export
@ -218,7 +218,7 @@ openclaw gateway diagnostics export --json
```
<ParamField path="--output <path>" type="string">
输出 zip 路径。默认写入状态目录下的支持导出。
输出 zip 路径。默认为状态目录下的支持导出。
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
要包含的最大已清理日志行数。
@ -245,13 +245,13 @@ openclaw gateway diagnostics export --json
以 JSON 打印写入路径、大小和清单。
</ParamField>
导出内容包含清单、Markdown 摘要、配置形状、已清理的配置详情、已清理的日志摘要、已清理的 Gateway 网关 Status/健康快照，以及在存在时的最新稳定性包。
导出包含清单、Markdown 摘要、配置形状、已清理的配置详情、已清理的日志摘要、已清理的 Gateway 网关状态/健康快照，以及存在时的最新稳定性包。
它旨在用于共享。它会保留有助于调试的运行细节，例如安全的 OpenClaw 日志字段、子系统名称、状态码、持续时间、已配置模式、端口、插件 ID、提供商 ID、非密钥功能设置，以及已脱敏的运行日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭据、Cookie、账号/消息标识符、提示/指令文本、主机名和密钥值。当 LogTape 风格的消息看起来像用户/聊天/工具载荷文本时，导出只保留该消息已被省略以及其字节数。
它旨在用于共享。它保留有助于调试的运行详情，例如安全的 OpenClaw 日志字段、子系统名称、状态码、持续时间、已配置模式、端口、插件 ID、提供商 ID、非秘密功能设置，以及已脱敏的运行日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭据、Cookie、账户/消息标识符、提示/指令文本、主机名和秘密值。当 LogTape 风格的消息看起来像用户/聊天/工具载荷文本时，导出只保留消息已被省略这一事实及其字节数。
### `gateway status`
`gateway status` 会显示 Gateway 网关服务（launchd/systemd/schtasks），并可选探测连接性/身份验证能力。
`gateway status` 显示 Gateway 网关服务（launchd/systemd/schtasks），以及可选的连接性/身份验证能力探测。
```bash
openclaw gateway status
@ -260,13 +260,13 @@ openclaw gateway status --require-rpc
```
<ParamField path="--url <url>" type="string">
添加显式探测目标。已配置的远程 + localhost 仍会被探测。
添加显式探测目标。仍会探测已配置的远程目标 + localhost。
</ParamField>
<ParamField path="--token <token>" type="string">
探测的令牌身份验证。
用于探测的令牌身份验证。
</ParamField>
<ParamField path="--password <password>" type="string">
探测的密码身份验证。
用于探测的密码身份验证。
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="10000">
探测超时。
@ -275,29 +275,29 @@ openclaw gateway status --require-rpc
跳过连接性探测（仅服务视图）。
</ParamField>
<ParamField path="--deep" type="boolean">
同时扫描系统级服务。
也扫描系统级服务。
</ParamField>
<ParamField path="--require-rpc" type="boolean">
将默认连接性探测升级为读取探测，并在该读取探测失败时以非零状态退出。不能与 `--no-probe` 组合使用。
将默认连接性探测升级为读取探测，并在该读取探测失败时以非零状态退出。不能与 `--no-probe` 组合。
</ParamField>
<AccordionGroup>
<Accordion title="Status 语义">
- `gateway status` 即使在本地 CLI 配置缺失或无效时，也会继续可用于诊断。
- 默认的 `gateway status` 会验证服务状态、WebSocket 连接，以及握手时可见的鉴权能力。它不会验证读/写/admin 操作。
- 对首次设备鉴权，诊断探针不会修改状态：如果已有缓存的设备令牌，它们会复用；但它们不会仅为了检查 Status 而创建新的 CLI 设备身份或只读设备配对记录。
- `gateway status` 会在可能时解析已配置的鉴权 SecretRefs，用于探针鉴权。
- 如果此命令路径中所需的鉴权 SecretRef 未解析，且探针连接性/鉴权失败，`gateway status --json` 会报告 `rpc.authWarning`；请显式传入 `--token`/`--password`，或先解析密钥来源。
- 如果探针成功，则会抑制未解析鉴权引用警告，以避免误报。
- 在脚本和自动化中，如果监听中的服务还不够、你还需要读作用域 RPC 调用也保持健康，请使用 `--require-rpc`。
- `--deep` 会尽力扫描额外的 launchd/systemd/schtasks 安装。当检测到多个类似 Gateway 网关的服务时，人类可读输出会打印清理提示，并警告大多数设置应每台机器运行一个 Gateway 网关。
- 人类可读输出会包含解析后的文件日志路径，以及 CLI 与服务配置路径/有效性快照，以帮助诊断配置档或状态目录漂移。
- `gateway status` 即使在本地 CLI 配置缺失或无效时，也仍可用于诊断。
- 默认的 `gateway status` 会验证服务状态、WebSocket 连接，以及握手时可见的身份验证能力。它不会验证读/写/管理员操作。
- 诊断探测对于首次设备身份验证是非变更性的：当已有缓存设备令牌时会复用它，但不会仅为了检查状态而创建新的 CLI 设备身份或只读设备配对记录。
- `gateway status` 会在可能时为探测身份验证解析已配置的身份验证 SecretRefs。
- 如果此命令路径中必需的身份验证 SecretRef 未解析，且探测连接性/身份验证失败，`gateway status --json` 会报告 `rpc.authWarning`；请显式传入 `--token`/`--password`，或先解析密钥来源。
- 如果探测成功，会抑制未解析的 auth-ref 警告，以避免误报。
- 当正在监听的服务还不够、你还需要读范围 RPC 调用也健康时，请在脚本和自动化中使用 `--require-rpc`。
- `--deep` 会尽力扫描额外的 launchd/systemd/schtasks 安装。当检测到多个类似 Gateway 网关的服务时，人类可读输出会打印清理提示，并警告大多数设置应在每台机器上运行一个 Gateway 网关。
- 人类可读输出包含已解析的文件日志路径，以及 CLI 与服务配置路径/有效性快照，帮助诊断配置文件或状态目录漂移。
</Accordion>
<Accordion title="Linux systemd 鉴权漂移检查">
- 在 Linux systemd 安装中，服务鉴权漂移检查会读取 unit 中的 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号的路径、多个文件，以及可选的 `-` 文件）。
- 漂移检查会使用合并后的运行时环境解析 `gateway.auth.token` SecretRefs（先用服务命令环境，再回退到进程环境）。
- 如果令牌鉴权实际上未启用（显式 `gateway.auth.mode` 为 `password`/`none`/`trusted-proxy`，或 mode 未设置且密码可能胜出、没有令牌候选可胜出），令牌漂移检查会跳过配置令牌解析。
<Accordion title="Linux systemd 身份验证漂移检查">
- 在 Linux systemd 安装中，服务身份验证漂移检查会从单元读取 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号的路径、多个文件以及可选的 `-` 文件）。
- 漂移检查会使用合并后的运行时环境解析 `gateway.auth.token` SecretRefs（先使用服务命令环境，再回退到进程环境）。
- 如果令牌身份验证实际上未启用（显式 `gateway.auth.mode` 为 `password`/`none`/`trusted-proxy`，或模式未设置且密码可能胜出并且没有令牌候选项可胜出），令牌漂移检查会跳过配置令牌解析。
</Accordion>
</AccordionGroup>
@ -307,16 +307,16 @@ openclaw gateway status --require-rpc
`gateway probe` 是“调试一切”的命令。它始终会探测：
- 你配置的远程 Gateway 网关（如果已设置），以及
- localhost（loopback），**即使已配置远程目标**。
- localhost（loopback）**即使已配置远程目标**。
如果你传入 `--url`，该显式目标会被添加到这两者之前。人类可读输出会将目标标记为：
如果你传入 `--url`，该显式目标会添加到两者之前。人类可读输出会将目标标记为：
- `URL (explicit)`
- `Remote (configured)` 或 `Remote (configured, inactive)`
- `Local loopback`
<Note>
如果多个 Gateway 网关可达，它会全部打印出来。当你使用隔离的配置档/端口时（例如救援机器人），支持多个 Gateway 网关，但大多数安装仍然只运行单个 Gateway 网关。
如果多个 Gateway 网关可访问，它会全部打印出来。当你使用隔离的配置文件/端口（例如救援机器人）时，支持多个 Gateway 网关，但大多数安装仍只运行单个 Gateway 网关。
</Note>
```bash
@ -326,50 +326,51 @@ openclaw gateway probe --json
<AccordionGroup>
<Accordion title="解读">
- `Reachable: yes` 表示至少有一个目标接受了 WebSocket 连接。
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 报告探针可以验证的鉴权信息。它与可达性是分开的。
- `Read probe: ok` 表示读作用域详情 RPC 调用（`health`/`status`/`system-presence`/`config.get`）也成功了。
- `Read probe: limited - missing scope: operator.read` 表示连接成功，但读作用域 RPC 受限。这会报告为**降级**可达性，而不是完全失败。
- 和 `gateway status` 一样，probe 会复用已有缓存的设备鉴权，但不会创建首次设备身份或配对状态。
- 只有在没有任何被探测目标可达时，退出码才非零。
- `Reachable: yes` 表示至少一个目标接受了 WebSocket 连接。
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` 报告探测可验证的身份验证能力。它与可达性是分开的。
- `Read probe: ok` 表示读范围详情 RPC 调用（`health`/`status`/`system-presence`/`config.get`）也成功了。
- `Read probe: limited - missing scope: operator.read` 表示连接成功，但读范围 RPC 受限。这会报告为**降级**可达性，而不是完全失败。
- `Connect: ok` 之后的 `Read probe: failed` 表示 Gateway 网关接受了 WebSocket 连接，但后续读诊断超时或失败。这同样是**降级**可达性，而不是不可访问的 Gateway 网关。
- 与 `gateway status` 类似，探测会复用现有缓存设备身份验证，但不会创建首次设备身份或配对状态。
- 只有在没有任何被探测目标可达时，退出码才为非零。
</Accordion>
<Accordion title="JSON 输出">
顶层：
- `ok`：至少有一个目标可达。
- `degraded`：至少有一个目标的详情 RPC 受到作用域限制。
- `ok`：至少一个目标可达。
- `degraded`：至少一个目标接受了连接，但未完成完整详情 RPC 诊断。
- `capability`：在可达目标中看到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。
- `primaryTargetId`：按以下顺序视为活动胜出者的最佳目标：显式 URL、SSH 隧道、已配置远程目标，然后是 local loopback。
- `warnings[]`：尽力提供的警告记录，包含 `code`、`message`，以及可选的 `targetIds`。
- `network`：根据当前配置和主机网络派生的 local loopback/tailnet URL 提示。
- `discovery.timeoutMs` 和 `discovery.count`：本次探针实际使用的设备发现预算/结果数量。
- `primaryTargetId`：按以下顺序作为活跃胜出者处理的最佳目标：显式 URL、SSH 隧道、已配置远程目标，然后是 local loopback。
- `warnings[]`：尽力提供的警告记录，包含 `code`、`message` 以及可选的 `targetIds`。
- `network`：从当前配置和主机网络派生的 local loopback/tailnet URL 提示。
- `discovery.timeoutMs` 和 `discovery.count`：此次探测实际使用的设备发现预算/结果数量。
每个目标（`targets[].connect`）：
- `ok`：连接后的可达性 + 降级分类。
- `rpcOk`：完整详情 RPC 成功。
- `scopeLimited`：详情 RPC 因缺少 operator 作用域而失败。
- `scopeLimited`：详情 RPC 因缺少操作员范围而失败。
每个目标（`targets[].auth`）：
- `role`：可用时，`hello-ok` 中报告的鉴权角色。
- `scopes`：可用时，`hello-ok` 中报告的已授予作用域。
- `capability`：该目标暴露的鉴权能力分类。
- `role`：可用时在 `hello-ok` 中报告的身份验证角色。
- `scopes`：可用时在 `hello-ok` 中报告的已授予范围。
- `capability`：该目标暴露的身份验证能力分类。
</Accordion>
<Accordion title="常见警告代码">
- `ssh_tunnel_failed`：SSH 隧道设置失败；命令回退到直接探针。
- `multiple_gateways`：不止一个目标可达；除非你有意运行隔离的配置档，例如救援机器人，否则这并不常见。
- `auth_secretref_unresolved`：无法为失败目标解析已配置的鉴权 SecretRef。
- `probe_scope_limited`：WebSocket 连接成功，但读探针因缺少 `operator.read` 而受限。
- `ssh_tunnel_failed`：SSH 隧道设置失败；命令已回退到直接探测。
- `multiple_gateways`：多个目标可达；除非你有意运行隔离配置文件（例如救援机器人），否则这并不常见。
- `auth_secretref_unresolved`：无法为失败目标解析已配置的身份验证 SecretRef。
- `probe_scope_limited`：WebSocket 连接成功，但读探测因缺少 `operator.read` 而受限。
</Accordion>
</AccordionGroup>
#### 通过 SSH 远程访问（Mac 应用一致性）
#### 通过 SSH 访问远程（与 Mac 应用一致）
macOS 应用的“Remote over SSH”模式使用本地端口转发，因此远程 Gateway 网关（可能仅绑定到 loopback）可通过 `ws://127.0.0.1:<port>` 访问。
macOS 应用的“通过 SSH 访问远程”模式使用本地端口转发，让远程 Gateway 网关（可能只绑定到 loopback）可通过 `ws://127.0.0.1:<port>` 访问。
CLI 等效命令：
@ -384,7 +385,7 @@ openclaw gateway probe --ssh user@gateway-host
身份文件。
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
从解析后的设备发现端点（`local.` 加上已配置的广域域名，如果有）中选择第一个发现的 Gateway 网关主机作为 SSH 目标。仅 TXT 的提示会被忽略。
从已解析的设备发现端点（`local.` 加上已配置的广域域名，如果有）中选择第一个发现的 Gateway 网关主机作为 SSH 目标。仅 TXT 提示会被忽略。
</ParamField>
配置（可选，用作默认值）：
@ -394,7 +395,7 @@ openclaw gateway probe --ssh user@gateway-host
### `gateway call <method>`
低级 RPC 辅助命令。
低层 RPC 辅助命令。
```bash
openclaw gateway call status
@ -402,7 +403,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
<ParamField path="--params <json>" type="string" default="{}">
用于参数的 JSON 对象字符串。
params 的 JSON 对象字符串。
</ParamField>
<ParamField path="--url <url>" type="string">
Gateway 网关 WebSocket URL。
@ -417,14 +418,14 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
超时预算。
</ParamField>
<ParamField path="--expect-final" type="boolean">
主要用于智能体风格的 RPC，这类 RPC 会在最终载荷之前流式传输中间事件。
主要用于智能体式 RPC，这类 RPC 会在最终负载之前流式传输中间事件。
</ParamField>
<ParamField path="--json" type="boolean">
机器可读 JSON 输出。
</ParamField>
<Note>
`--params` 必须是有效的 JSON。
`--params` 必须是有效 JSON。
</Note>
## 管理 Gateway 网关服务
@ -439,7 +440,7 @@ openclaw gateway uninstall
### 使用包装器安装
当托管服务必须通过另一个可执行文件启动时，请使用 `--wrapper`，例如密钥管理器 shim 或 run-as 辅助程序。包装器会接收正常的 Gateway 网关参数，并负责最终用这些参数 exec `openclaw` 或 Node。
当托管服务必须通过另一个可执行文件启动时使用 `--wrapper`，例如密钥管理器 shim 或 run-as 辅助程序。包装器会接收正常的 Gateway 网关参数，并负责最终用这些参数 exec `openclaw` 或 Node。
```bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'
@ -453,7 +454,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```
你也可以通过环境设置包装器。`gateway install` 会验证该路径是可执行文件，将包装器写入服务 `ProgramArguments`，并在服务环境中持久化 `OPENCLAW_WRAPPER`，供后续强制重新安装、更新和 Doctor 修复使用。
你也可以通过环境设置包装器。`gateway install` 会验证路径是可执行文件，将包装器写入服务 `ProgramArguments`，并在服务环境中持久化 `OPENCLAW_WRAPPER`，用于之后的强制重装、更新和 Doctor 修复。
```bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
@ -475,16 +476,16 @@ openclaw gateway restart
</Accordion>
<Accordion title="生命周期行为">
- 使用 `gateway restart` 重启托管服务。不要将 `gateway stop` 和 `gateway start` 串联起来替代重启；在 macOS 上，`gateway stop` 会在停止 LaunchAgent 之前有意禁用它。
- 生命周期命令接受 `--json`，便于脚本使用。
- 使用 `gateway restart` 重启托管服务。不要将 `gateway stop` 和 `gateway start` 串联起来作为重启替代；在 macOS 上，`gateway stop` 会有意先禁用 LaunchAgent 再停止它。
- 生命周期命令接受 `--json`，用于脚本。
</Accordion>
<Accordion title="安装时的鉴权和 SecretRefs">
- 当令牌鉴权需要令牌且 `gateway.auth.token` 由 SecretRef 管理时，`gateway install` 会验证 SecretRef 可解析，但不会将解析后的令牌持久化到服务环境元数据中。
- 如果令牌鉴权需要令牌且已配置的令牌 SecretRef 未解析，安装会封闭失败，而不是持久化回退明文。
- 对于 `gateway run` 上的密码鉴权，优先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`，或由 SecretRef 支持的 `gateway.auth.password`，而不是内联 `--password`。
- 在推断鉴权模式中，仅存在于 shell 的 `OPENCLAW_GATEWAY_PASSWORD` 不会放宽安装令牌要求；安装托管服务时请使用持久配置（`gateway.auth.password` 或配置 `env`）。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，安装会被阻止，直到显式设置 mode。
<Accordion title="安装时的身份验证和 SecretRefs">
- 当令牌身份验证需要令牌且 `gateway.auth.token` 由 SecretRef 管理时，`gateway install` 会验证 SecretRef 可解析，但不会将已解析令牌持久化到服务环境元数据中。
- 如果令牌身份验证需要令牌且已配置的令牌 SecretRef 未解析，安装会封闭失败，而不是持久化回退明文。
- 对于 `gateway run` 上的密码身份验证，优先使用 `OPENCLAW_GATEWAY_PASSWORD`、`--password-file`，或基于 SecretRef 的 `gateway.auth.password`，而不是内联 `--password`。
- 在推断身份验证模式下，仅 shell 中的 `OPENCLAW_GATEWAY_PASSWORD` 不会放宽安装令牌要求；安装托管服务时请使用持久配置（`gateway.auth.password` 或配置 `env`）。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，安装会被阻止，直到显式设置模式。
</Accordion>
</AccordionGroup>
@ -493,17 +494,17 @@ openclaw gateway restart
`gateway discover` 会扫描 Gateway 网关信标（`_openclaw-gw._tcp`）。
- Multicast DNS-SD：`local.`
- Unicast DNS-SD（Wide-Area Bonjour）：选择一个域名（示例：`openclaw.internal.`）并设置 split DNS + DNS 服务器；参见 [Bonjour](/zh-CN/gateway/bonjour)。
- 组播 DNS-SD：`local.`
- 单播 DNS-SD（广域 Bonjour）：选择一个域名（示例：`openclaw.internal.`）并设置 split DNS + DNS 服务器；参见 [Bonjour](/zh-CN/gateway/bonjour)。
只有启用了 Bonjour 设备发现（默认）的 Gateway 网关才会广播信标。
只有启用了 Bonjour 设备发现（默认）的 Gateway 网关才会播发该信标。
广域设备发现记录包含（TXT）：
广域设备发现记录包括（TXT）：
- `role`（Gateway 网关角色提示）
- `transport`（传输提示，例如 `gateway`）
- `gatewayPort`（WebSocket 端口，通常为 `18789`）
- `sshPort`（可选；缺失时客户端默认 SSH 目标为 `22`）
- `sshPort`（可选；当它不存在时，客户端默认 SSH 目标为 `22`）
- `tailnetDns`（MagicDNS 主机名，可用时）
- `gatewayTls` / `gatewayTlsSha256`（TLS 已启用 + 证书指纹）
- `cliPath`（写入广域区域的远程安装提示）
@ -515,10 +516,10 @@ openclaw gateway discover
```
<ParamField path="--timeout <ms>" type="number" default="2000">
每条命令的超时时间（浏览/解析）。
每条命令的超时时间（browse/resolve）。
</ParamField>
<ParamField path="--json" type="boolean">
机器可读输出（也会禁用样式/旋转指示器）。
机器可读输出（也会禁用样式/加载指示器）。
</ParamField>
示例：
@ -529,8 +530,8 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- CLI 会扫描 `local.` 加上已配置的广域域名（如果启用）。
- JSON 输出中的 `wsUrl` 来自解析后的服务端点，而不是来自仅 TXT 的提示，例如 `lanHost` 或 `tailnetDns`。
- CLI 会在启用配置的广域域名时扫描 `local.` 加上该域名。
- JSON 输出中的 `wsUrl` 派生自解析后的服务端点，而不是来自仅 TXT 的提示，例如 `lanHost` 或 `tailnetDns`。
- 在 `local.` mDNS 上，只有当 `discovery.mdns.mode` 为 `full` 时，才会广播 `sshPort` 和 `cliPath`。广域 DNS-SD 仍会写入 `cliPath`；`sshPort` 在那里也保持可选。
</Note>

297
docs/zh-CN/gateway/troubleshooting.md
View File

@ -1,24 +1,24 @@
---
read_when:
- 故障排除中心将你引导到这里，以便进行更深入的诊断
- 你需要稳定的、基于症状的运行手册章节，并包含精确命令
- 你需要基于稳定症状的运行手册章节，并包含确切命令
sidebarTitle: Troubleshooting
summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除运行手册
title: 故障排除
x-i18n:
generated_at: "2026-04-28T11:54:26Z"
generated_at: "2026-04-28T20:56:35Z"
model: gpt-5.5
provider: openai
source_hash: 73743b962f3a44f52ac766f0a5879ed1e10bdce7e7ec7b34053e826a6e77e6f1
source_hash: 2ad4332803ad43f90e793fba71a0fce874b63cb4d4711c6a308ecfa030257cb3
source_path: gateway/troubleshooting.md
workflow: 16
---
此页面是深入运行手册。如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
这是深度运行手册。如果你想先走快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
## 命令阶梯
按以下顺序先运行这些命令：
先按此顺序运行这些命令：
```bash
openclaw status
@ -32,13 +32,13 @@ openclaw channels status --probe
- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok`，以及一行 `Capability: ...`。
- `openclaw doctor` 未报告阻塞性的配置/服务问题。
- `openclaw channels status --probe` 显示每个账户的实时传输状态，并在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。
- `openclaw channels status --probe` 显示每个账户的实时传输状态；在支持的地方，还会显示探测/审计结果，例如 `works` 或 `audit ok`。
## 分裂安装与新版配置保护
## 分裂安装和新版配置保护
当 Gateway 网关服务在更新后意外停止，或日志显示某个 `openclaw` 二进制文件比最后写入 `openclaw.json` 的版本更旧时，请使用此部分。
当 Gateway 网关服务在更新后意外停止，或者日志显示某个 `openclaw` 二进制文件比上次写入 `openclaw.json` 的版本更旧时，使用本节。
OpenClaw 会用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍可检查由新版 OpenClaw 写入的配置，但来自旧版二进制文件的进程和服务变更会被拒绝继续执行。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制服务重装、服务模式 Gateway 网关启动，以及 `gateway --force` 端口清理。
OpenClaw 会用 `meta.lastTouchedVersion` 标记配置写入。只读命令仍可检查由新版 OpenClaw 写入的配置，但来自旧版二进制文件的进程和服务变更会拒绝继续。被阻止的操作包括 Gateway 网关服务启动、停止、重启、卸载、强制服务重装、服务模式 Gateway 网关启动，以及 `gateway --force` 端口清理。
```bash
which openclaw
@ -60,18 +60,18 @@ openclaw config get meta.lastTouchedVersion
```
</Step>
<Step title="移除过时包装器">
移除仍指向旧版 `openclaw` 二进制文件的过时系统包或旧包装器条目。
<Step title="移除过期包装器">
移除仍指向旧 `openclaw` 二进制文件的过期系统包或旧包装器条目。
</Step>
</Steps>
<Warning>
仅限有意降级或紧急恢复时，为单个命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作时保持未设置。
仅在有意降级或紧急恢复时，为单条命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作请保持未设置。
</Warning>
## Anthropic 429：长上下文需要额外用量权限
## Anthropic 429 长上下文需要额外用量资格
当日志/错误包含以下内容时使用：`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
当日志/错误包含：`HTTP 429: rate_limit_error: Extra usage is required for long context requests` 时，使用本节。
```bash
openclaw logs --follow
@ -81,37 +81,37 @@ openclaw config get agents.defaults.models
查找：
- 所选 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。
- 当前 Anthropic 凭证不具备长上下文用量资格。
- 选中的 Anthropic Opus/Sonnet 模型启用了 `params.context1m: true`。
- 当前 Anthropic 凭证不符合长上下文用量资格。
- 请求只在需要 1M beta 路径的长会话/模型运行中失败。
修复选项：
<Steps>
<Step title="禁用 context1m">
为该模型禁用 `context1m`，回退到普通上下文窗口。
对该模型禁用 `context1m`，回退到普通上下文窗口。
</Step>
<Step title="使用具备资格的凭证">
使用具备长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。
<Step title="使用符合资格的凭证">
使用符合长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。
</Step>
<Step title="配置回退模型">
配置回退模型，以便 Anthropic 长上下文请求被拒绝时运行仍可继续。
配置回退模型，让 Anthropic 长上下文请求被拒绝时运行仍能继续。
</Step>
</Steps>
相关：
- [Anthropic](/zh-CN/providers/anthropic)
- [Token 使用量和费用](/zh-CN/reference/token-use)
- [Token 使用和费用](/zh-CN/reference/token-use)
- [为什么我会看到来自 Anthropic 的 HTTP 429？](/zh-CN/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
## 本地 OpenAI 兼容后端可通过直接探测，但智能体运行失败
## 本地 OpenAI 兼容后端通过直接探测，但智能体运行失败
在以下情况使用：
在以下情况使用本节：
- `curl ... /v1/models` 可用
- 微型直接 `/v1/chat/completions` 调用可用
- OpenClaw 模型运行只在普通智能体轮次中失败
- 很小的直接 `/v1/chat/completions` 调用可用
- OpenClaw 模型运行只在普通智能体轮次上失败
```bash
curl http://127.0.0.1:1234/v1/models
@ -124,27 +124,26 @@ openclaw logs --follow
查找：
- 直接微型调用成功，但 OpenClaw 运行只在较大提示词上失败
- 即使直接 `/v1/chat/completions`
使用同一个裸模型 ID 可用，也出现 `model_not_found` 或 404 错误
- 后端错误提示 `messages[].content` 期望字符串
- 直接的小调用成功，但 OpenClaw 运行只在更大的 prompt 上失败
- 即使直接 `/v1/chat/completions` 使用相同的裸模型 ID 可用，仍出现 `model_not_found` 或 404 错误
- 后端报错称 `messages[].content` 预期为字符串
- 使用 OpenAI 兼容本地后端时，间歇出现 `incomplete turn detected ... stopReason=stop payloads=0` 警告
- 只在较大提示词 token 数量或完整智能体运行时提示词下出现的后端崩溃
- 只在更大的 prompt token 数量或完整智能体运行时 prompt 中出现的后端崩溃
<AccordionGroup>
<Accordion title="常见特征">
- 本地 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`。
- 本地 MLX/vLLM 风格服务器出现 `model_not_found` → 确认 `baseUrl` 包含 `/v1`，`api` 对 `/v1/chat/completions` 后端是 `"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`。
- `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但该轮次没有返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常表示后端正在发出空/非文本内容，或抑制最终答案文本。
- 直接微型请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输很可能已经正确；后端在较大的智能体运行时提示词形态上失败。
- 禁用工具后失败减少但未消失 → 工具 schema 是压力来源之一，但剩余问题仍是上游模型/服务器容量或后端错误。
- `incomplete turn detected ... stopReason=stop payloads=0` → 后端完成了 Chat Completions 请求，但没有为该轮次返回用户可见的助手文本。OpenClaw 会对可安全重放的空 OpenAI 兼容轮次重试一次；持续失败通常意味着后端正在发出空内容/非文本内容，或抑制最终回答文本。
- 直接的小请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输很可能已经正确；后端在更大的智能体运行时 prompt 形态上失败。
- 禁用工具后失败减少但未消失 → 工具 schema 是压力的一部分，但剩余问题仍是上游模型/服务器容量限制或后端 bug。
</Accordion>
<Accordion title="修复选项">
1. 为仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。
2. 为无法可靠处理 OpenClaw 工具 schema 表面的模型/后端设置 `compat.supportsTools: false`。
3. 尽可能降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用具备更强长上下文支持的后端。
4. 如果微型直接请求持续通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并带上已接受的载荷形态向上游提交复现。
1. 对仅支持字符串的 Chat Completions 后端设置 `compat.requiresStringContent: true`。
2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型/后端设置 `compat.supportsTools: false`。
3. 尽可能降低 prompt 压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用长上下文支持更强的后端。
4. 如果直接的小请求一直通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并用已被接受的 payload 形态向上游提交复现。
</Accordion>
</AccordionGroup>
@ -156,7 +155,7 @@ openclaw logs --follow
## 没有回复
如果渠道已启动但没有任何回应，请先检查路由和策略，再重新连接任何东西。
如果渠道已上线但没有任何回复，请先检查路由和策略，再重新连接任何东西。
```bash
openclaw status
@ -168,13 +167,13 @@ openclaw logs --follow
查找：
- 私信发送者的配对处于待处理状态。
- 私信发送者的配对待处理。
- 群组提及门控（`requireMention`、`mentionPatterns`）。
- 渠道/群组 allowlist 不匹配。
常见特征：
- `drop guild message (mention required` → 群组消息会被忽略，直到被提及。
- `drop guild message (mention required` → 群组消息在被提及前会被忽略。
- `pairing request` → 发送者需要批准。
- `blocked` / `allowlist` → 发送者/渠道被策略过滤。
@ -184,9 +183,9 @@ openclaw logs --follow
- [群组](/zh-CN/channels/groups)
- [配对](/zh-CN/channels/pairing)
## Dashboard 控制 UI 连接性
## 控制面板控制 UI 连接
当 Dashboard/控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
当控制面板/控制 UI 无法连接时，验证 URL、身份验证模式和安全上下文假设。
```bash
openclaw gateway status
@ -198,39 +197,40 @@ openclaw gateway status --json
查找：
- 正确的探测 URL 和 Dashboard URL。
- 客户端与 Gateway 网关之间的认证模式/token 不匹配。
- 在需要设备身份时使用 HTTP。
- 正确的探测 URL 和控制面板 URL。
- 客户端和 Gateway 网关之间的身份验证模式/token 不匹配。
- 需要设备身份时却使用 HTTP。
<AccordionGroup>
<Accordion title="连接/认证特征">
- `device identity required` → 非安全上下文或缺少设备认证。
- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或你正从非 loopback 浏览器来源连接，且没有显式 allowlist）。
- `device nonce required` / `device nonce mismatch` → 客户端未完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。
- `device signature invalid` / `device signature expired` → 客户端为当前握手签名了错误载荷（或时间戳过期）。
- 带 `canRetryWithDeviceToken=true` 的 `AUTH_TOKEN_MISMATCH` → 客户端可使用缓存设备 token 执行一次受信任重试。
<Accordion title="连接 / 身份验证特征">
- `device identity required` → 非安全上下文或缺少设备身份验证。
- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 浏览器来源连接，但没有显式 allowlist）。
- `device nonce required` / `device nonce mismatch` → 客户端未完成基于 challenge 的设备身份验证流程（`connect.challenge` + `device.nonce`）。
- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的 payload（或过期时间戳）。
- `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可使用缓存的设备 token 执行一次受信任重试。
- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存 scope 集。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的 scope 集。
- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会先被串行化，然后限流器才记录失败。因此，来自同一客户端的两个并发错误重试可能会让第二次尝试显示 `retry later`，而不是两次普通的不匹配。
- 来自浏览器来源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源使用单独的桶。
- 在该重试路径之外，连接身份验证优先级为：先显式共享 token/密码，然后显式 `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 目标错误。
</Accordion>
</AccordionGroup>
### 认证详情代码快速映射
### 身份验证详细代码快速对照
使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作：
| 详情代码 | 含义 | 建议操作 |
| 详细代码 | 含义 | 建议操作 |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端粘贴/设置令牌并重试。对于仪表盘路径：先运行 `openclaw config get gateway.auth.token`，然后粘贴到 Control UI 设置中。 |
| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。缓存令牌重试会复用已存储的已批准作用域；显式传入 `deviceToken` / `scopes` 的调用方会保留请求的作用域。如果仍然失败，请运行[令牌漂移恢复检查清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 |
| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的按设备令牌已过期或被撤销。 | 使用[设备 CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 |
| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：先运行 `openclaw devices list`，然后运行 `openclaw devices approve <requestId>`。作用域/角色升级在你审查所请求的访问权限后使用相同流程。 |
| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端粘贴/设置令牌后重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后粘贴到 Control UI 设置中。 |
| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方会保留请求的作用域。如果仍然失败，请运行 [令牌漂移恢复检查清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 |
| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备令牌已过期或被撤销。 | 使用 [设备 CLI](/zh-CN/cli/devices) 轮换/重新批准设备令牌，然后重新连接。 |
| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后运行 `openclaw devices approve <requestId>`。在你审查请求的访问权限后，作用域/角色升级使用相同流程。 |
<Note>
使用共享 Gateway 网关令牌/密码认证的直接回环后端 RPC 不应依赖 CLI 的已配对设备作用域基线。如果子智能体或其他内部调用仍因 `scope-upgrade` 失败，请确认调用方使用的是 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且没有强制指定显式 `deviceIdentity` 或设备令牌。
使用共享 Gateway 网关令牌/密码进行身份验证的直接回环后端 RPC 不应依赖 CLI 的已配对设备作用域基线。如果子智能体或其他内部调用仍然因 `scope-upgrade` 失败，请确认调用方正在使用 `client.id: "gateway-client"` 和 `client.mode: "backend"`，并且未强制使用显式 `deviceIdentity` 或设备令牌。
</Note>
设备认证 v2 迁移检查：
@ -247,18 +247,18 @@ openclaw gateway status
<Step title="等待 connect.challenge">
客户端等待 Gateway 网关发出的 `connect.challenge`。
</Step>
<Step title="签署载荷">
客户端签署绑定挑战的载荷。
<Step title="签名载荷">
客户端签名与 challenge 绑定的载荷。
</Step>
<Step title="发送设备 nonce">
客户端发送 `connect.params.device.nonce`，并使用相同的挑战 nonce。
客户端发送带有相同 challenge nonce 的 `connect.params.device.nonce`。
</Step>
</Steps>
如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝：
- 已配对设备令牌会话只能管理**自己的**设备，除非调用方也拥有 `operator.admin`
- `openclaw devices rotate --scope ...` 只能请求调用方会话已经持有的 operator 作用域
- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的操作员作用域
相关：
@ -282,7 +282,7 @@ openclaw gateway status --deep # also scan system-level services
查找：
- `Runtime: stopped` 以及退出提示。
- 带退出提示的 `Runtime: stopped`。
- 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。
- 端口/监听器冲突。
- 使用 `--deep` 时出现额外的 launchd/systemd/schtasks 安装。
@ -290,25 +290,25 @@ openclaw gateway status --deep # also scan system-level services
<AccordionGroup>
<Accordion title="常见特征">
- `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` → 没有有效 Gateway 网关认证路径（令牌/密码，或已配置的可信代理）的非回环绑定。
- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → local Gateway 网关模式未启用，或配置文件被覆盖并丢失了 `gateway.mode`。修复：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新标记预期的 local 模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
- `refusing to bind gateway ... without auth` → 非回环绑定缺少有效的 Gateway 网关认证路径（令牌/密码，或在已配置时使用可信代理）。
- `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。
- `Other gateway-like services detected (best effort)` → 存在陈旧或并行的 launchd/systemd/schtasks 单元。大多数设置应每台机器只保留一个 Gateway 网关；如果确实需要多个，请隔离端口 + 配置/状态/工作区。请参阅 [/gateway#multiple-gateways-same-host](/zh-CN/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 网关服务。
- `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数设置应在每台机器上只保留一个 Gateway 网关；如果确实需要多个，请隔离端口 + 配置/状态/工作区。请参阅 [/gateway#multiple-gateways-same-host](/zh-CN/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 网关服务。
</Accordion>
</AccordionGroup>
相关：
- [后台执行和进程工具](/zh-CN/gateway/background-process)
- [后台 exec 和进程工具](/zh-CN/gateway/background-process)
- [配置](/zh-CN/gateway/configuration)
- [Doctor](/zh-CN/gateway/doctor)
## Gateway 网关恢复了最后已知良好配置
## Gateway 网关恢复了 last-known-good 配置
当 Gateway 网关启动，但日志称其恢复了 `openclaw.json` 时使用此项。
当 Gateway 网关启动，但日志显示它恢复了 `openclaw.json` 时使用此项。
```bash
openclaw logs --follow
@ -329,12 +329,12 @@ openclaw doctor
<Accordion title="发生了什么">
- 被拒绝的配置在启动或热重载期间未通过验证。
- OpenClaw 将被拒绝的载荷保留为 `.clobbered.*`。
- 活动配置从最后通过验证的最后已知良好副本恢复。
- 下一个主智能体轮次会被警告不要盲目重写被拒绝的配置。
- 如果所有验证问题都位于 `plugins.entries.<id>...` 下，OpenClaw 不会恢复整个文件。插件本地故障会保持显眼，而无关的用户设置仍保留在活动配置中。
- 活动配置已从最后一次验证通过的 last-known-good 副本恢复。
- 下一个主智能体轮次会收到警告，不要盲目重写被拒绝的配置。
- 如果所有验证问题都位于 `plugins.entries.<id>...` 下，OpenClaw 不会恢复整个文件。插件本地失败会保持显眼，同时无关的用户设置仍保留在活动配置中。
</Accordion>
<Accordion title="检查和修复">
<Accordion title="检查并修复">
```bash
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
@ -345,17 +345,17 @@ openclaw doctor
</Accordion>
<Accordion title="常见特征">
- `.clobbered.*` 存在 → 外部直接编辑或启动读取已被恢复。
- `.rejected.*` 存在 → OpenClaw 拥有的配置写入在提交前未通过架构或覆盖检查。
- `Config write rejected:` → 该写入尝试删除必需形状、大幅缩小文件，或持久化无效配置。
- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动将当前文件视为已被覆盖，因为它相比最后已知良好备份丢失了字段或大小。
- `Config last-known-good promotion skipped` → 候选配置包含经过遮盖的密钥占位符，例如 `***`。
- `.rejected.*` 存在 → OpenClaw 拥有的配置写入在提交前未通过 schema 或覆盖检查。
- `Config write rejected:` → 该写入尝试丢弃必需结构、大幅缩小文件，或持久化无效配置。
- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为被覆盖，因为与 last-known-good 备份相比，它丢失了字段或大小。
- `Config last-known-good promotion skipped` → 候选配置包含经过遮蔽的密钥占位符，例如 `***`。
</Accordion>
<Accordion title="修复选项">
1. 如果恢复后的活动配置正确，请保留它。
2. 只从 `.clobbered.*` 或 `.rejected.*` 复制预期键，然后用 `openclaw config set` 或 `config.patch` 应用它们。
3. 重启前运行 `openclaw config validate`。
4. 如果手动编辑，请保留完整的 JSON5 配置，而不只是你想更改的局部对象。
2. 仅从 `.clobbered.*` 或 `.rejected.*` 复制预期键名，然后使用 `openclaw config set` 或 `config.patch` 应用它们。
3. 在重启前运行 `openclaw config validate`。
4. 如果你手动编辑，请保留完整 JSON5 配置，而不是只保留你想更改的局部对象。
</Accordion>
</AccordionGroup>
@ -368,7 +368,7 @@ openclaw doctor
## Gateway 网关探测警告
当 `openclaw gateway probe` 访问到了某个目标，但仍打印警告块时使用此项。
当 `openclaw gateway probe` 能到达某个目标，但仍打印警告块时使用此项。
```bash
openclaw gateway probe
@ -379,15 +379,16 @@ openclaw gateway probe --ssh user@gateway-host
查找：
- JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。
- 警告是否与 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的认证引用有关。
- 警告是否关于 SSH 回退、多个 Gateway 网关、缺失作用域或未解析的认证引用。
常见特征：
- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了直接配置目标/local loopback 目标。
- `multiple reachable gateways detected` → 有多个目标响应。通常这表示有意的多 Gateway 网关设置，或存在陈旧/重复监听器。
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详情 RPC 受作用域限制；配对设备身份或使用带有 `operator.read` 的凭证。
- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端仍需配对/批准后才能获得正常 operator 访问。
- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 此命令路径无法为失败目标获取认证材料。
- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍然尝试了直接配置/回环目标。
- `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 警告文本 → 失败目标在此命令路径中无法使用认证材料。
相关：
@ -397,7 +398,7 @@ openclaw gateway probe --ssh user@gateway-host
## 渠道已连接，但消息未流动
如果渠道状态为已连接但消息流已停止，请关注策略、权限和渠道特定的投递规则。
如果渠道状态为已连接但消息流已停止，请重点检查策略、权限和渠道特定的投递规则。
```bash
openclaw channels status --probe
@ -410,12 +411,12 @@ openclaw config get channels
查找：
- 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。
- 群组允许列表和提及要求。
- 群组 allowlist 和提及要求。
- 缺失的渠道 API 权限/作用域。
常见特征：
- `mention required` → 消息因群组提及策略被忽略。
- `mention required` → 消息被群组提及策略忽略。
- `pairing` / 待批准跟踪 → 发送者未获批准。
- `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → 渠道认证/权限问题。
@ -428,7 +429,7 @@ openclaw config get channels
## Cron 和心跳投递
If cron 或心跳没有运行或没有送达，请先验证调度器状态，然后验证送达目标。
如果 Cron 或心跳没有运行或没有投递，请先验证调度器状态，再验证投递目标。
```bash
openclaw cron status
@ -438,21 +439,21 @@ openclaw system heartbeat last
openclaw logs --follow
```
检查：
查找：
- cron 已启用，并且存在下次唤醒时间。
- Cron 已启用，并且存在下一次唤醒时间。
- 作业运行历史状态（`ok`、`skipped`、`error`）。
- 心跳跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。
<AccordionGroup>
<Accordion title="常见特征">
- `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` → 心跳送达目标的账户 ID 无效。
- `heartbeat skipped` 且带有 `reason=dm-blocked` → 心跳目标解析为私信样式的目的地，而 `agents.defaults.heartbeat.directPolicy`（或按智能体覆盖）被设置为 `block`。
<Accordion title="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` → 心跳投递目标的账号 ID 无效。
- `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标解析为私信样式目的地，而 `agents.defaults.heartbeat.directPolicy`（或每智能体覆盖项）设置为 `block`。
</Accordion>
</AccordionGroup>
@ -463,9 +464,9 @@ openclaw logs --follow
- [计划任务](/zh-CN/automation/cron-jobs)
- [计划任务：故障排除](/zh-CN/automation/cron-jobs#troubleshooting)
## 节点已配对，但工具失败
## 节点已配对，工具失败
如果节点已配对但工具失败，请隔离前台、权限和审批状态。
如果节点已配对但工具失败，请隔离前台、权限和批准状态。
```bash
openclaw nodes status
@ -475,28 +476,28 @@ openclaw logs --follow
openclaw status
```
检查：
查找：
- 节点在线，并具备预期能力。
- 摄像头、麦克风、位置、屏幕的操作系统权限授权。
- Exec 审批和 allowlist 状态。
- 节点在线，并具有预期能力。
- 摄像头/麦克风/位置/屏幕的操作系统权限授权。
- Exec 批准和允许列表状态。
常见特征：
- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须在前台。
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。
- `SYSTEM_RUN_DENIED: approval required` → exec 审批待处理。
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 阻止。
- `SYSTEM_RUN_DENIED: approval required` → Exec 批准待处理。
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表阻止。
相关：
- [Exec 审批](/zh-CN/tools/exec-approvals)
- [Exec 批准](/zh-CN/tools/exec-approvals)
- [节点故障排除](/zh-CN/nodes/troubleshooting)
- [节点](/zh-CN/nodes/index)
## 浏览器工具失败
当浏览器工具操作失败但 Gateway 网关本身健康时，使用此部分。
当 Gateway 网关本身健康但浏览器工具操作失败时，请使用此流程。
```bash
openclaw browser status
@ -506,56 +507,56 @@ openclaw logs --follow
openclaw doctor
```
检查：
查找：
- 是否设置了 `plugins.allow`，并且包含 `browser`。
- `plugins.allow` 是否已设置且包含 `browser`。
- 有效的浏览器可执行文件路径。
- CDP 配置文件可达性。
- `existing-session` / `user` 配置文件的本地 Chrome 可用性。
<AccordionGroup>
<Accordion title="插件 / 可执行文件特征">
<Accordion title="Plugin / executable signatures">
- `unknown command "browser"` 或 `unknown command 'browser'` → 内置浏览器插件被 `plugins.allow` 排除。
- 浏览器工具缺失 / 不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。
- 浏览器工具缺失 / 不可用，但 `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 端口错误或超出范围。
- `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; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少内置浏览器插件的 `playwright-core` 运行时依赖；运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍可工作，但导航、AI 快照、CSS 选择器元素截图和 PDF 导出仍不可用。
</Accordion>
<Accordion title="Chrome MCP / 现有会话特征">
- `Could not find DevToolsActivePort for chrome` → Chrome MCP 现有会话尚无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器打开，批准首次附加提示，然后重试。如果不需要已登录状态，优先使用托管的 `openclaw` 配置文件。
<Accordion title="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 仍无法打开。
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或 HTTP 端点已响应但 CDP WebSocket 仍无法打开。
</Accordion>
<Accordion title="元素 / 截图 / 上传特征">
<Accordion title="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 上传钩子需要快照 refs，而不是 CSS 选择器。
- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件上，每次调用发送一个上传文件。
- `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 现有会话配置文件上的 `act:type` 省略 `timeoutMs`，或在需要自定义超时时使用托管 / CDP 浏览器配置文件。
- `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP 现有会话配置文件上的 `act:evaluate` 省略 `timeoutMs`，或在需要自定义超时时使用托管 / CDP 浏览器配置文件。
- `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 配置文件上的过期视口 / 深色模式 / 区域设置 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile <name>` 关闭活动控制会话，并释放 Playwright/CDP 仿真状态，而无需重启整个 Gateway 网关。
- 附加专用或远程 CDP 配置文件上的过期视口 / 深色模式 / 区域设置 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile <name>` 关闭活跃控制会话，并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。
</Accordion>
</AccordionGroup>
相关：
- [浏览器（OpenClaw 管理的）](/zh-CN/tools/browser)
- [浏览器（OpenClaw 托管）](/zh-CN/tools/browser)
- [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)
## 如果你升级后某些东西突然损坏
## 如果你升级后某些东西突然坏了
大多数升级后故障都是配置漂移，或现在开始强制执行更严格的默认值。
大多数升级后的故障来自配置漂移，或现在会强制执行的更严格默认值。
<AccordionGroup>
<Accordion title="1. 凭证和 URL 覆盖行为已更改">
<Accordion title="1. Auth and URL override behavior changed">
```bash
openclaw gateway status
openclaw config get gateway.mode
@ -563,10 +564,10 @@ openclaw doctor
openclaw config get gateway.auth.mode
```
检查内容：
要检查的内容：
- 如果 `gateway.mode=remote`，CLI 调用可能正在指向远程，而你的本地服务本身正常。
- 显式 `--url` 调用不会回退到已存储凭证。
- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程，而你的本地服务是正常的。
- 显式 `--url` 调用不会回退到已存储的凭证。
常见特征：
@ -574,7 +575,7 @@ openclaw doctor
- `unauthorized` → 端点可达，但认证错误。
</Accordion>
<Accordion title="2. 绑定和认证保护规则更严格">
<Accordion title="2. Bind and auth guardrails are stricter">
```bash
openclaw config get gateway.bind
openclaw config get gateway.auth.mode
@ -583,18 +584,18 @@ openclaw doctor
openclaw logs --follow
```
检查内容：
要检查的内容：
- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌 / 密码认证，或正确配置的非 loopback `trusted-proxy` 部署。
- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌/密码认证，或正确配置的非 loopback `trusted-proxy` 部署。
- `gateway.token` 等旧键不会替代 `gateway.auth.token`。
常见特征：
- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。
- `Connectivity probe: failed`，而运行时正在运行 → Gateway 网关存活，但当前认证 / URL 无法访问。
- `Connectivity probe: failed` 且运行时正在运行 → Gateway 网关存活，但当前认证/url 无法访问。
</Accordion>
<Accordion title="3. 配对和设备身份状态已更改">
<Accordion title="3. Pairing and device identity state changed">
```bash
openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
@ -602,20 +603,20 @@ openclaw doctor
openclaw doctor
```
检查内容：
要检查的内容：
- 仪表盘 / 节点是否有待处理的设备审批。
- 策略或身份更改后是否有待处理的私信配对审批。
- 仪表板/节点的待处理设备批准。
- 策略或身份变更后的待处理私信配对批准。
常见特征：
- `device identity required` → 设备认证未满足。
- `pairing required` → 发送方 / 设备必须获得批准。
- `pairing required` → 发送者/设备必须获批准。
</Accordion>
</AccordionGroup>
如果检查后服务配置和运行时仍不一致，请从同一个配置文件 / 状态目录重新安装服务元数据：
如果检查后服务配置和运行时仍不一致，请从同一个配置文件/状态目录重新安装服务元数据：
```bash
openclaw gateway install --force