跳转至

查询

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

查询运行中的网关

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

使用 token、password 或 none 认证时,对已配置的本地回环 Gateway 的普通 RPC 调用不会打开共享状态数据库进行设备认证。显式 URL 目标和已配对的远程连接保留其设备认证规则。现有身份通过 SQLite 读取,无需复制共享数据库,也无需进入其写入者生命周期。这些读取可能会创建 SQLite 协调文件(WAL/SHM),但不会更改已存储的身份、token 或 schema。

如果无法读取设备身份存储,调用会在连接前停止并报告恢复指导。它不会在未选择设备身份的情况下静默连接;请检查状态目录访问权限,并在重试前运行 openclaw doctor --fix。

  • 默认:人类可读(在 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:等待“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、通道或配置的钩子仍在就绪时会一直保持红色。本地或经过认证的详细 /readyz 响应包含一个 eventLoop 诊断块(延迟、利用率、CPU 核心比率、degraded 标志)。

<ParamField path="--port " type="number"> 以此端口上的本地回环 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 对象,以便脚本检查相同状态。

<ParamField path="--days " type="number" default="30"> 要包含的天数。

<ParamField path="--agent " type="string"> 将摘要范围限定为某个已配置的 agent ID。

--all-agents boolean(路径)
聚合所有已配置的 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

<ParamField path="--limit " type="number" default="25"> 要包含的最近事件的最大数量(最大 1000)。

<ParamField path="--type " type="string"> 按诊断事件类型过滤,例如 payload.large 或 diagnostic.memory.pressure。

<ParamField path="--since-seq " type="number"> 仅包含某个诊断序列号之后的事件。

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

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

<ParamField path="--output " type="string"> --export 的输出路径。

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

gateway diagnostics export

编写一个用于缺陷报告的本地诊断 zip 包。有关隐私模型和捆绑包内容,请参阅诊断导出。

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

<ParamField path="--output " type="string"> 输出 zip 路径。默认为状态目录下的支持导出文件。

<ParamField path="--log-lines " type="number" default="5000"> 包含的最大脱敏日志行数。

<ParamField path="--log-bytes " type="number" default="1000000"> 要检查的最大日志字节数。

<ParamField path="--url " type="string"> 用于健康快照的 Gateway WebSocket URL。

<ParamField path="--token " type="string"> 用于健康快照的 Gateway 令牌。

<ParamField path="--password " type="string"> 用于健康快照的 Gateway 密码。

<ParamField path="--timeout " type="number" default="3000"> 状态/健康快照超时时间。

--no-stability-bundle boolean (path)
跳过持久化稳定性捆绑包查找。

--json boolean (path)
以 JSON 形式输出写入路径、大小和清单。

导出包包含以下内容:manifest.json(文件清单)、summary.md(Markdown 摘要)、diagnostics.json(顶层配置/日志/发现/稳定性/状态/健康摘要)、config/sanitized.json、status/gateway-status.json、health/gateway-health.json、logs/openclaw-sanitized.jsonl,以及存在捆绑包时的 stability/latest.json。

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

gateway status

显示 Gateway 服务(launchd/systemd/schtasks)以及可选连接/身份验证检查。

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

在源码检出环境下,pnpm openclaw gateway status 会在已记录的输入字节仍然匹配时复用当前已准备好的运行时产物,即使 Git 将这些输入标记为脏状态。已变更的输入或缺失的输出仍然需要刷新;status 不会绕过正在运行的 Gateway 的产物发布保护机制。

<ParamField path="--url " type="string"> 检查此显式 WebSocket URL,而不是服务派生的目标。不能与 --port 结合使用。

<ParamField path="--port " type="number"> 使用调用方 CLI 配置中的身份验证和 TLS 选择一个本地 Gateway 端口。支持 gateway --port 19001 status 和 gateway status --port 19001;显式状态端口优先。本机服务详细信息仍作为诊断信息可见,但不会选择检查目标。

<ParamField path="--token " type="string"> 用于检查的 Token 身份验证。

<ParamField path="--password " type="string"> 用于检查的密码身份验证。

<ParamField path="--timeout " type="number" default="10000"> 检查超时时间。未显式指定时,RPC 检查使用 10 秒,Windows 任务计划程序状态和注册检查允许冷启动 60 秒。只读注册查询在总运行时间和无输出时间上都使用此配额。显式设置的值同样适用于本机服务检查。每个操作都有各自的预算;这不是整个命令的总截止时间。

--no-probe boolean (path)
跳过连接检查(仅服务视图)。

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

--require-rpc boolean (path)
将连接检查升级为读取检查,如果失败则返回非零退出码。不能与 --no-probe 组合使用。
状态语义
  • 即使本地 CLI 配置缺失或无效,也仍可用于诊断。配置问题会作为警告,并附有 openclaw doctor --fix 指导;有效的连接设置和已记录的服务身份仍然可用。
  • 如果服务发现无法检查必需文件,例如仅 root 可读的 systemd 环境文件,status 会将本机服务报告为未知,并继续使用调用方的 Gateway 目标和凭据。观察到的服务所有权拒绝仍视为错误;status 不会更改文件权限或放宽生命周期检查。
  • 默认输出证明服务状态、WebSocket 连接以及在握手时可见的身份验证能力——而不是读/写/管理员操作。
  • 检查对首次设备身份验证是非变更性的:当存在缓存的设备令牌时,它们会复用该令牌,但绝不会仅仅为了检查状态而创建新的 CLI 设备身份或只读配对记录。
  • 尽可能为检查身份验证解析已配置的 auth SecretRef。如果必需的 SecretRef 无法解析,当检查连接/身份验证失败时,--json 会报告 rpc.authWarning;请显式传入 --token/--password 或修复密钥来源。一旦检查成功,未解析身份验证的警告就会被抑制。
  • 当正在运行的 Gateway 报告版本时,JSON 输出会包含 gateway.version;如果握手检查无法提供版本元数据,--require-rpc 可以回退到 status.runtimeVersion RPC 负载。
  • 在脚本/自动化中使用 --require-rpc,当仅有监听服务还不够、你还需要读范围的 RPC 也保持健康时。
  • --deep 会扫描额外的 launchd/systemd/schtasks 安装;当发现多个类似 Gateway 的服务时,人类可读输出会打印清理提示(通常每台机器运行一个 gateway),并在相关时报告最近的监督者重启交接。
  • --deep 在建议修复官方插件版本漂移之前,会确认确切的 npm 目标。对于未发布的版本或注册表失败,报告时不附带更新命令;在注册表访问恢复或发布组恢复后重试深度状态。普通状态和就绪检查不会查询 npm 进行漂移修复。
  • --deep 还会以插件感知模式(pluginValidation: "full")运行配置验证,并显示插件清单警告(例如缺少通道配置元数据)。默认的 gateway status 采用跳过插件验证的快速只读路径。
  • 在 Linux 上,status 报告 systemd 当前加载的有效服务,包括已加载的 drop-in 文件。如果 unit 文件或 drop-in 文件在磁盘上发生了更改,Systemd reload: pending 表示你必须运行 systemctl --user daemon-reload(系统服务使用 sudo systemctl daemon-reload)才能让这些更改生效。
  • 人类可读输出包括解析后的文件日志路径,以及 CLI 与服务配置路径/有效性,以帮助诊断配置文件或状态目录漂移。
  • 如果 Gateway 未报告版本,人类可读输出在可读时仍会显示本地检查的服务包版本和路径。仅当该服务是检查目标时,版本不匹配才会建议重新安装;安装限制会显示为现有的拒绝消息。
  • 当本机服务仅为诊断目的时,例如使用非默认状态目录的 Gateway,缺少本机服务仅作提示信息。连接检查仍会报告所选 Gateway 的结果。
  • 安装和重新安装指导遵循调用 shell 的安装规则,而不是存储的服务环境或检查目标。Nix 模式、外部监督、非规范安装身份以及 Linux sudo/用户管理器不匹配会显示安装拒绝,而不是不可用的命令。仅诊断目标本身不是拒绝。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

这个“调试一切”命令。它始终检查:

  • 你配置的远程网关(若已设置),以及
  • 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

<ParamField path="--port " type="number"> 将此端口用于本地回环检查目标和 SSH 隧道远程端口。在不使用 --url 时,这会仅选择本地回环目标,而不是已配置的网关环境 URL、环境端口或远程目标。

解读
  • Reachable: yes 表示至少一个目标接受了 WebSocket 连接。
  • Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only 报告检查在认证方面能证明的内容,与可达性分开。
  • 成功的读取检查意味着读取作用域详细 RPC 调用(health/status/system-presence/config.get)也成功了。
  • 因缺少 operator.read 作用域而受限的读取检查意味着连接成功,但读取作用域 RPC 受限。报告为 degraded 可达性,而不是完全失败。
  • Connect: ok 之后的读取检查失败意味着 WebSocket 已连接,但后续的读取诊断超时或失败——同样是 degraded,而不是不可达。
  • 与 gateway status 类似,此命令复用现有缓存的设备认证,但不会创建首次设备身份或配对状态。
  • 仅当没有任何被检查目标可达时,退出码才为非零。
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(可达性 + degraded 分类)、rpcOk(完整详细 RPC 成功)、scopeLimited(详细 RPC 因缺少 operator 作用域而失败)。

每个目标(targets[].auth):在可用时于 hello-ok 中报告 role 和 scopes,以及呈现出来的 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

<ParamField path="--ssh " type="string"> user@host 或 user@host:port(端口默认为 22)。

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

<ParamField path="--ssh-identity " type="string"> 身份文件。

--ssh-auto 布尔值 (path)
从解析后的发现端点(local. 加上已配置的广域域名,若有)中选择第一个发现的网关主机作为 SSH 目标。仅含 TXT 的提示会被忽略。

配置默认值(可选):gateway.remote.sshTarget、gateway.remote.sshIdentity。

gateway call <method>

底层 RPC 辅助命令。

此命令仅加载选择和认证 Gateway 连接所需的配置。它不会验证无关的设置,也不会预加载插件运行时;请使用 openclaw config validate 检查完整配置。

使用 --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}'

要将现有检出添加到 Control UI 的 Place 选择器中,请使用 项目注册和列表示例。

对于 sessions.send 和 chat.send,JSON 中的 timeoutMs 是接收代理的 执行预算,而不是确认超时。普通协调时请省略它;--timeout 独立限制此 CLI 的等待时间:

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

started 响应表示已接受,而不是回复已完成。这些 CLI 方法 面向操作员和外部自动化。代理使用其公开的 sessions_send 工具, 而不是 shell 或直接 RPC 替代方案。消息工具不可用 并不构成使用 CLI 的许可。子代理通过其已接受的任务 完成路径返回结果;父代理负责与其他会话进行必要的协调。

在代理的 exec 子进程(OPENCLAW_SHELL=exec)中,消息 RPC 会在 连接前被拒绝,因此 worker 报告不会表现为新的人类输入。 普通操作员终端和非消息 Gateway 诊断保持不变。

<ParamField path="--params " type="string" default="{}"> 参数的 JSON 对象字符串。

<ParamField path="--url " type="string"> Gateway WebSocket URL。

<ParamField path="--port " type="number"> 将目标指向此端口上的本地回环 Gateway。对于此调用,会覆盖 OPENCLAW_GATEWAY_URL 和 OPENCLAW_GATEWAY_PORT。不能与 --url 组合使用。

<ParamField path="--token " type="string"> Gateway token。

<ParamField path="--password " type="string"> Gateway 密码。

<ParamField path="--timeout " type="number" default="10000"> 超时预算。

--expect-final boolean (path)
主要用于在最终载荷之前流式传输中间事件的代理式 RPC。

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

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

Note

--params 必须是有效 JSON,并且每个方法都会验证其自身的参数结构(额外/错误命名的字段会被拒绝)。对于自定义端口的本地 Gateway,请使用 --port;显式 --url 目标仍需要显式凭据。

gateway suspend

为空闲 Gateway 准备协作式主机冻结或快照。没有 --wait 时,活动工作会返回非零退出码并附带阻塞器详情。使用 --wait 时,CLI 会使用一个稳定的请求 ID 重试,直到有界截止时间。该值必须是非负秒数;空值会被拒绝。 使用 --wait 0 可执行单次尝试而不轮询。

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

就绪输出包括挂起 ID、租约过期时间和对应的 恢复命令。支持常见的 RPC 选项,例如 --url、--token、--password、 --timeout、--json 和 --port。

挂起阻塞器消息会列出活动的根请求,并包含聊天运行和待处理终端写入的运行 ID 与会话键。每个类别最多列出 八个持有者,其余部分显示省略计数。gateway.suspend.status 在排空期间返回相同详情,并且每次排空观察都会向 Gateway 日志写入 一行 DRAINING。待处理的最终写入在其持久化所有者完成之前保持受保护,即使聊天客户端断开连接也是如此。

gateway resume <suspensionId>

在解冻后或主机操作被放弃时,释放已准备的挂起。

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

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

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