五层架构拆解：一条消息从到达到执行的完整链路

第五章：五层架构拆解：一条消息从到达到执行的完整链路

5.1 五层架构总览

OpenClaw 的架构被设计为严格的五层模型，每一层有清晰的职责边界和技术实现。这种分层设计使得每一层可以独立演进，而不影响其他层的稳定性。

┌─────────────────────────────────────────────────────────────────┐
│  Layer 1: Input Sources                                         │
│  WhatsApp / Telegram / Slack / Discord / Email / Webhook / ...  │
└─────────────────────────┬───────────────────────────────────────┘
                          │ 原始平台消息
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 2: Integration Gateway                                   │
│  Channel Bridge │ Session Manager │ Command Queue │ Plugin Registry │
└─────────────────────────┬───────────────────────────────────────┘
                          │ InternalMessage（标准化）
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 3: Agent Core (Pi)                                       │
│  pi-ai │ pi-agent-core │ ReAct Loop │ Tool Registry             │
└─────────────────────────┬───────────────────────────────────────┘
                          │ ToolCall 请求
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 4: Action Layer                                          │
│  Tool Executor │ HITL Approval │ Integration Adapters           │
└─────────────────────────┬───────────────────────────────────────┘
                          │ API 调用 / 系统操作
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 5: External Systems                                      │
│  LLM Providers │ CRM │ Calendar │ Database │ Custom APIs        │
└─────────────────────────────────────────────────────────────────┘

每层的技术实现和关键边界：

5.2 完整时序图

以下是一条 WhatsApp 消息从到达 OpenClaw 到响应返回用户的完整时序图：

用户        WhatsApp    Channel     Gateway     Command     Pi          LLM        Action
(手机)      Business    Bridge      Core        Queue       Agent       Provider   Layer
  │           │           │           │           │           │           │          │
  │─发送消息──►│           │           │           │           │           │          │
  │           │─Webhook──►│           │           │           │           │          │
  │           │           │─解析消息──►│           │           │           │          │
  │           │           │           │─Session─► │           │           │          │
  │           │           │           │  解析     │           │           │          │
  │           │           │           │─写入─────►│           │           │          │
  │           │           │           │  Queue    │           │           │          │
  │           │           │           │           │─调度─────►│           │          │
  │           │           │           │           │           │─加载──────►           │
  │           │           │           │           │           │  Memory   │          │
  │           │           │           │           │           │─发起─────────────►   │
  │           │           │           │           │           │  Completion│          │
  │           │           │           │           │           │◄──响应─────────────   │
  │           │           │           │           │           │  (ToolCall)|          │
  │           │           │           │           │           │─执行工具──────────────►│
  │           │           │           │           │           │◄──工具结果────────────│
  │           │           │           │           │           │─再次发起───────────►  │
  │           │           │           │           │           │  Completion│          │
  │           │           │           │           │           │◄──最终响应─────────── │
  │           │           │           │◄─响应─────│           │           │          │
  │           │           │◄─格式化───│           │           │           │          │
  │           │◄─发送─────│           │           │           │           │          │
  │◄─收到回复──│           │           │           │           │           │          │

典型延迟分布（使用 Anthropic Claude Sonnet，单次工具调用）：

5.3 第一层：Input Sources

支持的 20+ 消息平台

Input Sources 层是用户消息进入 OpenClaw 系统的入口点。OpenClaw 支持的平台分为以下几类：

即时通讯平台：

工单与支持平台：

邮件与协作平台：

自定义接入：

平台特殊性的处理

不同平台的消息格式差异很大。WhatsApp 的消息有 from（E.164 手机号）、type（text/image/audio）、timestamp；Slack 的消息有 user（用户ID）、channel（频道ID）、thread_ts（线程时间戳）。

Channel Bridge 的核心职责就是屏蔽这些差异，将所有平台的消息转换为统一的 InternalMessage 格式，使 Gateway 的后续处理与平台无关。

Channel Bridge 配置示例

{
  "channels": [
    {
      "id": "whatsapp-main",
      "type": "whatsapp",
      "name": "WhatsApp Business Main",
      "config": {
        "phoneNumberId": "${WHATSAPP_PHONE_NUMBER_ID}",
        "accessToken": "${WHATSAPP_ACCESS_TOKEN}",
        "verifyToken": "${WHATSAPP_VERIFY_TOKEN}",
        "webhookPath": "/webhooks/whatsapp"
      }
    },
    {
      "id": "telegram-bot",
      "type": "telegram",
      "name": "Telegram Support Bot",
      "config": {
        "botToken": "${TELEGRAM_BOT_TOKEN}",
        "mode": "webhook",
        "webhookUrl": "https://your-domain.com/webhooks/telegram"
      }
    },
    {
      "id": "slack-workspace",
      "type": "slack",
      "name": "Internal Slack Workspace",
      "config": {
        "botToken": "${SLACK_BOT_TOKEN}",
        "signingSecret": "${SLACK_SIGNING_SECRET}",
        "appToken": "${SLACK_APP_TOKEN}",
        "socketMode": true
      }
    }
  ]
}

5.4 第二层：Integration Gateway

Integration Gateway 是整个系统的核心调度中心，以单个 Node.js 进程运行。

Channel Bridge 子系统

Gateway 内嵌所有 Channel Bridge，统一管理它们的生命周期：

Gateway 进程启动时：
1. 读取 channels 配置
2. 为每个 channel 实例化对应的 Channel Bridge 类
3. 调用 bridge.connect() 建立与平台的连接
4. 注册消息处理回调（bridge.onMessage → gateway.handleIncoming）
5. 启动 Webhook 服务器（统一的 HTTP 服务，路由到各 Bridge）

Channel Bridge 的消息接收有两种模式：

• 推送模式（Webhook）：平台主动推送，延迟低，适合 WhatsApp、Slack 等
• 拉取模式（Polling）：Gateway 定期拉取，适合 Email、某些不支持 Webhook 的平台

Session 管理子系统

Session 管理是 Gateway 中最复杂的子系统之一。它需要解决的核心问题是：如何将来自不同平台、不同用户的消息，准确地映射到对应的 Agent Session。

Session 标识符的构成：

Session ID = channelId + "/" + senderId + "/" + threadId（可选）

示例：
  whatsapp-main/+8613812345678                    （WhatsApp 用户）
  telegram-bot/987654321                           （Telegram 用户）
  slack-workspace/U01ABC123/thread:1234567890.001  （Slack 线程）

Session 生命周期：

消息到达
   │
   ├─ Session ID 已存在？
   │  ├─ 是 → 加载现有 Session（恢复对话历史）
   │  └─ 否 → 创建新 Session（初始化 Memory）
   │
Session 处理中
   │
   ├─ 30分钟无新消息 → Session 进入 Idle 状态（Memory 写回磁盘）
   ├─ 24小时无新消息 → Session 过期（Short-term Memory 清理）
   └─ 用户发送 /reset → 手动重置 Session

Command Queue 子系统

Command Queue 是 Gateway 的并发控制核心。它的 Lane 设计解决了一个根本矛盾：希望系统整体高并发，但同时保证单个 Session 内的消息有序处理。

┌──────────────────────────────────────────────────────────────────┐
│  Command Queue 内部实现                                           │
│                                                                  │
│  Global Lane    ┌──────────────────────────────────────────┐    │
│  (max: 4)       │ ConfigReload │ PluginInstall │  DB Backup │    │
│                 └──────────────────────────────────────────┘    │
│                                                                  │
│  Session Lane   ┌─────┐ ┌─────┐ ┌─────┐                        │
│  (per session,  │Sess1│ │Sess2│ │Sess3│ ... N sessions          │
│   max: 1 each)  │ msg │ │ msg │ │ msg │                        │
│                 └─────┘ └─────┘ └─────┘                        │
│                                                                  │
│  SubAgent Lane  ┌──┐┌──┐┌──┐┌──┐┌──┐┌──┐┌──┐┌──┐             │
│  (max: 8)       │SA││SA││SA││SA││SA││SA││SA││SA│             │
│                 └──┘└──┘└──┘└──┘└──┘└──┘└──┘└──┘             │
│                                                                  │
│  Cron Lane      ⏰ Task1  ⏰ Task2  ⏰ Task3  ... (unlimited)   │
└──────────────────────────────────────────────────────────────────┘

steer-backlog 模式的重要性：当用户在短时间内连续发送多条消息（比如先发"帮我查一下"，然后发"订单号 12345"，然后发"谢谢"），Session Lane 会将前两条消息合并处理（steer-backlog），避免 Pi 对不完整的消息做出响应。

Plugin Registry 子系统

Plugin Registry 是 Gateway 的扩展点管理器。它维护一个 Plugin 注册表，管理 Plugin 的加载顺序（某些 Plugin 可能依赖其他 Plugin）、初始化状态和健康检查。

// Plugin Registry 提供的接口（简化）
interface PluginRegistry {
  register(plugin: PluginDefinition): void;
  getChannelBridge(type: string): ChannelBridge;
  getMiddleware(phase: 'pre' | 'post'): Middleware[];
  getGlobalService(name: string): any;
}

5.5 第三层：Agent Core (Pi)

Pi 的推理循环（ReAct Pattern）

Pi 使用 ReAct（Reasoning + Acting）模式执行推理循环：

1. Thought:  分析当前情况，决定下一步动作
2. Action:   调用一个工具（read/write/edit/bash 或 Skill 暴露的工具）
3. Observation: 接收工具执行结果
4. ... 重复 1-3 直到任务完成 ...
5. Response: 生成最终响应，返回给用户

Pi 的 System Prompt 设计是高度精炼的，保持在 < 1000 tokens：

你是 {agentName}，运行在 OpenClaw 框架上的 AI 助手。

你有以下工具可用：
- read(path): 读取文件或 URL 内容
- write(path, content): 写入文件
- edit(path, old, new): 精确编辑文件
- bash(command): 执行 shell 命令

{skillsContext}  ← 当前激活的 Skills 描述（动态注入）

当前 Session 信息：
- 用户: {userId}
- Channel: {channelName}
- 时间: {currentTime}

{memoryContext}  ← 从 Long-term Memory 检索的相关上下文（动态注入）

请用简洁、专业的方式回答用户的问题。需要使用工具时，先思考再行动。

pi-agent-core 的核心数据结构

// 推理循环的核心状态（简化）
interface AgentSession {
  id: string;
  agentId: string;
  messages: Message[];           // Short-term Memory（当前对话）
  tools: Tool[];                 // 当前可用工具列表
  maxIterations: number;         // 防止无限循环（默认 20）
  currentIteration: number;
  status: 'running' | 'waiting' | 'complete' | 'error';
}

interface Message {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string | ToolCall[] | ToolResult[];
}

interface ToolCall {
  id: string;
  name: string;
  input: Record<string, unknown>;
}

LLM 调用的重试与容错

Pi 对 LLM API 调用实现了指数退避重试：

// 重试配置（可在 openclaw.json 中覆盖）
{
  "llm": {
    "retryConfig": {
      "maxRetries": 3,
      "initialDelayMs": 1000,
      "maxDelayMs": 30000,
      "backoffMultiplier": 2,
      "retryOn": [429, 500, 502, 503, 504]
    }
  }
}

5.6 第四层：Action Layer

Tool 执行引擎

Action Layer 负责实际执行 Pi 请求的工具调用。它是 Pi 与外部世界之间的执行层。

工具执行流程：

Pi 发出 ToolCall
    │
    ▼
Action Layer 接收
    │
    ├─ 工具是否在审批白名单？
    │  ├─ 是 → 直接执行
    │  └─ 否 → 进入 HITL 审批队列
    │           │
    │           ├─ 等待人工审批（Control UI 显示请求）
    │           │  ├─ 审批通过 → 继续执行
    │           │  ├─ 拒绝 → 返回拒绝信息给 Pi
    │           │  └─ 超时（默认 300s）→ 取消执行
    │
    ▼
执行工具（bash/read/write/edit 或集成适配器）
    │
    ▼
返回 ToolResult 给 Pi

Human-in-the-Loop（HITL）审批

HITL 是 OpenClaw 生产安全的重要机制。它允许你为高风险操作设置强制的人工审批关卡。

配置 HITL 规则：

{
  "hitl": {
    "enabled": true,
    "rules": [
      {
        "id": "require-approval-for-writes",
        "description": "需要审批所有文件写入操作",
        "condition": {
          "tool": "write",
          "pathPattern": "/etc/**"
        },
        "action": "require_approval",
        "timeout": 300,
        "notifyChannels": ["slack-workspace"]
      },
      {
        "id": "require-approval-for-payments",
        "description": "需要审批所有支付操作",
        "condition": {
          "integration": "stripe",
          "methods": ["createPayment", "createRefund"]
        },
        "action": "require_approval",
        "approvers": ["[email protected]"]
      },
      {
        "id": "auto-approve-reads",
        "description": "自动批准所有只读操作",
        "condition": {
          "tool": ["read", "bash"],
          "bashPattern": "^(ls|cat|grep|find|curl -G).*"
        },
        "action": "auto_approve"
      }
    ]
  }
}

在 Control UI 中，HITL 审批队列会实时显示待审批的操作，包括：

• 操作的完整参数
• 触发该操作的对话上下文
• 预计影响范围
• 一键审批/拒绝按钮

集成适配器

对于 50+ 官方集成，Action Layer 提供对应的集成适配器，将 Pi 的工具调用转换为具体的 API 请求：

Pi 调用: tool("hubspot.createContact", { name: "Alice", email: "[email protected]" })
         ↓
Action Layer:
  1. 查找 "hubspot" 集成适配器
  2. 调用适配器的 createContact 方法
  3. 适配器构建 HubSpot API 请求：
     POST https://api.hubapi.com/crm/v3/objects/contacts
     Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}
     { "properties": { "firstname": "Alice", "email": "[email protected]" } }
  4. 处理响应，返回标准化的 ToolResult
         ↓
Pi 接收: { success: true, contactId: "1234567", url: "https://app.hubspot.com/..." }

集成配置示例

{
  "integrations": [
    {
      "id": "hubspot",
      "type": "hubspot",
      "config": {
        "accessToken": "${HUBSPOT_ACCESS_TOKEN}",
        "portalId": "${HUBSPOT_PORTAL_ID}"
      },
      "permissions": {
        "read": true,
        "write": true,
        "requireApproval": ["deleteContact", "deleteCompany"]
      }
    },
    {
      "id": "google-calendar",
      "type": "google-calendar",
      "config": {
        "serviceAccountKey": "${GOOGLE_SERVICE_ACCOUNT_KEY}",
        "delegatedUser": "[email protected]"
      },
      "permissions": {
        "read": true,
        "write": true,
        "requireApproval": ["deleteEvent"]
      }
    }
  ]
}

5.7 第五层：External Systems

LLM Provider 管理

External Systems 层中最重要的外部系统是 LLM Provider。OpenClaw 通过 pi-ai 包抽象了不同 Provider 的 API 差异。

支持的 LLM Provider 及关键参数：

多 Provider 故障转移配置：

{
  "llm": {
    "providers": [
      {
        "id": "anthropic-primary",
        "type": "anthropic",
        "apiKey": "${ANTHROPIC_API_KEY}",
        "defaultModel": "claude-sonnet-4-5-20251201",
        "priority": 1
      },
      {
        "id": "openai-fallback",
        "type": "openai",
        "apiKey": "${OPENAI_API_KEY}",
        "defaultModel": "gpt-4o-mini",
        "priority": 2
      }
    ],
    "failoverPolicy": {
      "enabled": true,
      "failoverOn": [429, 500, 503],
      "maxFailoverAttempts": 2
    }
  }
}

当主 Provider 返回错误时，Pi 会自动切换到次级 Provider，保证服务可用性。

CRM 集成

CRM 集成使 Agent 能够读写客户数据，是客服和销售场景的核心能力：

支持的 CRM：
  Salesforce    → SOQL 查询 + REST API
  HubSpot       → CRM API v3
  Pipedrive     → REST API v1/v2
  Zoho CRM      → REST API v4
  Freshsales    → REST API

日历集成

支持的日历服务：
  Google Calendar  → Calendar API v3
  Outlook          → Microsoft Graph Calendar API
  Calendly         → API v2（查询和创建预约）
  Cal.com          → REST API（开源日历）

文档集成

支持的文档服务：
  Notion           → Notion API（读写 Page 和 Database）
  Confluence       → REST API v2（读写空间和页面）
  Google Docs      → Google Docs API（读写文档）
  Google Drive     → Drive API（文件搜索和读取）
  SharePoint       → Microsoft Graph API

数据库集成（只读模式）

为了安全起见，数据库集成默认只支持只读操作（SELECT 查询）：

{
  "integrations": [
    {
      "id": "main-db",
      "type": "postgresql",
      "config": {
        "host": "localhost",
        "port": 5432,
        "database": "myapp",
        "user": "${DB_USER}",
        "password": "${DB_PASSWORD}",
        "ssl": true
      },
      "permissions": {
        "mode": "readonly",
        "allowedTables": ["users", "orders", "products"]
      }
    }
  ]
}

如果需要写入权限，必须通过 HITL 配置明确授权，并为每个写操作设置审批要求。

5.8 边界与安全设计

层级间的安全边界

五层架构不仅仅是功能分层，也是安全分层：

Input Sources 层：
  └─ 鉴权：验证 Webhook 签名（WhatsApp HMAC-SHA256 / Slack 签名验证）
  └─ 速率限制：每个 Channel 独立的消息速率限制
  └─ 内容过滤：可选的内容安全过滤中间件

Integration Gateway 层：
  └─ Session 隔离：不同 Session 的数据完全隔离
  └─ Command 验证：所有发往 Pi 的命令经过 Schema 验证
  └─ Single-writer：数据库写入唯一入口

Agent Core 层：
  └─ 工具沙箱：bash 工具可配置为沙箱模式（受限 shell）
  └─ 迭代限制：防止 Pi 陷入无限推理循环
  └─ Token 预算：每次 LLM 调用的最大 token 数限制

Action Layer 层：
  └─ HITL：高风险操作强制人工审批
  └─ 只读模式：数据库集成默认只读
  └─ 权限白名单：每个集成明确声明允许的操作

External Systems 层：
  └─ 密钥隔离：API Key 通过环境变量注入，不出现在配置文件
  └─ 最小权限：每个集成只申请所需的最小权限 scope

审计日志

所有跨层边界的操作都会生成审计日志：

{
  "timestamp": "2026-04-26T10:30:00.123Z",
  "level": "audit",
  "event": "tool_executed",
  "sessionId": "whatsapp-main/+8613812345678",
  "agentId": "support-agent",
  "tool": "hubspot.createContact",
  "input": { "name": "Alice", "email": "[email protected]" },
  "result": { "success": true, "contactId": "1234567" },
  "hitlApproval": { "required": false, "autoApproved": true },
  "durationMs": 342,
  "llmTokensUsed": { "input": 2341, "output": 187 }
}

小结

本章完整拆解了 OpenClaw 的五层架构：

Layer 1 - Input Sources：20+ 消息平台通过 Channel Bridge 统一接入，每个平台的特殊格式在这一层被抹平。

Layer 2 - Integration Gateway：核心调度中心，负责 Session 解析（8级优先级 Binding）、Command Queue（4个 Lane，4种模式）、Plugin Registry 管理。Single-writer Pattern 保证数据一致性。

Layer 3 - Agent Core (Pi)：使用 ReAct 模式的推理引擎，嵌入式执行（非 subprocess），仅 4 个基础工具，System Prompt < 1000 tokens，追求低延迟和高并发。

Layer 4 - Action Layer：Tool 执行与 HITL 审批的执行层，是 Pi 的"手"，也是安全的最后一道关卡。

Layer 5 - External Systems：LLM Provider、CRM、日历、文档、数据库等外部系统的集成点，通过统一的集成适配器屏蔽 API 差异。

理解这五层的职责边界和数据流向，是深度使用 OpenClaw 进行生产部署的基础。从 WhatsApp 消息到 Agent 响应，整个链路在 1-5 秒内完成，每一毫秒的延迟都有明确的归因。

这就是《OpenClaw 完全指南》的前五章。从产品理解（ch01）到实操安装（ch02），从概念全景（ch03）到竞品对比（ch04），再到架构拆解（ch05），你现在具备了深入使用 OpenClaw 所需的全部基础知识。