1.2 OpenClaw 的核心架构总览

生成模型：Claude Opus 4.6 (anthropic/claude-opus-4-6) Token 消耗：输入 ~130,000 tokens，输出 ~12,000 tokens（本章合计）

---

理解 OpenClaw 的整体架构，是深入阅读其源码的基础。本节将从宏观视角介绍 OpenClaw 的核心组件和数据流向。

1.2.1 架构图解：消息通道 → Gateway 控制平面 → Pi Agent 运行时 → 工具执行

OpenClaw 的架构可以用一句话概括：多个消息通道连接到一个 WebSocket 控制平面（Gateway），Gateway 将消息路由给 AI Agent 运行时处理，Agent 可以调用各种工具来完成任务，最后将回复通过原始通道发回给用户。

下图展示了完整的架构：

                    ┌─────────────────────────────────────────────┐
                    │              消息通道（Channels）             │
                    │                                             │
                    │  WhatsApp  Telegram  Discord  Slack  Signal │
                    │  iMessage  WebChat   Teams    Matrix   ...  │
                    └──────────────────┬──────────────────────────┘
                                       │
                                       │ 入站消息（规范化后）
                                       ▼
┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│                      Gateway（控制平面）                               │
│                      ws://127.0.0.1:18789                            │
│                                                                      │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │
│  │  WebSocket   │  │   会话管理    │  │   通道路由    │  │  认证授权  │ │
│  │   服务器     │  │  (Sessions)  │  │  (Routing)   │  │  (Auth)  │ │
│  └─────────────┘  └──────────────┘  └──────────────┘  └──────────┘ │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │
│  │  HTTP 服务器  │  │   Cron 调度  │  │   钩子系统    │  │  配置管理  │ │
│  │ (OpenAI API) │  │  (Scheduler) │  │   (Hooks)    │  │ (Config) │ │
│  └─────────────┘  └──────────────┘  └──────────────┘  └──────────┘ │
│                                                                      │
└──────────────────────────┬───────────────────────────────────────────┘
                           │
                           │ agent RPC 调用
                           ▼
┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│                    Pi Agent 运行时（Agent Runtime）                    │
│                                                                      │
│  ┌─────────────────┐  ┌────────────────┐  ┌───────────────────────┐ │
│  │   系统提示词构建   │  │  模型选择/故障转移 │  │   上下文窗口管理       │ │
│  │ (System Prompt)  │  │ (Model Select) │  │  (Context Window)    │ │
│  └─────────────────┘  └────────────────┘  └───────────────────────┘ │
│  ┌─────────────────┐  ┌────────────────┐  ┌───────────────────────┐ │
│  │   流式传输处理    │  │   压缩/裁剪     │  │     用量统计           │ │
│  │  (Streaming)    │  │ (Compaction)   │  │    (Usage)           │ │
│  └─────────────────┘  └────────────────┘  └───────────────────────┘ │
│                                                                      │
└──────────────────────────┬───────────────────────────────────────────┘
                           │
                           │ 工具调用
                           ▼
┌──────────────────────────────────────────────────────────────────────┐
│                                                                      │
│                        工具系统（Tools）                               │
│                                                                      │
│  ┌────────┐ ┌─────────┐ ┌────────┐ ┌──────┐ ┌───────┐ ┌─────────┐ │
│  │  Bash  │ │ Browser │ │ Canvas │ │ Cron │ │ Nodes │ │Sessions │ │
│  │  执行  │ │  控制   │ │  A2UI  │ │ 调度 │ │ 设备  │ │  通信   │ │
│  └────────┘ └─────────┘ └────────┘ └──────┘ └───────┘ └─────────┘ │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘
                           │
                           │ 连接
                           ▼
┌──────────────────────────────────────────────────────────────────────┐
│                        客户端（Clients）                              │
│                                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
│  │ macOS App│  │  iOS App │  │Android   │  │ CLI 终端  │            │
│  │ (菜单栏) │  │  (节点)  │  │App(节点) │  │          │            │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘            │
│  ┌──────────┐  ┌──────────┐                                         │
│  │ WebChat  │  │ Control  │                                         │
│  │  (网页)  │  │ UI(面板) │                                         │
│  └──────────┘  └──────────┘                                         │
└──────────────────────────────────────────────────────────────────────┘

这个架构有几个值得注意的特点：

单一控制平面：Gateway 是整个系统的枢纽。所有消息通道、客户端应用、节点设备都通过 WebSocket 连接到 Gateway。Gateway 负责协调一切——路由消息、管理会话、调度 Agent、分发事件。这种集中式设计简化了系统的状态管理和一致性保证。

关注点分离：通道只负责消息的收发和格式转换，不包含任何业务逻辑。Agent 运行时只关注 AI 推理和工具调用，不关心消息来自哪个通道。Gateway 在中间做协调——这是经典的中介者模式（Mediator Pattern）。

工具即能力：Agent 的能力不是硬编码的，而是通过可注册的工具来扩展。Bash 执行、浏览器控制、Canvas 渲染、Cron 定时任务、设备节点操作——每一种能力都是一个工具，Agent 可以根据需要调用。

1.2.2 关键子系统一览

让我们更具体地了解每个核心子系统的职责：

Gateway（网关 / 控制平面）

Gateway 是 OpenClaw 的心脏。它是一个长期运行的进程，监听在 127.0.0.1:18789 端口（默认），主要职责包括：

• WebSocket 服务器：维护与所有客户端、节点的连接

• HTTP 服务器：提供 OpenAI 兼容 API、控制面板 UI 等

• 通道管理：启动和维护所有消息通道的连接

• 会话管理：创建、维护、重置、持久化会话状态

• 消息路由：将入站消息路由到正确的 Agent 和会话

• 事件分发：向所有连接的客户端广播 Agent 事件、状态变更等

• Cron 调度：管理定时任务

• 配置管理：加载、校验、热重载配置

对应源码目录：src/gateway/（128 个文件）

Pi Agent Runtime（AI Agent 运行时）

Agent 运行时负责执行 AI 推理循环。当 Gateway 收到一条需要 AI 处理的消息时，它会调用 Agent 运行时来处理。关键功能：

• Agent 循环（Agent Loop）：接收消息 → 组装上下文 → 调用 LLM → 执行工具 → 流式回复 → 持久化

• 模型选择与故障转移：支持多模型、多提供者，自动切换

• 系统提示词构建：从工作区文件、技能、配置组装系统提示词

• 工具管理：注册、调度、执行 Agent 可用的工具

• 流式传输：将 LLM 的输出流式传输到客户端

• 上下文压缩：当对话太长时自动压缩上下文

对应源码目录：src/agents/（308 个文件——是整个项目最大的目录）

Channels（通道系统）

通道系统负责与外部消息平台的对接。每个通道是一个适配器，将平台特定的 API 转换为 OpenClaw 的内部消息格式。

• 核心通道：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、WebChat

• 扩展通道：Teams、Matrix、Google Chat、Nostr、Twitch 等（31 个扩展）

• 通道基础设施：白名单、提及门控、命令门控、打字指示器等

对应源码目录：src/channels/（31 个文件）+ src/whatsapp/、src/telegram/ 等 + extensions/

Tools（工具系统）

工具系统为 Agent 提供了与外部世界交互的能力：

• Bash：在宿主机或沙箱中执行 shell 命令

• Browser：通过 Playwright/CDP 控制 Chrome 浏览器

• Canvas/A2UI：推送 HTML 到可视化画布

• Cron：管理定时任务

• Nodes：调用设备节点的能力（摄像头、屏幕录制、位置等）

• Sessions：跨会话通信

对应源码目录：src/agents/tools/、src/browser/、src/canvas-host/、src/cron/、src/node-host/

Memory（记忆系统）

记忆系统让 Agent 能够"记住"之前的信息：

• 文件记忆：基于 Markdown 文件的持久化记忆

• 向量搜索：使用嵌入向量进行语义相似度搜索

• 混合搜索：结合 BM25 全文搜索和向量搜索

对应源码目录：src/memory/（43 个文件）

Skills（技能系统）

技能系统允许通过 Markdown 文件扩展 Agent 的能力：

• 内置技能：52 个预装技能（GitHub、Slack、天气、编程 Agent 等）

• 托管技能：通过 ClawHub 注册中心安装

• 工作区技能：用户在工作区目录下自定义

对应源码目录：src/agents/skills.ts、skills/（52 个子目录）

1.2.3 数据流全景：一条消息从用户发出到 AI 回复的完整路径

为了更直观地理解架构，让我们追踪一条消息的完整生命周期。假设用户在 WhatsApp 上发送了一条消息 "帮我查一下明天的天气"：

1. 用户在 WhatsApp 上发送 "帮我查一下明天的天气"
   │
   ▼
2. Baileys SDK 收到消息事件
   │  src/web/inbound.ts → 消息监听
   ▼
3. 自动回复系统接收消息
   │  src/web/auto-reply.ts → 判断是否需要处理
   │  - 检查白名单（sender 是否在 allowFrom 中）
   │  - 检查 DM 策略（pairing / open）
   │  - 转换媒体附件
   ▼
4. 消息规范化为内部格式
   │  src/channels/ → 发送者身份、聊天类型、会话标签
   ▼
5. Gateway 路由消息
   │  src/routing/resolve-route.ts → 确定目标 Agent
   │  src/routing/session-key.ts → 生成会话键（如 agent:main:main）
   ▼
6. Gateway 发起 Agent RPC 调用
   │  src/gateway/server-chat.ts → agentCommand()
   │  - 解析模型 + 思考级别
   │  - 加载技能快照
   ▼
7. Pi Agent 运行时接管
   │  src/agents/pi-embedded-runner.ts → runEmbeddedPiAgent()
   │  - 队列序列化（确保每个会话同一时间只有一个运行）
   │  - 解析 Auth Profile
   │  - 构建系统提示词
   │  - 加载会话历史
   ▼
8. 调用 LLM（如 Anthropic Claude）
   │  pi-agent-core → 发送 HTTP 请求到模型 API
   │  - 流式接收 token
   ▼
9. LLM 决定调用工具（如 weather 技能的 bash 命令）
   │  src/agents/pi-tools.ts → 工具调度
   │  src/agents/bash-tools.exec.ts → 执行命令
   ▼
10. 工具结果返回给 LLM
    │  LLM 根据工具结果生成最终回复
    ▼
11. 流式传输处理
    │  src/agents/pi-embedded-subscribe.ts → 事件桥接
    │  - assistant 文本流 → 分块
    │  - tool 事件 → 工具摘要
    ▼
12. Gateway 广播事件
    │  src/gateway/server-broadcast.ts → 向所有客户端推送
    ▼
13. 回复通过 WhatsApp 发回
    │  src/web/outbound.ts → 发送消息
    │  - Markdown 格式化
    │  - 分块（WhatsApp 有消息长度限制）
    ▼
14. 用户在 WhatsApp 上看到 "明天北京晴，最高温度 12°C..."

这个数据流覆盖了 OpenClaw 的所有核心子系统。在后续章节中，我们将逐一深入每个环节的源码实现。

值得注意的是，整个流程中有几个关键的设计决策：

• 步骤 6-7：Agent 调用是异步的。Gateway 先返回一个 runId，然后通过事件流推送结果。这允许长时间运行的任务不阻塞 Gateway。

• 步骤 7：队列序列化确保了每个会话的对话历史一致性——不会因为并发消息导致上下文混乱。

• 步骤 11：流式传输不是简单地逐 token 发送，而是经过分块（Chunking）处理后再发到通道，因为大多数消息平台不支持实时编辑消息。

---

至此，你已经对 OpenClaw 的架构有了全景式的了解。接下来让我们看看支撑这一架构的技术栈。