Gateway CLI

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

本页的子命令都在 openclaw gateway ... 下。

相关文档：

运行 Gateway

启动一个本地 Gateway 进程：

openclaw gateway

前台别名：

openclaw gateway run

注意事项：

  • 默认情况下，Gateway 在 ~/.openclaw/openclaw.json 中未设置 gateway.mode=local 时拒绝启动。临时或开发运行可以用 --allow-unconfigured。
  • 在没有认证的情况下绑定到回环之外的地址会被阻止（安全护栏）。
  • SIGUSR1 在授权时触发进程内重启（commands.restart 默认启用；设置 commands.restart: false 可阻止手动重启，但 Gateway 工具/配置应用/更新不受影响）。
  • SIGINT/SIGTERM 处理器会停止 Gateway 进程，但不会恢复自定义的终端状态。如果你用 TUI 或原始模式输入包装了 CLI，退出前需要自行恢复终端。

选项

  • --port <port>：WebSocket 端口（默认来自配置/环境变量；通常是 18789）。
  • --bind <loopback|lan|tailnet|auto|custom>：监听绑定模式。
  • --auth <token|password>：认证模式覆盖。
  • --token <token>：token 覆盖（同时为进程设置 OPENCLAW_GATEWAY_TOKEN）。
  • --password <password>：密码覆盖。注意：内联密码可能在本地进程列表中可见。
  • --password-file <path>：从文件读取 Gateway 密码。
  • --tailscale <off|serve|funnel>：通过 Tailscale 暴露 Gateway。
  • --tailscale-reset-on-exit：关闭时重置 Tailscale serve/funnel 配置。
  • --allow-unconfigured：允许在配置中没有 gateway.mode=local 的情况下启动 Gateway。
  • --dev：如果不存在则创建开发配置 + 工作区（跳过 BOOTSTRAP.md）。
  • --reset：重置开发配置 + 凭据 + 会话 + 工作区（需要 --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 token。
  • --password <password>：Gateway 密码。
  • --timeout <ms>：超时/预算（因命令而异）。
  • --expect-final：等待”最终”响应（Agent 调用）。

注意：设置 --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>：探测的 token 认证。
  • --password <password>：探测的密码认证。
  • --timeout <ms>：探测超时（默认 10000）。
  • --no-probe：跳过 RPC 探测（仅查看服务状态）。
  • --deep：同时扫描系统级服务。

注意事项：

  • gateway status 在可能时会解析配置的认证 SecretRef 用于探测认证。
  • 如果必需的认证 SecretRef 在当前命令路径中未解析，探测认证可能失败；显式传入 --token/--password 或先解析密钥来源。
  • 在 Linux systemd 安装中，服务认证漂移检查会读取单元中的 Environment= 和 EnvironmentFile= 值（包括 %h、引号路径、多文件和可选的 - 文件）。

gateway probe

gateway probe 是”全面调试”命令。它始终探测：

  • 你配置的远程 Gateway（如果设置了），以及
  • localhost（回环）即使配置了远程也会探测。

如果多个 Gateway 可达，会全部打印出来。当你使用隔离的配置文件/端口（例如救援机器人）时支持多 Gateway，但大多数安装仍然只运行一个 Gateway。

openclaw gateway probe
openclaw gateway probe --json

通过 SSH 的远程访问（Mac 应用对等功能）

macOS 应用的”Remote over 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。
  • 当 token 认证需要 token 且 gateway.auth.token 通过 SecretRef 管理时，gateway install 会验证 SecretRef 可解析，但不会把解析后的 token 持久化到服务环境元数据中。
  • 如果 token 认证需要 token 且配置的 token SecretRef 未解析，install 会安全失败而不是持久化回退的明文。
  • 对于 gateway run 的密码认证，推荐使用 OPENCLAW_GATEWAY_PASSWORD、--password-file 或通过 SecretRef 管理的 gateway.auth.password，而不是内联 --password。
  • 在推断认证模式下，仅存在于 shell 中的 OPENCLAW_GATEWAY_PASSWORD/CLAWDBOT_GATEWAY_PASSWORD 不会放宽 install 的 token 要求；安装托管服务时请使用持久化配置（gateway.auth.password 或 config env）。
  • 如果 gateway.auth.token 和 gateway.auth.password 都已配置但 gateway.auth.mode 未设置，install 会被阻止直到显式设置 mode。
  • 生命周期命令支持 --json 用于脚本（默认输出保持人类友好）。

发现 Gateway（Bonjour）

gateway discover 扫描 Gateway 信标（_openclaw-gw._tcp）。

  • 组播 DNS-SD：local.
  • 单播 DNS-SD（广域 Bonjour）：选择一个域（例如 openclaw.internal.）并设置 split DNS + DNS 服务器；参见 /gateway/bonjour

只有启用了 Bonjour 发现（默认启用）的 Gateway 才会广播信标。

广域发现记录包含（TXT）：

  • role（Gateway 角色提示）
  • 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'
arrow_back
上一页
Doctor
下一页
Health
arrow_forward