网关架构

Gateway（网关）是 OpenClaw 的核心守护进程，负责管理所有消息渠道、Agent 调度与设备连接。它是整个系统的单一入口点。

架构总览

┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
│ WhatsApp │  │ Telegram │  │ Discord  │  │ iMessage │
└────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘
     │             │             │             │
     └─────────────┴──────┬──────┴─────────────┘
                          │
                    ┌─────▼─────┐
                    │  Gateway  │  ◄── 127.0.0.1:18789
                    │   网关    │
                    └─────┬─────┘
                          │
              ┌───────────┼───────────┐
              │           │           │
        ┌─────▼────┐ ┌───▼────┐ ┌───▼────────┐
        │  Agent   │ │ Agent  │ │   Agent    │
        │  主智能体│ │ 编程助手│ │  写作助手  │
        └─────┬────┘ └───┬────┘ └───┬────────┘
              │           │           │
              └───────────┼───────────┘
                          │
              ┌───────────┼───────────┐
              │           │           │
        ┌─────▼────┐ ┌───▼────┐ ┌───▼────────┐
        │  OpenAI  │ │ Claude │ │  DeepSeek  │
        │          │ │        │ │            │
        └──────────┘ └────────┘ └────────────┘

Gateway 基础

Gateway 是一个长生命周期的守护进程（Daemon），拥有以下核心特性：

属性	说明
默认绑定地址	127.0.0.1:18789
协议	HTTP + WebSocket
进程模型	单进程、事件驱动
状态管理	内存 + 文件持久化

安全绑定

默认绑定到 127.0.0.1（仅本地访问）。如需远程访问，需显式配置绑定地址并启用认证。

WebSocket 协议

所有实时通信通过 WebSocket 进行。连接建立后，客户端必须发送 connect 帧作为第一条消息：

// 第一帧：connect 握手
{
  "type": "connect",
  "token": "your-gateway-token",
  "deviceId": "device-abc-123"
}

握手成功后，Gateway 会推送两类服务端事件：

Agent 事件

{
  "type": "agent",
  "event": "message",
  "sessionKey": "agent::user123",
  "data": {
    "role": "assistant",
    "content": "Hello! How can I help?"
  }
}

Presence 事件

{
  "type": "presence",
  "event": "status",
  "deviceId": "device-abc-123",
  "data": {
    "online": true,
    "lastSeen": "2025-01-15T10:30:00Z"
  }
}

身份认证

Gateway 使用 Token 认证机制：

# 设置 Gateway Token
export OPENCLAW_GATEWAY_TOKEN="your-secret-token"

# 启动 Gateway
openclaw gateway start

安全警告

OPENCLAW_GATEWAY_TOKEN 是 Gateway 的主密钥。请勿在代码仓库中提交此值，建议使用环境变量或密钥管理服务。

设备配对（Device Pairing）

新设备首次连接时需要完成配对流程：

新设备                      Gateway
  │                           │
  │──── connect (无 token) ──▶│
  │                           │
  │◀── pairing_challenge ─────│
  │                           │
  │──── pairing_response ────▶│  ◄── 需要在已配对设备上确认
  │                           │
  │◀── pairing_success ───────│
  │     (返回 device token)   │
  │                           │

配对成功后，设备获得唯一的 Device Token，后续连接无需重复配对。

组件角色

Channel Adapter（渠道适配器）

每个消息平台都有对应的 Channel Adapter：

• 将平台特有的消息格式标准化为 OpenClaw 内部格式
• 处理平台 API 的认证与速率限制
• 管理平台连接的生命周期

Agent Router（智能体路由器）

根据规则将消息路由到正确的 Agent：

routing:
  default: main-agent
  rules:
    - channel: telegram
      user: admin
      agent: coder-agent
    - channel: whatsapp
      group: "dev-team"
      agent: team-agent

Session Manager（会话管理器）

管理所有活跃会话的生命周期与状态持久化。

WhatsApp 限制

单实例约束

每台主机上只能运行一个 WhatsApp 会话。这是 WhatsApp Web 协议的固有限制。如需多个 WhatsApp 连接，需部署在不同主机上。

数据流详解

一条用户消息的完整生命周期：

1. 接收 — Channel Adapter 从平台收到消息
2. 标准化 — 转换为 OpenClaw 内部消息格式
3. 路由 — Agent Router 确定目标 Agent
4. 排队 — 消息进入目标 Agent 的 Session 队列
5. 处理 — Agent Loop 执行消息处理流水线
6. 回复 — 生成的回复通过 Channel Adapter 发送回平台

🇨🇳 中国用户须知

• Gateway 默认端口 18789 在国内云服务器上通常无需备案
• 如部署在国内服务器，建议使用 Nginx 反向代理并配置 SSL
• 国内用户连接 WhatsApp 需注意网络环境配置

下一步

• 了解 功能总览 查看完整能力列表
• 配置 多 Agent 路由 实现多智能体协作
• 查看 模型提供商 配置模型接入