网关架构

概述

OpenClaw 采用单 Gateway 守护进程架构，所有消息渠道（WhatsApp、Telegram、Slack、Discord、Signal、iMessage、WebChat）都由这一个进程统一管理。控制面客户端（macOS App、CLI、Web UI、自动化脚本）通过 WebSocket 连接到 Gateway。

核心要点

• Gateway 监听默认地址 127.0.0.1:18789，同时提供 HTTP 服务（Canvas UI、A2UI）
• 每台主机只能运行一个 Gateway，它是唯一持有 WhatsApp 会话的进程
• 客户端角色分两类：
  • 普通客户端（macOS App / CLI / Web Admin）：发送请求、订阅事件
  • 节点（Node）：声明 role: node，提供设备能力（摄像头、屏幕录制、位置等）
• 协议为 WebSocket 文本帧 + JSON，首帧必须是 connect
• 支持幂等键（idempotency key），防止 send/agent 重复执行
• 远程访问推荐使用 Tailscale 或 SSH 隧道

连接生命周期

Client → req:connect → Gateway
Gateway → res(ok) + event:presence + event:tick
Client → req:agent
Gateway → res:agent(ack) → event:agent(streaming) → res:agent(final)

配置/使用

• 启动：openclaw gateway（前台运行，日志输出到 stdout）
• 健康检查：通过 WS 发送 health 请求
• 认证模式：
  • 默认：共享密钥（connect.params.auth.token）
  • Tailscale Serve：gateway.auth.allowTailscale: true
  • 受信代理：gateway.auth.mode: "trusted-proxy"
  • 禁用认证（仅内网）：gateway.auth.mode: "none"
• 设备配对：新设备 ID 需要审批，本地回环可配置自动审批

相关页面

• agent-loop — Agent 执行循环详解
• queue — 命令队列与并发控制
• session — 会话管理
• agent — Agent 运行时概述