Gateway 服务运行手册

最后更新：2025-12-09 · 翻译自 docs.openclaw.ai

它是什么

• 一个始终运行的进程，拥有单一的 Baileys/Telegram 连接以及控制/事件平面。
• 取代了旧版的 gateway 命令。CLI 入口点：openclaw gateway。
• 持续运行直到停止；在致命错误时以非零退出码退出，以便监督器重启它。

如何运行（本地）

openclaw gateway --port 18789
# 完整的调试/跟踪日志输出到标准输出：
openclaw gateway --port 18789 --verbose
# 如果端口被占用，终止占用者然后启动：
openclaw gateway --force
# 开发循环（TS 更改时自动重载）：
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）。单端口多路复用。
• 日志输出到标准输出；使用 launchd/systemd 保持运行并轮转日志。
• 传递 --verbose 以在排故时将调试日志（握手、请求/响应、事件）从日志文件镜像到标准输出。
• --force 使用 lsof 查找所选端口上的监听器，发送 SIGTERM，记录它杀死了什么，然后启动 Gateway。
• Gateway 认证默认启用：设置 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）或 gateway.auth.password。客户端必须发送 connect.params.auth.token/password。
• 向导（wizard）现在默认生成一个 Token，即使在环回地址上也是如此。
• 端口优先级：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789。

远程访问

• 首选 Tailscale/VPN；否则使用 SSH 隧道：

ssh -N -L 18789:127.0.0.1:18789 user@host

• 客户端然后通过隧道连接到 ws://127.0.0.1:18789。
• 如果配置了 Token，客户端即使通过隧道也必须在 connect.params.auth.token 中包含它。

多个 Gateway（同一主机）

通常不需要：一个 Gateway 可以服务多个消息通道和 Agent。仅在需要冗余或严格隔离时才使用多个 Gateway（例如：救援机器人）。

如果你隔离状态 + 配置并使用唯一端口，则支持多实例。

开发配置文件 (--dev)

快速路径：运行一个完全隔离的开发实例（配置/状态/工作区），而不影响你的主要设置。

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# 然后定位到开发实例：
openclaw --dev status
openclaw --dev health

协议（操作员视角）

完整文档：Gateway 协议。

客户端发送的强制性第一帧：

req {type:"req", id, method:"connect", params:{
  minProtocol, maxProtocol,
  client:{id, displayName?, version, platform, deviceFamily?,
          modelIdentifier?, mode, instanceId?},
  caps, auth?, locale?, userAgent?
}}

Gateway 回复：

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?}

方法（初始集合）

• health — 完整的健康快照。
• status — 简短摘要。
• system-presence — 当前在线状态列表。
• system-event — 发布在线状态/系统通知（结构化）。
• send — 通过活动通道发送消息。
• agent — 运行一个 Agent 回合（在同一连接上流式传输事件）。
• node.list — 列出已配对 + 当前连接的节点。
• node.describe — 描述一个节点（能力 + 支持的命令）。
• node.invoke — 在节点上调用命令（例如 canvas.*、camera.*）。
• node.pair.* — 配对生命周期（请求、列出、批准、拒绝、验证）。

事件

• agent — 来自 Agent 运行的流式工具/输出事件（带 seq 标签）。
• presence — 在线状态更新（带 stateVersion 的增量）推送到所有连接的客户端。
• tick — 定期保活/空操作，确认存活。
• shutdown — Gateway 正在退出；负载包含原因和可选的 restartExpectedMs。客户端应重新连接。

错误代码（res.error 结构）

错误使用 { code, message, details?, retryable?, retryAfterMs? } 结构。

标准代码：

• NOT_LINKED — WhatsApp 未认证。
• AGENT_TIMEOUT — Agent 未在配置的截止时间内响应。
• INVALID_REQUEST — 模式/参数验证失败。
• UNAVAILABLE — Gateway 正在关闭或依赖项不可用。

保活行为

• tick 事件（或 WS ping/pong）定期发出，以便客户端在没有流量时知道 Gateway 仍然活着。
• 发送/Agent 确认仍然是单独的响应；不要将 tick 用于发送。

重放 / 间隙

• 事件不会重放。客户端检测 seq 间隙，应在继续之前刷新（health + system-presence）。

Gateway 服务管理（CLI）

使用 Gateway CLI 进行安装/启动/停止/重启/状态查询：

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

注意事项：

• gateway status 默认使用服务解析的端口/配置探测 Gateway RPC。
• gateway status --deep 添加系统级扫描。
• gateway status --no-probe 跳过 RPC 探测（网络中断时有用）。
• gateway status --json 对脚本稳定。
• logs 通过 RPC 跟踪 Gateway 文件日志（无需手动 tail/grep）。

监督（systemd 用户单元）

OpenClaw 在 Linux/WSL2 上默认安装一个 systemd 用户服务。我们推荐单用户机器使用用户服务（更简单的环境，每用户配置）。对于多用户或始终在线的服务器，使用系统服务。

[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=<token>
WorkingDirectory=/home/youruser

[Install]
WantedBy=default.target

启用持久化（必需，以便用户服务在注销/空闲后仍然存活）：

sudo loginctl enable-linger youruser

操作检查

• 存活检查：打开 WS 并发送 req:connect → 期望收到带有 payload.type="hello-ok"（含快照）的 res。
• 就绪检查：调用 health → 期望 ok: true 并且 linkChannel 中有已链接的通道。
• 调试：订阅 tick 和 presence 事件。

安全保证

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

CLI 辅助工具

• openclaw gateway health|status — 通过 Gateway WS 请求健康/状态。
• openclaw message send --target <id> --message "hi" — 通过 Gateway 发送（对 WhatsApp 幂等）。
• openclaw agent --message "hi" --to <id> — 运行一个 Agent 回合。
• openclaw gateway call <method> --params '{}' — 原始方法调用器，用于调试。
• openclaw gateway stop|restart — 停止/重启受监督的 Gateway 服务。