【OpenClaw】 源码剖析（一）：项目全景——21万Star背后的架构哲学与工程减法

OpenClaw 源码剖析（一）：项目全景——21万Star背后的架构哲学与工程减法

写在前面（2026.05.07 首发）：2025 年初，GitHub 上出现了一个名叫OpenClaw的项目，它没有 LangChain 那样层层抽象的"优雅"，也没有 AutoGPT 那样"让 AI 自由发挥"的浪漫。它做了一件在 AI Agent 领域堪称"反潮流"的事——把框架做到极致的薄，把能力做到极致的厚。一年后，这个项目在 GitHub 上收获了21 万 Star，成为历史上增长最快的 AI 开源项目之一。它的底层框架 pi-mono，核心只有4 个工具，系统提示词不到1000 个 token，完全不依赖 LangChain / LangGraph 等重量级框架。这种"工程减法"的哲学，让 OpenClaw 在一众"加法框架"中脱颖而出。

从今天起，我将用5 篇文章，带你从源码层面彻底搞懂 OpenClaw 的每一个核心子系统。这是第一篇——项目全景。

📑 文章目录

• 📌 一、OpenClaw 是什么？一句话定义
• ⭐ 二、21万Star的增长密码
• 🏗️ 三、六大核心子系统：一张图看懂全局架构
• 📂 四、源码目录结构：pnpm monorepo 的精巧布局
• 🔄 五、Agent Loop：让 AI 真正"干活"的核心引擎
• ⚖️ 六、加法 vs 减法：两种 AI Agent 工程哲学
• 📊 七、框架横评：六大维度对比
• 🔮 八、系列预告：接下来我们要拆什么？
• 🎁 总结速查卡

📌 一、OpenClaw 是什么？一句话定义

OpenClaw 是一个开源的、自托管的个人 AI 助手框架，用 TypeScript 编写，核心定位是"AI Gateway"——连接大模型与真实世界的工具执行层。

这句话里有三个关键词，每一个都值得展开：

1.1 “开源的、自托管的”

OpenClaw 采用 MIT 协议开源，这意味着你可以自由地使用、修改和分发它。更重要的是"自托管"——你的 AI 助手运行在你自己的电脑或服务器上，数据不经过任何第三方。在 2026 年这个 AI 隐私焦虑日益严重的时代，这个定位击中了一个巨大的痛点。你不需要把对话数据上传到某个 SaaS 平台，不需要担心 API Key 被滥用，不需要信任一个你无法审计的黑盒服务。OpenClaw 的所有状态——配置、记忆、技能——都是纯文件，你可以用cat命令查看，用git追踪变更，用你熟悉的任何工具来管理。

1.2 “AI Gateway”

这是 OpenClaw 最核心的架构决策。它不是一个简单的 ChatBot 包装器，也不是一个通用的 Agent 编排框架。它是一个Gateway——一个流量调度器、唯一事实来源和控制平面。所有来自 Telegram、Discord、微信、飞书、Slack 等 25+ 消息通道的事件，都先汇聚到 Gateway，由 Gateway 统一处理路由、排队、状态管理，然后才去调用 LLM。这种"星型拓扑"架构的优势在于状态一致性——与分布式多 Bot 方案不同，OpenClaw 的单一 Gateway 保证了无论你从哪个通道发消息，Agent 看到的都是同一个世界。

1.3 “连接大模型与真实世界的工具执行层”

大模型很聪明，但它被关在"数字笼子"里——它不能读文件、不能执行代码、不能搜索网页、不能发消息。OpenClaw 的价值就在于打开这个笼子。通过 Tools 系统，Agent 可以在沙箱中执行代码、读写文件、调用 API；通过 Skills 系统，社区贡献了 5700+ 个即插即用的技能插件；通过 Channel 系统，Agent 可以同时接入 25+ 个消息平台。OpenClaw 做的不是让模型更聪明，而是让模型能做事。

⭐ 二、21万Star的增长密码

上图是 OpenClaw 在 GitHub 上的 Star 增长曲线。从 2025 年初的零到 2026 年 5 月的 21 万，这个增长速度在开源项目历史上都是罕见的。对比之下，AutoGPT 在同一时期只增长到约 3 万 Star。

为什么 OpenClaw 能这么火？我总结了三个核心原因：

2.1 击中了"AI 隐私焦虑"

2025-2026 年，随着 AI 助手越来越多地处理个人邮件、聊天记录、工作文档，用户对数据隐私的焦虑达到了顶峰。OpenClaw 的"自托管"定位，让用户第一次可以拥有一个完全属于自己的 AI 助手——数据在本地，模型在本地（或你选择的 API），一切尽在掌控。这种"数据主权"的叙事，在技术社区引发了强烈的共鸣。

2.2 "反框架"的工程美学

在 LangChain 把 AI Agent 框架做得越来越复杂的背景下，OpenClaw 反其道而行之——框架做到极致的薄。pi-mono 底层框架只有 4 个工具，系统提示词不到 1000 个 token。这种"减法哲学"让开发者耳目一新：原来 AI Agent 不需要那么多抽象层，原来简单到极致就是最好的架构。这种反差感，是 OpenClaw 在技术社区出圈的关键。

2.3 25+ 消息通道的"实用主义"

大多数 AI Agent 框架只支持 API 调用或 Web 界面，但 OpenClaw 从第一天起就支持 Telegram、Discord、微信、飞书等 25+ 消息通道。这意味着你不需要写任何适配代码，就能让你的 AI 助手出现在你日常使用的每一个聊天工具里。这种"开箱即用"的体验，大大降低了使用门槛，也让 OpenClaw 从"开发者玩具"变成了"生产力工具"。

🏗️ 三、六大核心子系统：一张图看懂全局架构

上图是 OpenClaw 的全局架构图。可以看到，整个系统由六大核心子系统组成，它们各司其职，通过 Gateway 这个"中央调度器"协同工作。下面我们逐一介绍：

3.1 Channel（消息接入层）

Channel 是 OpenClaw 与外部世界的"触角"。它负责接入各种聊天平台（Telegram、Discord、微信、飞书、Slack、QQ、钉钉等 25+ 平台），并将不同平台的消息格式统一为 OpenClaw 内部的标准格式。每个 Channel 是一个独立的适配器，实现了统一的IChannel接口，包含onMessage、onPresence、send等方法。这种"适配器模式"的设计，使得新增一个消息平台只需要实现一个适配器，而不需要修改任何核心代码。

3.2 Gateway（控制平面）

Gateway 是整个系统的"大脑"和"心脏"。它是一个 WebSocket 服务器，承担了四个核心职责：消息路由（把来自不同 Channel 的消息派发给对应的 Agent）、会话管理（维护每个用户的会话状态）、状态一致性（作为唯一事实来源，保证所有组件看到的状态一致）和流式推送（将 Agent 的输出实时推送给 Channel）。Gateway 的设计哲学是"薄而强"——它不处理业务逻辑，只做调度和状态管理，所有"聪明"的事情都交给 Agent。

3.3 Agent（推理引擎）

Agent 是真正"干活"的核心引擎。它接收 Gateway 派发的消息，组装上下文（系统提示词 + 工具定义 + 历史对话 + 用户消息），调用 LLM 进行推理，然后根据推理结果决定下一步行动——要么直接回复用户，要么调用工具执行操作。Agent 的核心是一个Loop（循环），我们将在第五节详细剖析。

3.4 Tools（工具执行层）

Tools 是 Agent 与真实世界的"手脚"。它提供了文件读写、代码执行、网页搜索、API 调用等能力。每个 Tool 在独立的沙箱中执行，确保安全性。OpenClaw 的 Tools 系统设计得非常精巧——它不是简单的函数调用，而是一个完整的工具生命周期管理器，包含工具注册、参数校验、沙箱隔离、超时控制、结果缓存等机制。

3.5 Memory（记忆系统）

Memory 是 Agent 的"长期记忆"。它负责存储和检索对话历史、用户偏好、任务状态等信息。OpenClaw 的 Memory 系统采用了分层设计：短期记忆（当前会话的上下文窗口）、长期记忆（跨会话的持久化存储）和工作记忆（当前任务的临时状态）。这种分层设计让 Agent 既能"记住"长期偏好，又不会被过多的历史信息淹没。

3.6 Canvas（渲染输出层）

Canvas 是 Agent 输出的"画布"。它负责将 Agent 的回复渲染为富文本格式——Markdown、代码高亮、图表、表格、实时预览等。Canvas 不是一个简单的文本渲染器，它支持流式渲染（Agent 边生成边显示）、交互式组件（可点击的按钮、可展开的代码块）和多模态输出（文本 + 图片 + 文件）。这种"所见即所得"的输出体验，是 OpenClaw 区别于其他 AI Agent 框架的一个重要特色。

3.7 Skills（技能生态）

Skills 是 OpenClaw 的"应用商店"。它是一个插件系统，允许社区开发者贡献和分享技能包。目前 ClawHub（OpenClaw 官方技能注册中心）上已有5700+个社区技能，涵盖编程辅助、数据分析、文档处理、自动化运维等各个领域。每个 Skill 是一个独立的 npm 包，可以通过openclaw skill install <name>一键安装。Skills 系统的设计遵循"约定优于配置"的原则——你只需要按照约定的目录结构编写代码，OpenClaw 会自动发现和加载你的技能。

📂 四、源码目录结构：pnpm monorepo 的精巧布局

OpenClaw 采用pnpm monorepo结构管理代码。这种结构的核心思想是：所有代码在一个仓库里，但每个子包可以独立版本化和发布。上图展示了核心目录结构，其中最重要的几个目录是：

4.1src/gateway/—— Gateway 核心

这是整个系统的入口。gateway.ts是主文件，负责启动 WebSocket 服务器、注册 Channel 适配器、初始化会话管理器。router.ts实现了消息路由逻辑——根据消息来源和内容，决定派发给哪个 Agent。session.ts管理每个用户的会话状态，包括上下文窗口、对话历史、当前任务等。

4.2src/agent/—— Agent 核心

这是整个系统最核心的代码。loop.ts实现了 Agent Loop——那个"接收消息 → 组装上下文 → LLM 推理 → 执行工具 → 输出响应"的循环。context.ts负责上下文组装——从 Memory 加载历史对话，拼接系统提示词和工具定义。stream.ts处理流式输出——将 LLM 的 token-by-token 输出实时推送给 Gateway。

4.3src/channels/—— Channel 适配器

每个子目录对应一个消息平台。telegram/、discord/、wechat/、feishu/等，每个适配器实现了统一的IChannel接口。这种"约定优于配置"的设计，使得新增一个平台只需要创建一个新目录，实现几个标准方法即可。

4.4src/tools/—— 工具系统

registry.ts是工具注册中心，管理所有可用工具的元数据。sandbox.ts实现了沙箱执行环境——每个工具调用都在独立的子进程中运行，设置了资源限制和超时控制。executor.ts是工具执行器，负责参数校验、调用分发、结果收集。

4.5src/memory/—— 记忆系统

store.ts是记忆存储的抽象层，支持多种后端（文件系统、SQLite、Redis）。manager.ts实现了分层记忆管理——短期记忆用 LRU 缓存，长期记忆用持久化存储，工作记忆用临时文件。retrieval.ts实现了记忆检索——基于相关性和时间衰减的混合检索策略。

4.6packages/—— 子包

core/包含核心类型定义和接口，是所有子包的公共依赖。sdk/是 Skill 开发工具包，提供了编写自定义技能的 API 和脚手架。cli/是命令行工具，提供了openclaw start、openclaw skill install等命令。

🔄 五、Agent Loop：让 AI 真正"干活"的核心引擎

Agent Loop 是 OpenClaw 最核心的设计，也是它区别于其他 AI Agent 框架的关键。上图展示了 Agent Loop 的五步推理周期，下面我们深入剖析每一步：

5.1 Step 1：接收消息

当用户在任何一个 Channel（比如 Telegram）发送消息时，Channel 适配器会将消息转换为 OpenClaw 内部格式，然后通过 WebSocket 推送给 Gateway。Gateway 根据消息的来源和内容，通过 RPC 调用将消息派发给对应的 Agent。这个过程中，Gateway 还会附带一些元数据——会话 ID、用户信息、消息时间戳等。

5.2 Step 2：组装上下文

Agent 收到消息后，第一步是组装上下文。这是一个"拼图"过程：从 Memory 加载历史对话（短期记忆 + 长期记忆检索结果），拼接系统提示词（定义 Agent 的角色和行为规范），注入工具定义（告诉 LLM 有哪些工具可用），最后加上用户的当前消息。上下文组装的质量直接决定了 Agent 的表现——太多历史信息会淹没重点，太少又会让 Agent “失忆”。OpenClaw 的上下文组装策略是"相关性优先"——优先保留与当前任务最相关的历史片段，而不是简单地按时间顺序截断。

5.3 Step 3：LLM 推理

上下文组装完成后，Agent 将其发送给 LLM 进行推理。LLM 的输出有两种可能：文本回复（直接回答用户的问题）或工具调用请求（请求执行某个工具，比如"搜索网页"或"执行代码"）。OpenClaw 支持多种 LLM 后端——OpenAI、Anthropic、本地模型（通过 Ollama）等，通过统一的IModelProvider接口抽象。

5.4 Step 4：执行工具

如果 LLM 请求调用工具，Agent 会在沙箱中执行该工具。沙箱是一个独立的子进程，设置了资源限制（CPU、内存、执行时间）和网络隔离。工具执行完成后，结果会被追加到上下文中，然后 Agent 回到 Step 3，让 LLM 基于工具结果继续推理。这个"推理 → 执行 → 再推理"的循环，就是 Agent Loop 的核心——它让 Agent 能够多步推理、逐步行动，而不是一次性给出答案。

5.5 Step 5：输出响应

当 LLM 不再请求调用工具时，Agent 将最终的文本回复通过流式输出推送给 Gateway，Gateway 再推送给对应的 Channel，最终呈现在用户的聊天界面上。流式输出是 OpenClaw 的一个重要特性——用户不需要等待 Agent 完成所有推理，就能看到 Agent 正在"思考"和"说话"的过程。这种实时反馈大大提升了用户体验。

5.6 循环的本质

Agent Loop 的本质是一个while 循环。伪代码如下：

// Agent Loop 核心逻辑（简化版）while(true){constcontext=assembleContext(message,memory);constresponse=awaitllm.chat(context);if(response.hasToolCall()){constresult=awaitsandbox.execute(response.toolCall);context.append(result);// 追加工具结果，继续循环}else{streamOutput(response);// 流式输出，结束循环break;}}

这段代码虽然简单，但它蕴含了一个深刻的设计哲学：Agent 的能力不是来自框架的复杂度，而是来自循环的深度。每次循环都是一次"思考 → 行动 → 观察"的迭代，循环次数越多，Agent 能完成的任务越复杂。而框架要做的，就是让这个循环尽可能高效、安全、可观测。

⚖️ 六、加法 vs 减法：两种 AI Agent 工程哲学

在 AI Agent 框架的设计上，存在两种截然不同的哲学：加法哲学和减法哲学。上图清晰地对比了这两种哲学的差异。

6.1 加法哲学：LangChain 的路径

LangChain 是"加法哲学"的典型代表。它的核心思路是：AI Agent 太复杂了，我们需要层层抽象来管理这种复杂性。于是有了 Chain → Agent → Tool → Memory 的抽象层级，有了 LCEL（LangChain Expression Language）这种 DSL，有了 LangGraph 这种状态机框架。每一层抽象都增加了灵活性，但也增加了理解成本和调试难度。

加法哲学的问题在于：抽象是有代价的。当你用 LangChain 写一个简单的 Agent 时，你需要理解 Chain、Agent、Tool、Memory、Callback、Tracer 等概念；当你调试一个问题时，你需要穿越多层抽象才能找到根因；当你想定制一个行为时，你需要理解框架的"约定"才能知道在哪里扩展。LangChain 核心包有 200+ 依赖，安装后接近半 GB——这不是"灵活"，这是"负担"。

6.2 减法哲学：OpenClaw 的路径

OpenClaw 是"减法哲学"的极端实践。它的核心思路是：AI Agent 的复杂性应该来自任务本身，而不是框架。框架做得越少，Agent 能做的越多。

OpenClaw 的减法体现在三个层面：

第一，源码即配置。OpenClaw 的默认安装方式是git clone，源码就在本地。代理"坐在源码里，也知道源码"，不满意就"直接提示它改自己"。这种"自修改代码"的方式，虽然看起来"反常规开源"，但实际上极大地降低了定制门槛——你不需要学习框架的配置 DSL，直接改源码就行。

第二，零依赖核心。OpenClaw 的底层框架 pi-mono，核心只有 4 个工具（文件读写、代码执行、网页搜索、Shell 命令），系统提示词不到 1000 个 token。它不依赖 LangChain、LangGraph 或任何重量级框架。这种"极简核心"的设计，让 OpenClaw 的启动时间不到 1 秒，内存占用不到 50MB。

第三，文件即状态。OpenClaw 的所有状态——配置、记忆、技能——都是纯文件。你可以用cat查看，用git追踪，用你熟悉的任何工具管理。这种"文件优先"的设计，让 OpenClaw 的状态管理变得极其透明和可审计。

6.3 减法的代价

当然，减法哲学也有代价。OpenClaw 的"源码即配置"意味着你需要理解 TypeScript 代码才能深度定制；"零依赖核心"意味着一些高级功能需要自己实现；"文件即状态"意味着在分布式场景下需要额外的同步机制。但这些代价，在 OpenClaw 的目标场景（个人 AI 助手、小团队部署）下，是完全可以接受的。

📊 七、框架横评：六大维度对比

上图从六个维度对比了当前主流的 AI Agent 框架。数据来源是社区评测和我的个人使用体验，评分范围 1-10。几个关键观察：

7.1 架构简洁度：OpenClaw 一骑绝尘

OpenClaw 在架构简洁度上拿到了 9.5 分，远超其他框架。这得益于它的"减法哲学"——pi-mono 核心只有 4 个工具，系统提示词不到 1000 token。相比之下，LangChain 的抽象层级太多（5.0 分），AutoGPT 的架构混乱（4.0 分），CrewAI 和 Dify 相对好一些但也不够简洁。

7.2 工具生态：OpenClaw 和 LangChain 并列

OpenClaw 的 ClawHub 有 5700+ 社区技能，LangChain 有丰富的 Tool 生态，两者在工具生态上并列第一（9.0 vs 8.5）。但两者的路线不同——OpenClaw 的 Skills 是"即插即用"的 npm 包，LangChain 的 Tools 是"需要编排"的函数。前者更适合"拿来就用"的场景，后者更适合"精细控制"的场景。

7.3 消息通道：OpenClaw 碾压式领先

这是 OpenClaw 最独特的优势。25+ 原生消息通道的支持，让其他框架望尘莫及（9.5 vs 最高 4.0）。大多数框架只支持 API 调用或 Web 界面，而 OpenClaw 从架构层面就把"多通道接入"作为一等公民来设计。这使得 OpenClaw 不只是一个"开发框架"，更是一个"部署平台"。

7.4 生产就绪：Dify 领先，OpenClaw 紧随

Dify 在生产就绪度上领先（7.5 分），因为它有完善的 Web UI、用户管理、API 网关等企业级功能。OpenClaw 紧随其后（8.0 分），它的自托管架构和文件即状态的设计，使得部署和运维非常简单。LangChain 和 CrewAI 在生产环境中的表现一般，AutoGPT 则明显不适合生产使用。

🔮 八、系列预告：接下来我们要拆什么？

这篇"项目全景"只是开胃菜。在接下来的四篇文章中，我们将深入 OpenClaw 的每一个核心子系统，逐行阅读关键源码：

每一篇都会包含源码级分析（关键代码逐行解读）、架构图（用图说话）和实战建议（如何基于 OpenClaw 构建你自己的 AI 助手）。关注我，不要错过后续更新。

🎁 总结速查卡

OpenClaw 核心信息

六大子系统速查

一句话总结

OpenClaw 证明了 AI Agent 框架的一个核心原则：框架做得越少，Agent 能做的越多。21 万 Star 不是因为它复杂，而是因为它简单到极致。减法，才是最难的加法。

参考链接：

• OpenClaw GitHub 仓库
• OpenClaw 官方文档
• ClawHub 技能市场
• OpenClaw-Book 深度解读
• OpenClaw PRISM 安全论文
• Datawhale hello-claw 教程