第三章：Gateway 架构

理解 OpenClaw 的核心 -- 消息路由中枢。

本章概览

在这一章中，你将了解：

Gateway 是什么，为什么它是 OpenClaw 的核心
消息从聊天平台到 AI 的完整流转过程
三种使用入口：仪表盘、CLI、手机 IM
会话模型：私聊共享、群组隔离、多智能体路由
配置文件结构和重要参数

为什么要了解架构？

作为产品经理，理解 Gateway 架构能帮助你：

明白多平台消息整合是如何实现的
评估 OpenClaw 能否满足你的业务需求
与技术团队讨论 AI 助手集成方案时更有话语权
设计类似的产品架构时有参考

3.1 什么是 Gateway？

一句话解释

Gateway 是 OpenClaw 的消息路由中枢，它负责接收来自各个聊天平台的消息，交给 AI Agent 处理，然后把回复发送回对应的平台。

用一个比喻来理解

想象你是一家公司的前台接待员：

有客户打电话来咨询
有客户发邮件来询问
有客户直接走进大厅来拜访
还有客户通过网站聊天窗口联系

作为前台，你的工作是：

接收 -- 不管客户通过什么渠道来的，你都能接到
识别 -- 判断这个客户要找谁、要做什么
转接 -- 把问题交给对应的专家处理
回复 -- 把专家的回答通过客户联系你的那个渠道传回去

Gateway 就是这个前台接待员。 只不过它接待的是来自微信、飞书、WhatsApp、Telegram 等平台的消息，把它们转交给 AI Agent 处理。

Gateway = 聊天平台的"前台接待员"

接收各个渠道的消息 → 统一转交给 AI 处理 → 将回复送回原渠道

为什么需要 Gateway？

你可能会问：为什么不能让每个平台直接和 AI 对话？为什么要多一个 Gateway 层？

原因有三个：

1. 统一接口

每个聊天平台的 API 都不一样。Gateway 把这些不同的接口统一成一个标准格式，AI Agent 不需要关心消息来自哪里。

没有 Gateway：
AI Agent 需要理解 N 种平台 API（复杂）

有 Gateway：
AI Agent 只需要理解 1 种统一格式（简单）

2. 会话共享

因为所有平台的消息都经过 Gateway，所以 Gateway 可以维护一个统一的会话上下文。这就是为什么你在微信上说的话，切换到飞书后 AI 还记得。

3. 易于扩展

如果以后要支持一个新的聊天平台，只需要在 Gateway 层添加一个新的"连接器"，AI Agent 不需要任何改动。

3.2 三种使用入口

OpenClaw 提供三种方式与系统交互：

入口	适合场景
仪表盘（浏览器，`http://127.0.0.1:18789/`）	日常聊天、改配置、看节点、调会话——最常用
CLI（`openclaw …`）	脚本化、自动化、批量发消息
手机 IM（微信 / 飞书等）	出门在外、随时随地呼叫智能体

仪表盘核心区域

打开 http://127.0.0.1:18789/ 后能看到：

聊天：直接和智能体对话，效果等同于在 IM 里聊
节点：当前连入的所有设备（手机、电脑、伴侣应用）
会话：所有正在进行的会话列表
配置：可视化改配置文件

如果打不开仪表盘，说明 Gateway 没在跑，手动启动：

bash

openclaw gateway --port 18789

3.3 消息流转全过程

让我们跟着一条消息，走完它的完整旅程。

场景：你在微信上发了一条消息

你在微信上输入："帮我写一个产品需求文档的大纲"

第一步：消息发出

┌──────────┐
│   微信   │ ← 你在这里发消息
└────┬─────┘
     │
     │ (1) 微信服务器收到消息
     │     通过回调转发给 OpenClaw
     ▼

第二步：Gateway 接收

     │
     │ (2) Gateway 的渠道连接器接收消息
     ▼
┌─────────────────────────────┐
│         Gateway             │
│  ┌────────────────────────┐ │
│  │ 渠道连接器             │ │ ← 接收平台格式的消息
│  │                        │ │
│  │ 解析消息内容：          │ │
│  │ - 发送者：你的账号 ID   │ │
│  │ - 内容：帮我写...       │ │
│  │ - 时间：2026-xx-xx     │ │
│  └──────────┬─────────────┘ │
│             │               │
│             ▼               │
│  ┌────────────────────────┐ │
│  │ 消息标准化             │ │ ← 转换为统一格式
│  └──────────┬─────────────┘ │
└─────────────┼───────────────┘
              │
              ▼

第三步：路由到 AI Agent

              │
              │ (3) 标准化消息传递给 Pi 智能体
              ▼
┌─────────────────────────────┐
│       Pi 智能体引擎         │
│                             │
│  ┌────────────────────────┐ │
│  │ 上下文管理器           │ │ ← 加载这个用户的历史对话
│  └───────────────────────┘ │
│             │               │
│  ┌──────────▼─────────────┐ │
│  │ 记忆系统               │ │ ← 检查持久化记忆
│  └───────────────────────┘ │
│             │               │
│  ┌──────────▼─────────────┐ │
│  │ LLM 调用               │ │ ← 发送给 Claude/GPT/...
│  │ "帮我写一个产品需求文  │ │
│  │  档的大纲"             │ │
│  └──────────┬─────────────┘ │
│             │               │
│  ┌──────────▼─────────────┐ │
│  │ AI 回复                │ │ ← 收到 AI 的回复
│  │ "好的！以下是产品需求  │ │
│  │  文档的大纲建议：..."  │ │
│  └───────────────────────┘ │
└─────────────┼───────────────┘
              │
              ▼

第四步：回复返回

              │
              │ (4) 回复通过 Gateway 返回到微信
              ▼
┌─────────────────────────────┐
│         Gateway             │
│  ┌────────────────────────┐ │
│  │ 消息格式化             │ │ ← 将回复转换为微信格式
│  └──────────┬─────────────┘ │
│             │               │
│  ┌──────────▼─────────────┐ │
│  │ 渠道连接器             │ │ ← 通过渠道 API 发送
│  └──────────┬─────────────┘ │
─────────────┼───────────────┘
              │
              ▼
┌──────────
│   微信   │ ← 你在这里收到回复
└──────────

全程耗时通常在 2-10 秒 之间，取决于 LLM 的响应速度。

3.4 会话模型

私聊：共享上下文

默认所有私聊会折叠成一个共享会话叫 main。你和同一个智能体在不同 IM 里聊也是同一个上下文。

早上（微信）: 今天有什么会议？
→ OpenClaw 回复你的日程安排

下午（飞书）: 帮我写一个会议纪要
→ OpenClaw 帮你写好纪要（它还记得早上的会议信息）

群组：独立隔离

每个群是独立隔离的会话，互不影响。 群 A 的对话不会被带到群 B 中。

群组中怎么触发机器人

为了避免群里刷屏，OpenClaw 默认只在被 @ 时才回复。

群主可以通过斜杠命令切换：

/activation always    # 所有消息都触发（慎用）
/activation mention   # 仅 @ 时触发（默认）

多智能体路由（高级用法）

可以把不同渠道、不同账号路由到不同的智能体，每个智能体有自己的工作区和会话。详见官方文档的多智能体路由章节。

3.5 用户身份映射

关键问题：AI 怎么知道你是同一个人？

Gateway 维护一个用户身份映射表（User Identity Map），把不同平台的账号关联到同一个 OpenClaw 用户：

微信 +86138xxx → user_001
飞书 @zhangsan → user_001

所有平台的消息共享同一个会话上下文

当 Gateway 收到消息时，它会：

根据消息来源渠道和发送者 ID 查找用户映射
如果找到映射，就知道这是哪个用户
加载该用户的统一会话上下文
把消息连同上下文一起交给智能体引擎

单人使用更简单

如果你只是自己一个人使用 OpenClaw（最常见的场景），身份映射通常会在设置各个渠道时自动完成，你不需要手动配置。

3.6 配置文件详解

OpenClaw 的所有配置和数据都存储在 ~/.openclaw/ 目录中。

目录结构

~/.openclaw/
│
├── openclaw.json          # 主配置文件
│
├── channels/              # 渠道配置
│   ├── telegram.json      # Telegram 配置
│   ├── feishu.json        # 飞书配置
│   └── whatsapp.json      # WhatsApp 配置
│
├── conversations/         # 对话历史
│   ├── main.json          # 私聊共享会话
│   ├── group_001.json     # 群组 1
│   └── group_002.json     # 群组 2
│
├── memory/                # 持久化记忆
│   └── user_001.json
│
├── skills/                # 已安装的 Skills
│   ├── email-sender/
│   └── calendar-sync/
│
├── logs/                  # 运行日志
│   └── openclaw.log
│
└── gateway/               # Gateway 运行时状态
    └── openclaw.pid       # 进程 ID 文件

主配置文件

下面是官方文档给出的最小化加固配置示例：

json

{
  "channels": {
    "feishu": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}

字段	作用	建议
`channels.<渠道>.allowFrom`	白名单——只接受这些账号的消息	必配，避免陌生人触发智能体烧 token
`channels.<渠道>.groups."*".requireMention`	所有群组默认要 @ 才回复	建议 `true`
`messages.groupChat.mentionPatterns`	自定义触发词	起一个团队认得的名字

安全提醒

~/.openclaw/ 目录的权限设置为 700（仅自己可访问）
不要把这个目录同步到云盘或提交到 Git
开启白名单模式，防止陌生人使用你的 AI 助手

3.7 媒体消息

OpenClaw 原生支持收发多种媒体类型：

图片：直接发图给智能体分析
音频 / 语音消息：可选转录钩子，先转文字再交给智能体
文档：PDF、Word、文本等

3.8 自动化能力

OpenClaw 内置三类自动化入口，让智能体不只是"被动应答"：

定时任务（cron）：定时触发智能体执行任务
Webhooks：外部系统 HTTP 回调进来
Gmail 钩子（Pub/Sub）：邮件触发——比如收到特定邮件就让智能体处理

3.9 架构设计的启示

给产品经理的思考

OpenClaw 的 Gateway 架构有几个值得借鉴的设计思路：

1. 中间层解耦 Gateway 作为中间层，让 AI Agent 和消息平台完全解耦。这意味着添加新平台不需要修改核心逻辑。这种设计模式在很多产品中都适用。

2. 统一用户身份 跨平台的用户身份映射，让用户在任何平台都能获得一致的体验。这对于全渠道（Omnichannel）产品设计很有参考价值。

3. 本地优先 所有数据存储在本地，用户拥有完全的控制权。在隐私越来越重要的今天，这种设计理念值得每个产品经理思考。

4. 可扩展性 通过 Connector 模式支持新平台，通过 Skills 模式支持新功能。这种插件化的架构让产品能快速响应市场需求。

5. 一句话概括架构

Gateway 是心脏，节点是手脚，Pi 是大脑。

本章小结

在这一章中，我们深入了解了：

Gateway 的角色 -- 消息路由中枢，是 OpenClaw 的核心组件
消息流转过程 -- 从聊天平台到 AI 再返回的完整链路
三种使用入口 -- 仪表盘、CLI、手机 IM
会话模型 -- 私聊共享、群组隔离、多智能体路由
多平台会话共享 -- 通过用户身份映射实现跨平台上下文保持
配置文件结构 -- ~/.openclaw/ 目录的完整组织方式

下一步

理解了架构之后，让我们开始实际操作 -- 第四章：聊天平台集成，把你的聊天平台和 OpenClaw 连接起来！

第三章：Gateway 架构 ​

本章概览 ​

3.1 什么是 Gateway？ ​

一句话解释 ​

用一个比喻来理解 ​

为什么需要 Gateway？ ​

3.2 三种使用入口 ​

仪表盘核心区域 ​

3.3 消息流转全过程 ​

场景：你在微信上发了一条消息 ​

第一步：消息发出 ​

第二步：Gateway 接收 ​

第三步：路由到 AI Agent ​

第四步：回复返回 ​

3.4 会话模型 ​

私聊：共享上下文 ​

群组：独立隔离 ​

群组中怎么触发机器人 ​

多智能体路由（高级用法） ​

3.5 用户身份映射 ​

3.6 配置文件详解 ​

目录结构 ​

主配置文件 ​

3.7 媒体消息 ​

3.8 自动化能力 ​

3.9 架构设计的启示 ​

本章小结 ​