Gateway 运行手册

使用此页面进行 Gateway 服务的第一天启动和第二天运维。

基于症状的诊断，包含精确的命令阶梯和日志签名。 面向任务的设置指南 + 完整配置参考。 SecretRef 合约、运行时快照行为和迁移/重新加载操作。 精确的 `secrets apply` 目标/路径规则和仅引用认证配置文件行为。

5 分钟本地启动

openclaw gateway --port 18789
# debug/trace 镜像到 stdio
openclaw gateway --port 18789 --verbose
# 在选定端口上强制杀死监听器，然后启动
openclaw gateway --force
 
openclaw gateway status
openclaw status
openclaw logs --follow

健康基线：Runtime: running 和 RPC probe: ok。

 
openclaw channels status --probe
 Gateway 配置重载监视活动配置文件路径（从配置/状态默认值解析，或设置 `OPENCLAW_CONFIG_PATH` 时）。 默认模式是 `gateway.reload.mode="hybrid"`。

运行时模型

  • 一个始终运行的进程用于路由、控制平面和渠道连接。
  • 单一多路复用端口用于：
    • WebSocket 控制/RPC
    • HTTP API（OpenAI 兼容、Responses、工具调用）
    • 控制 UI 和 hooks
  • 默认绑定模式：loopback。
  • 默认需要认证（gateway.auth.token / gateway.auth.password，或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）。

端口和绑定优先级

设置解析顺序
Gateway 端口--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
绑定模式CLI/覆盖 → gateway.bind → loopback

热重载模式

gateway.reload.mode行为
off无配置重载
hot仅应用热安全更改
restart在需要重载的更改时重启
hybrid（默认）安全时热应用，需要时重启

Operator 命令集

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

远程访问

首选：Tailscale/VPN。 后备：SSH 隧道。

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

然后将客户端连接到本地的 ws://127.0.0.1:18789。

如果配置了 Gateway 认证，客户端仍然必须发送认证（`token`/`password`），即使通过 SSH 隧道。

请参阅：远程 Gateway、认证、Tailscale。

监督和服务生命周期

使用受监督的运行以获得类似生产的可靠性。

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

LaunchAgent 标签是 ai.openclaw.gateway（默认）或 ai.openclaw.<profile>（命名配置）。openclaw doctor 审计并修复服务配置漂移。

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

要在注销后持久化，启用 linger：

sudo loginctl enable-linger <user>

为多用户/始终在线主机使用系统单元。

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

一台主机上的多个 Gateway

大多数设置应该运行一个 Gateway。 仅在需要严格隔离/冗余时才使用多个（例如救援配置）。

每个实例的检查清单：

  • 唯一的 gateway.port
  • 唯一的 OPENCLAW_CONFIG_PATH
  • 唯一的 OPENCLAW_STATE_DIR
  • 唯一的 agents.defaults.workspace

示例：

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

请参阅：多个 Gateway。

Dev 配置快速路径

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

默认值包括隔离状态/配置和基础 Gateway 端口 19001。

协议快速参考（operator 视图）

  • 第一个客户端帧必须是 connect。
  • Gateway 返回 hello-ok 快照（presence、health、stateVersion、uptimeMs、限制/策略）。
  • 请求：req(method, params) → res(ok/payload|error)。
  • 常见事件：connect.challenge、agent、chat、presence、tick、health、heartbeat、shutdown。

代理运行是两阶段的：

  1. 即时接受确认（status:"accepted"）
  2. 最终完成响应（status:"ok"|"error"），中间有流式 agent 事件。

请参阅完整协议文档：Gateway 协议。

运维检查

存活

  • 打开 WS 并发送 connect。
  • 期望带快照的 hello-ok 响应。

就绪

openclaw gateway status
openclaw channels status --probe
openclaw health

间隙恢复

事件不会重放。在序列间隙上，继续前刷新状态（health、system-presence）。

常见故障签名

签名可能的问题
refusing to bind gateway ... without auth无令牌/密码的非回环绑定
another gateway instance is already listening / EADDRINUSE端口冲突
Gateway start blocked: set gateway.mode=local配置设为远程模式
unauthorized during connect客户端和 Gateway 之间的认证不匹配

有关完整诊断阶梯，请使用 Gateway 故障排除。

安全保证

  • 当 Gateway 不可用时，Gateway 协议客户端快速失败（无隐式直连渠道后备）。
  • 无效/非连接的第一帧被拒绝并关闭。
  • 正常关闭在套接字关闭前发出 shutdown 事件。

相关：