跳转至

查询

WebSocket RPC 查询子命令及其共享选项。openclaw gateway 参考的一部分。

查询正在运行的 Gateway

所有查询命令都使用 WebSocket RPC。

在使用 token、密码或 none 认证时，针对已配置的本地回环 Gateway 的普通 RPC 调用不会打开共享状态数据库以进行设备认证。显式 URL 目标和已配对的远程连接保留其设备认证规则。

  • 默认：人类可读（在 TTY 中显示颜色）。
  • --json：机器可读 JSON（无样式/无 spinner）。
  • --no-color（或 NO_COLOR=1）：禁用 ANSI，同时保留人类可读布局。
  • --url <url>：Gateway WebSocket URL。
  • --token <token>：Gateway token。
  • --password <password>：Gateway 密码。
  • --timeout <ms>：超时/预算（默认值因命令而异；见下文各命令）。
  • --expect-final：等待 "final" 响应（agent 调用）。

Note

设置 --url 时，CLI 不会回退到配置或环境凭据。请显式传入 --token 或 --password。缺少显式凭据会报错。

WebSocket 打开握手超时会报告带有 ETIMEDOUT 的 Gateway 传输错误，其中包含目标和状态检查提示。JSON 错误输出使用 error.type: "gateway_transport_error"，与其他连接失败相同。

gateway health

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

/healthz 是存活探针：只要服务器能够响应 HTTP，它就会立即返回。/readyz 更严格，在启动插件 sidecar、通道或已配置的 hooks 仍在稳定时保持红色。本地或经过认证的详细 /readyz 响应包含一个 eventLoop 诊断块（延迟、利用率、CPU 核心比率、degraded 标志）。

针对此端口上的本地回环 Gateway。本次调用会覆盖 OPENCLAW_GATEWAY_URL 和 OPENCLAW_GATEWAY_PORT。

gateway usage-cost

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

openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --agent work --json
openclaw gateway usage-cost --all-agents
openclaw gateway usage-cost --json

人类可读输出会提示，当使用缓存正在刷新、部分可用或过期时，总计可能不完整。该命令从一次请求中返回可用快照；稍后再次运行以检查刷新后的总计。JSON 输出保留 cacheStatus 对象，以便脚本检查相同状态。

要包含的天数。

将摘要限定到一个已配置的 agent id。

--all-agents boolean (path)
跨所有已配置的 agent 聚合。不能与 --agent 组合。

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

要包含的最近事件最大数量（最大 1000）。

按诊断事件类型过滤，例如 payload.large 或 diagnostic.memory.pressure。

仅包含某个诊断序列号之后的事件。

--bundle [path] string (path)
读取已持久化的稳定性 bundle，而不是调用正在运行的 Gateway。--bundle latest（或单独的 --bundle）选择状态目录下最新的 bundle；也可以直接传入 bundle JSON 路径。

--export boolean (path)
写入可共享的支持诊断 zip，而不是打印稳定性详情。

--export 的输出路径。

隐私和 bundle 行为
  • 记录保留操作元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、approval id、通道/插件名称以及脱敏的会话摘要。它们排除聊天文本、webhook 主体、工具输出、原始请求/响应主体、token、cookie、secret 值、主机名和原始会话 id。设置 diagnostics.enabled: false 可完全禁用记录器。
  • 致命 Gateway 退出、关闭超时和重启启动失败会写入诊断快照到 ~/.openclaw/logs/stability/openclaw-stability-*.json，即使记录器没有事件。当错误带有 stack 时，error.stack 会保留它，并脱敏 secret，限制为 8,000 个 UTF-16 码元。使用 openclaw gateway stability --bundle latest 检查最新的 bundle；--limit、--type 和 --since-seq 也适用于 bundle 输出。
  • 失败的关闭步骤包含 evidence.shutdown：步骤以及脱敏的错误名称、消息、代码和 stack，包括嵌套原因和聚合错误。使用 openclaw gateway stability --bundle latest --json 检查这些详情。捕获限制为 32 个错误，每个 stack 8,000 个 UTF-16 码元。gateway.restart_close_failed 标识抛出的关闭失败；gateway.restart_shutdown_timeout 标识整体关闭截止时间。超时还会保留已观察到的任何关闭错误。重启和停止失败会在退出前刷新现有文件 logger，并在其关闭预算内完成。

gateway diagnostics export

写入一个为 bug 报告设计的本地诊断 zip。有关隐私模型和 bundle 内容，请参阅 诊断导出。

openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json

输出 zip 路径。默认为状态目录下的支持导出。

要包含的最大脱敏日志行数。

要检查的最大日志字节数。

用于健康快照的 Gateway WebSocket URL。

用于健康快照的 Gateway token。

用于健康快照的 Gateway 密码。

状态/健康快照超时。

--no-stability-bundle boolean (path)
跳过已持久化的稳定性 bundle 查找。

--json boolean (path)
以 JSON 格式打印已写入的路径、大小和 manifest。

导出包包含：manifest.json（文件清单）、summary.md（Markdown 摘要）、diagnostics.json（顶层 config/logs/discovery/stability/status/health 摘要）、config/sanitized.json、status/gateway-status.json、health/gateway-health.json、logs/openclaw-sanitized.jsonl，以及当 bundle 存在时的 stability/latest.json。

它设计用于共享。它保留对调试有用的运维细节——安全日志字段、子系统名称、状态码、持续时间、已配置模式、端口、插件/提供商 ID、非机密功能设置以及已脱敏的运维日志消息——并省略或脱敏聊天文本、webhook 正文、工具输出、凭据、cookie、账户/消息标识符、prompt/指令文本、主机名和机密值。当日志消息看起来像用户/聊天/工具负载文本（例如“用户说”、“聊天文本”、“工具输出”、“webhook 正文”）时，导出仅保留消息被省略这一事实及其字节数。

gateway status

显示 Gateway 服务（launchd/systemd/schtasks）以及可选的连接性/身份验证探测。

openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
openclaw gateway status --port 19001

探测此显式 WebSocket URL，而不是从服务推导的目标。不能与 --port 组合使用。

使用调用 CLI 的配置选择本地 Gateway 端口，用于身份验证和 TLS。接受 gateway --port 19001 status 和 gateway status --port 19001；显式 status 端口优先。原生服务详情仍作为诊断信息可见，但不会选择探测目标。

探测的 Token 身份验证。

探测的密码身份验证。

探测超时。未显式指定值时，RPC 探测使用 10 秒，Windows 任务计划程序状态和注册探测允许 60 秒用于冷启动。只读注册查询将此允许时间同时用于其总运行时间和无输出时间。显式值也适用于原生服务探测。每个操作都有各自的预算；这不是整体命令截止时间。

--no-probe boolean (path)
跳过连接性探测（仅服务视图）。

--deep boolean (path)
同时扫描系统级服务。

--require-rpc boolean (path)
将连接性探测升级为读取探测，如果失败则以非零退出。不能与 --no-probe 组合使用。
状态语义
  • 即使本地 CLI 配置缺失或无效，仍可用于诊断。
  • 如果服务发现无法检查必需的文件（例如仅 root 可读的 systemd 环境文件），status 会将原生服务报告为未知，并继续使用调用方的 Gateway 目标和凭据。观察到的服务所有权拒绝仍为错误；status 不会更改文件权限或放宽生命周期检查。
  • 默认输出证明服务状态、WebSocket 连接以及握手时可见的身份验证能力——而不是读取/写入/管理操作。
  • 对于首次设备身份验证，探测是非变更性的：如果存在已缓存的设备 token，则复用该 token，但绝不会仅为了检查 status 而创建新的 CLI 设备身份或只读配对记录。
  • 在可能的情况下，解析已配置的身份验证 SecretRefs 用于探测身份验证。如果必需的 SecretRef 未解析，当探测连接性/身份验证失败时，--json 会报告 rpc.authWarning；请显式传递 --token/--password 或修复 secret 源。一旦探测成功，未解析身份验证警告将被抑制。
  • 当正在运行的 Gateway 报告版本时，JSON 输出包含 gateway.version；如果握手探测无法提供版本元数据，--require-rpc 可以回退到 status.runtimeVersion RPC 负载。
  • 在脚本/自动化中使用 --require-rpc，当仅监听服务不够，并且你还需要读取范围的 RPC 也健康时。
  • --deep 会扫描额外的 launchd/systemd/schtasks 安装；当发现多个类似 gateway 的服务时，人类可读输出会打印清理提示（通常每台机器只运行一个 gateway），并在相关时报告最近的 supervisor 重启交接。
  • --deep 会在建议修复官方插件版本漂移之前确认确切的 npm 目标。未发布的版本或注册表失败会报告而不提供更新命令；在注册表访问或发布队列恢复后重试 deep status。普通 status 和就绪检查不会查询 npm 以进行漂移修复。
  • --deep 还会以插件感知模式（pluginValidation: "full"）运行配置验证，并显示插件 manifest 警告（例如缺少 channel 配置元数据）。默认 gateway status 保持跳过插件验证的快速只读路径。
  • 在 Linux 上，status 会报告 systemd 当前加载的有效服务，包括已加载的 drop-in。如果 unit 或某个 drop-in 在磁盘上已更改，Systemd reload: pending 表示你必须在这些更改生效之前运行 systemctl --user daemon-reload（对于系统服务则运行 sudo systemctl daemon-reload）。
  • 人类可读输出包含已解析的文件日志路径，以及 CLI 与服务配置路径/有效性，以帮助诊断 profile 或 state-dir 漂移。
  • 如果 Gateway 未报告版本，人类可读输出仍会在可读时显示本地检查的服务包版本和路径。版本不匹配仅在该服务是探测目标时建议重新安装；安装限制会显示为现有的拒绝消息。
  • 当该服务仅用于诊断时，缺失的原生服务是信息性的，例如使用非默认状态目录的 Gateway。连接性探测仍会报告所选 Gateway 的结果。
  • 安装和重新安装指南遵循调用 shell 的安装规则，而不是存储的服务环境或探测目标。Nix 模式、外部监督、非规范安装身份以及 Linux sudo/user-manager 不匹配会显示安装拒绝，而不是不可用的命令。仅诊断目标本身不是拒绝。Nix 模式阻止安装，而不是阻止启动现有服务。
  • 人类可读输出包含 Gateway heap:，其中包含已配置的服务堆控制以及基于 CLI 可见内存的单独安装时建议。JSON 输出以 service.gatewayHeap 公开相同报告。两者都不是对正在运行的 Gateway 的 V8 堆上限的测量；请使用运行时内存诊断。
Linux systemd 认证漂移检查
  • 服务认证漂移检查会读取单元中的 Environment= 和 EnvironmentFile=。Environment= 的赋值可能带引号。每个 EnvironmentFile= 指令使用一个不带引号的绝对路径，包括含空格的路径；支持多个指令和可选的 - 前缀文件。%h 展开为服务用户的主目录，%% 表示字面百分号。
  • 使用合并后的运行时环境（服务命令环境优先，进程环境作为回退）解析 gateway.auth.token 的 SecretRef。
  • 当令牌认证未实际生效时，令牌漂移检查会跳过配置令牌解析（gateway.auth.mode 显式为 password/none/trusted-proxy，或模式未设置时密码可能生效且没有任何令牌候选可能生效）。

gateway probe

“调试一切”（debug everything）命令。它始终探测：

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

传入 --url 会在两者之前添加该显式目标。人类可读输出将目标标记为 URL (explicit)、Remote (configured) / Remote (configured, inactive) 和 Local loopback。

Note

如果多个探测目标可达，则全部打印。SSH 隧道、TLS/代理 URL 和已配置的远程 URL 即使使用不同的传输端口，也可以指向同一个网关；multiple_gateways 仅用于标识不同或身份不明确的可达网关。运行多个网关可用于隔离的配置文件（例如救援机器人），但大多数安装只需运行单个网关。

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --port 18789

将此端口用于本地回环探测目标和 SSH 隧道远程端口。在没有 --url 的情况下，此选项仅选择本地回环目标，而不是已配置的网关环境 URL、环境端口或远程目标。

解读
  • 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，表示 WebSocket 已连接，但后续的读取诊断超时或失败——同样视为 降级，而非不可达。
  • 与 gateway status 一样，probe 命令会复用现有缓存的设备认证，但不会创建首次设备身份或配对状态。
  • 仅当没有任何探测目标可达时，退出码才为非零。
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：本次探测实际使用的发现预算/结果数量。

每个目标（targets[].connect）：ok（可达性 + 降级分类）、rpcOk（完整详情 RPC 成功）、scopeLimited（详情 RPC 因缺少 operator 作用域而失败）。

每个目标（targets[].auth）：role 和 scopes 在 hello-ok 中可用时报告，另外还有呈现的 capability 分类。

常见警告代码
  • ssh_tunnel_failed：SSH 隧道设置失败；命令回退到直接探测。
  • multiple_gateways：不同的网关身份可达，或 OpenClaw 无法证明可达目标是同一网关。指向同一网关的 SSH 隧道、代理 URL 或已配置的远程 URL 不会触发此警告。
  • auth_secretref_unresolved：对于失败的目标，无法解析已配置的认证 SecretRef。
  • probe_scope_limited：WebSocket 连接成功，但读取探测因缺少 operator.read 而受限。
  • local_tls_runtime_unavailable：本地 Gateway TLS 已启用，但 OpenClaw 无法加载本地证书指纹。

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

macOS 应用的“Remote over SSH”模式使用本地端口转发，使仅监听回环的远程网关可以通过 ws://127.0.0.1:<port> 访问。

CLI 等效命令：

openclaw gateway probe --ssh user@gateway-host

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

OpenClaw 仅启动在操作系统管理系统目录中找到的 SSH 客户端。在原生 Windows 上，请安装 OpenSSH Client 可选功能；Windows 会将其放在 %SystemRoot%\System32\OpenSSH 下。

身份文件。

--ssh-auto 布尔（路径）
从解析后的发现端点（local. 加上已配置的广域网域，如果有）中选择第一个发现的网关主机作为 SSH 目标。仅 TXT 提示会被忽略。

配置默认值（可选）：gateway.remote.sshTarget、gateway.remote.sshIdentity。

gateway call <method>

底层 RPC 辅助命令。

使用 --expect-url <url> 将调用绑定到先前观察到的 Gateway 端点，而不更改 URL 选择或身份验证。CLI 在连接之前会比较精确解析后的 URL，如果目标发生变化则调用失败。自动化可以从 openclaw status --json 中的 gateway.url 获取端点；已脱敏的 URL 不能作为精确的端点断言。

openclaw gateway call status
openclaw gateway call health --port 18999
openclaw gateway call logs.tail --params '{"limit": 200}'

要将现有 checkout 添加到 Control UI 的 Place 选择器中，请参阅项目注册与列出示例。

对于 sessions.send 和 chat.send，JSON timeoutMs 是接收方 agent 的执行预算，而非确认超时。普通协调时请省略该参数；--timeout 会独立地限制此 CLI 的等待时长：

openclaw gateway call sessions.send --params '{"key":"<session-key>","message":"Status update"}' --timeout 10000

started 响应仅表示请求已被接受，并不代表已收到完整回复。这些 CLI 方法面向操作员和外部自动化。Agent 应使用其暴露的 sessions_send 工具，绝不可将其当作 shell 或直接 RPC 的替代品。消息工具不可用并不代表允许使用 CLI。子 agent 通过其被接受的任务完成路径返回结果；父 agent 负责转发与其他会话之间所需的任何协调。

在 agent 的 exec 子进程（OPENCLAW_SHELL=exec）中，消息 RPC 会在连接之前被拒绝，因此 worker 报告不会作为新的用户输入出现。普通操作员终端和非消息类 Gateway 诊断保持不变。

用于 params 的 JSON 对象字符串。

Gateway WebSocket URL。

在指定端口上连接本地回环 Gateway。本次调用会覆盖 OPENCLAW_GATEWAY_URL 和 OPENCLAW_GATEWAY_PORT。不能与 --url 同时使用。

Gateway 令牌。

Gateway 密码。

超时预算。

--expect-final boolean (path)
主要用于 agent 风格的 RPC；这类 RPC 会在最终 payload 之前流式输出中间事件。

--json boolean (path)
机器可读的 JSON 输出。

openclaw.setup.detect 默认使用 40 秒，以便 Gateway 完成其有界 AI 访问扫描。显式设置的 --timeout 仍然优先。

Note

--params 必须是有效的 JSON，且每个方法都会验证自身的参数结构（多余或命名错误的字段会被拒绝）。对于自定义端口的本地 Gateway，请使用 --port；显式指定 --url 目标时仍需显式提供凭据。

gateway suspend

为协作式主机冻结或快照准备一个空闲的 Gateway。不带 --wait 时，若存在进行中的工作，命令会返回非零退出码，并附上阻塞项详情。使用 --wait 时，CLI 会使用一个稳定的请求 ID 重试，直到达到有界截止时间。该值必须是不小于 0 的秒数；空值会被拒绝。使用 --wait 0 可在不轮询的情况下只尝试一次。

openclaw gateway suspend
openclaw gateway suspend --request-id snapshot-2026-08-11 --wait 30
openclaw gateway suspend --port 18999 --json

就绪输出包含 suspension ID、租约到期时间以及对应的 resume 命令。支持常用的 RPC 选项，例如 --url、--token、--password、--timeout、--json 和 --port。

gateway resume <suspensionId>

在解冻后或主机操作被放弃时，释放已准备好的 suspension。

openclaw gateway resume <suspensionId>
openclaw gateway resume <suspensionId> --port 18999 --json

已过期或已恢复的租约属于成功的空操作。不同的活动 suspension ID 会被拒绝。一旦 shutdown 提交，即使是原始所有者，恢复也会被拒绝；gateway.suspend.status 会报告该所有者的 shutdown 进度，直到服务器拆除关闭 RPC 访问。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw