6.1 Gateway运维手册

网关与运维网关与运维

Gateway 运维手册提供了 OpenClaw Gateway 的完整运维指南,包括架构说明、CLI 使用、进程管理、监控和故障处理等内容。

概述

Gateway 是 OpenClaw 的核心常驻进程,负责管理 Baileys/Telegram 连接以及控制和事件平面。它取代了旧版的 gateway 命令,提供了更强大和统一的运维体验。

核心特性

  • 常驻运行: Gateway 持续运行直到手动停止
  • 单端口服务: WebSocket + HTTP 端点统一在一个端口 (默认 18789)
  • 自动重启: 致命错误时以非零退出码退出,触发 supervisor 重启
  • 热重载: 监控配置文件变化并自动应用
  • 多实例支持: 支持冗余和隔离的多 Gateway 部署

Gateway 架构

端口分配

端口 用途 计算方式
18789 WebSocket RPC + HTTP API 基础端口
18791 浏览器控制端口 基础端口 + 2
18793 Canvas 文件服务器 基础端口 + 4
18800-18899 CDP 调试端口范围 控制端口 + 9 到 + 108

HTTP 端点

Gateway 的单端口多路复用 HTTP 服务器提供以下端点:

  • /v1/chat/completions - OpenAI 兼容 API
  • /v1/responses - OpenResponses API
  • /tools/invoke - 工具调用端点
  • WebSocket - 节点到 Gateway 的 RPC 通信

CLI 使用

基本命令

# 启动 Gateway (默认端口 18789)
openclaw gateway

# 指定端口
openclaw gateway --port 19000

# 开发模式 (隔离实例,自动分配端口)
openclaw gateway --dev

# 强制启动 (杀死占用端口的进程)
openclaw gateway --force

# 详细日志输出
openclaw gateway --verbose

# 允许未配置启动
openclaw gateway --allow-unconfigured

状态检查

# 查看 Gateway 状态
openclaw gateway status

# 深度检查 (包括连接详情)
openclaw gateway status --deep

# JSON 格式输出
openclaw gateway status --json

# 不进行探测检查
openclaw gateway status --no-probe

日志管理

# 实时跟踪日志
openclaw logs --follow

# 查看最近 100 条日志
openclaw logs --last 100

# 按级别过滤
openclaw logs --level error

# JSON 格式
openclaw logs --format json

交互命令

# 调用 RPC 方法
openclaw call config.get --params '{}'

# 发送消息
openclaw message send --to agent-id --text "Hello"

# Agent 管理
openclaw agent list
openclaw agent status agent-id

进程管理

macOS (launchd)

macOS 使用 launchd 管理 Gateway 进程。

安装服务

# 安装 launchd 服务
openclaw gateway install

# 服务配置文件位置
~/Library/LaunchAgents/bot.molt.gateway.plist

# 审计服务配置
openclaw doctor

服务管理

# 启动服务
launchctl load ~/Library/LaunchAgents/bot.molt.gateway.plist

# 停止服务
launchctl unload ~/Library/LaunchAgents/bot.molt.gateway.plist

# 查看服务状态
launchctl list | grep openclaw

# 查看服务日志
log show --predicate 'process == "openclaw"' --last 1h

launchd 配置示例

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>bot.molt.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/openclaw</string>
        <string>gateway</string>
        <string>--port</string>
        <string>18789</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/openclaw-gateway.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/openclaw-gateway-error.log</string>
</dict>
</plist>

Linux / WSL2 (systemd)

Linux 系统使用 systemd 管理 Gateway。默认使用用户单元,适合个人使用。

用户单元 (推荐)

# 创建服务配置
mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/openclaw-gateway.service

# 启用用户 lingering (允许非登录时运行服务)
loginctl enable-linger $USER

# 重载配置
systemctl --user daemon-reload

# 启动服务
systemctl --user start openclaw-gateway

# 设置开机自启
systemctl --user enable openclaw-gateway

# 查看状态
systemctl --user status openclaw-gateway

# 查看日志
journalctl --user -u openclaw-gateway -f

systemd 用户单元配置

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

# 环境变量
Environment="OPENCLAW_GATEWAY_TOKEN=your-token"
Environment="NODE_ENV=production"

# 资源限制
LimitNOFILE=4096

[Install]
WantedBy=default.target

系统单元 (多用户/服务器)

# 创建系统服务 (需要 root 权限)
sudo nano /etc/systemd/system/openclaw-gateway.service

# 配置示例
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=openclaw
Group=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway

Windows (WSL2)

Windows 用户推荐使用 WSL2,按照 Linux systemd 指南配置。

配置热重载

Gateway 自动监控配置文件 ~/.openclaw/openclaw.json 的变化。

重载模式

{
  "gateway": {
    "hotReload": {
      "mode": "hybrid"  // "hybrid" | "off"
    }
  }
}
  • hybrid (默认): 安全变更立即应用,关键变更触发重启
  • off: 禁用热重载,需手动重启

安全变更 vs 关键变更

安全变更 (立即应用):

  • Agent 配置 (模型、提示词等)
  • 工具策略
  • 日志级别

关键变更 (触发重启):

  • 端口配置
  • 认证配置
  • 网络绑定
  • Tailscale 配置

认证配置

Gateway 要求配置认证以保护访问。

Token 认证

{
  "gateway": {
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

# 设置环境变量
export OPENCLAW_GATEWAY_TOKEN="your-secure-token"

密码认证

{
  "gateway": {
    "auth": {
      "password": "${OPENCLAW_GATEWAY_PASSWORD}"
    }
  }
}

多 Gateway 部署

多 Gateway 仅用于冗余和隔离,需要独立的端口、状态和配置。

使用 Profile 隔离

# Gateway 1 (默认)
openclaw gateway --port 18789

# Gateway 2 (rescue profile)
openclaw --profile rescue gateway --port 19001

# 检查状态
openclaw status
openclaw --profile rescue status

开发 Profile

开发模式自动分配端口,避免冲突:

# 自动分配: 19001, 19003, 19005...
openclaw gateway --dev

# 等同于
openclaw --profile dev gateway --port 19001

必需隔离项

  • OPENCLAW_CONFIG_PATH - 独立配置文件
  • OPENCLAW_STATE_DIR - 独立状态目录
  • agents.defaults.workspace - 独立工作空间
  • gateway.port - 不重叠的端口

协议和事件

连接协议

客户端必须首先发送 connect 帧:

{
  "type": "req",
  "id": "connect-1",
  "method": "connect",
  "params": {
    "auth": {
      "token": "your-token"
    }
  }
}

事件类型

  • agent - Agent 响应事件
  • presence - 连接状态变化
  • tick - 心跳事件
  • shutdown - 关闭通知

连接快照

{
  "presence": "available",
  "health": "healthy",
  "stateVersion": 123,
  "uptimeMs": 3600000,
  "policy": {
    "sandbox": "non-main",
    "tools": ["exec", "read", "write"]
  }
}

错误处理

错误响应格式

{
  "type": "res",
  "id": "req-id",
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "details": {},
    "retryable": true,
    "retryAfterMs": 5000
  }
}

标准错误码

  • NOT_LINKED - WhatsApp 未配对
  • AGENT_TIMEOUT - Agent 响应超时
  • INVALID_REQUEST - 请求格式错误
  • UNAVAILABLE - 服务不可用

连接错误

非 connect 帧或格式错误的 JSON 会立即关闭 WebSocket 连接。

优雅关闭

# 发送 SIGTERM 触发优雅关闭
kill -TERM $(pgrep openclaw)

# Gateway 发送 shutdown 事件
{
  "type": "event",
  "event": "shutdown",
  "payload": {
    "reason": "SIGTERM received",
    "gracePeriodMs": 30000
  }
}

运维检查清单

  • ✅ Gateway 服务正常运行
  • ✅ 端口未被占用或冲突
  • ✅ 认证配置正确
  • ✅ Supervisor (launchd/systemd) 配置有效
  • ✅ 日志正常输出
  • ✅ 热重载功能正常
  • ✅ 网络连通性正常
  • ✅ 磁盘空间充足
  • ✅ 资源限制合理
  • ✅ 备份策略已执行

故障排查

Gateway 无法启动

# 检查端口占用
lsof -i :18789

# 强制启动
openclaw gateway --force

# 检查配置
openclaw config validate

# 查看详细日志
openclaw gateway --verbose

服务自动重启

# 查看服务日志
journalctl --user -u openclaw-gateway -n 100

# 检查崩溃原因
openclaw logs --level error --last 1000

# 禁用自动重启进行调试
systemctl --user stop openclaw-gateway
openclaw gateway --verbose

热重载不生效

# 检查热重载配置
openclaw config show | grep hotReload

# 手动重载
openclaw gateway reload

# 查看重载日志
openclaw logs --filter reload

性能优化

资源限制

# 增加文件描述符限制
ulimit -n 4096

# systemd 配置
[Service]
LimitNOFILE=4096
LimitNPROC=2048

日志优化

{
  "gateway": {
    "logging": {
      "level": "info",  // 生产环境避免使用 debug
      "format": "json",
      "rotation": {
        "enabled": true,
        "maxSize": "100M",
        "maxFiles": 10
      }
    }
  }
}

监控建议

  • 进程监控: 确保 Gateway 进程存活
  • 端口监控: 监控端口可达性
  • 连接数: 跟踪活跃连接数
  • 错误率: 监控错误日志频率
  • 响应时间: 监控 RPC 调用延迟
  • 资源使用: CPU、内存、磁盘使用率

相关资源