本页是 openclaw gateway 命令的完整参考，用于启动本地 Gateway、查询运行状态、管理服务生命周期，以及通过 Bonjour 发现局域网实例。关键命令包括 gateway run、status、probe、discover；启动时默认要求 gateway.mode=local 配置，可使用 --allow-unconfigured 绕过。绑定非回环地址时必须配置认证，否则被阻止。

OpenClaw 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 绕过此限制。
openclaw onboard --mode local 和 openclaw setup 会写入 gateway.mode=local。如果配置文件存在但缺少 gateway.mode，应将其视为损坏或被覆盖的配置并修复，而不是默认本地模式。
绑定到非回环地址时，若未配置认证则会被阻止（安全保护机制）。
SIGUSR1 信号在授权情况下（默认启用 commands.restart）触发进程内重启；设置 commands.restart: false 可禁止手动重启，但 gateway tool/config apply/update 仍可触发重启。
SIGINT/SIGTERM 处理器会停止 gateway 进程，但不会恢复自定义终端状态。如果你用 TUI 或 raw 模式包装了 CLI，退出前需自行还原终端。

选项

--port <port> number

WebSocket 端口（默认值来自配置/环境变量，通常为 18789）。

--bind <loopback|lan|tailnet|auto|custom> string

监听绑定模式。

--auth <token|password> string

认证模式覆盖。

--token <token> string

Token 覆盖（同时为进程设置 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 配置。

--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

WebSocket 日志样式。

--compact boolean

--ws-log compact 的别名。

--raw-stream boolean

将原始模型流事件记录到 jsonl。

--raw-stream-path <path> string

原始流 jsonl 路径。

重启 Gateway

bash

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --safe --skip-deferral
openclaw gateway restart --force

--safe 要求运行中的 Gateway 在重启前预检活跃工作并延迟重启，直到回复投递、嵌入运行和任务运行完成。同时会合并重复的安全重启请求。--force 跳过延期立即重启。--skip-deferral 需要 --safe，适用于任务运行卡死时的操作逃生舱口。

Gateway 性能分析

设置 OPENCLAW_GATEWAY_STARTUP_TRACE=1 记录启动阶段时序。
设置 OPENCLAW_GATEWAY_RESTART_TRACE=1 记录重启时序。
设置 OPENCLAW_DIAGNOSTICS=timeline 并配合路径，写入启动诊断 JSONL。
运行基准测试：pnpm build 后使用 pnpm test:startup:gateway 或 pnpm test:restart:gateway。
/healthz 为存活探针，/readyz 为就绪探针。

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

HTTP /healthz 端点返回后表示服务器可应答 HTTP。/readyz 更严格，在启动插件侧车、频道或配置的 hooks 未就绪前保持红色。

`gateway usage-cost`

从会话日志获取使用成本摘要。

bash

openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json

--days <days> number

包含的天数。

`gateway stability`

从运行中的 Gateway 获取近期诊断稳定性记录。

bash

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

最大事件数（最多 1000）。

--type <type> string

按诊断事件类型筛选，如 payload.large 或 diagnostic.memory.pressure。

--since-seq <seq> number

仅包含指定诊断序列号之后的事件。

--bundle [path] string

读取持久化的稳定性 bundle，而不是调用运行中的 Gateway。使用 --bundle latest 使用最新的 bundle，或直接传递 bundle JSON 路径。

--export boolean

写入可分享的支持诊断 zip 文件。

--output <path> string

--export 的输出路径。

隐私与 bundle 行为

记录包含操作元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、频道/插件名称、以及脱敏的会话摘要。不包含聊天文本、webhook 体、工具输出、原始请求/响应体、token、cookie、secret 值、主机名或原始会话 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 内容详见诊断导出。

bash

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

最多包含的清理日志行数。

--log-bytes <bytes> number

最大检查日志字节数。

--url <url> string

健康快照的 Gateway WebSocket URL。

--token <token> string

健康快照的 Gateway token。

--password <password> string

健康快照的 Gateway 密码。

--timeout <ms> number

状态/健康快照超时。

--no-stability-bundle boolean

跳过持久化稳定性 bundle 查找。

--json boolean

将写入路径、大小和清单打印为 JSON。

导出包含清单、Markdown 摘要、配置形状、清理后的配置详情、清理后的日志摘要、清理后的 Gateway 状态/健康快照，以及最新的稳定性 bundle。设计为可共享，保持有助于调试的操作细节，省略聊天文本等敏感内容。

`gateway status`

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

bash

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

--url <url> string

添加显式探测目标；已配置的远程和本地地址仍然会被探测。

--token <token> string

探测的 Token 认证。

--password <password> string

探测的密码认证。

--timeout <ms> number

探测超时。

--no-probe boolean

跳过 RPC 探测（仅显示服务状态）。

--deep boolean

同时扫描系统级额外服务（launchd/systemd/schtasks），检测多 gateway 实例并输出清理提示。

--require-rpc boolean

升级默认连接探测为读取探测，并在该读取探测失败时以非零退出。不能与 --no-probe 组合使用。

状态语义

gateway status 即使在本地 CLI 配置缺失或无效时仍可用于诊断。
默认 gateway status 证明服务状态、WebSocket 连接和握手时的认证能力。不证明读/写/管理操作。
诊断探测对于首次设备认证是非侵入性的：重用现有缓存的设备 token（如果存在），但不会创建新的 CLI 设备身份或只读设备配对记录。
gateway status 在可能的情况下会为探测认证解析配置的 auth SecretRef。
如果所需 auth SecretRef 未解析，gateway status --json 在探测连接/认证失败时会报告 rpc.authWarning；此时可显式传递 --token/--password 或先解析 secret 来源。
如果探测成功，未解析的 auth-ref 警告会被抑制。
当探测启用时，JSON 输出包含 gateway.version（如果运行中的 Gateway 报告）；--require-rpc 可以在后续握手探测无法提供版本元数据时回退到 status.runtimeVersion RPC 载荷。
在脚本和自动化中，当仅有监听服务不够用、需要 Gateway RPC 本身也健康时，使用 --require-rpc。
--deep 添加额外的启动加载/系统服务扫描。当检测到多个 gateway 类似服务时，人类输出打印清理提示，并警告大多数设置应在每台机器上运行一个 gateway。
--deep 还报告最近的 Gateway supervisor 重启交接（当服务进程干净退出并由外部 supervisor 重启时）。
--deep 以插件感知模式运行配置验证（pluginValidation: "full"），并呈现已配置插件清单的警告（例如缺少频道配置元数据），使安装和更新冒烟检查能够捕捉它们。默认 gateway status 使用跳过插件验证的快速只读路径。
人类输出包含已解析的日志路径以及 CLI 与服务的配置路径/有效性快照，便于诊断 profile 或状态目录漂移。

Linux systemd 认证漂移检查

在 Linux systemd 安装中，服务认证漂移检查读取 unit 中的 Environment= 和 EnvironmentFile= 值（包括 %h、带引号路径、多个文件和可选 - 文件）。
漂移检查通过合并后的运行时环境（服务命令环境优先，然后进程环境回退）解析 gateway.auth.token SecretRef。
如果 token 认证未有效激活（显式 gateway.auth.mode 为 password/none/trusted-proxy，或 mode 未设置且密码可获胜而 token 候选无法获胜），则 token 漂移检查跳过配置 token 解析。

`gateway probe`

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

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

如果传递 --url，该显式目标会添加到两者之前。人类输出将目标标记为：

URL (explicit)
Remote (configured) 或 Remote (configured, inactive)
Local loopback

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

bash

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 受限。这被报告为降级可达性，而非完全失败。
Read probe: failed 在连接成功后后续读诊断超时或失败时出现。也属于降级可达性。
与 gateway status 一样，探测重用现有缓存的设备 token，但不会创建设备身份或配对状态。
只有当没有任何探测目标可达时，退出码才为非零。

JSON 输出

顶层：

ok：至少有一个目标可达。
degraded：至少有一个目标接受了连接但未完成完整详细 RPC 诊断。
capability：在所有可达目标中看到的最佳能力（read_only、write_capable、admin_capable、pairing_pending、connected_no_operator_scope 或 unknown）。
primaryTargetId：最佳目标（按顺序：显式 URL、SSH 隧道、配置的远程、本地回环）。
warnings[]：尽力而为的警告记录，含 code、message 和可选 targetIds。
network：根据当前配置和主机网络派生的本地回环/tailnet URL 提示。
discovery.timeoutMs 和 discovery.count：本次探测 pass 实际使用的发现预算/结果计数。

每个目标（targets[].connect）：

ok：连接后的可达性 + 降级分类。
rpcOk：完整详细 RPC 成功。
scopeLimited：详细 RPC 因缺少 operator 范围而失败。

每个目标（targets[].auth）：

role：hello-ok 中报告的认证角色（如果可用）。
scopes：hello-ok 中报告的授权范围（如果可用）。
capability：该目标的表面认证能力分类。

常见警告代码

ssh_tunnel_failed：SSH 隧道设置失败，命令回退到直接探测。
multiple_gateways：多个目标可达；除非有意运行隔离的 profile（如救援机器人），否则不常见。
auth_secretref_unresolved：对于失败的目标，配置的 auth SecretRef 无法解析。
probe_scope_limited：WebSocket 连接成功，但读探测因缺少 operator.read 而受限。

通过 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> string

user@host 或 user@host:port（port 默认为 22）。

--ssh-identity <path> string

身份文件。

--ssh-auto boolean

从已解析的发现端点自动选择第一个发现的 gateway 主机作为 SSH 目标（local. 加上配置的 wide-area 域，如果有）。忽略仅 TXT 的提示。

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

gateway.remote.sshTarget
gateway.remote.sshIdentity

`gateway call <method>`

低级 RPC 辅助工具。

bash

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

--params <json> string

用于参数的 JSON 对象字符串。

--url <url> string

Gateway WebSocket URL。

--token <token> string

Gateway token。

--password <password> string

Gateway 密码。

--timeout <ms> number

超时预算。

--expect-final boolean

主要用于 agent 风格的 RPC，它们会在最终载荷之前流式传输中间事件。

--json boolean

机器可读 JSON 输出。

--params 必须为有效 JSON。

管理 Gateway 服务

bash

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

使用包装器安装

当托管服务必须通过另一个可执行文件启动时（例如 secrets manager shim 或 run-as helper），使用 --wrapper。包装器接收正常的 Gateway 参数，并最终负责执行 openclaw 或 Node。

bash

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 修复使用。

bash

OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor

要移除持久化包装器，在重新安装时清除 OPENCLAW_WRAPPER：

bash

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 stop 和 gateway 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 覆盖配置的重启排空预算。裸数字为毫秒；单位如 s、m、h 也可接受。--wait 0 表示无限等待。
gateway restart --safe --skip-deferral 运行 OpenClaw 感知的安全重启，但绕过延期门，使 Gateway 即使在阻挡器报告时也立即发出重启。用于任务运行卡住的逃生舱口；需要 --safe。
gateway restart --force 跳过活跃工作排空并立即重启。当操作员已经检查了列出的任务阻挡器并希望立即恢复 Gateway 时使用。
生命周期命令接受 --json 用于脚本化。

安装时的认证与 SecretRef

当 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。

发现 Gateway（Bonjour）

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

多播 DNS-SD：local.
单播 DNS-SD（Wide-Area Bonjour）：选择一个域名（示例：openclaw.internal.），配置 split DNS 和 DNS 服务器；参见 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> number

每个命令的超时（浏览/解析）。

--json boolean

机器可读输出（同时禁用样式/进度条）。

示例：

bash

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

CLI 扫描 local. 以及配置的 wide-area 域（如果已启用）。JSON 输出中的 wsUrl 来自已解析的服务端点，而非仅 TXT 提示（如 lanHost 或 tailnetDns）。在 local. mDNS 和 wide-area DNS-SD 上，sshPort 和 cliPath 仅在 discovery.mdns.mode 为 full 时发布。

常见问题

`openclaw gateway` 启动时提示 "gateway.mode=local 未设置" 怎么解决？

运行 openclaw onboard --mode local 或 openclaw setup 完成初始配置，这会自动向 ~/.openclaw/openclaw.json 写入 gateway.mode=local。如果只是临时测试，可加 --allow-unconfigured 参数绕过检查，但建议正式环境走 onboard 流程。

如何确认 Gateway 的 RPC 是否正常，而不只是进程在跑？

运行 openclaw gateway status --require-rpc，这会在 RPC 探测失败时以非零状态退出，可用于健康检查脚本。也可以用 openclaw gateway probe 获取详细的连接诊断信息，包括是否降级。

Gateway 启动后外部设备无法访问，怎么开放局域网访问？

默认 Gateway 只监听回环地址（loopback）。启动时加 --bind lan 即可绑定到局域网 IP，让同网段设备可访问。如果需要公网访问，使用 --tailscale funnel 或配合反向代理。注意：绑定到非回环地址时必须配置认证（token 或密码），否则会被阻止。

OpenClaw Gateway CLI 命令参考与故障排查 ​

启动 Gateway ​

选项 ​

重启 Gateway ​

Gateway 性能分析 ​

查询运行中的 Gateway ​

gateway health ​

gateway usage-cost ​

gateway stability ​

gateway diagnostics export ​

gateway status ​

gateway probe ​

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

gateway call &lt;method&gt; ​

管理 Gateway 服务 ​

使用包装器安装 ​

发现 Gateway（Bonjour） ​

gateway discover ​

常见问题 ​

openclaw gateway 启动时提示 "gateway.mode=local 未设置" 怎么解决？ ​

如何确认 Gateway 的 RPC 是否正常，而不只是进程在跑？ ​

Gateway 启动后外部设备无法访问，怎么开放局域网访问？ ​

OpenClaw Gateway CLI 命令参考与故障排查

启动 Gateway

选项

重启 Gateway

Gateway 性能分析

查询运行中的 Gateway

`gateway health`

`gateway usage-cost`

`gateway stability`

`gateway diagnostics export`

`gateway status`

`gateway probe`

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

`gateway call <method>`

管理 Gateway 服务

使用包装器安装

发现 Gateway（Bonjour）

`gateway discover`

常见问题

`openclaw gateway` 启动时提示 "gateway.mode=local 未设置" 怎么解决？

如何确认 Gateway 的 RPC 是否正常，而不只是进程在跑？

Gateway 启动后外部设备无法访问，怎么开放局域网访问？