查询
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¶
/healthz 是一个存活检查:只要服务器能够响应 HTTP,它就会立即返回。/readyz 更为严格,在启动插件 sidecar、通道或配置的钩子仍在就绪时会一直保持红色。本地或经过认证的详细 /readyz 响应包含一个 eventLoop 诊断块(延迟、利用率、CPU 核心比率、degraded 标志)。
<ParamField path="--port 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
<ParamField path="--agent
--all-agentsboolean(路径)- 聚合所有已配置的 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 1000)。
<ParamField path="--type payload.large 或 diagnostic.memory.pressure。
<ParamField path="--since-seq
--bundle [path]string(路径)- 读取持久化的稳定性 bundle,而不是调用运行中的 Gateway。
--bundle latest(或单独的--bundle)会选择状态目录下最新的 bundle;您也可以直接传入 bundle 的 JSON 路径。
--exportboolean(路径)- 写入可共享的支持诊断 zip,而不是打印稳定性详情。
<ParamField path="--output --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
<ParamField path="--log-lines
<ParamField path="--log-bytes
<ParamField path="--url
<ParamField path="--token
<ParamField path="--password
<ParamField path="--timeout
--no-stability-bundleboolean (path)- 跳过持久化稳定性捆绑包查找。
--jsonboolean (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 --port 结合使用。
<ParamField path="--port gateway --port 19001 status 和 gateway status --port 19001;显式状态端口优先。本机服务详细信息仍作为诊断信息可见,但不会选择检查目标。
<ParamField path="--token
<ParamField path="--password
<ParamField path="--timeout
--no-probeboolean (path)- 跳过连接检查(仅服务视图)。
--deepboolean (path)- 同时扫描系统级服务。
--require-rpcboolean (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.runtimeVersionRPC 负载。 - 在脚本/自动化中使用
--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.tokenSecretRef(服务命令环境优先,其次回退到进程环境)。 - 当令牌认证未实际生效时,令牌漂移检查会跳过配置令牌解析(
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 仅用于彼此不同或身份不明确的可达网关。支持为隔离配置文件(例如救援机器人)运行多个网关,但大多数安装只运行单个网关。
<ParamField path="--port --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 对应命令:
<ParamField path="--ssh user@host 或 user@host:port(端口默认为 22)。
OpenClaw 只会启动在操作系统管理的系统目录中找到的 SSH 客户端。在原生 Windows 上,请安装 OpenSSH Client 可选功能;Windows 会将其放在 %SystemRoot%\System32\OpenSSH 下。
<ParamField path="--ssh-identity
--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
<ParamField path="--url
<ParamField path="--port OPENCLAW_GATEWAY_URL 和 OPENCLAW_GATEWAY_PORT。不能与 --url 组合使用。
<ParamField path="--token
<ParamField path="--password
<ParamField path="--timeout
--expect-finalboolean (path)- 主要用于在最终载荷之前流式传输中间事件的代理式 RPC。
--jsonboolean (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>¶
在解冻后或主机操作被放弃时,释放已准备的挂起。
已过期或已恢复的租约是成功的无操作。不同的活动
挂起 ID 会被拒绝。一旦关闭已提交,即使原始所有者也会拒绝恢复;gateway.suspend.status 会报告该所有者的关闭进度,直到服务器拆除关闭 RPC 访问。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw