Gateway 网关

Gateway 是一个单进程服务，默认绑定 127.0.0.1:18789，同时提供：

• WebSocket RPC（客户端、Node 设备通信）
• OpenAI 兼容 HTTP API
• Control UI（Vite + Lit SPA）
• Webhook 端点

# 前台启动
openclaw gateway --port 18789

# 注册为系统服务（macOS launchd / Linux systemd）
openclaw gateway install

# 查看状态
openclaw gateway status

配置文件位于 ~/.openclaw/openclaw.json，格式为 JSON5（支持注释、尾逗号）。 Gateway 启动时会做严格校验——未知字段或非法值会阻止启动。

{
  // 最小可用配置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-5" }
    }
  },
  channels: {
    telegram: { dmPolicy: "pairing" }
  }
}

修改配置的几种方式：

• openclaw configure — 交互式编辑
• openclaw config set <path> <value> — 单字段修改
• Control UI 的 Config 标签页
• 直接编辑文件（支持热更新）

Gateway 监听配置文件变更，支持四种热更新模式（gateway.reload.mode）：

大型配置可以使用 $include 拆分为多个文件，Gateway 会深度合并：

{
  $include: [
    "./channels.json",
    "./agents.json",
    "./cron.json"
  ],
  // 其他顶层配置...
}

最多支持 10 级嵌套引用。

Gateway 启动时自动读取 ~/.openclaw/.env 和当前目录的 .env。 配置值中可以用 ${VAR_NAME} 引用环境变量。

敏感凭据推荐使用 SecretRef 对象（支持 env、file、exec 三种来源）：

{
  channels: {
    telegram: {
      botToken: { source: "env", id: "TELEGRAM_BOT_TOKEN" }
    }
  }
}

Gateway 默认只监听 loopback。如需远程访问，推荐以下方式（安全性从高到低）：

1. Tailscale Serve/Funnel：零配置内网穿透，自动 HTTPS
2. SSH 隧道：ssh -N -L 18789:127.0.0.1:18789 user@host
3. VPN：通过 VPN 网络直连

不建议直接将 Gateway 端口暴露到公网。如必须，务必启用认证并设置 allowlist。

客户端通过 WebSocket 连接 Gateway。首帧必须是 connect， Gateway 返回 hello-ok 快照。之后通过 JSON 帧交互：

• 请求：{type:"req", id, method, params}
• 事件：{type:"event", event, payload}

Agent 执行分两阶段：先返回 accepted ACK，然后流式返回内容和工具调用事件，最终发送 completion。

一台机器可以运行多个 Gateway 实例，但每个实例必须使用独立的：

• 端口号
• 配置文件路径
• 状态目录
• Workspace 目录

OPENCLAW_CONFIG_PATH=~/.openclaw/work.json \
OPENCLAW_STATE_DIR=~/.openclaw-work \
openclaw gateway --port 18790