学了个寂寞

Appearance

Gateway CLI ​

Gateway 是 OpenClaw 的 WebSocket 服务器，负责处理频道连接、节点通信、会话管理和 Hooks 调用。

本页所有子命令均在 openclaw gateway … 下。

相关文档：

启动 Gateway ​

在前台运行本地 Gateway 进程：

bash
openclaw gateway

前台别名：

bash
openclaw gateway run

注意事项：

  • 默认情况下，除非在 ~/.openclaw/openclaw.json 中设置了 gateway.mode=local，否则 Gateway 会拒绝启动。临时/开发环境可使用 --allow-unconfigured 绕过此限制。
  • 绑定到非回环地址时，若未配置认证则会被阻止（安全保护机制）。
  • SIGUSR1 信号在授权情况下（默认启用 commands.restart）触发进程内重启；设置 commands.restart: false 可禁止手动重启，但 gateway tool/config apply/update 仍可触发重启。
  • SIGINT/SIGTERM 处理器会停止 gateway 进程，但不会恢复自定义终端状态。如果你用 TUI 或 raw 模式包装了 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：详细日志。
  • --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：将原始模型流事件记录到 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 ​

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

gateway status ​

gateway status 显示 Gateway 服务（launchd/systemd/schtasks）以及可选的 RPC 探测结果。

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

选项：

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

注意事项：

  • gateway status 在可能的情况下会为探测认证解析配置的 auth SecretRef。
  • 如果此命令路径中所需的 auth SecretRef 未解析，gateway status --json 在探测连接/认证失败时会报告 rpc.authWarning；此时可显式传递 --token/--password 或先解析 secret 来源。
  • 如果探测成功，未解析的 auth-ref 警告会被抑制，以避免误报。
  • 在脚本和自动化中，当仅有监听服务不够用、需要 Gateway RPC 本身也健康时，使用 --require-rpc。
  • 在 Linux systemd 安装中，服务认证漂移检查会读取 unit 中的 Environment= 和 EnvironmentFile= 值（包括 %h、带引号路径、多个文件和可选 - 文件）。

gateway probe ​

gateway probe 是"调试一切"的命令，它总是探测：

  • 你配置的远程 gateway（如果已设置），以及
  • 本地回环地址（即使已配置远程 gateway 也会探测）。

如果多个 gateway 可达，它会全部打印出来。使用隔离的 profile/端口时（例如救援机器人），可支持多个 gateway，但大多数安装仍然只运行单个 gateway。

bash
openclaw gateway probe
openclaw gateway probe --json

结果解读：

  • Reachable: yes 表示至少有一个目标接受了 WebSocket 连接。
  • RPC: ok 表示详细 RPC 调用（health/status/system-presence/config.get）也成功了。
  • RPC: limited - missing scope: operator.read 表示连接成功，但详细 RPC 受到权限范围限制。这被报告为降级可达性，而非完全失败。
  • 只有当没有任何探测目标可达时，退出码才为非零。

JSON 说明（--json）：

  • 顶层：
    • ok：至少有一个目标可达。
    • degraded：至少有一个目标的详细 RPC 受权限范围限制。
  • 每个目标（targets[].connect）：
    • ok：连接后的可达性及降级分类。
    • rpcOk：完整详细 RPC 成功。
    • scopeLimited：详细 RPC 因缺少 operator 权限范围而失败。

通过 SSH 连接远程 Gateway（与 macOS 应用对等） ​

macOS 应用的"Remote over SSH"模式使用本地端口转发，使仅绑定到回环的远程 gateway 可通过 ws://127.0.0.1:<port> 访问。

CLI 等价命令：

bash
openclaw gateway probe --ssh user@gateway-host

选项：

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

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

  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

gateway call <method> ​

低级 RPC 辅助工具。

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

管理 Gateway 服务 ​

bash
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 未解析，安装会失败（不会回退到明文持久化）。
  • 对于 gateway run 的密码认证，优先使用 OPENCLAW_GATEWAY_PASSWORD、--password-file 或 SecretRef 支持的 gateway.auth.password，而非内联 --password。
  • 在推断认证模式下，仅 shell 中的 OPENCLAW_GATEWAY_PASSWORD 不会放宽安装 token 要求；安装托管服务时使用持久化配置（gateway.auth.password 或配置 env）。
  • 如果 gateway.auth.token 和 gateway.auth.password 都已配置且 gateway.auth.mode 未设置，安装会被阻止，直到显式设置 mode。
  • 生命周期命令支持 --json 用于脚本化。

发现 Gateway（Bonjour） ​

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

  • 多播 DNS-SD：local.
  • 单播 DNS-SD（Wide-Area Bonjour）：选择一个域名（示例：openclaw.internal.），配置 split DNS 和 DNS 服务器；参见 /openclaw/gateway/bonjour

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

Wide-Area 发现记录包含（TXT）：

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

gateway discover ​

bash
openclaw gateway discover

选项：

  • --timeout <ms>：每个命令的超时（浏览/解析）；默认 2000。
  • --json：机器可读输出（同时禁用样式/进度条）。

示例：

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

小提示：gateway discover 是排查"我的龙虾在哪里"最好用的命令——在局域网内广播发现，一眼看清所有在线的 OpenClaw 实例。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策