OpenClaw Gateway CLI (`openclaw gateway`) — run, query, and discover gateways

Read when…
  • Running the Gateway from the CLI (dev or servers)
  • Debugging Gateway auth, bind modes, and connectivity
  • Discovering gateways via Bonjour (LAN + tailnet)

Gateway CLI

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

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

相关文档：

运行Gateway

运行本地Gateway进程：

openclaw gateway

前台别名：

openclaw gateway run

注意事项：

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

选项

  • --port <port>: WebSocket端口（默认来自config/env；通常是18789）。
  • --bind <loopback|lan|tailnet|auto|custom>: 监听绑定模式。
  • --auth <token|password>: 身份验证模式覆盖。
  • --token <token>: 令牌覆盖（也设置进程的OPENCLAW_GATEWAY_TOKEN）。
  • --password <password>: 密码覆盖（也设置进程的OPENCLAW_GATEWAY_PASSWORD）。
  • --tailscale <off|serve|funnel>: 通过Tailscale暴露Gateway。
  • --tailscale-reset-on-exit: 关机时重置Tailscale服务/漏斗配置。
  • --allow-unconfigured: 允许在配置中没有gateway.mode=local的情况下启动网关。
  • --dev: 如果缺少，则创建一个dev配置+工作区（跳过BOOTSTRAP.md）。
  • --reset: 重置dev配置+凭据+会话+工作区（需要--dev）。
  • --force: 在启动前终止选定端口上的任何现有监听器。
  • --verbose: 详细日志。
  • --claude-cli-logs: 仅在控制台显示claude-cli日志（并启用其stdout/stderr）。
  • --ws-log <auto|full|compact>: websocket日志样式（默认auto）。
  • --compact: --ws-log compact的别名。
  • --raw-stream: 将原始模型流事件记录为jsonl。
  • --raw-stream-path <path>: 原始流jsonl路径。

查询正在运行的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

选项：

  • --url <url>: 覆盖探测URL。
  • --token <token>: 探测的令牌认证。
  • --password <password>: 探测的密码认证。
  • --timeout <ms>: 探测超时（默认10000）。
  • --no-probe: 跳过RPC探测（仅服务视图）。
  • --deep: 扫描系统级服务。

gateway probe

gateway probe是“调试一切”的命令。它总是探测：

  • 您配置的远程网关（如果已设置），以及
  • 本地主机（回环）即使远程已配置。

如果有多个网关可达，它会打印所有。当您使用隔离的配置文件/端口（例如，救援机器人）时支持多个网关，但大多数安装仍然只运行一个网关。

openclaw gateway probe
openclaw gateway probe --json

通过SSH远程（Mac应用对等）

macOS应用的“通过SSH远程”模式使用本地端口转发，因此远程网关（可能仅绑定到回环）可以在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: 选择第一个发现的网关主机作为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。
  • 生命周期命令接受--json用于脚本编写。

发现网关（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'