Gateway 概述

Gateway 是 OpenClaw 的核心后台服务进程，负责接收来自各个 IM 渠道（WhatsApp、Telegram、Discord 等）的消息，驱动 AI Agent 处理，并将回复发送回去。

快速启动（5 分钟）

步骤 1：启动 Gateway

# 默认端口 18789
openclaw gateway --port 18789

# 开启详细日志
openclaw gateway --port 18789 --verbose

# 强制释放已占用端口后启动
openclaw gateway --force

步骤 2：检查服务状态

openclaw gateway status
openclaw status
openclaw logs --follow

健康状态显示 Runtime: running 且 RPC probe: ok 说明服务正常。

步骤 3：验证渠道连通性

openclaw channels status --probe

Gateway 的工作原理

• 单进程架构：一个常驻进程，同时处理消息路由、控制平面和渠道连接。
• 单端口复用：同一端口承载 WebSocket 控制/RPC、HTTP API（OpenAI 兼容、工具调用）、控制面板和 Hooks。
• 默认绑定到本机回环地址（loopback），不对外网暴露。
• 默认要求认证：通过 gateway.auth.token 或环境变量 OPENCLAW_GATEWAY_TOKEN 设置。

端口与绑定地址的优先级

设置	解析顺序
端口	--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789（默认）
绑定模式	命令行参数 → gateway.bind → loopback（默认）

热重载

Gateway 监控配置文件，修改后自动应用，无需手动重启（大多数设置）。

gateway.reload.mode	行为
hybrid（默认）	安全变更即时热应用；需重启的变更自动重启
hot	仅热应用安全变更，需重启时记录警告
restart	任何变更都重启
off	禁用文件监控，下次手动重启才生效

常用操作命令

openclaw gateway status        # 查看服务状态
openclaw gateway status --deep # 详细状态
openclaw gateway status --json # JSON 格式输出
openclaw gateway install       # 安装为系统服务（macOS/Linux）
openclaw gateway restart       # 重启 Gateway
openclaw gateway stop          # 停止 Gateway
openclaw secrets reload        # 重载 Secrets
openclaw logs --follow         # 实时查看日志
openclaw doctor                # 诊断配置问题

以系统服务运行（生产环境）

macOS（launchd）

openclaw gateway install    # 安装 LaunchAgent
openclaw gateway status     # 检查状态
openclaw gateway restart    # 重启
openclaw gateway stop       # 停止

服务 Label：ai.openclaw.gateway（默认）或 ai.openclaw.<profile>（命名配置）。 openclaw doctor 可自动检测和修复服务配置漂移。

Linux（systemd 用户服务）

openclaw gateway install
systemctl --user enable --now openclaw-gateway.service
openclaw gateway status

若需注销后也保持运行：

sudo loginctl enable-linger <用户名>

Linux（系统级服务，多用户）

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway.service

在一台机器上运行多个 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

开发环境快速启动

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

开发配置默认使用独立 state/config 和端口 19001。

常见故障特征

错误信息	可能原因
refusing to bind gateway ... without auth	非回环地址绑定但未配置 token/password
another gateway instance is already listening / EADDRINUSE	端口冲突
Gateway start blocked: set gateway.mode=local	配置设置为 remote 模式
unauthorized during connect	客户端与 Gateway 认证不匹配

安全保证

• 当 Gateway 不可用时，协议客户端立即快速失败（不自动降级为直接渠道连接）。
• 第一帧不是 connect 的连接会被拒绝并关闭。
• Gateway 优雅关闭时会在断开 socket 前发送 shutdown 事件。