openclaw gateway … 下。
Bonjour 发现
本地 mDNS + 广域 DNS-SD 设置。
发现概览
OpenClaw 如何发布和查找网关。
配置
顶层 gateway 配置键。
运行 Gateway
运行一个本地 Gateway 进程:启动行为
启动行为
- 默认情况下,除非在
~/.openclaw/openclaw.json中设置了gateway.mode=local,否则 Gateway 会拒绝启动。临时/开发运行时可使用--allow-unconfigured。 - 预期
openclaw onboard --mode local和openclaw setup会写入gateway.mode=local。如果文件存在但缺少gateway.mode,请将其视为损坏或被覆盖的配置,并修复它,而不是隐式假定为本地模式。 - 如果文件存在且缺少
gateway.mode,Gateway 会将其视为可疑的配置损坏,并拒绝替你“猜测为本地模式”。 - 在没有认证的情况下,绑定到 loopback 之外的地址会被阻止(安全护栏)。
- 目前
lan、tailnet和custom仅通过仅限 IPv4 的 BYOH 路径解析。 - 目前这条路径不原生支持仅 IPv6 的 BYOH。如果主机本身只有 IPv6,请使用 IPv4 sidecar 或代理。
- 授权时,
SIGUSR1会触发进程内重启(commands.restart默认启用;将commands.restart: false可阻止手动重启,但仍允许 gateway 工具/配置 apply/update)。 SIGINT/SIGTERM处理器会停止 gateway 进程,但不会恢复任何自定义终端状态。如果你把 CLI 包装在 TUI 或 raw-mode 输入中,请在退出前恢复终端。
选项
WebSocket 端口(默认来自配置/环境;通常为
18789)。监听器绑定模式。
lan、tailnet 和 custom 目前仅通过仅限 IPv4 的路径解析。认证模式覆盖。
令牌覆盖(同时为该进程设置
OPENCLAW_GATEWAY_TOKEN)。密码覆盖。
从文件读取 gateway 密码。
通过 Tailscale 暴露 Gateway。
在关闭时重置 Tailscale serve/funnel 配置。
目前预期是 IPv4 地址。对于仅 IPv6 的 BYOH,请在 Gateway 前放置一个 IPv4 sidecar 或代理,并让 OpenClaw 指向该 IPv4 端点。
允许在配置中没有
gateway.mode=local 的情况下启动 gateway。仅绕过临时/开发引导的启动保护;不会写入或修复配置文件。如果缺失则创建开发配置 + 工作区(跳过 BOOTSTRAP.md)。
重置开发配置 + 凭据 + 会话 + 工作区(需要
--dev)。启动前杀掉所选端口上的任何现有监听器。
详细日志。
仅在控制台显示 CLI 后端日志(并启用 stdout/stderr)。
WebSocket 日志样式。
--ws-log compact 的别名。将原始模型流事件记录为 jsonl。
原始流 jsonl 路径。
重启 Gateway
openclaw gateway restart --safe 会在重启前要求正在运行的 Gateway 预检当前的 OpenClaw 工作。如果存在排队中的操作、回复投递、嵌入式运行或任务运行仍在活动,Gateway 会报告阻塞项,合并重复的安全重启请求,并在活动工作耗尽后重启。普通的 restart 为兼容性保留现有的服务管理器行为。仅当你明确希望立即覆盖路径时才使用 --force。
openclaw gateway restart --safe --skip-deferral 会执行与 --safe 相同的 OpenClaw 感知协调重启,但会绕过活动工作延迟门控,因此即使报告了阻塞项,Gateway 也会立即发出重启。当延迟被卡住的任务运行钉住,而 --safe 单独使用会无限等待时,可将其作为操作员的逃生出口。--skip-deferral 需要 --safe。
Gateway 性能剖析
- 设置
OPENCLAW_GATEWAY_STARTUP_TRACE=1,可在 Gateway 启动期间记录各阶段耗时,包括每个阶段的eventLoopMax延迟,以及已安装索引、清单注册表、启动规划和 owner-map 工作的插件查找表计时。 - 设置
OPENCLAW_GATEWAY_RESTART_TRACE=1,可记录重启范围内的restart trace:行,用于重启信号处理、活动工作耗尽、关闭阶段、下次启动、就绪时间以及内存指标。 - 设置
OPENCLAW_DIAGNOSTICS=timeline并配合OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>,可为外部 QA harness 写出尽力而为的 JSONL 启动诊断时间线。你也可以在配置中通过diagnostics.flags: ["timeline"]启用该标志;路径仍由环境变量提供。添加OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1可包含事件循环采样。 - 先运行
pnpm build,然后运行pnpm test:startup:gateway -- --runs 5 --warmup 1,即可针对构建后的 CLI 入口对 Gateway 启动进行基准测试。该基准会记录首次进程输出、/healthz、/readyz、启动追踪时间、事件循环延迟以及插件查找表计时细节。 - 先运行
pnpm build,然后在 macOS 或 Linux 上运行pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5,即可针对构建后的 CLI 入口对进程内 Gateway 重启进行基准测试。重启基准会使用 SIGUSR1,在子进程中启用启动和重启追踪,并记录下一个/healthz、下一个/readyz、停机时间、就绪时间、CPU、RSS 以及重启追踪指标。 - 将
/healthz视为存活探针,将/readyz视为可用就绪状态。追踪行和基准输出用于归属定位;不要把单条追踪跨度或单个样本当作完整的性能结论。
查询正在运行的 Gateway
所有查询命令都使用 WebSocket RPC。- 输出模式
- 共享选项
- 默认:人类可读(TTY 中带颜色)。
--json:机器可读 JSON(无样式/无 spinner)。--no-color(或NO_COLOR=1):禁用 ANSI,同时保留人类布局。
当你设置
--url 时,CLI 不会回退到配置或环境凭据。请显式传入 --token 或 --password。缺少显式凭据会报错。gateway health
/healthz 端点是一个存活探针:当服务器能够响应 HTTP 时就会返回。HTTP /readyz 端点更严格,在启动插件 sidecar、channels 或已配置 hooks 仍在就绪过程中时会保持红色。本地或已认证的详细就绪响应包含一个 eventLoop 诊断块,其中包含事件循环延迟、事件循环利用率、CPU 核心比率以及 degraded 标志。
gateway usage-cost
从会话日志中获取使用成本摘要。
要包含的天数。
gateway stability
从正在运行的 Gateway 获取最近的诊断稳定性记录器。
要包含的最近事件最大数量(最多
1000)。按诊断事件类型过滤,例如
payload.large 或 diagnostic.memory.pressure。仅包含某个诊断序号之后的事件。
读取已持久化的稳定性 bundle,而不是调用正在运行的 Gateway。使用
--bundle latest(或仅 --bundle)获取状态目录下最新的 bundle,或者直接传入 bundle JSON 路径。写出一个可共享的支持诊断 zip,而不是打印稳定性细节。
--export 的输出路径。隐私和 bundle 行为
隐私和 bundle 行为
- 记录保留运行时元数据:事件名称、计数、字节大小、内存读数、队列/会话状态、channel/plugin 名称,以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、令牌、cookie、密钥值、主机名或原始会话 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 内容,请参见 Diagnostics Export。
输出 zip 路径。默认为状态目录下的支持导出。
要包含的最大已净化日志行数。
要检查的最大日志字节数。
用于健康快照的 Gateway WebSocket URL。
用于健康快照的 Gateway 令牌。
用于健康快照的 Gateway 密码。
状态/健康快照超时。
跳过已持久化稳定性 bundle 的查找。
以 JSON 形式打印写入路径、大小和清单。
gateway status
gateway status 会显示 Gateway 服务(launchd/systemd/schtasks),以及一个可选的连通性/认证能力探测。
添加一个显式探测目标。已配置的远程和 localhost 仍会被探测。
用于探测的令牌认证。
用于探测的密码认证。
探测超时。
跳过连通性探测(仅服务视图)。
也扫描系统级服务。
将默认连通性探测升级为读探测,并在该读探测失败时以非零退出。不能与
--no-probe 组合使用。状态语义
状态语义
- 即使本地 CLI 配置缺失或无效,
gateway status仍可用于诊断。 - 默认的
gateway status会证明服务状态、WebSocket 连接,以及握手时可见的认证能力。它不能证明读/写/管理操作可用。 - 对于首次设备认证,诊断探测是非变更性的:如果存在已缓存的设备令牌,它会复用该令牌,但不会为了检查状态而创建新的 CLI 设备身份或只读设备配对记录。
gateway status会在可能的情况下解析配置中的认证 SecretRef 以用于探测认证。- 如果在该命令路径中必需的认证 SecretRef 无法解析,而探测连接/认证失败,
gateway status --json会报告rpc.authWarning;请显式传入--token/--password或先解析密钥来源。 - 如果探测成功,则会抑制未解析 auth-ref 的警告,以避免误报。
- 当启用探测时,如果正在运行的 Gateway 报告了版本,JSON 输出会包含
gateway.version;如果后续握手探测无法提供版本元数据,--require-rpc可以回退到status.runtimeVersionRPC 载荷。 - 当仅有监听服务还不够、你还需要读范围 RPC 调用也正常时,请在脚本和自动化中使用
--require-rpc。 --deep会尽力扫描额外的 launchd/systemd/schtasks 安装项。当检测到多个类似 gateway 的服务时,人类输出会打印清理提示,并警告大多数部署应该每台机器只运行一个 gateway。- 如果服务进程因外部监督器重启而正常退出,
--deep还会报告最近一次 Gateway 监督器重启交接。 --deep会以插件感知模式运行配置验证(pluginValidation: "full"),并显示已配置的插件清单警告(例如缺失 channel 配置元数据),以便安装和更新冒烟检查能够发现问题。默认的gateway status保留快速只读路径,跳过插件验证。- 人类输出会包含解析后的文件日志路径,以及 CLI 与服务配置路径/有效性快照,以帮助诊断 profile 或 state-dir 漂移。
Linux systemd 认证漂移检查
Linux systemd 认证漂移检查
- 在 Linux systemd 安装中,服务认证漂移检查会从 unit 中读取
Environment=和EnvironmentFile=两种值(包括%h、带引号的路径、多个文件以及可选的-文件)。 - 漂移检查会使用合并后的运行时环境解析
gateway.auth.tokenSecretRef(先使用服务命令环境,再回退到进程环境)。 - 如果令牌认证实际上未启用(显式的
gateway.auth.mode为password/none/trusted-proxy,或者模式未设置且密码可能生效而没有令牌候选可以生效),则 token 漂移检查会跳过配置令牌解析。
gateway probe
gateway probe 是“调试一切”的命令。它总会探测:
- 你已配置的远程 gateway(如果已设置),以及
- localhost(loopback)即使已配置远程。
--url,该显式目标会被添加到两者之前。人类可读输出将目标标记为:
URL (explicit)Remote (configured)或Remote (configured, inactive)Local loopback
如果多个探测目标都可达,它会全部打印出来。SSH 隧道、TLS/proxy URL 和已配置的远程 URL 即使传输端口不同,也可能指向同一个 gateway;
multiple_gateways 仅保留给彼此不同或身份上无法区分的可达 gateway。使用隔离配置文件(例如救援 bot)时支持多个 gateway,但大多数安装仍只运行一个 gateway。解释
解释
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表示 Gateway 接受了 WebSocket 连接,但后续读诊断超时或失败。这同样是降级可达性,而不是不可达的 Gateway。 - 与
gateway status一样,probe 会复用现有缓存的设备认证,但不会创建首次设备身份或配对状态。 - 只有当所有被探测的目标都不可达时,退出码才为非零。
JSON 输出
JSON 输出
顶层:
ok:至少有一个目标可达。degraded:至少有一个目标接受了连接,但未完成完整的详细 RPC 诊断。capability:在可达目标中看到的最佳能力(read_only、write_capable、admin_capable、pairing_pending、connected_no_operator_scope或unknown)。primaryTargetId:按以下优先级作为活动胜者的最佳目标:显式 URL、SSH 隧道、已配置远程,然后是本地 loopback。warnings[]:尽力而为的警告记录,包含code、message和可选的targetIds。network:从当前配置和主机网络派生的本地 loopback/tailnet URL 提示。discovery.timeoutMs和discovery.count:本次探测实际使用的发现预算/结果数量。
targets[].connect):ok:连接后的可达性 + 降级分类。rpcOk:完整详细 RPC 成功。scopeLimited:由于缺少 operator 范围,详细 RPC 失败。
targets[].auth):role:可用时在hello-ok中报告的认证角色。scopes:可用时在hello-ok中报告的已授予范围。capability:该目标显示出的认证能力分类。
Common warning codes
Common warning codes
ssh_tunnel_failed: SSH 隧道设置失败;命令回退到直接探测。multiple_gateways: 探测到了不同的 gateway 身份,或者 OpenClaw 无法证明可达目标属于同一个 gateway。指向同一 gateway 的 SSH 隧道、代理 URL 或已配置远程 URL 不会触发此警告。auth_secretref_unresolved: 失败目标所配置的认证 SecretRef 无法解析。probe_scope_limited: WebSocket 连接成功,但读探测因缺少operator.read而受限。
通过 SSH 的远程(Mac app parity)
macOS 应用的“通过 SSH 的远程”模式使用本地端口转发,因此远程 gateway(可能仅绑定到 loopback)会变为可通过ws://127.0.0.1:<port> 访问。
CLI 等价命令:
user@host 或 user@host:port(端口默认为 22)。身份文件。
从解析出的发现端点(
local. 加上已配置的广域域名,如有)中选择发现到的第一个 gateway 主机作为 SSH 目标。TXT-only 提示会被忽略。gateway.remote.sshTargetgateway.remote.sshIdentity
gateway call <method>
底层 RPC 帮助工具。
用于参数的 JSON 对象字符串。
Gateway WebSocket URL。
Gateway 令牌。
Gateway 密码。
超时预算。
主要用于会在最终载荷前流式传输中间事件的 agent 风格 RPC。
机器可读 JSON 输出。
--params 必须是有效的 JSON。管理 Gateway 服务
使用包装器安装
当托管服务必须通过另一个可执行文件启动时,请使用--wrapper,例如
秘密管理器 shim 或 run-as 帮助程序。包装器会接收普通的 Gateway 参数,并负责最终以这些参数 exec openclaw 或 Node。
gateway install 会验证该路径是
一个可执行文件,将包装器写入服务的 ProgramArguments,并将
OPENCLAW_WRAPPER 持久化到服务环境中,以便后续强制重装、更新和 doctor
修复。
OPENCLAW_WRAPPER:
命令选项
命令选项
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port,--runtime <node|bun>,--token,--wrapper <path>,--force,--jsongateway restart:--safe,--skip-deferral,--force,--wait <duration>,--jsongateway uninstall|start:--jsongateway 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
安装时的认证和 SecretRef
- 当令牌认证需要 token 且
gateway.auth.token由 SecretRef 管理时,gateway install会验证该 SecretRef 是否可解析,但不会将解析出的 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未设置,则在显式设置模式之前会阻止安装。
发现 gateways(Bonjour)
gateway discover 扫描 Gateway 信标(_openclaw-gw._tcp)。
- 多播 DNS-SD:
local. - 单播 DNS-SD(广域 Bonjour):选择一个域(例如:
openclaw.internal.),并配置分割 DNS + DNS 服务器;参见 Bonjour。
role(gateway 角色提示)transport(传输提示,例如gateway)gatewayPort(WebSocket 端口,通常为18789)sshPort(仅完整发现模式;当缺失时,客户端默认将 SSH 目标设为22)tailnetDns(MagicDNS 主机名,如可用)gatewayTls/gatewayTlsSha256(已启用 TLS + 证书指纹)cliPath(仅完整发现模式)
gateway discover
每个命令的超时时间(浏览/解析)。
可供机器读取的输出(也会禁用样式/转轮)。
- CLI 会扫描
local.以及已启用时配置的广域域。 - JSON 输出中的
wsUrl派生自已解析的服务端点,而不是仅来自 TXT 提示,例如lanHost或tailnetDns。 - 在
local.mDNS 和广域 DNS-SD 上,仅当discovery.mdns.mode为full时才会发布sshPort和cliPath。