gateway

Gateway(网关) 网关 CLI

Gateway(网关) 网关是 OpenClaw 的 WebSocket 服务器（通道、节点、会话、钩子）。

本页中的子命令位于 openclaw gateway … 之下。

运行 Gateway(网关) 网关

运行本地 Gateway(网关) 网关进程：

openclaw gateway

前台别名：

openclaw gateway run

注意：

默认情况下，除非在 ~/.openclaw/openclaw.json 中设置了 gateway.mode=local，否则 Gateway(网关) 网关将拒绝启动。对于临时/开发运行，请使用 --allow-unconfigured。
在未经过身份验证的情况下绑定到回环地址之外会被阻止（安全防护措施）。
当获得授权时，SIGUSR1 会触发进程内重启（commands.restart 默认启用；设置 commands.restart: false 可阻止手动重启，但仍允许 gateway 工具/config apply/update）。
SIGINT/SIGTERM 处理程序会停止网关进程，但不会恢复任何自定义终端状态。如果您使用 TUI 或原始模式输入封装 CLI，请在退出前恢复终端。

选项

--port <port>: WebSocket 端口（默认值来自配置/环境；通常为 18789）。
--bind <loopback|lan|tailnet|auto|custom>: 监听器绑定模式。
--auth <token|password>: 认证模式覆盖。
--token <token>: 令牌覆盖（同时为该进程设置 OPENCLAW_GATEWAY_TOKEN）。
--password <password>: 密码覆盖。警告：内联密码可能会在本地进程列表中暴露。
--password-file <path>: 从文件读取网关密码。
--tailscale <off|serve|funnel>: 通过 Tailscale 暴露 Gateway(网关) 网关。
--tailscale-reset-on-exit: 关闭时重置 Tailscale serve/funnel 配置。
--allow-unconfigured: 允许在没有配置 gateway.mode=local 的情况下启动网关。
--dev: 如果缺失，则创建开发配置 + 工作区（跳过 BOOTSTRAP.md）。
--reset: 重置开发配置 + 凭证 + 会话 + 工作区（需要 --dev）。
--force：在启动之前终止所选端口上的任何现有监听器。
--verbose：详细日志。
--cli-backend-logs：仅在控制台中显示 CLI 后端日志（并启用 stdout/stderr）。
--claude-cli-logs：--cli-backend-logs 的已弃用别名。
--ws-log <auto|full|compact>：websocket 日志样式（默认为 auto）。
--compact：--ws-log compact 的别名。
--raw-stream：将原始模型流事件记录到 l。
--raw-stream-path <path>：原始流 l 路径。

查询正在运行的 Gateway(网关)

所有查询命令均使用 WebSocket RPC。

输出模式：

默认：人类可读（在 TTY 中着色）。
--json：机器可读的 JSON（无样式/加载指示器）。
--no-color（或 NO_COLOR=1）：禁用 ANSI，同时保留人类可读布局。

共享选项（在支持的情况下）：

--url <url>：Gateway(网关) WebSocket URL。
--token <token>：Gateway(网关) 令牌。
--password <password>：Gateway(网关) 密码。
--timeout <ms>：超时/预算（因命令而异）。
--expect-final：等待“最终”响应（代理调用）。

注意：当您设置 --url 时，CLI 不会回退到配置或环境凭据。请显式传递 --token 或 --password。缺少显式凭据将报错。

`gateway health`

openclaw gateway health --url ws://127.0.0.1:18789

`gateway status`

gateway status 显示 Gateway(网关) 服务（launchd/systemd/schtasks）以及可选的 RPC 探测。

openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc

选项：

--url <url>：覆盖探测 URL。
--token <token>：探测的令牌认证。
--password <password>：探测的密码认证。
--timeout <ms>：探测超时（默认 10000）。
--no-probe：跳过 RPC 探测（仅显示服务）。
--deep：同时扫描系统级服务。
--require-rpc：当 RPC 探测失败时以非零值退出。不能与 --no-probe 结合使用。

注意事项：

gateway status 会在可能的情况下解析已配置的身份验证 SecretRef，用于探测身份验证。
如果所需的身份验证 SecretRef 在此命令路径中未解析，则当探测连接/身份验证失败时，gateway status --json 会报告 rpc.authWarning；请显式传递 --token/--password 或先解析密钥源。
如果探测成功，将抑制未解析的 auth-ref 警告，以避免误报。
在脚本和自动化中使用 --require-rpc，当仅有侦听服务不足且您需要 Gateway(网关) RPC 本身健康时。
在 Linux systemd 安装中，服务身份验证漂移检查会从单元中读取 Environment= 和 EnvironmentFile= 值（包括 %h、带引号的路径、多个文件以及可选的 - 文件）。
Drift checks resolve gateway.auth.token SecretRefs using merged runtime env (service command env first, then process env fallback).
If token auth is not effectively active (explicit gateway.auth.mode of password/none/trusted-proxy, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.

`gateway probe`

gateway probe is the “debug everything” command. It always probes:

your configured remote gateway (if set), and
localhost (loopback) even if remote is configured.

If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.

openclaw gateway probe
openclaw gateway probe --json

Interpretation:

Reachable: yes means at least one target accepted a WebSocket connect.
RPC: ok means detail RPC calls (health/status/system-presence/config.get) also succeeded.
RPC: limited - missing scope: operator.read means connect succeeded but detail RPC is scope-limited. This is reported as degraded reachability, not full failure.
Exit code is non-zero only when no probed target is reachable.

JSON notes (--json):

Top level:
- ok: at least one target is reachable.
- degraded: at least one target had scope-limited detail RPC.
Per target (targets[].connect):
- ok: reachability after connect + degraded classification.
- rpcOk: full detail RPC success.
- scopeLimited: detail RPC failed due to missing operator scope.

Remote over SSH (Mac app parity)

macOS 应用的“通过 SSH 远程连接”模式使用本地端口转发，因此远程 Gateway（可能仅绑定到环回接口）可在 ws://127.0.0.1:<port> 访问。

CLI 等效命令：

openclaw gateway probe --ssh user@gateway-host

选项：

--ssh <target>：user@host 或 user@host:port（端口默认为 22）。
--ssh-identity <path>：身份文件。
--ssh-auto：选择第一个发现的 Gateway 主机作为 SSH 目标（仅限 LAN/WAB）。

配置（可选，用作默认值）：

gateway.remote.sshTarget
gateway.remote.sshIdentity

`gateway call <method>`

底层 RPC 辅助工具。

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

管理 Gateway(网关) 服务

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

注意：

gateway install 支持 --port、--runtime、--token、--force、--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，安装将被阻止，直到显式设置模式。
生命周期命令接受 --json 用于脚本编写。

发现 Gateway (Bonjour)

gateway discover 扫描 Gateway(网关) 信标（_openclaw-gw._tcp）。

多播 DNS-SD：local.
单播 DNS-SD（广域 Bonjour）：选择一个域（例如：openclaw.internal.）并设置分流 DNS + DNS 服务器；请参阅 /gateway/bonjour

只有启用了 Bonjour 发现功能（默认）的网关才会通告信标。

广域发现记录包括 (TXT)：

role（网关角色提示）
transport（传输提示，例如 gateway）
gatewayPort（WebSocket 端口，通常为 18789）
sshPort（SSH 端口；如果不存在，默认为 22）
tailnetDns（MagicDNS 主机名，如果可用）
gatewayTls / gatewayTlsSha256（已启用 TLS + 证书指纹）
cliPath（远程安装的可选提示）

`gateway discover`

openclaw gateway discover

选项：

--timeout <ms>：每条命令的超时时间（浏览/解析）；默认为 2000。
--json：机器可读输出（同时禁用样式/旋转图标）。

示例：

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'