Skip to main content
Gateway 是 OpenClaw 的 WebSocket 服务器(通道、节点、会话、钩子)。本页中的子命令位于 openclaw gateway … 下。

Bonjour 发现

本地 mDNS + 广域 DNS-SD 设置。

发现概览

OpenClaw 如何发布和查找网关。

配置

顶层 gateway 配置键。

运行 Gateway

运行一个本地 Gateway 进程:
openclaw gateway
前台别名:
openclaw gateway run
  • 默认情况下,除非在 ~/.openclaw/openclaw.json 中设置了 gateway.mode=local,否则 Gateway 会拒绝启动。临时/开发运行时可使用 --allow-unconfigured
  • 预期 openclaw onboard --mode localopenclaw setup 会写入 gateway.mode=local。如果文件存在但缺少 gateway.mode,请将其视为损坏或被覆盖的配置,并修复它,而不是隐式假定为本地模式。
  • 如果文件存在且缺少 gateway.mode,Gateway 会将其视为可疑的配置损坏,并拒绝替你“猜测为本地模式”。
  • 在没有认证的情况下,绑定到 loopback 之外的地址会被阻止(安全护栏)。
  • 目前 lantailnetcustom 仅通过仅限 IPv4 的 BYOH 路径解析。
  • 目前这条路径不原生支持仅 IPv6 的 BYOH。如果主机本身只有 IPv6,请使用 IPv4 sidecar 或代理。
  • 授权时,SIGUSR1 会触发进程内重启(commands.restart 默认启用;将 commands.restart: false 可阻止手动重启,但仍允许 gateway 工具/配置 apply/update)。
  • SIGINT/SIGTERM 处理器会停止 gateway 进程,但不会恢复任何自定义终端状态。如果你把 CLI 包装在 TUI 或 raw-mode 输入中,请在退出前恢复终端。

选项

--port <port>
number
WebSocket 端口(默认来自配置/环境;通常为 18789)。
--bind <loopback|lan|tailnet|auto|custom>
string
监听器绑定模式。lantailnetcustom 目前仅通过仅限 IPv4 的路径解析。
--auth <token|password>
string
认证模式覆盖。
--token <token>
string
令牌覆盖(同时为该进程设置 OPENCLAW_GATEWAY_TOKEN)。
--password <password>
string
密码覆盖。
--password-file <path>
string
从文件读取 gateway 密码。
--tailscale <off|serve|funnel>
string
通过 Tailscale 暴露 Gateway。
--tailscale-reset-on-exit
boolean
在关闭时重置 Tailscale serve/funnel 配置。
--bind custom + gateway.customBindHost
string
目前预期是 IPv4 地址。对于仅 IPv6 的 BYOH,请在 Gateway 前放置一个 IPv4 sidecar 或代理,并让 OpenClaw 指向该 IPv4 端点。
--allow-unconfigured
boolean
允许在配置中没有 gateway.mode=local 的情况下启动 gateway。仅绕过临时/开发引导的启动保护;不会写入或修复配置文件。
--dev
boolean
如果缺失则创建开发配置 + 工作区(跳过 BOOTSTRAP.md)。
--reset
boolean
重置开发配置 + 凭据 + 会话 + 工作区(需要 --dev)。
--force
boolean
启动前杀掉所选端口上的任何现有监听器。
--verbose
boolean
详细日志。
--cli-backend-logs
boolean
仅在控制台显示 CLI 后端日志(并启用 stdout/stderr)。
--ws-log <auto|full|compact>
string
default:"auto"
WebSocket 日志样式。
--compact
boolean
--ws-log compact 的别名。
--raw-stream
boolean
将原始模型流事件记录为 jsonl。
--raw-stream-path <path>
string
原始流 jsonl 路径。

重启 Gateway

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --safe --skip-deferral
openclaw gateway restart --force
openclaw gateway restart --safe 会在重启前要求正在运行的 Gateway 预检当前的 OpenClaw 工作。如果存在排队中的操作、回复投递、嵌入式运行或任务运行仍在活动,Gateway 会报告阻塞项,合并重复的安全重启请求,并在活动工作耗尽后重启。普通的 restart 为兼容性保留现有的服务管理器行为。仅当你明确希望立即覆盖路径时才使用 --force openclaw gateway restart --safe --skip-deferral 会执行与 --safe 相同的 OpenClaw 感知协调重启,但会绕过活动工作延迟门控,因此即使报告了阻塞项,Gateway 也会立即发出重启。当延迟被卡住的任务运行钉住,而 --safe 单独使用会无限等待时,可将其作为操作员的逃生出口。--skip-deferral 需要 --safe
行内 --password 可能会暴露在本地进程列表中。建议使用 --password-file、环境变量或由 SecretRef 支持的 gateway.auth.password

Gateway 性能剖析

  • 设置 OPENCLAW_GATEWAY_STARTUP_TRACE=1,可在 Gateway 启动期间记录各阶段耗时,包括每个阶段的 eventLoopMax 延迟,以及已安装索引、清单注册表、启动规划和 owner-map 工作的插件查找表计时。
  • 设置 OPENCLAW_GATEWAY_RESTART_TRACE=1,可记录重启范围内的 restart trace: 行,用于重启信号处理、活动工作耗尽、关闭阶段、下次启动、就绪时间以及内存指标。
  • 设置 OPENCLAW_DIAGNOSTICS=timeline 并配合 OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>,可为外部 QA harness 写出尽力而为的 JSONL 启动诊断时间线。你也可以在配置中通过 diagnostics.flags: ["timeline"] 启用该标志;路径仍由环境变量提供。添加 OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 可包含事件循环采样。
  • 先运行 pnpm build,然后运行 pnpm test:startup:gateway -- --runs 5 --warmup 1,即可针对构建后的 CLI 入口对 Gateway 启动进行基准测试。该基准会记录首次进程输出、/healthz/readyz、启动追踪时间、事件循环延迟以及插件查找表计时细节。
  • 先运行 pnpm build,然后在 macOS 或 Linux 上运行 pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5,即可针对构建后的 CLI 入口对进程内 Gateway 重启进行基准测试。重启基准会使用 SIGUSR1,在子进程中启用启动和重启追踪,并记录下一个 /healthz、下一个 /readyz、停机时间、就绪时间、CPU、RSS 以及重启追踪指标。
  • /healthz 视为存活探针,将 /readyz 视为可用就绪状态。追踪行和基准输出用于归属定位;不要把单条追踪跨度或单个样本当作完整的性能结论。

查询正在运行的 Gateway

所有查询命令都使用 WebSocket RPC。
  • 默认:人类可读(TTY 中带颜色)。
  • --json:机器可读 JSON(无样式/无 spinner)。
  • --no-color(或 NO_COLOR=1):禁用 ANSI,同时保留人类布局。
当你设置 --url 时,CLI 不会回退到配置或环境凭据。请显式传入 --token--password。缺少显式凭据会报错。

gateway health

openclaw gateway health --url ws://127.0.0.1:18789
HTTP /healthz 端点是一个存活探针:当服务器能够响应 HTTP 时就会返回。HTTP /readyz 端点更严格,在启动插件 sidecar、channels 或已配置 hooks 仍在就绪过程中时会保持红色。本地或已认证的详细就绪响应包含一个 eventLoop 诊断块,其中包含事件循环延迟、事件循环利用率、CPU 核心比率以及 degraded 标志。

gateway usage-cost

从会话日志中获取使用成本摘要。
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json
--days <days>
number
default:"30"
要包含的天数。

gateway stability

从正在运行的 Gateway 获取最近的诊断稳定性记录器。
openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --bundle latest
openclaw gateway stability --bundle latest --export
openclaw gateway stability --json
--limit <limit>
number
default:"25"
要包含的最近事件最大数量(最多 1000)。
--type <type>
string
按诊断事件类型过滤,例如 payload.largediagnostic.memory.pressure
--since-seq <seq>
number
仅包含某个诊断序号之后的事件。
--bundle [path]
string
读取已持久化的稳定性 bundle,而不是调用正在运行的 Gateway。使用 --bundle latest(或仅 --bundle)获取状态目录下最新的 bundle,或者直接传入 bundle JSON 路径。
--export
boolean
写出一个可共享的支持诊断 zip,而不是打印稳定性细节。
--output <path>
string
--export 的输出路径。
  • 记录保留运行时元数据:事件名称、计数、字节大小、内存读数、队列/会话状态、channel/plugin 名称,以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、cookie、密钥值、主机名或原始会话 id。设置 diagnostics.enabled: false 可完全禁用记录器。
  • 在 Gateway 致命退出、关闭超时以及重启启动失败时,如果记录器有事件,OpenClaw 会将相同的诊断快照写入 ~/.openclaw/logs/stability/openclaw-stability-*.json。使用 openclaw gateway stability --bundle latest 检查最新 bundle;--limit--type--since-seq 也适用于 bundle 输出。

gateway diagnostics export

写出一个本地诊断 zip,专为附加到 bug 报告中设计。关于隐私模型和 bundle 内容,请参见 Diagnostics Export
openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json
--output <path>
string
输出 zip 路径。默认为状态目录下的支持导出。
--log-lines <count>
number
default:"5000"
要包含的最大已净化日志行数。
--log-bytes <bytes>
number
default:"1000000"
要检查的最大日志字节数。
--url <url>
string
用于健康快照的 Gateway WebSocket URL。
--token <token>
string
用于健康快照的 Gateway 令牌。
--password <password>
string
用于健康快照的 Gateway 密码。
--timeout <ms>
number
default:"3000"
状态/健康快照超时。
--no-stability-bundle
boolean
跳过已持久化稳定性 bundle 的查找。
--json
boolean
以 JSON 形式打印写入路径、大小和清单。
导出内容包含清单、Markdown 摘要、配置形状、已净化的配置细节、已净化的日志摘要、已净化的 Gateway 状态/健康快照,以及(如果存在)最新的稳定性 bundle。 它专为共享而设计。它保留有助于调试的运行细节,例如安全的 OpenClaw 日志字段、子系统名称、状态码、持续时间、已配置模式、端口、插件 id、provider id、非密钥功能设置以及已脱敏的运行日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭据、cookie、账户/消息标识符、提示/指令文本、主机名和密钥值。当一条类似 LogTape 风格的消息看起来像用户/聊天/工具载荷文本时,导出只保留“已省略该消息”以及其字节数。

gateway status

gateway status 会显示 Gateway 服务(launchd/systemd/schtasks),以及一个可选的连通性/认证能力探测。
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
--url <url>
string
添加一个显式探测目标。已配置的远程和 localhost 仍会被探测。
--token <token>
string
用于探测的令牌认证。
--password <password>
string
用于探测的密码认证。
--timeout <ms>
number
default:"10000"
探测超时。
--no-probe
boolean
跳过连通性探测(仅服务视图)。
--deep
boolean
也扫描系统级服务。
--require-rpc
boolean
将默认连通性探测升级为读探测,并在该读探测失败时以非零退出。不能与 --no-probe 组合使用。
  • 即使本地 CLI 配置缺失或无效,gateway status 仍可用于诊断。
  • 默认的 gateway status 会证明服务状态、WebSocket 连接,以及握手时可见的认证能力。它不能证明读/写/管理操作可用。
  • 对于首次设备认证,诊断探测是非变更性的:如果存在已缓存的设备令牌,它会复用该令牌,但不会为了检查状态而创建新的 CLI 设备身份或只读设备配对记录。
  • gateway status 会在可能的情况下解析配置中的认证 SecretRef 以用于探测认证。
  • 如果在该命令路径中必需的认证 SecretRef 无法解析,而探测连接/认证失败,gateway status --json 会报告 rpc.authWarning;请显式传入 --token/--password 或先解析密钥来源。
  • 如果探测成功,则会抑制未解析 auth-ref 的警告,以避免误报。
  • 当启用探测时,如果正在运行的 Gateway 报告了版本,JSON 输出会包含 gateway.version;如果后续握手探测无法提供版本元数据,--require-rpc 可以回退到 status.runtimeVersion RPC 载荷。
  • 当仅有监听服务还不够、你还需要读范围 RPC 调用也正常时,请在脚本和自动化中使用 --require-rpc
  • --deep 会尽力扫描额外的 launchd/systemd/schtasks 安装项。当检测到多个类似 gateway 的服务时,人类输出会打印清理提示,并警告大多数部署应该每台机器只运行一个 gateway。
  • 如果服务进程因外部监督器重启而正常退出,--deep 还会报告最近一次 Gateway 监督器重启交接。
  • --deep 会以插件感知模式运行配置验证(pluginValidation: "full"),并显示已配置的插件清单警告(例如缺失 channel 配置元数据),以便安装和更新冒烟检查能够发现问题。默认的 gateway status 保留快速只读路径,跳过插件验证。
  • 人类输出会包含解析后的文件日志路径,以及 CLI 与服务配置路径/有效性快照,以帮助诊断 profile 或 state-dir 漂移。
  • 在 Linux systemd 安装中,服务认证漂移检查会从 unit 中读取 Environment=EnvironmentFile= 两种值(包括 %h、带引号的路径、多个文件以及可选的 - 文件)。
  • 漂移检查会使用合并后的运行时环境解析 gateway.auth.token SecretRef(先使用服务命令环境,再回退到进程环境)。
  • 如果令牌认证实际上未启用(显式的 gateway.auth.modepassword/none/trusted-proxy,或者模式未设置且密码可能生效而没有令牌候选可以生效),则 token 漂移检查会跳过配置令牌解析。

gateway probe

gateway probe 是“调试一切”的命令。它总会探测:
  • 你已配置的远程 gateway(如果已设置),以及
  • localhost(loopback)即使已配置远程
如果你传入 --url,该显式目标会被添加到两者之前。人类可读输出将目标标记为:
  • URL (explicit)
  • Remote (configured)Remote (configured, inactive)
  • Local loopback
如果多个探测目标都可达,它会全部打印出来。SSH 隧道、TLS/proxy URL 和已配置的远程 URL 即使传输端口不同,也可能指向同一个 gateway;multiple_gateways 仅保留给彼此不同或身份上无法区分的可达 gateway。使用隔离配置文件(例如救援 bot)时支持多个 gateway,但大多数安装仍只运行一个 gateway。
openclaw gateway probe
openclaw gateway probe --json
  • 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_onlywrite_capableadmin_capablepairing_pendingconnected_no_operator_scopeunknown)。
  • primaryTargetId:按以下优先级作为活动胜者的最佳目标:显式 URL、SSH 隧道、已配置远程,然后是本地 loopback。
  • warnings[]:尽力而为的警告记录,包含 codemessage 和可选的 targetIds
  • network:从当前配置和主机网络派生的本地 loopback/tailnet URL 提示。
  • discovery.timeoutMsdiscovery.count:本次探测实际使用的发现预算/结果数量。
每个目标(targets[].connect):
  • ok:连接后的可达性 + 降级分类。
  • rpcOk:完整详细 RPC 成功。
  • scopeLimited:由于缺少 operator 范围,详细 RPC 失败。
每个目标(targets[].auth):
  • role:可用时在 hello-ok 中报告的认证角色。
  • scopes:可用时在 hello-ok 中报告的已授予范围。
  • capability:该目标显示出的认证能力分类。
  • ssh_tunnel_failed: SSH 隧道设置失败;命令回退到直接探测。
  • multiple_gateways: 探测到了不同的 gateway 身份,或者 OpenClaw 无法证明可达目标属于同一个 gateway。指向同一 gateway 的 SSH 隧道、代理 URL 或已配置远程 URL 不会触发此警告。
  • auth_secretref_unresolved: 失败目标所配置的认证 SecretRef 无法解析。
  • probe_scope_limited: WebSocket 连接成功,但读探测因缺少 operator.read 而受限。

通过 SSH 的远程(Mac app parity)

macOS 应用的“通过 SSH 的远程”模式使用本地端口转发,因此远程 gateway(可能仅绑定到 loopback)会变为可通过 ws://127.0.0.1:<port> 访问。 CLI 等价命令:
openclaw gateway probe --ssh user@gateway-host
--ssh <target>
string
user@hostuser@host:port(端口默认为 22)。
--ssh-identity <path>
string
身份文件。
--ssh-auto
boolean
从解析出的发现端点(local. 加上已配置的广域域名,如有)中选择发现到的第一个 gateway 主机作为 SSH 目标。TXT-only 提示会被忽略。
配置(可选,作为默认值使用):
  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

gateway call <method>

底层 RPC 帮助工具。
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
--params <json>
string
default:"{}"
用于参数的 JSON 对象字符串。
--url <url>
string
Gateway WebSocket URL。
--token <token>
string
Gateway 令牌。
--password <password>
string
Gateway 密码。
--timeout <ms>
number
超时预算。
--expect-final
boolean
主要用于会在最终载荷前流式传输中间事件的 agent 风格 RPC。
--json
boolean
机器可读 JSON 输出。
--params 必须是有效的 JSON。

管理 Gateway 服务

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

使用包装器安装

当托管服务必须通过另一个可执行文件启动时,请使用 --wrapper,例如 秘密管理器 shim 或 run-as 帮助程序。包装器会接收普通的 Gateway 参数,并负责最终以这些参数 exec openclaw 或 Node。
cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
你也可以通过环境变量设置包装器。gateway install 会验证该路径是 一个可执行文件,将包装器写入服务的 ProgramArguments,并将 OPENCLAW_WRAPPER 持久化到服务环境中,以便后续强制重装、更新和 doctor 修复。
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
要移除已持久化的包装器,请在重新安装时清空 OPENCLAW_WRAPPER
OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart
  • 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 stopgateway 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 会覆盖该次重启配置的排空预算。裸数字表示毫秒;支持 smh 等单位。--wait 0 表示无限等待。
  • gateway restart --safe --skip-deferral 会运行支持 OpenClaw 的安全重启,但绕过延后门控,因此即使报告了阻塞项,Gateway 也会立即发出重启。用于处理卡住的任务运行延后;需要 --safe
  • gateway restart --force 会跳过活跃工作排空并立即重启。当操作员已经检查过所列出的任务阻塞项并希望立刻恢复 gateway 时,请使用它。
  • 生命周期命令支持 --json,便于脚本化。
  • 当令牌认证需要 token 且 gateway.auth.token 由 SecretRef 管理时,gateway install 会验证该 SecretRef 是否可解析,但不会将解析出的 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.tokengateway.auth.password,且 gateway.auth.mode 未设置,则在显式设置模式之前会阻止安装。

发现 gateways(Bonjour)

gateway discover 扫描 Gateway 信标(_openclaw-gw._tcp)。
  • 多播 DNS-SD:local.
  • 单播 DNS-SD(广域 Bonjour):选择一个域(例如:openclaw.internal.),并配置分割 DNS + DNS 服务器;参见 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>
number
default:"2000"
每个命令的超时时间(浏览/解析)。
--json
boolean
可供机器读取的输出(也会禁用样式/转轮)。
示例:
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
  • CLI 会扫描 local. 以及已启用时配置的广域域。
  • JSON 输出中的 wsUrl 派生自已解析的服务端点,而不是仅来自 TXT 提示,例如 lanHosttailnetDns
  • local. mDNS 和广域 DNS-SD 上,仅当 discovery.mdns.modefull 时才会发布 sshPortcliPath

相关内容