Gateway 网关运行手册

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

5 分钟本地启动

openclaw gateway --port 18789# 将调试/跟踪输出同步到标准 I/Oopenclaw gateway --port 18789 --verbose# 强制终止所选端口上的监听进程，然后启动openclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

运行时模型

• 一个始终运行的进程，负责路由、控制平面和渠道连接。
• 单个多路复用端口用于：
  • WebSocket 控制/RPC
  • HTTP API（/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke）
  • 插件 HTTP 路由，例如可选的 /api/v1/admin/rpc
  • Control UI 和 Hooks
• 默认绑定模式：loopback。在检测到的容器环境内，有效默认值为 auto（解析为 0.0.0.0 以支持端口转发）；但启用 Tailscale serve/funnel 时除外，此时始终强制使用 loopback。
• 默认要求身份验证。共享密钥设置使用 gateway.auth.token / gateway.auth.password（或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD），非 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 的其余部分使用相同的受信任操作员身份验证边界。

管理 HTTP RPC（POST /api/v1/admin/rpc）是一个独立且默认关闭的插件路由，适用于无法使用 WebSocket RPC 的主机工具。请参阅管理 HTTP RPC。

端口和绑定优先级

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

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

热重新加载模式

操作员命令集

openclaw gateway statusopenclaw gateway status --deep   # 添加系统级服务扫描openclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

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

多个 Gateway 网关（同一主机）

大多数安装应在每台机器上运行一个 Gateway 网关。一个 Gateway 网关可以承载多个智能体和渠道。只有在有意进行隔离或需要救援 Bot 时，才需要多个 Gateway 网关。

实用检查：

openclaw gateway status --deepopenclaw gateway probe

预期行为：

• 当仍存在过期的 launchd/systemd/schtasks 安装时，gateway status --deep 可能会报告 Other gateway-like services detected (best effort) 并输出清理提示。
• 当不同的 Gateway 网关响应，或 OpenClaw 无法证明可达目标属于同一 Gateway 网关时，gateway probe 可能会警告存在 multiple reachable gateway identities。指向同一 Gateway 网关的 SSH 隧道、代理 URL 或已配置的远程 URL，表示同一个 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 19001OPENCLAW_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@gateway-host

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

另请参阅：远程 Gateway 网关、身份验证、Tailscale。

监督和服务生命周期

使用受监督的运行方式，以获得接近生产环境的可靠性。

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

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

无效配置错误会以代码 78 退出。Linux systemd 单元使用 RestartPreventExitStatus=78，在配置修复前停止重新启动。launchd 和 Windows Task Scheduler 没有等效的按退出代码停止规则，因此 Gateway 网关还会持久记录短时间内的异常启动历史，并在启动反复失败后禁止自动启动渠道/提供商账号。在此安全模式下，控制平面仍会启动，以便检查和修复；配置热重新加载和 secrets.reload 会拒绝自动重新启动渠道，而操作员显式发出的 channels.start 请求可以覆盖此限制。

开发配置文件快速路径

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

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

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

• 客户端的第一帧必须是 connect。
• Gateway 网关返回一个包含 snapshot（presence、health、stateVersion、uptimeMs）以及 policy 限制（maxPayload、maxBufferedBytes、tickIntervalMs）的 hello-ok 帧。
• hello-ok.features.methods / events 是一个保守的发现列表，并非 自动生成的所有可调用辅助路由的完整清单。
• 请求：req(method, params) → res(ok/payload|error)。
• 常见事件包括 connect.challenge、agent、chat、 session.message、session.operation、session.tool、需选择启用的 session.approval、sessions.changed、presence、tick、health、 heartbeat、配对/审批生命周期事件以及 shutdown。

智能体运行分为两个阶段：

1. 立即返回已接受的确认（status:"accepted"）
2. 最终完成响应（status:"ok"|"error"），期间会流式传输 agent 事件。

完整协议文档请参阅：Gateway 网关协议。

运行检查

存活性

• 打开 WS 并发送 connect。
• 预期收到包含快照的 hello-ok 响应。

就绪性

openclaw gateway statusopenclaw channels status --probeopenclaw health

缺口恢复

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

常见故障特征

如需完整的诊断步骤，请参阅 Gateway 网关故障排查。

安全保证

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

相关内容

• 配置
• Gateway 网关故障排查
• 后台进程
• 健康状态
• Doctor
• 身份验证
• 远程访问
• 密钥管理