用终端接管OpenClaw——CLI远程调用Gateway,全量命令解析,技术干货篇!

openclaw gateway call 命令的底层就是一个一次性WebSocket客户端：建连、握手、调用、断开。没有长连接、没有事件推送，干完就走。

工作原理：

核心特性一览：

CLI版本必须与远程网关的协议版本兼容。版本不匹配是最常见的问题来源，后面踩坑实录会详细展开。

三种配置方式，按优先级从低到高排列。本系列推荐第二种——配置文件方式，一次写好长期复用。

适合一次性临时调用。

编辑~/.openclaw/openclaw.json，添加远程网关配置：

配置后直接使用，无需每次传参：

这是最推荐的方式：地址和Token在文件里一次写好，所有命令自动带上。后面所有示例都默认你已经这么配过了。

适合CI/CD和Shell脚本场景，用环境变量隔离不同环境。

CLI按以下优先级解析网关地址：

1. –url 命令行参数（最高）

2. 环境变量 OPENCLAW_GATEWAY_URL

3. 配置文件 gateway.remote.url

4. 本地网关 wss://127.0.0.1:18443（最低）

[!] 重要陷阱：一旦你显式传了–url，CLI不会再回落到配置文件或环境变量里的Token。要么把–token一起传，要么干脆全靠配置文件。这是官方文档明确写的：”Missing explicit credentials is an error.”

openclaw gateway 下面是一套完整的网关管理命令家族。

gateway call 是整个CLI的核心——它能调用任何一个RPC方法。

–params 必须是合法的JSON字符串。

–json 模式没有颜色、没有 spinner，纯粹给脚本用。

12个典型场景，覆盖日常运维、Agent管理、配置操作全链路。

输出：

/healthz 是HTTP层的存活探针，收到响应就说明进程在。/readyz 更严格，startup插件、channels、hooks全部settle了才返回ok。health 命令走的是WebSocket RPC，比HTTP多一层——能拿到 eventLoop 诊断块，包含事件循环延迟、CPU利用率和 degraded 标志。

这四个命令是CLI独有的诊断利器。出了问题别瞎猜，先跑一遍这些。

gateway probe 是”debug everything”命令。它比 status 更深入——同时探测你配置的remote网关和localhost本地网关，还会验证认证能力和读写权限。

输出语义解读：

JSON模式下会输出完整的诊断结构：ok、degraded、capability、primaryTargetId、warnings[]、network，以及每个target的 connect 和 auth 详情。

Exit code非零 = 所有目标都不可达。

如果你的远端网关绑在loopback上，还可以通过SSH隧道探测：

配置文件也支持SSH默认值：gateway.remote.sshTarget 和 gateway.remote.sshIdentity。

gateway stability 拉取运行中网关的稳定性记录器数据。出过大body告警、内存压力事件、异常崩溃——这里都有记录。

隐私说明：记录只保留操作元数据（事件名、计数、字节大小、内存读数、队列状态），不保留聊天文本、webhook body、tool输出、token、cookie、secret。要彻底关闭可以设 diagnostics.enabled: false。

网关在fatal exit、shutdown超时、restart startup失败时会自动把诊断快照写到 ~/.openclaw/logs/stability/openclaw-stability-*.json。

做bug report的标准姿势：导出一个诊断zip，附到issue里。

导出内容包含：manifest、Markdown摘要、config shape（脱敏）、sanitized log、Gateway status/health snapshots、最新stability bundle。

该zip是设计成可安全分享的——保留操作细节（子系统名、状态码、耗时、端口、插件ID），脱掉了聊天文本、webhook body、tool输出、凭证、cookie、prompt内容、hostname。

这是CLI远程调用最关键的前置条件。版本不对，什么都白搭。

OpenClaw Gateway使用协议版本号进行兼容性检查：

当CLI和网关协议版本不匹配时：

方案A：升级网关端（推荐）

方案B：降级CLI端

方案C：使用Node.js脚本自定义协议版本

当CLI版本不匹配时，可以直接用Node.js脚本指定 minProtocol: 3：

结论：本文测试环境中，CLI版本为2026.5.19 (Protocol v4)，另一台网关版本为2026.5.7 (Protocol v3)，存在一个大版本差异。CLI方式遇到这种情况需要版本对齐才能工作，你对照自己CLI和网关的版本号看下是否匹配。WebSocket脚本方式可以手动指定协议版本绕过此限制。

CLI的价值在于可编程。以下是四种典型的集成方式。

CLI不只是能远程调用RPC，它还负责管理网关进程本身——安装、启动、停止、重启、卸载。

所有命令都支持 –json 输出。

当你的Token或Secret存储在外部Secret Manager（如Doppler、Vault）里，不想明文写到服务配置里，可以用wrapper套壳：

wrapper接收正常的Gateway参数，负责注入环境变量后exec到openclaw。

也可以通过环境变量设置：

清除wrapper：

重启不是只有一种：

–safe 的行为：检查当前有没有正在进行的reply delivery、embedded runs、task runs，有的话等它们跑完再重启。如果某个task一直卡着不结束，–safe –skip-deferral 就是逃生口——跑safe预检但不等了，直接重启。

–wait 30s 可以覆盖默认的drain超时时间。支持 s（秒）、m（分）、h（小时）单位，–wait 0 表示无限等待。

macOS上的区别：默认 stop 用 launchctl bootout，只在当前boot session生效，KeepAlive自动恢复机制依然存在——万一崩溃了会被拉起来，gateway start 也能正常用。加了 –disable 才是真正持久化禁用，直到你手动 gateway start。

如果在局域网里有多台机器跑着网关，gateway discover 通过Bonjour扫描会自动发现它们。这也是之前安全漏洞爆发出来的一个入口点，如果安全问题不重视，侵入一台，所有实例都能访问爆破。

底层扫描 _openclaw-gw._tcp beacon，支持两种模式：

发现的beacon会携带TXT hints：

只有开启了Bonjour discovery的网关（默认开启）才会广播beacon。

适合的场景：

不适合的场景：

WebSocket JSON-RPC的完整协议拆解——长连接、事件推送、双向错误信息

以下为实机验证踩坑记录，全部基于真实环境复现。

实测现象：

错误输出：

根因：CLI发送minProtocol:4, maxProtocol:4，远端网关只支持v3，协议协商失败。这个错误发生在握手阶段，Token还没来得及被检验就被断开了。

解决方案：

1. 升级网关到与CLI相同版本

2. 降级CLI：npm install -g openclaw@远端版本

3. 用Node.js脚本手动指定minProtocol: 3（WebSocket方式不受此限制）

关键点：看到protocol mismatch不要以为是Token错误。这是版本不匹配，和认证无关。

同一个远端网关(Protocol v3)：

CLI的协议版本由源码硬编码（MIN_CLIENT_PROTOCOL_VERSION），无法通过命令行参数覆盖。如果远端网关版本较老，CLI方式完全不可用，只能用WebSocket脚本。

CLI调用本地网关：

本地网关用ws://，远端网关用wss://。搞反了会连接失败但错误信息不明显。

实测现象（远端网关，WebSocket直连）：

即使Token正确、握手成功，如果没有设备签名且不是Control UI模式，网关会静默清空你声明的scopes。hello-ok返回“scopes”: []，后续所有需要权限的调用都会报missing scope。务必在握手成功后检查返回的scopes是否非空。

–expect-final会让CLI等待”最终响应”，如果方法本身只有一次响应（如health），CLI拿到第一个ok:true后还会继续等，直到超时。

在同一台本地网关上的实测对比：

结论已经很明显：CLI和WebSocket能力完全对齐（150+方法全量），Admin HTTP RPC只有~50个白名单方法。但CLI是一次性的刀——没有事件推送、没有长连接。WebSocket的完整协议细节和实时推送机制，第3篇会全面拆解。

这个坑官方文档写得很清楚但容易忽略：

一旦你传了–url，CLI就认为你要完全手动控制，不会再fallback到配置文件或环境变量里的Token。要么全手动，要么全靠配置文件。

以下是从源码扒出来的全部顶级命令，共55个。这张表相当于OpenClaw的命令行字典——不管你是日常运维还是写自动化脚本，碰到不确定的命令直接来这里查。配合前面的OpenClaw系列教程一起用，上手效率会快很多。

CLI是一次性的刀，干完就走。但有些场景需要一直在线——实时事件推送、双向通信、前端Web页面管理。第3篇将深入WebSocket全协议，拆解长连接、握手流程、事件订阅、心跳保活，以及如何用纯脚本写一个完整的OpenClaw管理前端。

版权声明：本文由AI技术博客原创，转载请注明出处。

#openclaw#龙虾#RPC#管理页面#CLI#命令行