OpenClaw Gateway 运维手册：从 5 分钟本地启动到生产级服务生命周期管理-酒店常州论坛

OpenClaw Gateway 运维手册：从 5 分钟本地启动到生产级服务生命周期管理

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

OpenClaw 的 Gateway 是一个常驻运行的单进程服务，承担路由、控制平面与渠道连接的职责，是连接 Agent、渠道与控制界面的核心枢纽。本文以官方 Gateway Runbook 为主体，结合仓库内src/gateway/与src/cli/的源码实现，系统讲解 Gateway 的启动、健康验证、OpenAI 兼容端点、配置热重载、多网关隔离、远程访问以及 macOS/Windows/Linux 三平台的监督式生命周期管理，帮助你完成从 Day-1 启动到 Day-2 运维的完整闭环。

5 分钟本地启动

启动 Gateway

本地启动 Gateway 只需一条命令。默认端口为18789，可通过--port显式指定：

openclaw gateway --port 18789 # debug/trace 镜像到 stdio openclaw gateway --port 18789 --verbose # 强制杀掉所选端口上的监听进程，然后再启动 openclaw gateway --force

--verbose会把 debug/trace 级别的日志镜像输出到标准输出，适合排查启动期问题。
--force会先强制结束目标端口上已存在的监听者再启动，用于端口被残留进程占用时的快速恢复。

验证服务健康

启动后立即验证 Gateway 是否真正就绪：

openclaw gateway status openclaw status openclaw logs --follow

健康基线是三条信息：Runtime: running（运行时正在运行）、Connectivity probe: ok（连通性探测通过）、以及一条与你预期一致的Capability行（能力声明）。若需要更强的证据而非仅仅可达性，使用：

openclaw gateway status --require-rpc

--require-rpc要求完成只读作用域的 RPC 往返验证，而不是仅凭端口可达就判定健康。

验证渠道就绪

openclaw channels status --probe

当 Gateway 可达时，该命令会对每个渠道账户执行真实的在线探测与可选的审计；如果 Gateway 不可达，CLI 会自动降级为仅基于配置的渠道摘要输出。

注意：Gateway 配置热重载会持续监听活动配置文件路径（由 profile/state 默认值解析得出，或在使用OPENCLAW_CONFIG_PATH时取该变量值）。默认重载模式为gateway.reload.mode="hybrid"。首次成功加载后，运行中的进程对外提供的是内存中的活动配置快照；一次成功的重载会原子地替换该快照。

运行时模型

从 src/gateway/ 的源码结构可以看到，Gateway 的设计遵循以下模型：

单一常驻进程：同时承担路由、控制平面与所有渠道连接，无需为每个渠道单独拉起进程。
单一多路复用端口承载以下全部流量：
- 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 杠杆率最高的兼容面，全部运行在主 Gateway 端口上，并与其他 Gateway HTTP API 共用同一套受信操作者认证边界：

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-first的：它会为每个已配置的 agent 返回openclaw、openclaw/default与openclaw/<agentId>。其中openclaw/default是稳定别名，始终映射到配置的默认 agent。当你需要覆盖后端 provider/model 时，发送x-openclaw-model请求头；否则由所选 agent 自身的模型与 embedding 配置主导。

需要说明的是，Admin HTTP RPC（POST /api/v1/admin/rpc）是独立且默认关闭的插件路由，专供无法使用 WebSocket RPC 的主机工具使用，详见 Admin HTTP RPC。

端口与绑定优先级

设置项	解析顺序
Gateway 端口	`--port`→`OPENCLAW_GATEWAY_PORT`→`gateway.port`→`18789`
绑定模式	CLI/覆盖值 →`gateway.bind`→`loopback`（容器内为`auto`）

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

Gateway 启动时会使用同一套有效端口与绑定值来预置本地 Control UI 源。例如--bind lan --port 3000会在运行时校验前预置http://localhost:3000与http://127.0.0.1:3000。任何远程浏览器源（如 HTTPS 代理 URL）都需要显式加入gateway.controlUi.allowedOrigins。

热重载模式

`gateway.reload.mode`	行为
`off`	不进行配置重载
`hybrid`（默认）	安全时热应用，必要时重启

早期的hot与restart模式已在v2026.7.2-beta.4退役，自v2026.8.1起稳定。openclaw doctor --fix（见 Doctor）会把两者统一映射到hybrid。从 config-reload-plan.ts 与 config-reload.ts 的命名可以看出，重载规划与执行被拆分为独立模块：能安全热应用的变更（如渠道配置、部分运行时参数）直接原子替换内存快照，需要进程级变更的则走受控重启路径。

操作命令集

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 健康探测。

多 Gateway（同一主机）

大多数安装场景应在每台机器上运行一个Gateway：单个 Gateway 即可承载多个 agent 与多个渠道。只有在刻意需要隔离或需要"救援机器人"时才需要多个 Gateway。

实用检查命令：

openclaw gateway status --deep openclaw gateway probe

预期现象：

gateway status --deep可能报告Other gateway-like gateway services detected (best effort)（尽力检测到其他类似 Gateway 的服务），并在存在陈旧 launchd/systemd/schtasks 安装时打印清理提示。
gateway probe在检测到不同 Gateway 应答、或无法证明可达目标为同一 Gateway 时，会警告multiple reachable gateway identities（多个可达的 Gateway 身份）。注意：通过 SSH 隧道、代理 URL 或配置的远程 URL 访问同一个Gateway，属于单 Gateway 的多个传输通道，即使传输端口不同也算一个 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 19001 OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

详细配置见 multiple-gateways。

远程访问

首选方案：Tailscale/VPN；兜底方案：SSH 隧道。

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

随后在本地以ws://127.0.0.1:18789连接客户端即可。

⚠️ SSH 隧道不绕过Gateway 认证。共享密钥模式下，即使通过隧道，客户端仍必须发送token/password；身份承载模式下，请求仍需满足对应的认证路径。

相关主题：Remote Gateway、Authentication、Tailscale。

监督与服务生命周期

原生服务控制命令只接收操作系统层面的环境（可执行文件查找、账户身份、locale 与服务管理器路由所需），不会继承应用凭据或任意 shell 变量。Gateway 有效负载与其安装的服务定义保留各自单独配置的环境。生产级可靠性请使用监督式运行。

macOS（launchd）

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

重启请使用openclaw gateway restart，不要用stop+start串联代替重启。
macOS 上gateway stop默认使用launchctl bootout：它会把 LaunchAgent 从当前启动会话移除，但不持久化禁用，因此意外崩溃后 KeepAlive 自动恢复仍然有效，gateway start也能干净地重新启用。若要跨重启持久抑制自动重生，使用openclaw gateway stop --disable。
LaunchAgent 标签为ai.openclaw.gateway（默认）或ai.openclaw.<profile>（命名 profile）。openclaw doctor会审计并修复服务配置漂移。

已有的系统级 LaunchDaemons

OpenClaw 只安装并管理每用户LaunchAgent，不安装也不管理系统级 LaunchDaemons。如果自定义 LaunchDaemon 已占用相同 Gateway 标签，OpenClaw 会拒绝写入、启动、重启或修复用户 LaunchAgent——因为两个KeepAlive管理器可能反复重启同一个 Gateway。

所有权检查会读取launchctl print system/<label>，同时检查/Library/LaunchDaemons下已安装的 plist。当系统所有权无法验证时采取 fail-closed，且--force不能绕过。openclaw gateway status会报告已加载的同标签系统任务；加--deep可扫描已安装的系统服务文件。

重试前先选定唯一生命周期所有者：

保留自定义系统 LaunchDaemon：移除竞争的用户 LaunchAgent，并在运行 Doctor 时设置OPENCLAW_SERVICE_REPAIR_POLICY=external，使其对服务生命周期保持纯诊断。
回归受支持的用户 LaunchAgent：用sudo launchctl bootout system/<label>卸载系统任务，移除或迁移其 plist，以目标用户登录 macOS 桌面后运行openclaw gateway install。

默认 profile 的<label>为ai.openclaw.gateway，命名 profile 使用ai.openclaw.<profile>。

Linux（systemd user）

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

登出后要保持持久运行，启用 lingering：

sudo loginctl enable-linger $(whoami)

无桌面会话的无头服务器上，重试systemctl --user前需确保设置了XDG_RUNTIME_DIR（export XDG_RUNTIME_DIR=/run/user/$(id -u)）。

需要自定义安装路径时的手写 user unit 示例：

[Unit] Description=OpenClaw Gateway After=network-online.target Wants=network-online.target StartLimitBurst=5 StartLimitIntervalSec=60 [Service] ExecStart=/usr/local/bin/openclaw gateway --port 18789 Restart=always RestartSec=5 RestartPreventExitStatus=78 TimeoutStopSec=330 TimeoutStartSec=30 SuccessExitStatus=0 143 OOMPolicy=continue KillMode=mixed [Install] WantedBy=default.target

TimeoutStopSec=330覆盖 Gateway 的五分钟协作式排空（drain）加上拆除缓冲。查看当前托管 unit 内容：systemctl --user cat openclaw-gateway.service（命名 profile 为systemctl --user cat openclaw-gateway-<profile>.service）。这与 active-sessions-shutdown-drain.ts 所体现的"优雅关闭前排空活动会话"设计相呼应。

Windows（原生）

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

Windows 原生托管启动使用名为OpenClaw Gateway的计划任务（命名 profile 为OpenClaw Gateway (<profile>)）。若计划任务创建被拒绝，OpenClaw 回退到指向状态目录内gateway.cmd的每用户启动文件夹启动器。

Linux（系统级服务）

多用户/常开主机应使用系统单元。以 user unit 示例为基础，安装到/etc/systemd/system/openclaw-gateway[-<profile>].service，若openclaw二进制在其他位置则调整ExecStart=，并在[Service]段添加User=：

[Service] User=<user>

将<user>替换为持有 OpenClaw 状态与配置的非 root账户。不带User=的系统单元会以 root 运行——以 root 运行 Gateway 及其 agent 命令不安全且不受支持。省略Group=时，systemd 使用所选账户的主组；默认User=同时提供该账户的HOME，OpenClaw 据此进行常规状态与配置查找。需要自定义位置时，在单元环境中设置OPENCLAW_STATE_DIR与OPENCLAW_CONFIG_PATH。不要为了绕过而把配置复制到 root 的家目录。单用户主机上，上述 user unit +loginctl enable-linger是无登录会话保持 Gateway 运行的受支持方式。

也不要让openclaw doctor --fix为同一 profile/port 安装用户级 Gateway 服务：当检测到系统级 OpenClaw Gateway 服务时，Doctor 会拒绝该自动安装；系统单元持有生命周期时使用OPENCLAW_SERVICE_REPAIR_POLICY=external。

写入单元后重载 systemd 并启用：

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

配置错误退出码约定：无效配置错误以退出码78结束。Linux systemd 单元用RestartPreventExitStatus=78在配置修复前停止重启。launchd 与 Windows 任务计划程序没有等效的按退出码停止规则，因此 Gateway 还会持久记录快速非干净启动历史，并在连续启动失败后抑制渠道/provider 账户自动启动。该安全模式下：控制平面仍启动以供检查与修复；配置热重载与secrets.reload拒绝自动重启渠道；显式的操作者channels.start请求可覆盖该抑制。分步恢复见 Restart recovery。

Dev profile 快速路径

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

默认包含隔离的状态/配置，基础 Gateway 端口为19001。

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

首帧必须是connect。
Gateway 返回hello-ok帧，携带snapshot（presence、health、stateVersion、uptimeMs）以及policy限制（maxPayload、maxBufferedBytes、tickIntervalMs）。
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。

Agent 运行是两阶段：

立即的接受确认（status:"accepted"）
最终完成响应（status:"ok"|"error"），期间流式agent事件

完整协议文档见 Gateway Protocol。

运维检查

存活（Liveness）

打开 WS 并发送connect。
期待带 snapshot 的hello-ok响应。

就绪（Readiness）

openclaw gateway status openclaw channels status --probe openclaw health

缺口恢复（Gap recovery）

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

常见失败特征速查

特征	可能原因
`refusing to bind gateway ... without auth`	非 loopback 绑定但缺少有效的 Gateway 认证路径
`another gateway instance is already listening`/`EADDRINUSE`	端口冲突
`Gateway start blocked: set gateway.mode=local`	配置为 remote 模式，或损坏的配置缺少`gateway.mode`
`unauthorized`during connect	客户端与 Gateway 之间的认证不匹配

完整诊断阶梯见 Gateway Troubleshooting。

安全保障

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

企业官网建设流程全解析