深度拆解 OpenClaw:从源码看懂 2026 年最火 AI Agent 的架构设计-夜雨聆风

深度拆解 OpenClaw:从源码看懂 2026 年最火 AI Agent 的架构设计

2026 年初，AI 领域发生了一次决定性的转变——从被动的聊天机器人，转向能够自主执行真实任务的 AI Agent。而站在这场变革中心的，正是 OpenClaw。

这个开源框架从 9,000 颗 GitHub Star 暴涨到 145,000+，仅用了一周时间。它到底有什么魔力？

本文将从源码层面，深度拆解 OpenClaw 的架构设计，带你看懂这个 2026 年最火 AI Agent 框架的核心原理。

一、全景概览：OpenClaw 的分层架构

OpenClaw 的架构可以分为六个核心层次，每一层各司其职，通过清晰的边界实现解耦：

层次	核心模块	职责
入口层	`openclaw.mjs` → `src/index.ts`、`src/cli/`	进程入口、环境初始化、CLI 命令注册
网关控制面	`src/gateway/`	WebSocket + HTTP 控制面，统一管理客户端、节点、工具、事件
Agent 执行层	`src/agents/`	模型选择、认证轮换、上下文窗口守卫、工具调用、安全策略
通道与消息 I/O	`src/channels/` 、`src/discord/`、`src/telegram/` 等	多通道接入、路由、消息发送
插件与扩展	`src/plugins/` 、`extensions/*`	插件注册、扩展工具/通道/HTTP 路由/CLI 命令
基础设施	`src/config/` 、`src/media/`、`src/memory/`、`src/infra/`	配置管理、媒体处理、向量记忆、安全沙箱

这种分层设计的核心理念是：Agent 和 Gateway 通过 WebSocket RPC 协议解耦，通道和 Agent 通过统一的路由/sessionKey 解耦，插件和核心通过注册表和 SDK 隔离。

数据来源：Moely – OpenClaw Source Code Review

二、消息流转全景：一条消息的完整旅程

当你在 Telegram、Discord 或 Slack 中发送一条消息时，它会经历一个精心设计的八步流水线：

用户发送消息 → 通道适配器（格式标准化）→ Gateway 网关（路由分发）
    → 会话路由 + 队列控制 → Agent Runner（构建上下文）
    → LLM API 处理 → Agentic Loop（自主决策循环）
    → Response Path → 通道适配器（格式化输出）→ 用户收到回复

关键路径详解：

通道适配器：接收原始消息，标准化格式，提取附件
Gateway 网关：中央协调器，Session Router 确定消息归属的会话
Lane Queue：并发控制层，防止多会话请求冲突或上下文丢失
Agent Runner：三个组件并行工作——模型选择器（Model Resolver）、系统提示词构建器（System Prompt Builder）、会话历史加载器（Session History Loader）
Context Window Guard：检查上下文是否接近模型 token 上限，必要时进行压缩
Agentic Loop：核心决策循环（详见第七节）
Response Path：流式输出，通道适配器将结果翻译为平台特定格式

数据来源：RoboRhythms – How OpenClaw AI Agent Works

三、Pi 内核：极简主义的哲学

OpenClaw 的心脏是 Pi——一个由 Mario Zechner 创建的极简编码 Agent。Pi 的设计哲学可以用一句话概括：

如果你想让 Agent 做新的事情，不要去下载扩展或技能包——让 Agent 自己扩展自己。

Pi 拥有所有 Agent 中最短的系统提示词，以及仅仅 4 个核心工具：

工具	功能
`Read`	读取文件
`Write`	写入文件
`Edit`	编辑文件
`Bash`	执行命令

这不是偷懒，而是刻意的架构决策。正如 Armin Ronacher 在其分析中所说：Pi 的整个理念是，如果你想让 Agent 做它还不会做的事情，你让它自己写代码来扩展自己。它推崇代码编写和运行代码的理念。

OpenClaw 如何消费 Pi

查看 package.json，OpenClaw 依赖四个 Pi 包（均为 v0.51.0）：

包名	角色
`@mariozechner/pi-agent-core`	核心类型：AgentMessage、AgentTool、AgentEvent、StreamFn
`@mariozechner/pi-ai`	LLM 抽象层：Model、complete()、streamSimple()、OAuthCredentials
`@mariozechner/pi-coding-agent`	会话管理：SessionManager、createAgentSession()、Skill、工具工厂
`@mariozechner/pi-tui`	终端 UI：TUI、Component、SlashCommand

OpenClaw 不 fork Pi，而是包装它。 Pi 提供基础的 Agent 循环、工具系统和会话管理；OpenClaw 在此之上添加网关、通道、额外工具、记忆、浏览器自动化和子 Agent 系统。

数据来源：CHATTERgo – OpenClaw Deep Dive

四、工具系统：从 4 到 24+ 的扩展之路

OpenClaw 不是简单地使用 Pi 的四个核心工具，而是对每一个都进行了生产级加固包装，代码位于 src/agents/pi-tools.ts：

核心工具的包装

Pi 原始工具	OpenClaw 包装	增强内容
Read	`createOpenClawReadTool`	MIME 检测、图片清理（移除超大图片）、Claude Code 兼容
Write	沙箱包装器	路径守卫，防止沙箱模式下写入沙箱根目录之外
Edit	沙箱包装器	参数标准化（old_string/new_string → oldText/newText）、沙箱路径守卫
Bash	完全替换	替换为 OpenClaw 的 `exec` 工具——支持 Docker 沙箱执行、后台进程管理、安全策略、超时处理、审批工作流

20+ 额外工具

类别	工具
消息	message、sessions_send、sessions_spawn、sessions_list、sessions_history
浏览器	browser（13 个子操作：navigate、snapshot、act、tabs、console、pdf…）
Web	web_search、web_fetch
媒体	image（视觉分析）、tts（文本转语音）
基础设施	gateway、nodes、cron、canvas、memory
通道特定	discord_actions、slack_actions、telegram_actions、whatsapp_actions
代码	apply_patch（OpenAI Codex 专用）、process（后台任务）

这种 “4 到 24+” 的扩展模式是一个值得学习的架构模式：Pi 以 4 个工具起步，OpenClaw 包装这 4 个并添加 20+ 个，但所有工具都通过 Pi 统一的 AgentTool 接口传递。Agent 循环不关心有多少工具——它只执行 LLM 选择的工具。

五、8 层工具策略系统：安全的核心

OpenClaw 架构中最精密的部分之一是其工具策略系统。在任何工具执行之前，它必须通过 八层允许/拒绝过滤器：

层级	策略	说明
1	Profile 策略	`tools.profile` — 命名策略预设
2	Provider Profile	`tools.byProvider.profile` — 按 LLM 提供商覆盖
3	全局白名单	`tools.allow` — 实例级限制
4	Provider 白名单	`tools.byProvider.allow` — 按提供商的全局限制
5	Agent 特定	`agents.{id}.tools.allow` — 按 Agent 限制
6	Group 策略	通道级限制（如在 Discord 服务器中禁用 exec）
7	Sandbox 策略	Docker 沙箱限制
8	Subagent 策略	子 Agent 的限制

实际效果：一个在你个人 WhatsApp 会话中允许的浏览器工具，可以在 Discord 群聊中被拒绝，而一个沙箱化的子 Agent 可能有完全不同的限制集。每一层都缩小可用工具范围——最严格的组合胜出。

这种多层策略系统对于多租户 Agent 至关重要。当一个 Agent 同时服务 WhatsApp DM、Discord 服务器和沙箱化子 Agent 时，你需要可组合的安全策略，而不是单一的允许/拒绝列表。

六、记忆系统：Markdown 文件 + 向量搜索

OpenClaw 的记忆系统是其最独特的设计之一。它不使用数据库或专有格式，而是使用一组纯 Markdown 文件来定义 Agent 的身份和记忆：

核心身份文件

文件	用途
`SOUL.md`	Agent 的人格、价值观和行为默认值——相当于 AI 的”性格表”
`user.md`	关于用户的信息：偏好、沟通风格、需要始终记住的上下文
`memory.md`	跨会话持久化的长期记忆
`tools.md`	Agent 可用的工具文档及使用策略
`bootstrap.md`	启动协议，告诉 Agent 如何初始化自己

向量搜索增强

除了文件存储，OpenClaw 的记忆系统（src/memory/）还支持：

向量嵌入：支持 OpenAI、Gemini 和本地 node-llama-cpp 嵌入提供商
SQLite-vec：使用 SQLite 向量扩展的本地向量存储
混合搜索：结合向量相似度搜索和关键词匹配
自动索引：自动索引会话记录、MEMORY.md 和每日笔记
去重：防止跨重建索引的重复条目

安全作用域至关重要：

主会话（与所有者的直接聊天）：可以读写 MEMORY.md 和访问向量搜索
群组会话：不能访问 MEMORY.md 或个人记忆——防止数据泄露

这种设计的巧妙之处在于：因为身份文件是纯 Markdown，你可以像编辑任何文本文档一样读取、编辑和版本控制它们。不需要理解代码库就能改变 Agent 的行为。

七、Agentic Loop：让 AI 真正自主行动

Agentic Loop 是 OpenClaw 与普通聊天机器人的根本区别。OpenClaw 不使用简单的”调用 LLM → 获取文本”架构，而是采用递归式自主循环。

工作原理

当一条消息到达时，系统不只是请求一个回复——它请求一个计划。它授予模型权限去唤醒、观察、使用工具、思考——反复进行，直到任务完成。

消息到达 → LLM 处理 → 是否包含工具调用？
    ├── 是 → 执行工具 → 将结果反馈给 LLM → 重新进入循环
    └── 否 → 视为最终文本 → 交给 Response Path

实际示例

假设你让 OpenClaw 检查收件箱、总结某个项目的邮件、并起草回复：

普通聊天机器人：会让你手动粘贴邮件内容
OpenClaw 的 Agentic Loop：调用邮件工具获取消息 → 将结果传给 LLM 进行总结 → 调用起草工具撰写回复——所有这些在你的聊天窗口显示任何文字之前就完成了

Pi 嵌入式运行器

Agentic Loop 的核心实现位于 src/agents/pi-embedded-runner/，它是 OpenClaw 包装 Pi Agent 循环的方式：

Phase 1 – 设置：解析工作区 + 沙箱 → 构建 OpenClaw 工具（Pi 的 4 个 + 20+ 额外工具）→ 打开 SessionManager → 加载 SettingsManager → 调用 createAgentSession()

Phase 2 – 上下文组装：构建系统提示词（基础 + 工具 + 技能 + SOUL.md + USER.md + AGENTS.md + HEARTBEAT.md）→ 解析模型 + 认证 → 加载完整历史 → 清理历史（Anthropic/Gemini 轮次排序）→ 自动注入图片 → 上下文裁剪扩展

Phase 3 – 执行：调用 session.prompt()（Pi 的实际 Agent 循环）→ subscribeEmbeddedPiSession() 包装 Pi 的流 → 每次工具调用前通过 8 层工具策略检查

Phase 4 – 完成：触发压缩（如果需要）→ 持久化到 JSONL → 格式化并发送回复 → 释放会话锁

Pi 扩展：上下文裁剪与压缩保护

OpenClaw 附带两个自定义 Pi 扩展：

上下文裁剪扩展（src/agents/pi-extensions/context-pruning/）：

软裁剪：截断大型工具结果，保留头部 + 尾部
硬清除：用占位符替换非常旧的工具结果
保护：永远不裁剪第一条用户消息之前的内容
触发条件：仅在 Anthropic 缓存 TTL 过期时激活（默认 5 分钟）

压缩保护扩展（src/agents/pi-extensions/compaction-safeguard.ts）：

防止压缩消耗过多上下文
单独总结被丢弃的消息
跟踪文件操作并包含在摘要中

八、子 Agent 系统：任务委派的艺术

OpenClaw 在 Pi 之上添加了子 Agent 编排层（src/agents/subagent-registry.ts）：

功能	说明
生成	`sessions_spawn` 工具创建子 Agent 会话，拥有独立的工作区和工具集
注册表	在内存 + 磁盘中跟踪子 Agent 运行状态
生命周期	监听 Pi Agent 事件：启动/完成/错误
清理	可配置策略——删除或保留已完成的子 Agent 数据
通知	子 Agent 完成时通知父 Agent
跨进程	使用 Gateway RPC 跨进程等待子 Agent

实际应用：OpenClaw Agent 可以委派任务——”研究这个主题”生成一个研究子 Agent，”起草回复”生成一个写作子 Agent——所有这些由父 Agent 协调。

此外，OpenClaw 还实现了 **Agent Communication Protocol (ACP)**（src/acp/），这是一个新兴的 Agent 间通信标准，允许外部 ACP 兼容客户端通过 stdio（NDJSON）控制 OpenClaw Agent，为与其他 Agent 框架的互操作性打开了大门。

九、浏览器自动化：Playwright + AI 快照

OpenClaw 实现了一个精密的浏览器控制系统（browser-tool.ts 中 725 行代码），基于 Playwright 和 Chrome DevTools Protocol (CDP)。

13 个浏览器操作

navigate、snapshot、screenshot、act（点击/输入/拖拽）、tabs、open、focus、close、console、pdf 等。

视觉系统：无需外部库

OpenClaw 不使用外部视觉库（tesseract、pixelmatch 等）来理解网页。它利用 Playwright 内部的 _snapshotForAI 方法——一个可访问性树 API，生成稳定的、基于角色的元素引用。

Agent 通过稳定的引用来操作元素：click e7、type e4 "user@example.com"。这比基于像素的方法更可靠，因为角色引用能够在页面布局变化、动画和响应式断点中保持稳定。

多配置架构

配置	说明
`openclaw`	Playwright 管理的浏览器，独立用户数据目录，与个人浏览器完全隔离
`chrome extension`	通过本地扩展中继连接到你的实际 Chrome 浏览器，适用于需要已登录会话的场景
`sandbox`	Docker 容器化浏览器，完全隔离，用于不受信任的站点
`remote`	Browserless.io 或类似的远程 CDP 端点，用于服务器端自动化

十、成本与部署：真实的权衡

运行 OpenClaw 的成本取决于你的部署方式：

方案	硬件要求	API 成本	隐私级别	适用场景
云端 LLM （Claude/GPT/Gemini）	任何现代机器	$2-75+/天	中等	追求能力，不需高端硬件
本地 LLM （Ollama）	16GB+ RAM，推荐独立 GPU	$0	高	隐私优先，有合适硬件
混合方案（本地路由 + 云端复杂任务）	16GB+ RAM	低到中等	高（常规任务）	成本敏感的高级用户

方案

硬件要求

API 成本

隐私级别

适用场景

云端 LLM

（Claude/GPT/Gemini）

任何现代机器

$2-75+/天

中等

追求能力，不需高端硬件

本地 LLM

（Ollama）

16GB+ RAM，推荐独立 GPU

高

隐私优先，有合适硬件

混合方案

（本地路由 + 云端复杂任务）

16GB+ RAM

低到中等

高（常规任务）

成本敏感的高级用户

混合方案的最佳实践

社区中大多数认真使用的用户正在采用混合方案：

通过 OpenRouter 连接，而非单一 LLM 提供商
设置 Gemini Flash 等廉价模型作为日常任务默认
配置 Claude Sonnet 作为复杂推理的子 Agent
设置每日和每小时 token 预算限制
监控哪些任务消耗最多 token 并调整模型分配

任务类型	推荐模型	原因
日常对话	Gemini Flash / GPT-4o mini	低复杂度，低成本
文档总结	Gemini Pro / Claude Haiku	较大上下文，中等成本
代码生成/调试	Claude Sonnet	高推理需求
多步骤 Agent 任务	Claude Sonnet + 子 Agent	可靠性优先

有用户报告使用混合方案一整天仅花费 $2.50，而使用单一云端模型三天花了 $75。差异在于刻意的模型路由，而非降低能力。

数据来源：RoboRhythms – How OpenClaw AI Agent Works

十一、安全模型：三层防护

OpenClaw 的安全跨越入站、执行和数据三个边界：

入站安全

DM 配对：未知发送者需要验证码
显式白名单：明确允许的用户列表
群组提及门控：群组中需要 @提及才响应

执行安全

Docker 沙箱：非主会话在容器中执行
8 层工具策略：前文详述的多层过滤系统
提升模式：敏感操作需要显式切换到提升权限

数据安全

本地存储：所有数据存储在本地
记忆作用域：主会话 vs 群组会话的严格隔离
凭证存储：~/.openclaw/credentials/ 独立管理
网络隔离：Gateway WebSocket 仅监听回环地址（127.0.0.1:18789），基于 token 认证

三个权限级别：non-main（最受限）→ main（正常）→ elevated（显式切换，用于敏感操作）。

十二、架构启示：值得学习的设计模式

通过对 OpenClaw 源码的深度分析，我们可以提炼出几个值得学习的架构模式：

1. 包装而非 Fork

OpenClaw 将 Pi 作为 npm 包依赖，包装其工具和会话管理，而不是 fork 代码库。这意味着 Pi 的改进会自动流向下游。

2. 4-to-24+ 工具扩展模式

Pi 以 4 个工具起步，OpenClaw 包装这 4 个并添加 20+ 个——但所有工具都通过 Pi 统一的 AgentTool 接口。Agent 循环不关心有多少工具，它只执行 LLM 选择的工具。

3. 多层策略系统

当一个 Agent 同时服务多个通道和多种角色时，你需要可组合的安全策略，而不是单一的允许/拒绝列表。OpenClaw 的 8 层策略系统是这方面的典范。

4. 扩展优于插件

Pi 的扩展系统（生命周期钩子 + 状态持久化）比插件系统更适合 Agent 内部关注点（上下文管理、压缩），因为扩展可以拦截 Agent 循环本身。

5. 完整历史 + 智能淘汰

OpenClaw 将完整对话历史传递给 LLM，使用压缩（持久化总结）和裁剪（瞬态修剪）来管理成本——保留了激进总结会丢失的细微差别。

6. 身份即文件

用纯 Markdown 文件定义 Agent 身份和记忆，让非开发者也能定制 Agent 行为，同时支持版本控制和团队协作。

总结

OpenClaw 的成功不是偶然的。它在架构层面做出了一系列深思熟虑的设计决策：

极简内核 + 丰富扩展：Pi 的 4 个工具 + OpenClaw 的 20+ 工具
递归式自主循环：Agentic Loop 让 AI 真正能够自主行动
多层安全：8 层工具策略 + 三层权限 + 沙箱隔离
本地优先：数据存储在本地，身份文件可读可编辑
灵活部署：云端、本地、混合三种方案适应不同需求

对于想要构建自己的 AI Agent 系统的开发者来说，OpenClaw 的源码是一本值得反复研读的教科书。它展示了如何在保持架构简洁的同时，构建一个功能强大、安全可靠的自主 AI Agent 框架。

参考链接汇总

OpenClaw 官方文档
OpenClaw GitHub 仓库
CHATTERgo – OpenClaw Deep Dive: Architecture, Agent Loop
RoboRhythms – How OpenClaw AI Agent Works
Moely – OpenClaw Source Code Review
Gate.com – What Is OpenClaw
Optimum Web – OpenClaw: The Definitive Guide
Armin Ronacher – Pi: The Minimal Agent Within OpenClaw
ClawHub Skills Registry