前言

理解一个系统的数据流是掌握其架构的关键。本文将从消息的输入到响应的输出，全面剖析 OpenClaw 的数据流动过程。

1. 数据流全景

1.1 完整数据流图

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              OpenClaw 数据流全景                                  │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│   [外部消息源]                                                                    │
│   💬 Telegram  💬 Discord  💬 Slack  📧 Email  🌐 Web                            │
│            │                                                                     │
│            ▼                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────┐   │
│   │  Layer 1: Channel Transport                                             │   │
│   │  • WebSocket / Webhook 接收                                             │   │
│   │  • 平台协议解析 → 统一消息格式                                           │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│            │                                                                     │
│            ▼                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────┐   │
│   │  Layer 2: Inbound Processing                                             │   │
│   │  • 身份认证  • 权限验证  • 白名单检查  • 速率限制  • 垃圾过滤            │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│            │                                                                     │
│            ▼                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────┐   │
│   │  Layer 3: Session Management                                            │   │
│   │  • 会话路由  • 新建/恢复会话  • 上下文加载  • 记忆检索                   │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│            │                                                                     │
│            ▼                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────┐   │
│   │  Layer 4: Pre-Processing Hooks                                          │   │
│   │  before-agent-start → 消息预处理 → 上下文增强 → 指令注入                 │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│            │                                                                     │
│            ▼                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────┐   │
│   │  Layer 5: Agent Processing (核心层)                                     │   │
│   │                                                                             │   │
│   │  Context Builder ──► AI Model ──► Tool Executor                         │   │
│   │       │                    │              │                             │   │
│   │       │    ┌───────────────┘              │                             │   │
│   │       │    │         (循环直到完成)         │                             │   │
│   │       └────┘                              │                             │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│            │                                                                     │
│            ▼                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────┐   │
│   │  Layer 6-7: Post-Processing & Approval                                  │   │
│   │  after-agent-reply → 响应过滤 → 风险评估 → 审批/放行/拒绝               │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│            │                                                                     │
│            ▼                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────┐   │
│   │  Layer 8-10: Outbound & Persistence                                     │   │
│   │  格式转换 → 投递队列 → 会话持久化 → 响应发送                           │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

2. 配置加载流程

2.1 配置层次结构

openclaw.yaml (用户配置)
        │
        ▼
┌──────────────────┐
│  Schema Validate │
│    (Zod Schema)  │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Config Merge    │
│   & Normalize    │
└────────┬─────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌───────┐ ┌───────┐
│Memory │ │Plugins│
│Config │ │Config │
└───┬───┘ └───┬───┘
    │         │
    ▼         ▼
┌─────────┐ ┌─────────┐
│ Session │ │Capability│
│ Store   │ │Registry │
└─────────┘ └─────────┘

3. 会话状态管理

3.1 Session 状态机

           CREATED
              │
              ▼
           ACTIVE ◄──────────────┐
              │                   │
    ┌─────────┼─────────┐        │恢复
    │         │         │        │
    ▼         ▼         ▼        │
 IDLE     PAUSED    CLOSING      │
    │         │         │        │
    └─────────┼─────────┘        │
              │                   │
              └───────────────────┘
                   (重新激活)

CLOSING ──► CLOSED

4. 错误处理与重试

4.1 错误分类

4.2 重试配置

const retryConfig = {
  maxAttempts: 3,
  baseDelay: 1000,
  maxDelay: 30000,
  backoffMultiplier: 2,
  jitter: true,
};

5. 本章小结

┌─────────────────────────────────────────────────────────────────┐
│                        本章要点                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  🔄 数据流层次                                                   │
│  ├── 渠道传输 → 入站处理 → 会话管理                             │
│  ├── 前置钩子 → Agent处理 → 后置钩子                           │
│  └── 审批流程 → 出站处理 → 持久化                              │
│                                                                  │
│  💾 配置加载                                                    │
│  └── YAML → Zod验证 → 多源合并 → 注入                          │
│                                                                  │
│  📊 状态管理                                                    │
│  └── 创建 → 活跃 → 空闲/暂停/关闭 → 关闭                       │
│                                                                  │
│  🔄 错误处理                                                    │
│  └── 分类 → 重试策略 → 降级方案                                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

系列导航

如有问题欢迎在评论区留言！