网关（Gateway）服务运行手册

最后更新：2025-12-09

它是什么

  • 始终运行的进程（always-on process），拥有单一的 Baileys/Telegram 连接以及控制/事件平面（control/event plane）。
  • 替代了旧版 gateway 命令。CLI 入口点：openclaw gateway。
  • 持续运行直到停止；发生致命错误时以非零状态退出，以便监督进程（supervisor）重启它。

如何运行（本地）

openclaw gateway --port 18789
# 在 stdio 中输出完整的 debug/trace 日志：
openclaw gateway --port 18789 --verbose
# 如果端口被占用，终止监听器后启动：
openclaw gateway --force
# 开发循环（TS 变更时自动重载）：
pnpm gateway:watch
  • 配置热重载（Config hot reload）监控 ~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH）。
    • 默认模式：gateway.reload.mode="hybrid"（热应用安全变更，关键变更时重启）。
    • 热重载在需要时通过 SIGUSR1 使用进程内重启（in-process restart）。
    • 通过 gateway.reload.mode="off" 禁用。
  • 将 WebSocket 控制平面（control plane）绑定到 127.0.0.1:<port>（默认 18789）。
  • 同一端口也提供 HTTP 服务（控制 UI、hooks、A2UI）。单端口复用（Single-port multiplex）。
  • 默认在 canvasHost.port（默认 18793）上启动 Canvas 文件服务器（file server），从 ~/.openclaw/workspace/canvas 提供 http://<gateway-host>:18793/__openclaw__/canvas/ 服务。通过 canvasHost.enabled=false 或 OPENCLAW_SKIP_CANVAS_HOST=1 禁用。
  • 日志输出到 stdout；使用 launchd/systemd 保持其存活并轮换日志。
  • 传递 --verbose 可在故障排查时将调试日志（handshakes、req/res、events）从日志文件镜像到 stdio。
  • --force 使用 lsof 查找选定端口上的监听器，发送 SIGTERM，记录被终止的进程，然后启动网关（如果 lsof 缺失则快速失败）。
  • 如果在监督进程（supervisor）下运行（launchd/systemd/mac app 子进程模式），停止/重启通常发送 SIGTERM；旧版本可能将此显示为 pnpm ELIFECYCLE 退出代码 143（SIGTERM），这是正常关闭，不是崩溃。
  • SIGUSR1 在授权时触发进程内重启（gateway tool/config apply/update，或启用 commands.restart 以手动重启）。
  • 默认需要网关认证（Gateway auth）：设置 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）或 gateway.auth.password。客户端必须发送 connect.params.auth.token/password，除非使用 Tailscale Serve 身份。
  • 向导（wizard）现在默认生成令牌（token），即使在 loopback 上也是如此。
  • 端口优先级：--port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789。

远程访问（Remote access）

  • 首选 Tailscale/VPN；否则使用 SSH 隧道（tunnel）： 
    ssh -N -L 18789:127.0.0.1:18789 user@host
  • 客户端随后通过隧道连接到 ws://127.0.0.1:18789。
  • 如果配置了令牌，即使通过隧道，客户端也必须在 connect.params.auth.token 中包含它。

多网关（same host）

通常不必要：一个网关（Gateway）可以服务多个消息通道（messaging channels）和代理（agents）。仅在需要冗余或严格隔离（如：rescue bot）时使用多个网关。

如果隔离状态 + 配置并使用唯一端口，则支持。完整指南：Multiple gateways。

服务名称（Service names）支持配置文件（profile-aware）：

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

安装元数据（Install metadata）嵌入在服务配置中：

  • OPENCLAW_SERVICE_MARKER=openclaw
  • OPENCLAW_SERVICE_KIND=gateway
  • OPENCLAW_SERVICE_VERSION=<version>

Rescue-Bot 模式（Rescue-Bot Pattern）：保持第二个网关（Gateway）隔离，使用自己的 profile、state dir、workspace 和基础端口间距（base port spacing）。完整指南：Rescue-bot guide。

开发配置文件（Dev profile）（--dev）

快速路径：运行完全隔离的开发实例（config/state/workspace），不触及您的主要设置。

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

默认值（可通过 env/flags/config 覆盖）：

  • OPENCLAW_STATE_DIR=~/.openclaw-dev
  • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
  • OPENCLAW_GATEWAY_PORT=19001（Gateway WS + HTTP）
  • 浏览器控制服务端口 = 19003（派生：gateway.port+2，仅 loopback）
  • canvasHost.port=19005（派生：gateway.port+4）
  • 当您在 --dev 下运行 setup/onboard 时，agents.defaults.workspace 默认变为 ~/.openclaw/workspace-dev。

派生端口（Derived ports）（经验法则）：

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

每个实例的检查清单（Checklist）：

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

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

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

示例：

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

协议（Protocol）（操作员视角）

  • 完整文档：Gateway protocol 和 Bridge protocol (legacy)。
  • 客户端强制性的第一帧：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 带错误，然后关闭）。
  • 握手之后：
    • 请求（Requests）：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • 事件（Events）：{type:"event", event, payload, seq?, stateVersion?}
  • 结构化在线条目（Structured presence entries）：{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}；流式输出（streamed output）作为 event:"agent" 到达。

方法（Methods）（初始集合）

  • health — 完整健康快照（与 openclaw health --json 形状相同）。
  • status — 简短摘要。
  • system-presence — 当前在线列表。
  • system-event — 发布在线/系统备注（结构化）。
  • send — 通过活动通道发送消息。
  • agent — 运行代理轮次（streams events back on same connection）。
  • node.list — 列出已配对 + 当前连接的节点（包括 caps、deviceFamily、modelIdentifier、paired、connected 和广告的 commands）。
  • node.describe — 描述节点（capabilities + supported node.invoke commands；适用于已配对节点和当前连接的未配对节点）。
  • node.invoke — 在节点上调用命令（例如 canvas.*、camera.*）。
  • node.pair.* — 配对生命周期（request、list、approve、reject、verify）。

另见：Presence 了解在线如何生成/去重以及为什么稳定的 client.instanceId 很重要。

事件（Events）

  • agent — 从代理运行流式传输的工具/输出事件（带 seq 标签）。
  • presence — 在线更新（带 stateVersion 的增量）推送到所有连接的客户端。
  • tick — 周期性 keepalive/no-op 以确认存活性。
  • shutdown — 网关正在退出；有效负载（payload）包括 reason 和可选的 restartExpectedMs。客户端应重新连接。

WebChat 集成

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

类型和验证（Typing and validation）

  • 服务器使用 AJV 根据从协议定义发出的 JSON Schema 验证每个入站帧。
  • 客户端（TS/Swift）使用生成的类型（TS 直接；Swift 通过仓库的生成器）。
  • 协议定义是真相来源（source of truth）；使用以下命令重新生成 schema/models：
    • pnpm protocol:gen
    • pnpm protocol:gen:swift

连接快照（Connection snapshot）

  • hello-ok 包括一个带有 presence、health、stateVersion 和 uptimeMs 的 snapshot，以及 policy {maxPayload,maxBufferedBytes,tickIntervalMs}，以便客户端可以立即渲染而无需额外请求。
  • health/system-presence 仍可用于手动刷新，但在连接时不需要。

错误代码（Error codes）（res.error shape）

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

Keepalive 行为

  • 定期发出 tick 事件（或 WS ping/pong），以便客户端知道网关处于活动状态，即使没有流量发生。
  • 发送/代理确认保持为单独的响应；不要为发送重载 ticks。

重放 / 间隙（Replay / gaps）

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

监督（Supervision）（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 配置，并可将其更新为当前默认值。

网关服务管理（Gateway service management）（CLI）

使用网关 CLI 进行 install/start/stop/restart/status：

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

注意事项：

  • gateway status 默认使用服务解析的端口/配置探测网关 RPC（使用 --url 覆盖）。
  • gateway status --deep 添加系统级扫描（LaunchDaemons/system units）。
  • gateway status --no-probe 跳过 RPC 探测（当网络关闭时有用）。
  • gateway status --json 对脚本稳定。
  • gateway status 将 supervisor runtime（launchd/systemd 运行）与 RPC reachability（WS connect + status RPC）分开报告。
  • gateway status 打印配置路径 + 探测目标，以避免"localhost vs LAN bind"混淆和配置文件不匹配。
  • gateway status 在服务看起来运行但端口关闭时包括最后一个网关错误行。
  • logs 通过 RPC 尾随网关文件日志（无需手动 tail/grep）。
  • 如果检测到其他类网关服务，CLI 会发出警告，除非它们是 OpenClaw 配置文件服务。 我们仍然建议大多数设置每台机器一个网关；使用隔离的配置文件/端口进行冗余或 rescue bot。参见 Multiple gateways。
    • 清理：openclaw gateway uninstall（当前服务）和 openclaw doctor（旧版迁移）。
  • gateway install 在已安装时是 no-op；使用 openclaw gateway install --force 重新安装（配置文件/env/路径更改）。

捆绑的 mac 应用：

  • OpenClaw.app 可以捆绑基于 Node 的网关中继（gateway relay），并安装标记为 bot.molt.gateway（或 bot.molt.<profile>；旧版 com.openclaw.* 标签仍可干净卸载）的每用户 LaunchAgent。
  • 要干净地停止它，请使用 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>。

监督（Supervision）（systemd user unit）

OpenClaw 默认在 Linux/WSL2 上安装 systemd 用户服务（user service）。我们 建议对单用户机器使用用户服务（更简单的 env，每用户配置）。 对于多用户或始终在线的服务器使用 system service（无需持久化 （lingering），共享监督）。

openclaw gateway install 写入用户单元（user unit）。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

入职（Onboarding）在 Linux/WSL2 上运行此命令（可能提示 sudo；写入 /var/lib/systemd/linger）。 然后启用服务：

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

替代方案（system service） - 对于始终在线或多用户服务器，您可以 安装 systemd system 单元而不是用户单元（无需持久化）。 创建 /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 部分。

操作检查（Operational checks）

  • 存活性（Liveness）：打开 WS 并发送 req:connect → 期望 res 带有 payload.type="hello-ok"（带快照）。
  • 就绪性（Readiness）：调用 health → 期望 ok: true 和 linkChannel 中的链接通道（如果适用）。
  • 调试（Debug）：订阅 tick 和 presence 事件；确保 status 显示 linked/auth age；在线条目显示网关主机和连接的客户端。

安全保证（Safety guarantees）

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

CLI 辅助工具（CLI helpers）

  • openclaw gateway health|status — 通过网关 WS 请求 health/status。
  • openclaw message send --target <num> --message "hi" [--media ...] — 通过网关发送（对 WhatsApp 幂等）。
  • openclaw agent --message "hi" --to <num> — 运行代理轮次（默认等待 final）。
  • openclaw gateway call <method> --params '{"k":"v"}' — 用于调试的原始方法调用器。
  • openclaw gateway stop|restart — 停止/重启受监督的网关服务（launchd/systemd）。
  • 网关辅助子命令假定在 --url 上有运行的网关；它们不再自动生成一个。

迁移指南（Migration guidance）

  • 停用 openclaw gateway 和旧版 TCP 控制端口的使用。
  • 更新客户端以使用强制性连接和结构化在线的 WS 协议通信。
← 返回文档首页