Gateway 运维手册

本页面用于 Gateway 服务的 Day-1 启动和 Day-2 日常运维。

5 分钟本地启动

第一步：启动 Gateway

openclaw gateway --port 18789
# 调试/追踪输出到标准输出
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 可达时会运行实时的每账号渠道探测和可选审计。Gateway 不可达时，CLI 降级为仅基于配置的渠道摘要输出。

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），非回环反向代理设置可使用 gateway.auth.mode: "trusted-proxy"

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 的稳定别名
• 需要覆盖后端提供商/模型时使用 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

gateway status --deep 用于额外的服务发现（LaunchDaemons/systemd 系统单元/schtasks），不是更深层的 RPC 健康探测。

远程访问

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

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

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

SSH 隧道不绕过 Gateway 认证。共享密钥认证模式下，客户端即使通过隧道也必须发送 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>

Windows（原生）：

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

原生 Windows 托管启动使用名为 OpenClaw Gateway（或命名 profile 的 OpenClaw Gateway (<profile>)）的计划任务。如果计划任务创建被拒绝，OpenClaw 降级为指向 state 目录中 gateway.cmd 的每用户启动文件夹启动器。

同一主机多个 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

Dev 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、session.message、session.tool、sessions.changed、presence、tick、health、heartbeat、配对/批准生命周期事件和 shutdown

Agent 运行分两阶段：

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

完整协议文档：Gateway 协议。

操作检查

存活检查：

• 打开 WebSocket 并发送 connect
• 期望收到 hello-ok 响应和快照

就绪检查：

openclaw gateway status
openclaw channels status --probe
openclaw health

间隙恢复：

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

常见故障特征

特征	可能原因
refusing to bind gateway ... without auth	非回环绑定但没有有效的 Gateway 认证路径
another gateway instance is already listening / EADDRINUSE	端口冲突
Gateway start blocked: set gateway.mode=local	配置设为远程模式，或本地模式标记在损坏的配置中丢失
unauthorized during connect	客户端与 Gateway 认证不匹配

完整诊断路径，使用 Gateway 故障排查。

安全保证

• Gateway 协议客户端在 Gateway 不可用时快速失败（无隐式直连渠道降级）
• 无效/非 connect 首帧被拒绝并关闭连接
• 优雅关闭在套接字关闭前发出 shutdown 事件

---

相关链接：

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