第三章：Gateway 架构

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

本章概览

在这一章中，你将了解：

Gateway 是什么，为什么它是 OpenClaw 的核心
消息从聊天平台到 AI 的完整流转过程
多平台会话共享的工作原理
配置文件结构和重要参数
Daemon 模式的设置和管理

为什么要了解架构？

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

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

3.1 什么是 Gateway？

一句话解释

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

用一个比喻来理解

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

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

作为前台，你的工作是：

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

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

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

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

为什么需要 Gateway？

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

原因有三个：

1. 统一接口

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

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

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

2. 会话共享

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

3. 易于扩展

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

3.2 消息流转全过程

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

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

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

第一步：消息发出

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

当你在 Telegram 上发消息时，消息先到达 Telegram 的云端服务器，然后 Telegram 服务器通过你预先设置的 Webhook URL 把消息推送给 OpenClaw。

第二步：Gateway 接收

     │
     │ (2) Gateway 的 Telegram Connector 接收消息
     ▼
┌─────────────────────────────┐
│         Gateway             │
│  ┌────────────────────────┐ │
│  │ Telegram Connector     │ │ ← 接收 Telegram 格式的消息
│  │                        │ │
│  │ 解析消息内容：          │ │
│  │ - 发送者：你的 Telegram │ │
│  │ - 内容：帮我写...       │ │
│  │ - 时间：2025-xx-xx     │ │
│  └──────────┬─────────────┘ │
│             │               │
│             ▼               │
│  ┌────────────────────────┐ │
│  │ 消息标准化             │ │ ← 转换为统一格式
│  │ {                      │ │
│  │   platform: "telegram" │ │
│  │   user_id: "12345"     │ │
│  │   content: "帮我写..." │ │
│  │   timestamp: "..."     │ │
│  │ }                      │ │
│  └──────────┬─────────────┘ │
└─────────────┼───────────────┘
              │
              ▼

Gateway 中的 Telegram Connector（连接器）负责：

接收 Telegram 格式的消息
验证消息的合法性（安全检查）
将消息转换为 OpenClaw 的统一格式

第三步：路由到 AI Agent

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

Agent Engine 是 OpenClaw 的"大脑"，它负责：

加载用户的历史对话上下文
检查持久化记忆中是否有相关信息
调用 LLM（Claude / GPT 等）生成回复
如果需要，调用 Skills 执行具体任务

第四步：回复返回

              │
              │ (4) 回复通过 Gateway 返回到 Telegram
              ▼
┌─────────────────────────────┐
│         Gateway             │
│  ┌────────────────────────┐ │
│  │ 消息格式化             │ │ ← 将回复转换为 Telegram 格式
│  └──────────┬─────────────┘ │
│             │               │
│  ┌──────────▼─────────────┐ │
│  │ Telegram Connector     │ │ ← 通过 Telegram Bot API 发送
│  └──────────┬─────────────┘ │
└─────────────┼───────────────┘
              │
              ▼
┌──────────┐
│ Telegram │ ← 你在这里收到回复
│   App    │
└──────────┘

Gateway 把 AI 的回复：

转换成 Telegram 的消息格式
通过 Telegram Bot API 发送回你的对话

完整流程图

把上面的步骤合在一起：

你(Telegram) → Telegram 服务器 → Webhook → Gateway(Telegram Connector)
    → 消息标准化 → Agent Engine → LLM(Claude/GPT)
    → AI 回复 → Gateway → Telegram Connector → Telegram 服务器 → 你(Telegram)

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

3.3 多平台会话共享

这是 Gateway 架构最精妙的地方。

它是怎么工作的？

早上 8:00（WhatsApp）
你：帮我列一下今天的待办事项
AI：好的，今天你需要：
    1. 10:00 产品评审会
    2. 14:00 和设计师对需求
    3. 16:00 写周报

下午 15:00（Telegram）
你：第二项任务完成了，帮我更新一下
AI：收到！已更新你的待办事项：
    1. ✅ 10:00 产品评审会
    2. ✅ 14:00 和设计师对需求（已完成）
    3. ⬜ 16:00 写周报

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

用户身份映射

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

yaml

# Gateway 内部的用户映射（概念示意）
users:
  user_001:
    name: "张三"
    platforms:
      telegram: "tg_12345678"
      whatsapp: "+8613800138000"
      slack: "U0ABCDEFG"

当 Gateway 收到消息时，它会：

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

┌──────────────────────────────────────┐
│         用户身份映射机制              │
│                                      │
│  WhatsApp +86138xxx → user_001       │
│  Telegram @zhangsan  → user_001      │
│  Slack U0ABC         → user_001      │
│                                      │
│  所有平台的消息共享同一个会话上下文   │
└──────────────────────────────────────┘

配置身份映射

在实际使用中，你可以通过命令或配置文件来设置身份映射：

bash

# 添加 Telegram 账号映射
openclaw identity link telegram tg_12345678

# 添加 WhatsApp 账号映射
openclaw identity link whatsapp +8613800138000

# 查看当前映射
openclaw identity list

单人使用更简单

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

3.4 配置文件结构

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

目录结构详解

~/.openclaw/
│
├── config.yaml              # 主配置文件
│
├── gateway/                 # Gateway 相关配置
│   ├── platforms/           # 各平台的配置
│   │   ├── telegram.yaml    # Telegram 配置
│   │   ├── whatsapp.yaml    # WhatsApp 配置
│   │   └── slack.yaml       # Slack 配置
│   ├── routes.yaml          # 路由规则
│   └── identity.yaml        # 用户身份映射
│
├── conversations/           # 对话历史
│   ├── user_001/            # 按用户存储
│   │   ├── 2025-01-15.json  # 按日期分文件
│   │   └── 2025-01-16.json
│   └── user_002/
│
├── memory/                  # 持久化记忆
│   ├── user_001.json
│   └── user_002.json
│
├── skills/                  # 已安装的 Skills
│   ├── email-sender/
│   ├── calendar-sync/
│   └── web-browser/
│
├── logs/                    # 运行日志
│   ├── openclaw.log         # 主日志
│   ├── gateway.log          # Gateway 日志
│   └── error.log            # 错误日志
│
└── daemon/                  # Daemon 模式相关
    └── openclaw.pid         # 进程 ID 文件

主配置文件 config.yaml

yaml

# ~/.openclaw/config.yaml

# --- LLM 配置 ---
llm:
  provider: anthropic
  api_key: sk-ant-api03-xxxxx
  model: claude-sonnet-4-20250514
  max_tokens: 4096
  temperature: 0.7

# --- Gateway 配置 ---
gateway:
  # Gateway 监听端口
  port: 3000

  # 是否启用 HTTPS（生产环境建议启用）
  https:
    enabled: false
    cert_path: ""
    key_path: ""

  # 已启用的平台列表
  platforms:
    - telegram
    - whatsapp

  # Webhook 基础 URL（用于接收平台的回调）
  webhook_base_url: "https://your-domain.com"

  # 消息队列配置
  queue:
    max_concurrent: 5        # 最大并发处理数
    timeout: 30000           # 消息处理超时时间（毫秒）

# --- Agent 配置 ---
agent:
  name: "My Assistant"
  language: "zh-CN"
  system_prompt: |
    你是一个友好、专业的 AI 助手。
    请用中文回复用户的问题。
    保持回复简洁但信息完整。

# --- 记忆配置 ---
memory:
  enabled: true
  max_entries: 1000
  auto_summarize: true       # 自动总结长对话

# --- 安全配置 ---
security:
  # 白名单模式：只允许指定用户使用
  whitelist:
    enabled: true
    users:
      - telegram:tg_12345678
      - whatsapp:+8613800138000

  # 消息速率限制
  rate_limit:
    messages_per_minute: 20
    messages_per_hour: 200

# --- 日志配置 ---
logging:
  level: info
  file: ~/.openclaw/logs/openclaw.log
  max_size: 10MB
  max_files: 5

安全提醒

配置文件中包含 API Key 等敏感信息，请确保：

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

平台配置文件示例

每个平台有自己的配置文件：

yaml

# ~/.openclaw/gateway/platforms/telegram.yaml
platform: telegram
enabled: true
bot_token: "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
webhook_path: "/webhook/telegram"
allowed_users:
  - "tg_12345678"        # 你的 Telegram User ID
message_format:
  max_length: 4096        # Telegram 的消息长度限制
  parse_mode: "Markdown"  # 消息格式

yaml

# ~/.openclaw/gateway/platforms/whatsapp.yaml
platform: whatsapp
enabled: true
phone_number_id: "1234567890"
access_token: "EAAG..."
verify_token: "your-custom-verify-token"
webhook_path: "/webhook/whatsapp"
allowed_numbers:
  - "+8613800138000"

3.5 Daemon 模式

什么是 Daemon 模式？

Daemon（守护进程）模式让 OpenClaw 在后台持续运行，即使你关闭了终端窗口。

普通模式：
打开终端 → 运行 openclaw start → 关闭终端 → OpenClaw 停止

Daemon 模式：
运行 openclaw start --daemon → 关闭终端 → OpenClaw 继续运行

启动 Daemon 模式

bash

# 以 Daemon 模式启动
openclaw start --daemon

# 输出
🐾 OpenClaw daemon started (PID: 12345)
   Listening on port 3000
   Platforms: telegram, whatsapp
   Log file: ~/.openclaw/logs/openclaw.log

管理 Daemon

bash

# 查看状态
openclaw status

# 输出示例
🐾 OpenClaw Status
   Status:    Running (Daemon mode)
   PID:       12345
   Uptime:    2h 15m
   Port:      3000
   Platforms: telegram (connected), whatsapp (connected)
   Messages:  42 processed today
   LLM:       Claude Sonnet (anthropic)
   Memory:    156 MB

# 查看日志（实时）
openclaw logs --follow

# 重新启动
openclaw restart

# 停止
openclaw stop

开机自启动

如果你希望 OpenClaw 在电脑开机时自动启动：

macOS（使用 launchd）：

bash

# OpenClaw 提供了便捷命令
openclaw daemon install

# 这会创建一个 Launch Agent 配置
# ~/Library/LaunchAgents/com.openclaw.daemon.plist

Linux（使用 systemd）：

bash

# 创建 systemd 服务文件
openclaw daemon install

# 或手动创建
sudo tee /etc/systemd/system/openclaw.service << EOF
[Unit]
Description=OpenClaw AI Assistant
After=network.target

[Service]
Type=simple
User=$USER
ExecStart=$(which openclaw) start
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# 启用并启动
sudo systemctl enable openclaw
sudo systemctl start openclaw

Windows（使用任务计划程序）：

bash

openclaw daemon install

# 这会在 Windows 任务计划程序中创建一个任务
# 开机时自动以后台模式启动 OpenClaw

推荐配置

对于日常使用，建议设置开机自启动。这样你的 AI 助手就像一个真正的 7x24 在线的秘书，随时随地可以通过聊天平台联系它。

3.6 Gateway 的进阶特性

消息队列

当多个平台同时收到消息时，Gateway 使用消息队列确保有序处理：

同时到达的消息：
  Telegram: "明天有什么安排？"
  WhatsApp: "帮我写个邮件"
  Slack:    "查一下项目进度"

Gateway 消息队列：
  [1] Telegram 消息 → 处理中...
  [2] WhatsApp 消息 → 等待中
  [3] Slack 消息    → 等待中

你可以在配置中调整并发处理数：

yaml

gateway:
  queue:
    max_concurrent: 5    # 最多同时处理 5 条消息
    timeout: 30000       # 30 秒超时

路由规则

Gateway 支持自定义路由规则，例如把不同平台的消息路由到不同的 Agent 配置：

yaml

# ~/.openclaw/gateway/routes.yaml
routes:
  - platform: telegram
    agent_profile: personal    # 私人助手风格
  - platform: slack
    agent_profile: professional  # 职业助手风格
  - platform: whatsapp
    agent_profile: casual      # 随意闲聊风格

Webhook 安全

Gateway 内置了多层安全机制：

yaml

security:
  # 1. 验证消息签名（确保消息真的来自对应平台）
  verify_signatures: true

  # 2. IP 白名单（只接受来自平台服务器的请求）
  ip_whitelist:
    enabled: true

  # 3. 速率限制（防止滥用）
  rate_limit:
    enabled: true
    max_requests_per_minute: 60

3.7 架构设计的启示

给产品经理的思考

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

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

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

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

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

本章小结

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

Gateway 的角色 -- 消息路由中枢，是 OpenClaw 的核心组件
消息流转过程 -- 从聊天平台到 AI 再返回的完整链路
多平台会话共享 -- 通过用户身份映射实现跨平台上下文保持
配置文件结构 -- ~/.openclaw/ 目录的完整组织方式
Daemon 模式 -- 让 OpenClaw 在后台持续运行

下一步

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

第三章：Gateway 架构 ​

本章概览 ​

3.1 什么是 Gateway？ ​

一句话解释 ​

用一个比喻来理解 ​

为什么需要 Gateway？ ​

3.2 消息流转全过程 ​

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

第一步：消息发出 ​

第二步：Gateway 接收 ​

第三步：路由到 AI Agent ​

第四步：回复返回 ​

完整流程图 ​

3.3 多平台会话共享 ​

它是怎么工作的？ ​

用户身份映射 ​

配置身份映射 ​

3.4 配置文件结构 ​

目录结构详解 ​

主配置文件 config.yaml ​

平台配置文件示例 ​

3.5 Daemon 模式 ​

什么是 Daemon 模式？ ​

启动 Daemon 模式 ​

管理 Daemon ​

开机自启动 ​

3.6 Gateway 的进阶特性 ​

消息队列 ​

路由规则 ​

Webhook 安全 ​

3.7 架构设计的启示 ​

本章小结 ​

第三章：Gateway 架构

本章概览

3.1 什么是 Gateway？

一句话解释

用一个比喻来理解

为什么需要 Gateway？

3.2 消息流转全过程

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

第一步：消息发出

第二步：Gateway 接收

第三步：路由到 AI Agent

第四步：回复返回

完整流程图

3.3 多平台会话共享

它是怎么工作的？

用户身份映射

配置身份映射

3.4 配置文件结构

目录结构详解

主配置文件 config.yaml

平台配置文件示例

3.5 Daemon 模式

什么是 Daemon 模式？

启动 Daemon 模式

管理 Daemon

开机自启动

3.6 Gateway 的进阶特性

消息队列

路由规则

Webhook 安全

3.7 架构设计的启示

本章小结