核心概念全景：Gateway / Pi / Skills / Plugin / Memory 的关系图

第三章：核心概念全景：Gateway / Pi / Skills / Plugin / Memory 的关系图

3.1 五大核心组件概览

在深入每个组件之前，先用一句话定义每个组件的职责边界。这一精确定义将帮助你在后续实践中做出正确的架构决策。

这五个组件共同构成了 OpenClaw 的完整运行时。它们之间的关系不是线性的层级，而是围绕 Pi 的星形结构，由 Gateway 负责边界通信。

3.2 完整数据流：从 WhatsApp 到用户

理解数据流是理解 OpenClaw 架构的最直接方式。下面是一条 WhatsApp 消息从到达到响应的完整链路：

用户 (WhatsApp)
    │
    ▼ [HTTPS Webhook]
WhatsApp Business API
    │
    ▼ [HTTP POST]
Channel Bridge (whatsapp)
    │  解析原始消息格式，提取文本、附件、发送者信息
    │  转换为统一的 InternalMessage 格式
    ▼
Integration Gateway (Node.js 进程)
    │  Session 解析（按8级优先级匹配 Binding 规则）
    │  Command Queue 调度（写入对应 Lane）
    ▼
Pi Agent Core (嵌入式，非 subprocess)
    │  加载 System Prompt + Session Memory
    │  调用 LLM Provider（Anthropic Claude API）
    │  执行工具调用循环（read/write/edit/bash）
    │  查询/更新 Memory
    ▼
Action Layer
    │  执行外部集成调用（如果 Pi 决定调用 HubSpot、Jira 等）
    │  Human-in-the-loop 审批（高风险动作暂停等待）
    │  工具结果返回给 Pi
    ▼
Pi Agent Core (生成最终响应)
    │
    ▼
Integration Gateway (接收响应)
    │
    ▼
Channel Bridge (whatsapp)
    │  将响应格式化为 WhatsApp 消息格式
    ▼
WhatsApp Business API
    │
    ▼
用户收到回复

这个链路中涉及多次格式转换，但每次转换都有明确的边界和协议。下面我们逐一拆解每个节点。

3.3 Gateway 深度解析

Gateway 的核心职责

Gateway 是整个 OpenClaw 系统的边界进程，是外部世界与内部 Agent 世界的分界线。它以单个 Node.js 进程的形式运行，通过 WebSocket（localhost:18789）与 Pi 进程通信。

Gateway 有四个核心子系统：

1. Channel Bridge 集合

每个消息平台有一个对应的 Channel Bridge。Channel Bridge 负责：

• 维护与外部平台的连接（WebSocket、HTTP 长轮询、Webhook 接收）
• 将平台特定的消息格式转换为 InternalMessage
• 将 InternalResponse 转换回平台特定格式
• 处理平台特定的鉴权（如 WhatsApp 的签名验证）

// InternalMessage 的核心结构（简化）
interface InternalMessage {
  id: string;              // 消息唯一ID
  channelId: string;       // 来源 Channel
  senderId: string;        // 发送者在平台上的ID
  content: MessageContent; // 消息内容（文本/附件/位置等）
  metadata: {
    platform: string;      // 'whatsapp' | 'telegram' | 'slack' | ...
    timestamp: number;
    replyTo?: string;      // 引用消息ID（如果有）
    threadId?: string;     // 线程ID（Slack thread 等）
  };
  sessionContext?: SessionContext; // Session 解析结果（由 Gateway 填充）
}

2. Session 管理系统

Session 是 Pi 与特定用户在特定 Channel 上的一次持续对话上下文。Session 解析是 Gateway 的核心逻辑之一。

3. Command Queue

Gateway 内置一个四 Lane 的优先级队列，管理所有发往 Pi 的命令调度。

4. Plugin Registry

维护已安装 Plugin 的注册表，管理 Plugin 的生命周期（加载、启动、停止）。

Single-writer Pattern 的意义

Gateway 使用 Single-writer Pattern：任何时刻，只有一个进程（Gateway）向 SQLite 数据库写入数据，Pi 进程通过 Gateway 的接口访问 Memory，不直接操作数据库。

这个设计解决了以下问题：

• 避免 SQLite 的并发写入锁定问题
• 统一了事务管理和数据一致性控制
• 简化了 Pi 进程的职责（Pi 只需关心推理，不需要关心持久化）

Session 解析的 8 级优先级

当一条消息到达时，Gateway 需要确定这条消息属于哪个 Session，进而确定应该由哪个 Agent 处理、使用哪个配置。Session 解析按以下优先级顺序匹配 Binding 规则：

1. peer match      → 消息来自特定的对端标识符（精确的用户ID匹配）
2. parent          → 继承父 Session 的配置（用于多轮对话中的子任务）
3. guild + role    → Discord/Slack 中特定服务器+特定身份的组合
4. guild           → Discord/Slack 中特定服务器的所有用户
5. team            → 组织级别的配置
6. account         → 用户账号级别的配置
7. channel         → Channel 级别的默认配置
8. default         → 全局默认配置

优先级越高（数字越小），匹配越精确。这个机制允许你为不同用户配置不同的 Agent 行为，同时保持一个合理的默认值。

配置示例：

{
  "bindings": [
    {
      "priority": 1,
      "match": { "type": "peer", "peerId": "user:[email protected]" },
      "agent": "vip-agent",
      "config": { "model": "claude-opus-4-5-20251201" }
    },
    {
      "priority": 7,
      "match": { "type": "channel", "channelId": "whatsapp-business" },
      "agent": "support-agent",
      "config": { "model": "claude-haiku-3-5-20251201" }
    }
  ]
}

3.4 Pi 框架深度解析

Pi 的四个核心包

Pi 框架由四个 npm 包组成，每个包有明确的职责：

pi-ai/
  ├── 功能：LLM Provider 适配层
  ├── 职责：统一不同 Provider 的 API 调用接口
  └── 关键接口：LLMProvider, CompletionRequest, CompletionResponse

pi-agent-core/
  ├── 功能：Pi 的核心推理引擎
  ├── 职责：管理推理循环（ReAct 模式），调度工具调用，管理 Session 状态
  └── 关键接口：AgentSession, ToolRegistry, ReasoningLoop

pi-coding-agent/
  ├── 功能：面向编码场景的扩展 Agent
  ├── 职责：扩展 pi-agent-core，增加代码理解、测试生成等专用工具
  └── 关键接口：CodeContext, FileSystem, TestRunner

pi-tui/
  ├── 功能：Terminal UI（TUI 模式的 Control UI）
  ├── 职责：在没有浏览器的环境下提供可视化管理界面
  └── 关键接口：Dashboard, SessionViewer, LogStream

Pi 的四个基础工具

Pi 只暴露 4 个基础工具，这是一个刻意的设计决策，而非功能不足：

业务集成（调用 HubSpot API、查询 Jira 等）不是通过扩展这 4 个工具实现的，而是通过 Skills 和 Action Layer 实现的。Pi 的工具集保持最小化，让 System Prompt 可以控制在 1000 tokens 以内，这对性能和成本有显著影响。

嵌入式执行 vs Subprocess

Pi 作为 嵌入式模块 运行在 Gateway 进程中，而不是作为独立的子进程。这个设计有重要的性能和架构含义：

子进程模式（传统方式）：

Gateway ──IPC/HTTP──► Pi 子进程
  延迟：5-20ms（进程间通信）
  内存：Gateway + Pi 各自独立内存空间
  隔离性：强（进程崩溃不影响对方）

嵌入式模式（OpenClaw 方式）：

Gateway [Pi 模块在同一进程内]
  延迟：< 0.1ms（函数调用）
  内存：共享内存空间，Pi 直接访问 Gateway 内部数据结构
  隔离性：弱（但通过 TypeScript 类型系统和模块边界保证接口隔离）

嵌入式模式使 Pi 可以直接读取 Gateway 的 Session 状态、Memory 缓存，无需序列化/反序列化，这对高并发场景（Command Queue 中同时处理多个 Sub-agent 任务）的延迟和吞吐量有显著优势。

3.5 Command Queue 详解

Command Queue 是 Gateway 的任务调度中心，管理所有发往 Pi 的命令执行顺序。它的设计目标是：在保证 Session 内消息有序处理的同时，最大化整体并发吞吐量。

四个 Lane

┌─────────────────────────────────────────────────────────────┐
│                      Command Queue                          │
│                                                             │
│  Global Lane    [====] [====] [====] [====]  max: 4        │
│  Session Lane   [================================]  max: 1  │
│  SubAgent Lane  [=][=][=][=][=][=][=][=]     max: 8        │
│  Cron Lane      [=][=][=][=]...              max: ∞        │
└─────────────────────────────────────────────────────────────┘

Global Lane（并发上限：4）：处理需要独占资源的全局任务，如配置重载、Plugin 安装、数据库备份。并发上限为 4 防止资源争用。

Session Lane（并发上限：1）：每个活跃 Session 有自己独立的 Session Lane，并发上限为 1。这保证了同一个用户的消息按序处理，不会出现响应乱序的问题。Session Lane 是 Pi 处理用户消息的主要通道。

SubAgent Lane（并发上限：8）：当 Pi 在处理一个任务时决定启动子 Agent（例如并行爬取多个网页），子任务通过 SubAgent Lane 调度，最多 8 个并发。这是 OpenClaw 实现 Agent 并发分解（Decomposition）的机制。

Cron Lane（无并发上限）：处理定时任务（定期发送报告、定期同步数据等），不限并发，按 cron 表达式触发。

四种处理模式

collect      → 收集所有待处理命令后批量处理，适用于批量导入场景
steer        → 实时处理，每条命令立即进入 Pi 推理循环
followup     → 处理 Pi 推理后的后续动作（发送响应、更新 Memory 等）
steer-backlog → 当 Session Lane 积压时，合并处理多条积压消息

3.6 Skills 深度解析

Skills 不是代码

这是新手最常见的误解之一。Skills 不是你需要编写代码来实现的功能，而是将现有能力（Pi 的工具、Gateway 的集成、外部 API）组合成可复用场景的配置包。

一个 Skill 的结构：

# skills/email-summarizer.skill.yaml
id: email-summarizer
name: "Email Summarizer"
version: "1.0.0"
description: "Fetches and summarizes unread emails from Gmail"

triggers:
  - type: command
    pattern: "/summarize-emails"
  - type: schedule
    cron: "0 9 * * MON-FRI"  # 每个工作日早上9点

inputs:
  - name: maxEmails
    type: integer
    default: 10
    description: "Maximum number of emails to summarize"

steps:
  - id: fetch-emails
    action: integration.gmail.listUnread
    params:
      maxResults: "{{ inputs.maxEmails }}"
  
  - id: summarize
    action: pi.prompt
    params:
      prompt: |
        Please summarize the following emails concisely:
        {{ steps.fetch-emails.result | json }}
      model: claude-haiku-3-5-20251201

outputs:
  - name: summary
    value: "{{ steps.summarize.result }}"

这个 Skill 不需要写一行 TypeScript。它通过 YAML 描述了：触发条件、输入参数、执行步骤（调用 Gmail 集成 + 调用 Pi 做摘要）、输出结果。

Skills 市场

官方 Skills 市场（skills.openclaw.ai）提供社区贡献的 Skill 包。安装方式：

# 浏览可用 Skills
openclaw skills search "email"

# 安装 Skill
openclaw skills install [email protected]

# 列出已安装的 Skills
openclaw skills list

# 在 Agent 中启用 Skill
# 编辑 openclaw.json：
{
  "agents": [
    {
      "id": "my-agent",
      "skills": ["email-summarizer"]
    }
  ]
}

3.7 Plugin 深度解析

Plugin 不是 Skills

这是另一个常见误解。Plugin 和 Skills 的区别：

Plugin 主要用于以下场景：

• 添加尚未官方支持的消息平台（自定义 Channel Bridge）
• 实现自定义的消息中间件（如消息加密、合规过滤）
• 扩展 Plugin Registry 提供新的全局服务

Plugin 开发使用 plugin-sdk：

// plugins/custom-platform/index.ts
import { definePlugin, ChannelBridge, InternalMessage } from '@openclaw/plugin-sdk';

export default definePlugin({
  id: 'custom-platform',
  name: 'Custom Platform Bridge',
  version: '1.0.0',
  
  async setup(registry) {
    registry.registerChannelBridge({
      id: 'custom-platform',
      
      async connect(config) {
        // 建立与自定义平台的连接
      },
      
      async receive(): AsyncIterator<InternalMessage> {
        // 接收来自平台的消息，转换为 InternalMessage
      },
      
      async send(response) {
        // 将响应发送回平台
      }
    });
  }
});

3.8 Memory 系统深度解析

三层 Memory 架构

┌─────────────────────────────────────────────────────────────┐
│                     Memory System                           │
│                                                             │
│  Short-term Memory                                          │
│  └─ 当前 Session 对话历史（最近 N 条，默认50）              │
│  └─ 存储：内存（RAM），Session 结束后可选持久化             │
│  └─ 生命周期：随 Session                                    │
│                                                             │
│  Long-term Memory                                           │
│  └─ 用户画像（偏好、历史决策、关键事实）                    │
│  └─ 存储：SQLite（向量化后，可选 pgvector）                 │
│  └─ 生命周期：持久，跨 Session                              │
│                                                             │
│  Workspace Memory                                           │
│  └─ 团队共享知识库（Markdown 文件 + 语义搜索索引）          │
│  └─ 存储：本地文件系统 + SQLite 向量索引                   │
│  └─ 生命周期：持久，所有 Agent 共享                        │
└─────────────────────────────────────────────────────────────┘

Memory 配置示例

{
  "memory": {
    "shortTerm": {
      "maxMessages": 50,
      "persistOnSessionEnd": true
    },
    "longTerm": {
      "enabled": true,
      "storage": "sqlite",
      "embeddingModel": "text-embedding-3-small",
      "embeddingProvider": "openai",
      "maxEntries": 10000
    },
    "workspace": {
      "enabled": true,
      "paths": [
        "~/.openclaw/workspace/",
        "/path/to/company-docs/"
      ],
      "indexOnStartup": true,
      "watchForChanges": true
    }
  }
}

Memory 如何影响 Pi 的推理

在每次 Pi 处理消息之前，Gateway 会自动：

1. 加载当前 Session 的 Short-term Memory（对话历史）
2. 根据当前消息内容，从 Long-term Memory 中语义检索相关的用户信息
3. 将检索到的上下文注入到 System Prompt 的相关部分

这个过程对 Pi 和用户都是透明的，但对对话质量有显著影响：Pi 可以"记住"用户上次说过他不喜欢某种风格、偏好英文回复、曾经提过的项目背景等信息。

3.9 关键术语精确定义

在 OpenClaw 的文档和社区中，以下术语有精确的含义，混淆它们会导致配置错误：

Channel vs Session

Channel：一个持续的消息平台连接配置。例如，一个接入了 Slack 工作区的配置就是一个 Channel。Channel 是静态的，在配置文件中定义，不随时间变化。

Session：用户在 Channel 上的一次具体对话上下文。同一个 Channel 上不同用户的对话对应不同的 Session。Session 是动态的，随用户消息自动创建和管理。

WhatsApp Channel (1个)
  ├── Session: 用户A与 Agent 的对话
  ├── Session: 用户B与 Agent 的对话
  └── Session: 用户C与 Agent 的对话

Binding vs Tool

Binding：将一条传入消息路由到特定 Agent 和配置的规则。Binding 工作在 Gateway 层，发生在消息进入 Pi 之前。

Tool：Pi 在推理过程中可以调用的操作。Tool 工作在 Agent Core 层，发生在 Pi 推理循环内部。

Workspace vs Project

Workspace：OpenClaw 的 Memory 层概念，指共享知识库的存储位置（文件夹路径集合）。

Project：（非 OpenClaw 特定术语）通常指使用 OpenClaw 的一个业务应用。一个 Project 可能包含多个 Agent、多个 Channel、多个 Skill。

3.10 配置驱动 vs 代码驱动的范式差异

OpenClaw 坚持配置驱动范式，这与 LangChain、AutoGen 等框架的代码驱动范式形成鲜明对比。

配置驱动范式的核心思想

配置驱动意味着系统行为由数据（JSON/YAML 文件）描述，而非由代码（TypeScript/Python 函数）描述。

代码驱动（LangChain 风格）：

# 每次改变 Agent 行为都需要修改代码
chain = LLMChain(
    llm=ChatAnthropic(model="claude-opus-4-5"),
    prompt=ChatPromptTemplate.from_messages([
        ("system", "You are a customer support agent."),
        ("human", "{input}")
    ])
)
result = chain.invoke({"input": user_message})

配置驱动（OpenClaw 风格）：

{
  "agents": [{
    "id": "support-agent",
    "systemPrompt": "You are a customer support agent.",
    "llmProvider": "anthropic-primary"
  }]
}

修改 Agent 行为只需编辑 JSON 文件，无需重新编写和部署代码。这使非开发者可以独立维护 Agent 配置。

范式差异的实际影响

小结

本章梳理了 OpenClaw 五大核心组件的职责边界和相互关系：

• Gateway 是边界守门人，处理 Session 解析、Command Queue 调度和 Plugin 管理
• Pi 是推理大脑，通过 4 个基础工具和嵌入式执行实现高效 Agent 推理
• Skills 是配置化的能力包，让非开发者可以组合业务流程
• Plugin 是代码化的扩展点，供开发者添加 Gateway 层的新能力
• Memory 是三层上下文存储，支撑 Pi 的持续学习和个性化

理解这些组件的边界，是避免常见误解（Skills 不是代码、Plugin 不是 Skills）的关键。在下一章中，我们将通过与 LangChain、AutoGen、CrewAI 的系统比较，进一步明确 OpenClaw 的定位和适用场景。