网关运行手册

使用本页面进行网关服务的第一天启动和第二天运维。

5 分钟本地启动


bash
# 1. 安装并入门
curl -fsSL https://openclaw.ai/install.sh | bash

# 2. 启动网关
openclaw gateway

# 3. 打开控制界面
# 访问 http://127.0.0.1:18789/

运行时模型

▹一个始终在线的进程用于路由、控制平面和渠道连接
▹
单个多路复用端口用于：
- ▹WebSocket 控制/RPC
- ▹HTTP API（OpenAI 兼容、响应、工具调用）
- ▹控制界面和钩子
▹默认绑定模式：loopback（本地回环）
▹默认需要身份验证（gateway.auth.token / gateway.auth.password，或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD）

端口和绑定优先级

设置	解析顺序
网关端口	`--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789`
绑定模式	CLI/覆盖 → `gateway.bind` → `loopback`

热重载模式

`gateway.reload.mode`	行为
`off`	不重载配置
`hot`	仅应用热安全更改
`restart`	在需要重载的更改时重启
`hybrid`（默认）	安全时热应用，需要时重启

操作员命令集


bash
openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw logs --follow
openclaw doctor

远程访问

首选：Tailscale/VPN

备选：SSH 隧道


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

然后在本地连接到 ws://127.0.0.1:18789。

参见：远程网关、身份验证、Tailscale

监督和服务生命周期

使用监督运行以获得类似生产的可靠性。

macOS（launchd）


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

LaunchAgent 标签为 ai.openclaw.gateway（默认）或 ai.openclaw.<profile>（命名配置文件）。

openclaw doctor 审计并修复服务配置漂移。

Linux（systemd 用户）


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

要在注销后持久化，启用 lingering：


bash
sudo loginctl enable-linger <user>

Linux（系统服务）

用于多用户/始终在线的主机使用系统单元。


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

同一主机上的多个网关

大多数设置应该运行一个网关。

仅在需要严格隔离/冗余时使用多个（例如救援配置文件）。

每个实例的检查清单：

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

示例：


bash
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

参见：多个网关

开发配置文件快速路径


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

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

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

▹第一个客户端帧必须是 connect
▹网关返回 hello-ok 快照（presence、health、stateVersion、uptimeMs、limits/policy）
▹请求：req(method, params) → res(ok/payload|error)
▹常见事件：connect.challenge、agent、chat、presence、tick、health、heartbeat、shutdown

代理运行分为两个阶段：

▹立即接受确认（status:"accepted"）
▹最终完成响应（status:"ok"|"error"），中间有流式代理事件

参见完整协议文档：网关协议

运维检查

活性检查

打开 WS 并发送 connect。期望 hello-ok 响应和快照。

就绪检查


bash
openclaw gateway status
openclaw channels status --probe
openclaw health

间隙恢复

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

常见故障特征

特征	可能的问题
`refusing to bind gateway ... without auth`	非回环绑定但没有 token/password
`another gateway instance is already listening / EADDRINUSE`	端口冲突
`Gateway start blocked: set gateway.mode=local`	配置设置为远程模式
`unauthorized during connect`	客户端和网关之间的身份验证不匹配

有关完整的诊断阶梯，请使用网关故障排除。

安全保证

▹当网关不可用时，网关协议客户端快速失败（没有隐式的直接渠道回退）
▹无效/非连接的第一帧被拒绝并关闭
▹优雅关闭在套接字关闭前发出 shutdown 事件