Gateway 运维手册

本页面涵盖 Gateway 服务的第一天启动和日常运维操作。

5 分钟本地快速启动

第一步：启动 Gateway

openclaw gateway --port 18789
# 调试/追踪输出到 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 配置热重载监视活动配置文件路径（从 profile/state 默认值解析，或通过 OPENCLAW_CONFIG_PATH 指定）。默认模式为 gateway.reload.mode="hybrid"。

运行时模型

• 一个常驻进程，负责路由、控制面和渠道连接。
• 单复用端口，同时提供：
  • WebSocket 控制/RPC
  • HTTP API、OpenAI 兼容接口（/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke）
  • 控制 UI 和 Hooks
• 默认绑定模式：loopback。
• 默认需要认证（gateway.auth.token / gateway.auth.password，或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）。

OpenAI 兼容接口

OpenClaw 的最高价值兼容面是：

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

这套接口的重要性：

• 大多数 Open WebUI、LobeChat、LibreChat 集成首先探测 /v1/models。
• 许多 RAG 和记忆管道需要 /v1/embeddings。
• 更多 Agent 原生客户端越来越倾向于使用 /v1/responses。

规划要点：

• /v1/models 以 Agent 为主：返回 openclaw、openclaw/default 和 openclaw/<agentId>。
• openclaw/default 是稳定别名，始终映射到配置的默认 Agent。
• 需要覆盖后端 provider/model 时使用 x-openclaw-model；否则由选定 Agent 的正常模型和嵌入配置控制。

以上接口均在 Gateway 主端口上运行，与 Gateway HTTP API 其余部分使用相同的可信操作员认证边界。

端口与绑定优先级

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

热重载模式

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

运维命令集

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>（命名 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。 仅在需要严格隔离/冗余时（如救援 profile）才运行多实例。

每个实例的清单：

• 唯一的 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。

开发 profile 快速路径

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

默认包含隔离的 state/config，基础 Gateway 端口为 19001。

协议快速参考（运维视角）

• 第一个客户端帧必须是 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	非 loopback 绑定但未配置 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 事件。

---

相关链接：

• 故障排查
• 后台进程
• 配置
• 健康检查
• Doctor
• 认证