diff --git a/docs/zh-CN/cli/gateway.md b/docs/zh-CN/cli/gateway.md index 924af973f..51cc70f52 100644 --- a/docs/zh-CN/cli/gateway.md +++ b/docs/zh-CN/cli/gateway.md @@ -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 …` 下。 本地 mDNS + 广域 DNS-SD 设置。 - OpenClaw 如何公布和发现 Gateway 网关。 + OpenClaw 如何通告和发现 Gateway 网关。 - 顶层 Gateway 网关配置键。 + 顶层 gateway 配置键。 @@ -45,12 +45,12 @@ openclaw gateway run - - 默认情况下，除非在 `~/.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，请在退出前恢复终端。 @@ -67,7 +67,7 @@ openclaw gateway run 身份验证模式覆盖。 - 令牌覆盖（也会为进程设置 `OPENCLAW_GATEWAY_TOKEN`）。 + 令牌覆盖（也会为该进程设置 `OPENCLAW_GATEWAY_TOKEN`）。 密码覆盖。 @@ -91,7 +91,7 @@ openclaw gateway run 重置开发配置 + 凭据 + 会话 + 工作区（需要 `--dev`）。 - 启动前终止所选端口上任何现有监听器。 + 启动前终止选定端口上的任何现有监听器。 详细日志。 @@ -100,7 +100,7 @@ openclaw gateway run 仅在控制台显示 CLI 后端日志（并启用 stdout/stderr）。 - Websocket 日志样式。 + WebSocket 日志样式。 `--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 - 默认：人类可读（TTY 中带颜色）。 - - `--json`：机器可读的 JSON（无样式/spinner）。 + - `--json`：机器可读 JSON（无样式/加载指示器）。 - `--no-color`（或 `NO_COLOR=1`）：禁用 ANSI，同时保留人类可读布局。 @@ -143,7 +143,7 @@ openclaw gateway run -设置 `--url` 时，CLI 不会回退到配置或环境凭据。请显式传入 `--token` 或 `--password`。缺少显式凭据会报错。 +设置 `--url` 时，CLI 不会回退到配置或环境凭据。请显式传入 `--token` 或 `--password`。缺少显式凭据是错误。 ### `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`）。 - 按诊断事件类型过滤，例如 `payload.large` 或 `diagnostic.memory.pressure`。 + 按诊断事件类型筛选，例如 `payload.large` 或 `diagnostic.memory.pressure`。 - 仅包含某个诊断序列号之后的事件。 + 仅包含诊断序列号之后的事件。 - 读取持久化的稳定性包，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅使用 `--bundle`）读取状态目录下最新的包，或直接传入包 JSON 路径。 + 读取持久化的稳定性包，而不是调用正在运行的 Gateway 网关。使用 `--bundle latest`（或仅使用 `--bundle`）读取状态目录下的最新包，也可以直接传入包 JSON 路径。 写入可共享的支持诊断 zip，而不是打印稳定性详情。 @@ -201,15 +201,15 @@ openclaw gateway stability --json - - 记录会保留运行元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不会保留聊天文本、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` 也适用于包输出。 ### `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 ``` - 输出 zip 路径。默认写入状态目录下的支持导出。 + 输出 zip 路径。默认为状态目录下的支持导出。 要包含的最大已清理日志行数。 @@ -245,13 +245,13 @@ openclaw gateway diagnostics export --json 以 JSON 打印写入路径、大小和清单。 -导出内容包含清单、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 ``` - 添加显式探测目标。已配置的远程 + localhost 仍会被探测。 + 添加显式探测目标。仍会探测已配置的远程目标 + localhost。 - 探测的令牌身份验证。 + 用于探测的令牌身份验证。 - 探测的密码身份验证。 + 用于探测的密码身份验证。 探测超时。 @@ -275,29 +275,29 @@ openclaw gateway status --require-rpc 跳过连接性探测（仅服务视图）。 - 同时扫描系统级服务。 + 也扫描系统级服务。 - 将默认连接性探测升级为读取探测，并在该读取探测失败时以非零状态退出。不能与 `--no-probe` 组合使用。 + 将默认连接性探测升级为读取探测，并在该读取探测失败时以非零状态退出。不能与 `--no-probe` 组合。 - - `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 与服务配置路径/有效性快照，帮助诊断配置文件或状态目录漂移。 - - - 在 Linux systemd 安装中，服务鉴权漂移检查会读取 unit 中的 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号的路径、多个文件，以及可选的 `-` 文件）。 - - 漂移检查会使用合并后的运行时环境解析 `gateway.auth.token` SecretRefs（先用服务命令环境，再回退到进程环境）。 - - 如果令牌鉴权实际上未启用（显式 `gateway.auth.mode` 为 `password`/`none`/`trusted-proxy`，或 mode 未设置且密码可能胜出、没有令牌候选可胜出），令牌漂移检查会跳过配置令牌解析。 + + - 在 Linux systemd 安装中，服务身份验证漂移检查会从单元读取 `Environment=` 和 `EnvironmentFile=` 值（包括 `%h`、带引号的路径、多个文件以及可选的 `-` 文件）。 + - 漂移检查会使用合并后的运行时环境解析 `gateway.auth.token` SecretRefs（先使用服务命令环境，再回退到进程环境）。 + - 如果令牌身份验证实际上未启用（显式 `gateway.auth.mode` 为 `password`/`none`/`trusted-proxy`，或模式未设置且密码可能胜出并且没有令牌候选项可胜出），令牌漂移检查会跳过配置令牌解析。 @@ -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` -如果多个 Gateway 网关可达，它会全部打印出来。当你使用隔离的配置档/端口时（例如救援机器人），支持多个 Gateway 网关，但大多数安装仍然只运行单个 Gateway 网关。 +如果多个 Gateway 网关可访问，它会全部打印出来。当你使用隔离的配置文件/端口（例如救援机器人）时，支持多个 Gateway 网关，但大多数安装仍只运行单个 Gateway 网关。 ```bash @@ -326,50 +326,51 @@ openclaw gateway probe --json - - `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` 类似，探测会复用现有缓存设备身份验证，但不会创建首次设备身份或配对状态。 + - 只有在没有任何被探测目标可达时，退出码才为非零。 顶层： - - `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`：该目标暴露的身份验证能力分类。 - - `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` 而受限。 -#### 通过 SSH 远程访问（Mac 应用一致性） +#### 通过 SSH 访问远程（与 Mac 应用一致） -macOS 应用的“Remote over SSH”模式使用本地端口转发，因此远程 Gateway 网关（可能仅绑定到 loopback）可通过 `ws://127.0.0.1:` 访问。 +macOS 应用的“通过 SSH 访问远程”模式使用本地端口转发，让远程 Gateway 网关（可能只绑定到 loopback）可通过 `ws://127.0.0.1:` 访问。 CLI 等效命令： @@ -384,7 +385,7 @@ openclaw gateway probe --ssh user@gateway-host 身份文件。 - 从解析后的设备发现端点（`local.` 加上已配置的广域域名，如果有）中选择第一个发现的 Gateway 网关主机作为 SSH 目标。仅 TXT 的提示会被忽略。 + 从已解析的设备发现端点（`local.` 加上已配置的广域域名，如果有）中选择第一个发现的 Gateway 网关主机作为 SSH 目标。仅 TXT 提示会被忽略。 配置（可选，用作默认值）： @@ -394,7 +395,7 @@ openclaw gateway probe --ssh user@gateway-host ### `gateway call ` -低级 RPC 辅助命令。 +低层 RPC 辅助命令。 ```bash openclaw gateway call status @@ -402,7 +403,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' ``` - 用于参数的 JSON 对象字符串。 + params 的 JSON 对象字符串。 Gateway 网关 WebSocket URL。 @@ -417,14 +418,14 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' 超时预算。 - 主要用于智能体风格的 RPC，这类 RPC 会在最终载荷之前流式传输中间事件。 + 主要用于智能体式 RPC，这类 RPC 会在最终负载之前流式传输中间事件。 机器可读 JSON 输出。 -`--params` 必须是有效的 JSON。 +`--params` 必须是有效 JSON。 ## 管理 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 - - 使用 `gateway restart` 重启托管服务。不要将 `gateway stop` 和 `gateway start` 串联起来替代重启；在 macOS 上，`gateway stop` 会在停止 LaunchAgent 之前有意禁用它。 - - 生命周期命令接受 `--json`，便于脚本使用。 + - 使用 `gateway restart` 重启托管服务。不要将 `gateway stop` 和 `gateway start` 串联起来作为重启替代；在 macOS 上，`gateway stop` 会有意先禁用 LaunchAgent 再停止它。 + - 生命周期命令接受 `--json`，用于脚本。 - - - 当令牌鉴权需要令牌且 `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。 + + - 当令牌身份验证需要令牌且 `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` 未设置，安装会被阻止，直到显式设置模式。 @@ -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 ``` - 每条命令的超时时间（浏览/解析）。 + 每条命令的超时时间（browse/resolve）。 - 机器可读输出（也会禁用样式/旋转指示器）。 + 机器可读输出（也会禁用样式/加载指示器）。 示例： @@ -529,8 +530,8 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- 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` 在那里也保持可选。 diff --git a/docs/zh-CN/gateway/troubleshooting.md b/docs/zh-CN/gateway/troubleshooting.md index b90f48749..a4c9f1a27 100644 --- a/docs/zh-CN/gateway/troubleshooting.md +++ b/docs/zh-CN/gateway/troubleshooting.md @@ -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 ``` - - 移除仍指向旧版 `openclaw` 二进制文件的过时系统包或旧包装器条目。 + + 移除仍指向旧 `openclaw` 二进制文件的过期系统包或旧包装器条目。 -仅限有意降级或紧急恢复时，为单个命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作时保持未设置。 +仅在有意降级或紧急恢复时，为单条命令设置 `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1`。正常操作请保持未设置。 -## 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 路径的长会话/模型运行中失败。 修复选项： - 为该模型禁用 `context1m`，回退到普通上下文窗口。 + 对该模型禁用 `context1m`，回退到普通上下文窗口。 - - 使用具备长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。 + + 使用符合长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。 - 配置回退模型，以便 Anthropic 长上下文请求被拒绝时运行仍可继续。 + 配置回退模型，让 Anthropic 长上下文请求被拒绝时运行仍能继续。 相关： - [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 中出现的后端崩溃 - - 本地 MLX/vLLM 风格服务器出现 `model_not_found` → 验证 `baseUrl` 包含 `/v1`，用于 `/v1/chat/completions` 后端的 `api` 是 `"openai-completions"`，并且 `models.providers..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..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..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。 - 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 形态向上游提交复现。 @@ -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。 - - - `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 执行一次受信任重试。 + + - `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 目标错误。 -### 认证详情代码快速映射 +### 身份验证详细代码快速对照 使用失败 `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 `。作用域/角色升级在你审查所请求的访问权限后使用相同流程。 | +| `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 `。在你审查请求的访问权限后，作用域/角色升级使用相同流程。 | -使用共享 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` 或设备令牌。 设备认证 v2 迁移检查： @@ -247,18 +247,18 @@ openclaw gateway status 客户端等待 Gateway 网关发出的 `connect.challenge`。 - - 客户端签署绑定挑战的载荷。 + + 客户端签名与 challenge 绑定的载荷。 - 客户端发送 `connect.params.device.nonce`，并使用相同的挑战 nonce。 + 客户端发送带有相同 challenge nonce 的 `connect.params.device.nonce`。 如果 `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 - - `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 网关服务。 相关： -- [后台执行和进程工具](/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 - 被拒绝的配置在启动或热重载期间未通过验证。 - OpenClaw 将被拒绝的载荷保留为 `.clobbered.*`。 - - 活动配置从最后通过验证的最后已知良好副本恢复。 - - 下一个主智能体轮次会被警告不要盲目重写被拒绝的配置。 - - 如果所有验证问题都位于 `plugins.entries....` 下，OpenClaw 不会恢复整个文件。插件本地故障会保持显眼，而无关的用户设置仍保留在活动配置中。 + - 活动配置已从最后一次验证通过的 last-known-good 副本恢复。 + - 下一个主智能体轮次会收到警告，不要盲目重写被拒绝的配置。 + - 如果所有验证问题都位于 `plugins.entries....` 下，OpenClaw 不会恢复整个文件。插件本地失败会保持显眼，同时无关的用户设置仍保留在活动配置中。 - + ```bash CONFIG="$(openclaw config file)" ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head @@ -345,17 +345,17 @@ openclaw doctor - `.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` → 候选配置包含经过遮蔽的密钥占位符，例如 `***`。 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 配置，而不是只保留你想更改的局部对象。 @@ -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`）。 - - - `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`。 + + - `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`。 @@ -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 可用性。 - + - `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; '' is unsupported.` → 当前 Gateway 网关安装缺少内置浏览器插件的 `playwright-core` 运行时依赖；运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍可工作，但导航、AI 快照、CSS 选择器元素截图和 PDF 导出仍不可用。 - - - `Could not find DevToolsActivePort for chrome` → Chrome MCP 现有会话尚无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器打开，批准首次附加提示，然后重试。如果不需要已登录状态，优先使用托管的 `openclaw` 配置文件。 + + - `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 "" 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 仍无法打开。 - + - `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 ` 关闭活动控制会话，并释放 Playwright/CDP 仿真状态，而无需重启整个 Gateway 网关。 + - 附加专用或远程 CDP 配置文件上的过期视口 / 深色模式 / 区域设置 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile ` 关闭活跃控制会话，并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。 相关： -- [浏览器（OpenClaw 管理的）](/zh-CN/tools/browser) +- [浏览器（OpenClaw 托管）](/zh-CN/tools/browser) - [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting) -## 如果你升级后某些东西突然损坏 +## 如果你升级后某些东西突然坏了 -大多数升级后故障都是配置漂移，或现在开始强制执行更严格的默认值。 +大多数升级后的故障来自配置漂移，或现在会强制执行的更严格默认值。 - + ```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` → 端点可达，但认证错误。 - + ```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 无法访问。 - + ```bash openclaw devices list openclaw pairing list --channel [--account ] @@ -602,20 +603,20 @@ openclaw doctor openclaw doctor ``` - 检查内容： + 要检查的内容： - - 仪表盘 / 节点是否有待处理的设备审批。 - - 策略或身份更改后是否有待处理的私信配对审批。 + - 仪表板/节点的待处理设备批准。 + - 策略或身份变更后的待处理私信配对批准。 常见特征： - `device identity required` → 设备认证未满足。 - - `pairing required` → 发送方 / 设备必须获得批准。 + - `pairing required` → 发送者/设备必须获批准。 -如果检查后服务配置和运行时仍不一致，请从同一个配置文件 / 状态目录重新安装服务元数据： +如果检查后服务配置和运行时仍不一致，请从同一个配置文件/状态目录重新安装服务元数据： ```bash openclaw gateway install --force