四、Gateway 网关运维

4.1 Gateway 运行手册

将此页面用于 Gateway 网关服务的首日启动和后续运维。

运行时模型

一个始终在线的进程，用于：

• 路由 — 消息路由到正确的智能体和会话
• 控制平面 — 配置管理、健康检查
• 渠道连接 — 所有聊天渠道的连接管理

单端口复用

一个复用的单端口处理：

• WebSocket 控制/RPC
• HTTP API、与 OpenAI 兼容
• Control UI 和 hooks

4.2 端口和绑定

设置解析顺序

绑定模式

⚠️ 非 loopback 绑定必须配置 Gateway 认证（token 或 password）。

4.3 与 OpenAI 兼容的端点

OpenClaw 提供与 OpenAI 兼容的 API 端点：

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

为什么这组接口很重要

• 大多数 Open WebUI、LobeChat 和 LibreChat 集成都会先探测 /v1/models
• 许多 RAG 和记忆管道都依赖 /v1/embeddings
• 原生面向智能体的客户端越来越倾向于使用 /v1/responses

智能体优先的模型列表

/v1/models 返回：

• openclaw
• openclaw/default — 稳定别名，始终映射到已配置的默认智能体
• openclaw/<agentId> — 按智能体 ID

覆盖模型

使用 x-openclaw-model 请求头覆盖后端提供商/模型。

4.4 热重载模式

配置重载

Gateway 配置重载会监听活动配置文件路径。首次成功加载后，运行中的进程会提供当前内存中的活动配置快照；成功重载后会以原子方式替换该快照。

4.5 操作员命令集

Gateway 管理

# 查看状态
openclaw gateway status
openclaw gateway status --deep    # 添加系统级服务扫描
openclaw gateway status --json    # JSON 格式输出
 
# 安装服务
openclaw gateway install
 
# 重启/停止
openclaw gateway restart
openclaw gateway stop
 
# 强制启动
openclaw gateway --force

配置管理

# 重新加载密钥
openclaw secrets reload
 
# 查看日志
openclaw logs --follow
 
# 运行诊断
openclaw doctor

4.6 监督与服务生命周期

macOS (launchd)

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

LaunchAgent 标签：ai.openclaw.gateway（默认）或 ai.openclaw.<profile>（命名 profile）

Linux (systemd 用户服务)

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status
 
# 注销后继续持久运行
sudo loginctl enable-linger <user>

Linux (系统服务)

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

Windows（原生）

• 计划任务名称：OpenClaw Gateway
• 如果计划任务创建被拒绝，回退到 Startup 文件夹

4.7 多个 Gateway 网关

大多数安装应当每台机器运行一个 Gateway 网关。单个 Gateway 可以托管多个智能体和渠道。

只有当你有意需要隔离或救援机器人时，才需要多个 Gateway 网关。

每个实例的检查清单

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

示例

# 实例 A
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
 
# 实例 B
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

4.8 远程访问

首选：Tailscale/VPN

{
  "gateway": {
    "bind": "loopback",
    "tailscale": { "mode": "serve" }
  }
}

备选：SSH 隧道

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

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

SSH 隧道不会绕过 Gateway 身份验证。客户端仍然必须发送 token/password。

4.9 运维检查

存活性

1. 打开 WS 连接
2. 发送 connect 帧
3. 预期收到带快照的 hello-ok 响应

就绪性

openclaw gateway status
openclaw channels status --probe
openclaw health

间隙恢复

事件不会重放。遇到序列缺口时，请先刷新状态（health、system-presence）再继续。

4.10 常见故障特征

诊断命令

openclaw doctor           # 自动诊断和修复
openclaw logs --follow    # 实时查看日志
openclaw gateway status --deep  # 深度状态检查