AI摘要：该手册介绍了Gateway网关，它是OpenClaw核心进程。阐述本地运行方式，如基础启动、核心配置等；还提及远程访问、多网关部署、系统监管、运维检查、安全保证等内容，包括CLI辅助工具及从旧版迁移的指南，最后更新时间为2025-12-09 。

一、网关是什么
Gateway 是 OpenClaw 的常驻核心进程，提供统一的 Baileys/Telegram 连接、控制平面与事件分发能力，完全替代旧版 gateway 命令。
CLI 入口：openclaw gateway
运行特性：持续运行直至手动停止；发生致命错误时以非零退出码退出，便于 supervisor 自动重启
二、本地运行方式
基础启动
bash
运行

标准启动（默认端口 18789）

openclaw gateway --port 18789

启用完整调试/追踪日志（输出到 stdio）

openclaw gateway --port 18789 --verbose

端口被占用时强制终止旧进程并启动

openclaw gateway --force

开发模式（TS 代码变更自动重载）

pnpm gateway:watch
核心配置与特性
配置热重载
自动监听配置文件：~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH 指定路径）
默认模式：gateway.reload.mode="hybrid"（安全配置热应用，关键变更触发重启）
进程内重启：通过 SIGUSR1 信号触发；可设置 gateway.reload.mode="off" 禁用
端口与服务
WebSocket 控制平面绑定：127.0.0.1:（默认 18789）
单端口复用：同时提供 HTTP 服务（控制界面、hooks、A2UI）
兼容 OpenAI 接口：
Chat Completions：/v1/chat/completions
Responses：/v1/responses
Tools Invoke：/tools/invoke
Canvas 文件服务
默认在 canvasHost.port（18793）启动，文件根目录：~/.openclaw/workspace/canvas
访问地址：http://:18793/__openclaw__/canvas/
禁用方式：canvasHost.enabled=false 或 OPENCLAW_SKIP_CANVAS_HOST=1

日志与调试
日志默认输出到 stdout，建议配合 launchd/systemd 实现日志轮转
--verbose：将调试日志（握手、请求 / 响应、事件）同步输出到 stdio
--force：通过 lsof 查找端口占用进程，发送 SIGTERM 终止后启动（无 lsof 则快速失败）
信号与关闭
SIGTERM：正常关闭（supervisor 常用），旧版可能显示 pnpm ELIFECYCLE 143，属正常退出
SIGUSR1：触发进程内重启（配置 / 工具更新、手动重启）
认证机制
默认启用网关认证：配置 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）或 gateway.auth.password
客户端需在 connect.params.auth.token/password 中传递凭证（Tailscale Serve 身份除外）
新手引导默认生成令牌，即使本地回环地址也需认证
端口优先级
--port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789
三、远程访问
推荐方案（安全优先）
Tailscale/VPN：直接通过私有网络访问，无需额外端口暴露
SSH 隧道（备选）
bash
运行
ssh -N -L 18789:127.0.0.1:18789 user@host
客户端通过隧道连接：ws://127.0.0.1:18789，必须携带认证令牌
四、多网关部署（同一主机）
适用场景
通常无需多网关：单网关可支撑多消息渠道、多智能体
仅在冗余部署或严格隔离（如救援机器人）时使用
部署要求
隔离状态目录、配置文件，使用唯一端口
服务命名规则（按配置文件区分）：
macOS：bot.molt.（旧版 com.openclaw.* 兼容）
Linux：openclaw-gateway-.service
Windows：OpenClaw Gateway ()
服务元数据：
plaintext
OPENCLAW_SERVICE_MARKER=openclaw
OPENCLAW_SERVICE_KIND=gateway
OPENCLAW_SERVICE_VERSION=
救援机器人模式：独立配置文件、状态目录、工作区与端口区间（详见官方指南）
macOS 应用集成
OpenClaw.app 内置 Node 网关，安装为用户级 LaunchAgent（标签：bot.molt.gateway 或 bot.molt.）
启停命令：
bash
运行

停止

openclaw gateway stop

或 launchctl bootout gui/$UID/bot.molt.gateway

重启

openclaw gateway restart

或 launchctl kickstart -k gui/$UID/bot.molt.gateway

首次使用需先安装服务：openclaw gateway install
五、系统监管（Linux/WSL2）
推荐：systemd 用户单元（单用户机器）
安装服务
bash
运行
openclaw gateway install # 写入用户单元
openclaw doctor # 审计并更新服务配置
服务文件路径：~/.config/systemd/user/openclaw-gateway[-].service
ini
[Unit]
Description=OpenClaw Gateway (profile: , v)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
Environment=OPENCLAW_GATEWAY_TOKEN=
WorkingDirectory=/home/youruser

[Install]
WantedBy=default.target
启用 lingering（用户登出后服务继续运行）
bash
运行
sudo loginctl enable-linger youruser
启用并启动服务
bash
运行
systemctl --user enable --now openclaw-gateway[-].service
备选：systemd 系统单元（多用户 / 常驻服务器）
无需 lingering，共享系统监管
服务文件路径：/etc/systemd/system/openclaw-gateway[-].service
关键修改：WantedBy=multi-user.target，添加 User= 与 WorkingDirectory=
操作命令
bash
运行
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-].service
Windows 部署
Windows 环境需通过 WSL2 运行，遵循上述 Linux systemd 配置流程
六、运维检查
存活检查
建立 WebSocket 连接，发送 req:connect
预期响应：payload.type="hello-ok"（含系统快照）
就绪检查
调用 health 接口
预期结果：ok: true，且 linkChannel 包含已关联渠道（如有）
调试排查
订阅 tick、presence 事件
确认 status 显示渠道关联 / 认证时间
检查 presence 条目：包含网关主机与已连接客户端信息
七、安全保证
默认单主机单网关；多配置文件部署需隔离端口 / 状态
不回退到直接 Baileys 连接，网关关闭时请求快速失败
非 connect 首帧或格式错误 JSON，直接拒绝并关闭连接
优雅关闭：触发 shutdown 事件，客户端需处理关闭与重连逻辑
八、CLI 辅助工具
bash
运行

网关健康/状态查询

openclaw gateway health|status

通过网关发送消息（WhatsApp 幂等）

openclaw message send --target --message "hi" [--media ...]

运行智能体轮次（默认等待最终结果）

openclaw agent --message "hi" --to

原始方法调用（调试用）

openclaw gateway call --params '{"k":"v"}'

启停监管网关服务

openclaw gateway stop|restart
注：辅助工具默认连接 --url 指定的运行中网关，不再自动启动新网关
九、迁移指南
淘汰旧版 openclaw gateway 与 TCP 控制端口用法
客户端升级：适配 WebSocket 协议，使用强制 connect 与结构化 presence 机制。
最后更新：2025-12-09