网关服务运维手册

最后更新:2025-12-09

什么是网关

持续运行的进程,负责单一的 Baileys/Telegram 连接以及控制/事件平面。
替代旧版 gateway 命令。CLI 入口点:openclaw gateway。
持续运行直到停止;遇到致命错误时以非零状态退出,以便监督进程重启。

本地运行方式

bash

openclaw gateway --port 18789
# for full debug/trace logs in stdio:
openclaw gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
openclaw gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch

配置热重载会监视 ~/.openclaw/openclaw.json(或 OPENCLAW_CONFIG_PATH)。
- 默认模式:gateway.reload.mode="hybrid"(热应用安全更改,关键更改时重启)。
- 热重载在需要时通过 SIGUSR1 使用进程内重启。
- 使用 gateway.reload.mode="off" 禁用。
WebSocket 控制平面绑定到 127.0.0.1:<port>(默认 18789)。
同一端口还提供 HTTP 服务(控制 UI、钩子、A2UI)。单端口多路复用。
- OpenAI Chat Completions (HTTP):/v1/chat/completions。
- OpenResponses (HTTP):/v1/responses。
- Tools Invoke (HTTP):/tools/invoke。
默认在 canvasHost.port(默认 18793)上启动 Canvas 文件服务器,从 ~/.openclaw/workspace/canvas 提供 http://<gateway-host>:18793/__openclaw__/canvas/。使用 canvasHost.enabled=false 或 OPENCLAW_SKIP_CANVAS_HOST=1 禁用。
日志输出到 stdout;使用 launchd/systemd 保持运行并轮转日志。
在故障排查时传递 --verbose 可将调试日志(握手、请求/响应、事件)从日志文件镜像到 stdio。
--force 使用 lsof 查找所选端口上的监听器,发送 SIGTERM,记录被终止的内容,然后启动网关(如果缺少 lsof 则快速失败)。
如果在监督进程(launchd/systemd/mac 应用子进程模式)下运行,停止/重启通常会发送 SIGTERM;旧版本可能会显示为 pnpm ELIFECYCLE 退出码 143(SIGTERM),这是正常关闭,不是崩溃。
SIGUSR1 在授权时触发进程内重启(网关工具/配置应用/更新,或启用 commands.restart 进行手动重启)。
默认需要网关认证:设置 gateway.auth.token(或 OPENCLAW_GATEWAY_TOKEN)或 gateway.auth.password。除非使用 Tailscale Serve 身份,否则客户端必须发送 connect.params.auth.token/password。
向导现在默认生成令牌,即使在回环地址上也是如此。
端口优先级:--port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789。

远程访问

首选 Tailscale/VPN;否则使用 SSH 隧道:
bash
```
ssh -N -L 18789:127.0.0.1:18789 user@host
```
1
客户端通过隧道连接到 ws://127.0.0.1:18789。
如果配置了令牌,即使通过隧道,客户端也必须在 connect.params.auth.token 中包含它。

多个网关(同一主机)

通常不需要:一个网关可以服务多个消息通道和代理。仅在需要冗余或严格隔离(例如:救援机器人)时使用多个网关。

如果隔离状态 + 配置并使用唯一端口,则支持多网关。完整指南:多个网关。

服务名称支持配置文件:

macOS:bot.molt.<profile>(旧版 com.openclaw.* 可能仍然存在)
Linux:openclaw-gateway-<profile>.service
Windows:OpenClaw Gateway (<profile>)

安装元数据嵌入在服务配置中:

OPENCLAW_SERVICE_MARKER=openclaw
OPENCLAW_SERVICE_KIND=gateway
OPENCLAW_SERVICE_VERSION=<version>

救援机器人模式:保持第二个网关隔离,使用自己的配置文件、状态目录、工作空间和基础端口间距。完整指南:救援机器人指南。

开发配置文件(`--dev`)

快速通道:运行完全隔离的开发实例(配置/状态/工作空间),而不影响主要设置。

bash

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# then target the dev instance:
openclaw --dev status
openclaw --dev health

默认值(可通过环境变量/标志/配置覆盖):

OPENCLAW_STATE_DIR=~/.openclaw-dev
OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
OPENCLAW_GATEWAY_PORT=19001(网关 WS + HTTP)
浏览器控制服务端口 = 19003(派生:gateway.port+2,仅回环)
canvasHost.port=19005(派生:gateway.port+4)
在 --dev 下运行 setup/onboard 时,agents.defaults.workspace 默认变为 ~/.openclaw/workspace-dev。

派生端口(经验法则):

基础端口 = gateway.port(或 OPENCLAW_GATEWAY_PORT / --port)
浏览器控制服务端口 = 基础端口 + 2(仅回环)
canvasHost.port = base + 4(或 OPENCLAW_CANVAS_HOST_PORT / 配置覆盖)
浏览器配置文件 CDP 端口从 browser.controlPort + 9 .. + 108 自动分配(每个配置文件持久化)。

每个实例的检查清单:

唯一的 gateway.port
唯一的 OPENCLAW_CONFIG_PATH
唯一的 OPENCLAW_STATE_DIR
唯一的 agents.defaults.workspace
独立的 WhatsApp 号码(如果使用 WA)

每个配置文件的服务安装:

bash

openclaw --profile main gateway install
openclaw --profile rescue gateway install

示例:

bash

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

协议(操作员视角)

完整文档:网关协议和桥接协议(旧版)。
客户端必须发送的第一帧:req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }。
网关回复 res {type:"res", id, ok:true, payload:hello-ok }(或 ok:false 带错误,然后关闭)。
握手后:
- 请求:{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
- 事件:{type:"event", event, payload, seq?, stateVersion?}
结构化状态条目:{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }(对于 WS 客户端,instanceId 来自 connect.client.instanceId)。
agent 响应分两个阶段:首先 res 确认 {runId,status:"accepted"},然后在运行完成后发送最终的 res {runId,status:"ok"|"error",summary};流式输出以 event:"agent" 形式到达。

方法(初始集合)

health — 完整健康快照(与 openclaw health --json 形状相同)。
status — 简短摘要。
system-presence — 当前状态列表。
system-event — 发布状态/系统注释(结构化)。
send — 通过活动通道发送消息。
agent — 运行代理回合(在同一连接上流式返回事件)。
node.list — 列出已配对 + 当前连接的节点(包括 caps、deviceFamily、modelIdentifier、paired、connected 和广告的 commands)。
node.describe — 描述节点(能力 + 支持的 node.invoke 命令;适用于已配对节点和当前连接的未配对节点)。
node.invoke — 在节点上调用命令(例如 canvas.*、camera.*)。
node.pair.* — 配对生命周期(request、list、approve、reject、verify)。

另见:状态了解状态是如何产生/去重的,以及为什么稳定的 client.instanceId 很重要。

事件

agent — 来自代理运行的流式工具/输出事件(带序列标记)。
presence — 状态更新(带 stateVersion 的增量)推送给所有连接的客户端。
tick — 定期保活/空操作以确认活跃性。
shutdown — 网关正在退出;负载包括 reason 和可选的 restartExpectedMs。客户端应重新连接。

WebChat 集成

WebChat 是原生 SwiftUI UI,直接与网关 WebSocket 通信以获取历史记录、发送、中止和事件。
远程使用通过相同的 SSH/Tailscale 隧道;如果配置了网关令牌,客户端在 connect 期间包含它。
macOS 应用通过单个 WS(共享连接)连接;它从初始快照中填充状态并监听 presence 事件以更新 UI。

类型和验证

服务器使用 AJV 根据从协议定义生成的 JSON Schema 验证每个入站帧。
客户端(TS/Swift)使用生成的类型(TS 直接使用;Swift 通过仓库的生成器)。
协议定义是真理之源;使用以下命令重新生成 schema/模型:
- pnpm protocol:gen
- pnpm protocol:gen:swift

连接快照

hello-ok 包含带有 presence、health、stateVersion 和 uptimeMs 的 snapshot,加上 policy {maxPayload,maxBufferedBytes,tickIntervalMs},因此客户端无需额外请求即可立即渲染。
health/system-presence 仍可用于手动刷新,但在连接时不是必需的。

错误代码(res.error 形状)

错误使用 { code, message, details?, retryable?, retryAfterMs? }。
标准代码:
- NOT_LINKED — WhatsApp 未认证。
- AGENT_TIMEOUT — 代理在配置的截止时间内未响应。
- INVALID_REQUEST — schema/参数验证失败。
- UNAVAILABLE — 网关正在关闭或依赖项不可用。

保活行为

tick 事件(或 WS ping/pong)定期发送,以便客户端知道即使没有流量时网关也是活跃的。
发送/代理确认保持独立响应;不要将 tick 用于发送。

重放/间隙

事件不会重放。客户端检测到序列间隙后应在继续之前刷新(health + system-presence)。WebChat 和 macOS 客户端现在会在间隙时自动刷新。

监督(macOS 示例)

使用 launchd 保持服务运行:
- Program:openclaw 的路径
- Arguments:gateway
- KeepAlive:true
- StandardOut/Err:文件路径或 syslog
失败时,launchd 重启;致命的配置错误应持续退出以便操作员注意。
LaunchAgents 是按用户的,需要登录会话;对于无头设置,使用自定义 LaunchDaemon(未发布)。
- openclaw gateway install 写入 ~/Library/LaunchAgents/bot.molt.gateway.plist (或 bot.molt.<profile>.plist;旧版 com.openclaw.* 已清理)。
- openclaw doctor 审计 LaunchAgent 配置,可以将其更新为当前默认值。

网关服务管理(CLI)

使用网关 CLI 进行安装/启动/停止/重启/状态:

bash

openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

注意:

gateway status 默认使用服务的解析端口/配置探测网关 RPC(使用 --url 覆盖)。
gateway status --deep 添加系统级扫描(LaunchDaemons/系统单元)。
gateway status --no-probe 跳过 RPC 探测(网络故障时有用)。
gateway status --json 对脚本稳定。
gateway status 将 监督进程运行时(launchd/systemd 运行)与 RPC 可达性(WS 连接 + 状态 RPC)分开报告。
gateway status 打印配置路径 + 探测目标,以避免"localhost vs LAN 绑定"混淆和配置文件不匹配。
gateway status 在服务看起来正在运行但端口关闭时包含最后的网关错误行。
logs 通过 RPC 跟踪网关文件日志(无需手动 tail/grep)。
如果检测到其他类似网关的服务,除非它们是 OpenClaw 配置文件服务,否则 CLI 会警告。对于大多数设置,我们仍然建议每台机器一个网关;使用隔离的配置文件/端口实现冗余或救援机器人。参见多个网关。
- 清理:openclaw gateway uninstall(当前服务)和 openclaw doctor(旧版迁移)。
gateway install 在已安装时是空操作;使用 openclaw gateway install --force 重新安装(配置文件/环境/路径更改)。

捆绑的 mac 应用:

OpenClaw.app 可以捆绑基于 Node 的网关中继并安装带有标签的按用户 LaunchAgent bot.molt.gateway(或 bot.molt.<profile>;旧版 com.openclaw.* 标签仍可正常卸载)。
要正常停止它,使用 openclaw gateway stop(或 launchctl bootout gui/$UID/bot.molt.gateway)。
要重启,使用 openclaw gateway restart(或 launchctl kickstart -k gui/$UID/bot.molt.gateway)。
- launchctl 仅在已安装 LaunchAgent 时有效;否则先使用 openclaw gateway install。
- 运行命名配置文件时,将标签替换为 bot.molt.<profile>。

监督(systemd 用户单元)

OpenClaw 在 Linux/WSL2 上默认安装 systemd 用户服务。我们建议在单用户机器上使用用户服务(更简单的环境,按用户配置)。对于多用户或持续运行的服务器使用系统服务(无需 lingering,共享监督)。

openclaw gateway install 写入用户单元。openclaw doctor 审计单元并可以将其更新为匹配当前推荐的默认值。

创建 ~/.config/systemd/user/openclaw-gateway[-<profile>].service:

[Unit]
Description=OpenClaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
Environment=OPENCLAW_GATEWAY_TOKEN=
WorkingDirectory=/home/youruser

[Install]
WantedBy=default.target

启用 lingering(必需,以便用户服务在注销/空闲后存活):

sudo loginctl enable-linger youruser

入门流程在 Linux/WSL2 上运行此操作(可能提示输入 sudo;写入 /var/lib/systemd/linger)。然后启用服务:

systemctl --user enable --now openclaw-gateway[-<profile>].service

替代方案(系统服务) - 对于持续运行或多用户服务器,您可以安装 systemd 系统单元而不是用户单元(无需 lingering)。创建 /etc/systemd/system/openclaw-gateway[-<profile>].service(复制上面的单元, 切换 WantedBy=multi-user.target,设置 User= + WorkingDirectory=),然后:

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service

Windows (WSL2)

Windows 安装应使用 WSL2 并遵循上面的 Linux systemd 部分。

操作检查

活跃性:打开 WS 并发送 req:connect → 期望 res 带 payload.type="hello-ok"(带快照)。
就绪性:调用 health → 期望 ok: true 和 linkChannel 中的链接通道(如果适用)。
调试:订阅 tick 和 presence 事件;确保 status 显示链接/认证时间;状态条目显示网关主机和连接的客户端。

安全保证

默认假设每个主机一个网关;如果运行多个配置文件,隔离端口/状态并定位正确的实例。
不会回退到直接 Baileys 连接;如果网关宕机,发送快速失败。
非连接的第一帧或格式错误的 JSON 将被拒绝并关闭套接字。
优雅关闭:在关闭前发出 shutdown 事件;客户端必须处理关闭 + 重新连接。

CLI 辅助工具

openclaw gateway health|status — 通过网关 WS 请求健康/状态。
openclaw message send --target <num> --message "hi" [--media ...] — 通过网关发送(对 WhatsApp 是幂等的)。
openclaw agent --message "hi" --to <num> — 运行代理回合(默认等待最终结果)。
openclaw gateway call <method> --params '{"k":"v"}' — 用于调试的原始方法调用器。
openclaw gateway stop|restart — 停止/重启受监督的网关服务(launchd/systemd)。
网关辅助子命令假设在 --url 上有一个正在运行的网关;它们不再自动生成一个。

迁移指南

停用 openclaw gateway 和旧版 TCP 控制端口的使用。
更新客户端以使用带有强制连接和结构化状态的 WS 协议。

网关服务运维手册 ​

什么是网关 ​

本地运行方式 ​

远程访问 ​

多个网关(同一主机) ​

开发配置文件(--dev) ​

协议(操作员视角) ​

方法(初始集合) ​

事件 ​

WebChat 集成 ​

类型和验证 ​

连接快照 ​

错误代码(res.error 形状) ​

保活行为 ​

重放/间隙 ​

监督(macOS 示例) ​

网关服务管理(CLI) ​

监督(systemd 用户单元) ​

Windows (WSL2) ​

操作检查 ​

安全保证 ​

CLI 辅助工具 ​

迁移指南 ​

网关服务运维手册

什么是网关

本地运行方式

远程访问

多个网关(同一主机)

开发配置文件(`--dev`)

协议(操作员视角)

方法(初始集合)

事件

WebChat 集成

类型和验证

连接快照

错误代码(res.error 形状)

保活行为

重放/间隙

监督(macOS 示例)

网关服务管理(CLI)

监督(systemd 用户单元)

Windows (WSL2)

操作检查

安全保证

CLI 辅助工具

迁移指南