Gateway 网关

• 默认情况下，除非在 ~/.openclaw/openclaw.json 中设置了 gateway.mode=local，否则 Gateway 网关会拒绝启动。对临时/开发运行使用 --allow-unconfigured。
• openclaw onboard --mode local 和 openclaw setup 应写入 gateway.mode=local。如果文件存在但缺少 gateway.mode，应将其视为损坏或被覆盖的配置并修复，而不是隐式假定为本地模式。
• 如果文件存在且缺少 gateway.mode，Gateway 网关会将其视为可疑的配置损坏，并拒绝为你“猜测本地模式”。
• 未经身份验证绑定到 loopback 之外会被阻止（安全防护栏）。
• SIGUSR1 会在已授权时触发进程内重启（默认启用 commands.restart；设置 commands.restart: false 可阻止手动重启，同时仍允许 Gateway 网关工具/配置应用/更新）。
• SIGINT/SIGTERM 处理程序会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw-mode 输入包装 CLI，请在退出前恢复终端。

• 记录会保留运行元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、token、cookie、密钥值、主机名或原始会话 ID。设置 diagnostics.enabled: false 可完全禁用记录器。
• 在 Gateway 网关致命退出、关闭超时和重启启动失败时，如果记录器有事件，OpenClaw 会将同一诊断快照写入 ~/.openclaw/logs/stability/openclaw-stability-*.json。使用 openclaw gateway stability --bundle latest 检查最新包；--limit、--type 和 --since-seq 也适用于包输出。

• 即使本地 CLI 配置缺失或无效，gateway status 仍可用于诊断。
• 默认的 gateway status 会证明服务状态、WebSocket 连接，以及握手时可见的认证能力。它不会证明读/写/管理操作。
• 对首次设备认证，诊断探测不会产生变更：当已有缓存设备令牌时会复用它们，但不会仅为检查状态而创建新的 CLI 设备身份或只读设备配对记录。
• 可行时，gateway status 会解析已配置的认证 SecretRefs 用于探测认证。
• 如果此命令路径中所需的认证 SecretRef 未解析，gateway status --json 会在探测连通性/认证失败时报告 rpc.authWarning；请显式传入 --token/--password，或先解析密钥来源。
• 如果探测成功，未解析的认证引用警告会被抑制，以避免误报。
• 当监听服务本身还不够，而你还需要读取范围的 RPC 调用也健康时，请在脚本和自动化中使用 --require-rpc。
• --deep 会添加对额外 launchd/systemd/schtasks 安装的尽力扫描。当检测到多个类似 Gateway 网关的服务时，人类可读输出会打印清理提示，并警告大多数设置应在每台机器上运行一个 Gateway 网关。
• 当服务进程为外部监督器重启而干净退出时，--deep 也会报告最近一次 Gateway 网关监督器重启交接。
• --deep 会以插件感知模式（pluginValidation: "full"）运行配置验证，并显示已配置插件清单警告（例如缺少渠道配置元数据），以便安装和更新冒烟检查能捕获它们。默认的 gateway status 保持快速只读路径，跳过插件验证。
• 人类可读输出包含解析后的文件日志路径，以及 CLI 与服务配置路径/有效性快照，用于帮助诊断配置文件或状态目录漂移。

• 在 Linux systemd 安装上，服务认证漂移检查会从单元中读取 Environment= 和 EnvironmentFile= 值（包括 %h、带引号的路径、多个文件以及可选的 - 文件）。
• 漂移检查会使用合并后的运行时环境解析 gateway.auth.token SecretRefs（先使用服务命令环境，再回退到进程环境）。
• 如果令牌认证实际上未启用（显式 gateway.auth.mode 为 password/none/trusted-proxy，或模式未设置且密码可能优先、没有令牌候选可能优先），令牌漂移检查会跳过配置令牌解析。

• 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 一样，probe 会复用现有缓存设备认证，但不会创建首次设备身份或配对状态。
• 只有在没有任何被探测目标可达时，退出码才为非零。

顶层：

• 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：此探测轮次使用的实际设备发现预算/结果数量。

每个目标（targets[].connect）：

• ok：连接后的可达性 + 降级分类。
• rpcOk：完整详细 RPC 成功。
• scopeLimited：详细 RPC 因缺少 operator scope 而失败。

每个目标（targets[].auth）：

• role：可用时，hello-ok 中报告的认证角色。
• scopes：可用时，hello-ok 中报告的已授予 scope。
• capability：该目标显示的认证能力分类。

• ssh_tunnel_failed：SSH 隧道设置失败；命令回退到直接探测。
• multiple_gateways：多个目标可达；除非你有意运行隔离的配置文件（例如救援 bot），否则这并不常见。
• auth_secretref_unresolved：无法为失败目标解析已配置的认证 SecretRef。
• probe_scope_limited：WebSocket 连接成功，但读取探测因缺少 operator.read 而受限。

• gateway status：--url、--token、--password、--timeout、--no-probe、--require-rpc、--deep、--json
• gateway install：--port、--runtime <node|bun>、--token、--wrapper <path>、--force、--json
• gateway restart：--safe、--skip-deferral、--force、--wait <duration>、--json
• gateway uninstall|start：--json
• gateway stop：--disable、--json

• 使用 gateway restart 重启托管服务。不要把 gateway stop 和 gateway start 串联起来作为重启替代方式。
• 在 macOS 上，gateway stop 默认使用 launchctl bootout，这会从当前启动会话中移除 LaunchAgent，但不会持久化禁用设置 —— KeepAlive 自动恢复会在后续崩溃时继续生效，并且 gateway start 可以干净地重新启用，无需手动执行 launchctl enable。传入 --disable 可持久化抑制 KeepAlive 和 RunAtLoad，使 Gateway 网关在下一次显式执行 gateway start 之前不会重新生成；当手动停止需要在重启或系统重启后仍然保持时，请使用此选项。
• gateway restart --safe 会要求正在运行的 Gateway 网关预检活跃的 OpenClaw 工作，并将重启推迟到回复交付、嵌入式运行和任务运行全部排空之后。--safe 不能与 --force 或 --wait 组合使用。
• gateway restart --wait 30s 会覆盖该次重启配置的重启排空预算。裸数字表示毫秒；也接受 s、m 和 h 等单位。--wait 0 会无限期等待。
• gateway restart --safe --skip-deferral 会运行感知 OpenClaw 的安全重启，但绕过延迟门控，因此即使报告了阻塞项，Gateway 网关也会立即发出重启。用于任务运行延迟卡住时的操作员逃生口；需要 --safe。
• gateway restart --force 会跳过活跃工作排空并立即重启。当操作员已经检查过列出的任务阻塞项，并希望 Gateway 网关立即恢复时使用。
• 生命周期命令接受 --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 未设置，安装会被阻止，直到显式设置模式。