万字深度解析 OpenClaw 架构：为什么它能成为全球最火的开源 AI Agent？

2026 年初，OpenClaw 以 14 万+ GitHub 星标登顶全球榜首，超越了 Linux 和 React。这个"小龙虾"究竟有何魔力？本文从工程架构层面，深度拆解 OpenClaw 的四层解耦设计、插件化重构、三级记忆系统和 Gateway-Pi 执行架构。

---

📌 OpenClaw 是什么？

OpenClaw（原名 Clawdbot → Moltbot）是由 PSPDFKit 创始人 Peter Steinberger 开发的开源 AI Agent 运行时。

OpenClaw Logo

Slogan: "The AI that actually does things"

翻译：一只真正能干活儿的 AI

核心特点

特性	说明
🌐 多通道接入	Telegram、WhatsApp、Discord、飞书、iMessage 等 8+ 通道
🖥️ 本地运行	部署在个人电脑上，真正执行脚本
🔧 技能系统	60+ 官方 Skills，社区持续贡献
🔒 数据私有	全本地存储，不上云

---

🏗️ 第一层：四层解耦架构

OpenClaw 采用经典的四层解耦架构，从外到内依次是：

架构分层图

📊 架构一览

层级	名称	核心功能
第 1 层	交互层 (Channels)	协议适配，接入 8 个核心通道 + 50+ 扩展通道
第 2 层	网关层 (Gateway)	路由、排队、调度、鉴权、协议转换
第 3 层	智能体层 (Agent)	会话管理、上下文组装、记忆系统、执行循环、工具调用
第 4 层	执行层 (Execution)	本地节点、远端节点、技能、沙箱

---

🔌 第二层：交互层 (Channels)

核心职责：协议适配

OpenClaw 支持8 个核心通道 和 50+ 扩展通道：

  Telegram | WhatsApp | Discord | Slack | Signal | iMessage | 飞书 | WebChat

通道插件接口

  export type ChannelPlugin = {
  id: ChannelId;                    // 通道唯一标识
  meta: ChannelMeta;                // 通道元数据
  capabilities: ChannelCapabilities;// 能力声明
  config: ChannelConfigAdapter;     // 配置管理
  outbound?: ChannelOutboundAdapter;    // 发送消息
  pairing?: ChannelPairingAdapter;      // 配对逻辑
  messaging?: ChannelMessagingAdapter;  // 消息处理
}

---

🚪 第三层：网关层 (Gateway)

Gateway 是整个 OpenClaw 的核心服务，作为常驻 Node.js 进程，承担五大职责：

Gateway 网关

五大职责

职责	说明
🛣️ 路由	根据消息来源分配给对应的会话
🚗 排队	实现"车道式队列"（Lane Queue），默认串行、显式并行
⏰ 调度	管理定时任务（Heartbeat）
🔐 鉴权	验证请求合法性
🔄 协议转换	将不同通道的消息统一成内部格式

核心实现

  # gateway/dispatcher.py
def dispatch_task(payload):
    intent = extractor.analyze(payload.content)
    node_id = registry.get_active_node(payload.affinity)
    return forward_to_node(node_id, intent)

---

🤖 第四层：智能体层 (Agent)

Agent 层是 OpenClaw 的"大脑"，负责：

• • 📝 会话管理：维护多会话状态
• • 🧠 上下文组装：拼接历史对话 + 记忆
• • 💾 记忆系统：三级记忆管理（详见下文）
• • 🔄 执行循环：ReAct 推理循环
• • 🔧 工具调用：Skills 调用

核心配置文件

文件	用途
AGENTS.md	Agent 职责声明，决定工具权限
SOUL.md	个性化提示词，注入 system prompt
TOOLS.md	工具白名单/黑名单，安全边界
IDENTITY.md	身份标识（name/avatar），通道展示
USER.md	用户偏好，上下文先验
HEARTBEAT.md	定时任务配置
MEMORY.md	长期记忆文档（RAG 源）

---

💾 第五层：三级记忆系统

这是 OpenClaw 最独特的设计之一。OpenClaw 坚定地认为：AI 的记忆不应该是黑盒 。

AI 记忆系统

存储结构

  ~/.openclaw/workspace/
├── MEMORY.md                # 长期记忆（终身学习）
├── memory/
│   ├── 2026-03-12.md       # 今日日志（短期）
│   └── 2026-03-11.md       # 昨日日志
├── sessions/                # 会话存档（近端）
├── USER.md                   # 用户身份
└── SOUL.md                   # Agent 人格设定

存储层：SQLite + Vector

数据库架构：

  -- 文件元数据
CREATE TABLE files (
  id INTEGER PRIMARY KEY,
  path TEXT UNIQUE,
  mtime INTEGER,     -- 修改时间，用于增量索引
  hash TEXT          -- 内容哈希，去重
);

-- 文本块存储
CREATE TABLE chunks (
  id INTEGER PRIMARY KEY,
  file_id INTEGER,
  text TEXT,
  hash TEXT UNIQUE,  -- 文本哈希，跨文件去重
  embedding TEXT     -- JSON序列化的向量
);

-- 全文搜索（FTS5）
CREATE VIRTUAL TABLE chunks_fts USING fts5(text, content=chunks);

-- 向量搜索（sqlite-vec）
CREATE VIRTUAL TABLE chunks_vec USING vec0(embedding float[1536]);

混合检索策略：BM25 + Vector

  async function hybridSearch(query, options = {}) {
  const vecWeight = 0.7;   // 向量权重
  const bm25Weight = 0.3;  // BM25权重

  const vectorResults = await vectorSearch(query);
  const bm25Results = await bm25Search(query);

  // 合并并计算综合得分（并集而非交集）
  const allChunkIds = new Set([
    ...vectorResults.map(r => r.id),
    ...bm25Results.map(r => r.id)
  ]);
  // 加权平均后排序返回
}

优雅降级

如果 sqlite-vec 扩展未安装，系统自动回退到 JS 暴力计算：

  try {
  return await db.all(`SELECT ... vec_distance_cosine(...)`);
} catch (err) {
  const allChunks = await db.all("SELECT * FROM chunks");
  return allChunks.map(chunk => ({
    ...chunk,
    dist: cosineSimilarity(queryVector, JSON.parse(chunk.embedding))
  })).sort((a, b) => a.dist - b.dist).slice(0, limit);
}

---

🔧 插件化重构 (2026 PR #661)

2026 年，OpenClaw 进行了大规模插件化重构，解决了添加新模型提供商的难题。

插件系统

重构前的痛点

添加新模型提供商需要修改 4 个核心文件：

1. 1. 继承 BaseProvider 抽象类
2. 2. 在 providers/index.ts 手动注册
3. 3. 在 model-router.ts 添加路由分支
4. 4. 更新配置 Schema

代码复杂度随提供商数量线性增长（15+ else-if branches）。

插件架构设计

Provider Interface：

  // packages/core/src/provider-interface.ts
export interface Provider {
  readonly name: string;
  readonly version: string;
  chat(messages: Message[], options: ChatOptions): AsyncIterator<string>;
  estimateTokens(text: string): number;
  getSupportedFeatures(): ProviderFeatures;
}

动态加载：

  export class ProviderLoader {
  private providers = new Map<string, Provider>();
  async loadFromPackage(packageName: string): Promise<void> {
    const module = await import(packageName);
    if (!this.validateProvider(module.default)) {
      throw new Error(`Invalid provider: ${packageName}`);
    }
    const provider = new module.default();
    this.providers.set(provider.name, provider);
  }
}

四大优势

优势	说明
🔒 依赖隔离	核心框架从 45MB 降至 8MB
🚀 并行开发	社区可独立开发插件
📦 版本自主	各插件独立版本，可单独更新
🛡️ 安全增强	沙箱机制 + 权限声明

---

⚙️ 执行层：Gateway-Pi 架构

三层执行链

执行架构

层级	角色	说明
🧠 Orchestrator	大脑	云端部署，负责 LLM 推理和任务拆解
🌉 Gateway	协议桥	鉴权、流量整形、指令翻译
📱 Pi-embedded	执行端	运行在本地设备，真正执行脚本

执行示例：查 CPU 温度并生成图表

1. 1. Orchestrator → 识别技能需求 → 生成 JSON 指令
2. 2. Gateway → 验证签名 → 查找在线 Pi 节点 → Protobuf 封装 → WebSocket 发送
3. 3. Pi-embedded → 接收消息 → 解包
4. 4. Sandbox → 启动临时 Python 进程 → 挂载传感器权限
5. 5. Skill Execution → 执行 get_temp.py
6. 6. Callback → 结果（图片二进制）原路返回

---

✅ 架构优势总结

优势	说明
🛠️ 零运维	SQLite 单文件，无需复杂数据库
🔒 数据私有	全本地存储，不上云
📖 可审计	记忆透明，Markdown 文件可读
⚡ 增量索引	只处理变更文件，效率高
🔁 优雅降级	向量 → BM25 → 纯文本，逐级回退
🌐 插件生态	60+ 官方技能，社区持续贡献

---

⚠️ 面临的挑战

挑战	说明
💰 Token 消耗偏高	记忆系统是主因
🔍 向量检索不懂关系	能找到个体但推不出关系
📈 维护成本线性增长	文件越多，索引维护越复杂
📡 长连接抖动	WebSocket 1006 错误常见
📚 小白门槛	虽零运维，但需懂文件结构

---

📖 参考资料

1. 1. OpenClaw 三级记忆系统实现揭秘
2. 2. 2026 年 OpenClaw 插件化重构技术解析
3. 3. OpenClaw 核心源码解读：从 Gateway 到 Pi-embedded
4. 4. 不会写代码也能懂：OpenClaw 四层架构图解
5. 5. 吃龙虾咯！万字拆解 OpenClaw 的架构与设计
6. 6. 关于 OpenClaw，你需要了解的：核心架构、运作原理
7. 7. OpenClaw Architecture Deep Dive 2025

---

🦞 结语

OpenClaw 的核心设计哲学：AI 的记忆和执行不应该是黑盒。

用 Markdown 存真相，用 SQLite 建索引，用 BM25 + 向量 做检索，用 Gateway-Pi 做执行------这套组合既保证功能强大，又让一切透明可控。

---