Gateway 网关运行手册

使用此页面进行 Gateway 网关服务的第 1 天启动和第 2 天运维。

# 5 分钟本地启动

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

# 运行时模型

• 一个始终在线的进程，用于路由、控制平面和渠道连接。
• 单个多路复用端口用于：
  • WebSocket 控制/RPC
  • HTTP API，兼容 OpenAI（/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke）
  • 控制 UI 和钩子
• 默认绑定模式：loopback。
• 默认需要认证。共享密钥设置使用 gateway.auth.token / gateway.auth.password（或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD），非 local loopback 反向代理设置可以使用 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。
• 智能体原生客户端越来越倾向于使用 /v1/responses。

规划说明：

• /v1/models 以智能体为先：它返回 openclaw、openclaw/default 和 openclaw/<agentId>。
• openclaw/default 是稳定别名，始终映射到已配置的默认智能体。
• 当你想覆盖后端提供商/模型时，使用 x-openclaw-model；否则所选智能体的常规模型和嵌入设置保持控制权。

所有这些都运行在主 Gateway 网关端口上，并使用与其余 Gateway 网关 HTTP API 相同的可信操作员认证边界。

# 端口和绑定优先级

已安装的 Gateway 网关服务会在 supervisor 元数据中记录解析后的 --port。更改 gateway.port 后，运行 openclaw doctor --fix 或 openclaw gateway install --force，以便 launchd/systemd/schtasks 在新端口上启动进程。

Gateway 网关启动会在为非 local loopback 绑定播种本地 控制 UI 来源时使用相同的有效端口和绑定。例如，--bind lan --port 3000 会在运行时验证运行前播种 http://localhost:3000 和 http://127.0.0.1:3000。 将任何远程浏览器来源（例如 HTTPS 代理 URL）显式添加到 gateway.controlUi.allowedOrigins。

# 热重载模式

# 操作员命令集

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
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 健康探测。

# 多个 Gateway 网关（同一主机）

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

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

有用的检查：

openclaw gateway status --deep
openclaw gateway probe

预期结果：

• gateway status --deep 可以报告 Other gateway-like services detected (best effort)， 并在陈旧的 launchd/systemd/schtasks 安装仍然存在时打印清理提示。
• 当多个目标响应时，gateway probe 可以警告 multiple reachable gateways。
• 如果这是有意为之，请按 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/multiple-gateways。

# 远程访问

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

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

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

参见：远程 Gateway 网关、认证、Tailscale。

# 监督和服务生命周期

对类似生产环境的可靠性使用受监督运行。

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

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

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

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

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

# 开发配置文件快速路径

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

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

# 协议快速参考（操作员视角）

• 第一个客户端帧必须是 connect。
• Gateway 网关返回 hello-ok 快照（presence、health、stateVersion、uptimeMs、限制/策略）。
• hello-ok.features.methods / events 是保守的发现列表，不是 每个可调用辅助路由的生成式转储。
• 请求：req(method, params) → res(ok/payload|error)。
• 常见事件包括 connect.challenge、agent、chat、 session.message、session.tool、sessions.changed、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），再继续。

# 常见失败特征

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

# 安全保证

• 当 Gateway 网关不可用时，Gateway 网关协议客户端会快速失败（不会隐式回退到直接渠道）。
• 无效或非 connect 的首帧会被拒绝并关闭。
• 优雅关闭会在套接字关闭前发出 shutdown 事件。

相关内容：

• 故障排除
• 后台进程
• 配置
• 健康状态
• Doctor
• 身份验证

# 相关内容

• 配置
• Gateway 网关故障排除
• 远程访问
• 密钥管理