Gateway 运维手册

无论是第一天启动还是日常运维，都从这页开始。

  • 深度故障排除 — 以症状为切入点的诊断，附带精确的命令步骤和日志特征。
  • 配置 — 面向任务的配置指南 + 完整配置参考。
  • 密钥管理 — SecretRef 契约、运行时快照行为以及迁移/重载操作。
  • Secrets plan 契约 — secrets apply 的精确 target/path 规则与仅引用的认证配置行为。

5 分钟本地启动

第 1 步：启动 Gateway

openclaw gateway --port 18789
# 调试/追踪信息镜像到标准输出
openclaw gateway --port 18789 --verbose
# 强制关闭选定端口上的监听器，然后启动
openclaw gateway --force

第 2 步：验证服务健康

openclaw gateway status
openclaw status
openclaw logs --follow

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

第 3 步：验证频道就绪

openclaw channels status --probe

说明： Gateway 配置重载监听的是活跃配置文件路径（从 profile/state 默认值解析，或在设置了 OPENCLAW_CONFIG_PATH 时使用该值）。 默认模式为 gateway.reload.mode="hybrid"。

运行模型

  • 一个常驻进程负责路由、控制面和频道连接。
  • 单个复用端口用于：
    • WebSocket 控制/RPC
    • HTTP API（OpenAI 兼容、Responses、工具调用）
    • Control 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 认证，客户端即使通过 SSH 隧道也必须发送认证信息（token/password）。

参见：远程 Gateway、身份验证、Tailscale。

服务监管与生命周期

生产环境建议使用受监管的方式运行。

macOS（launchd）

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

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

Linux（systemd 用户服务）

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

要在登出后保持运行，启用 lingering：

sudo loginctl enable-linger <user>

Linux（系统级服务）

多用户/常驻主机使用系统级 unit。

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。

开发配置快速路径

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。

Agent 运行分两阶段：

  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非回环绑定但没有 token/password
another gateway instance is already listening / EADDRINUSE端口冲突
Gateway start blocked: set gateway.mode=local配置设为远程模式
unauthorized during connect客户端和 Gateway 之间的认证不匹配

完整诊断步骤见 Gateway 故障排除。

安全保证

  • Gateway 协议客户端在 Gateway 不可用时快速失败（不会隐式回退到直连频道）。
  • 无效/非 connect 的首帧会被拒绝并关闭连接。
  • 优雅关闭时在关闭 socket 前发送 shutdown 事件。

相关文档：

arrow_back
上一页
Peekaboo
下一页
Configuration
arrow_forward