OpenClaw 源码解读：从「只会聊天」到「真正干活」的 AI 框架是怎么炼成的

优质文章学习记录

10 Apr 2026 — 20 min read

写在前面：这篇文章是给小白看的，所以我会说得比较啰嗦，尽量把每一个概念都掰开揉碎了讲。如果你已经是老司机了，可以直接跳到架构部分。另外，我是个程序员，不是 AI，所以这篇文章里没有那种 AI 写出来的车轱辘话，都是我的大白话。

一、先聊聊：OpenClaw 到底是个啥？

1.1 不是爬虫，是 AI 助手运行时

先说个可能让大家误会的事儿。我第一次听到 OpenClaw 这个名字的时候，还以为它是个爬虫框架（毕竟 Claw 是爪子的意思，感觉像是抓取数据用的）。结果一查，完全不是这么回事儿。

OpenClaw 是一个本地优先的开源 AI Agent 运行时框架。

这句话里有几个关键词，我来逐个解释：

本地优先（Local-first）：你的数据都在你自己的电脑上，不上传到任何云服务。这意味着隐私安全，但也意味着你的电脑得一直开着。
开源（Open Source）：代码完全公开，采用 MIT 协议，你可以随便改、随便用，甚至拿去卖钱都行。
AI Agent：这个翻译过来叫"AI 智能体"。简单说，就是不仅能聊天，还能真正干活的 AI。比如你跟它说"帮我整理一下桌面的文件"，它真的能去操作你的文件系统，而不是只给你一堆文字建议。
运行时框架（Runtime Framework）：它不是一个 AI 模型，而是一个让 AI 模型"跑起来"并能与外界交互的系统。

1.2 它跟 ChatGPT 有什么区别？

很多人会问：我已经有 ChatGPT 了，为什么还需要 OpenClaw？

这个问题的答案，恰恰是 OpenClaw 存在的核心价值。

ChatGPT 是"思考者"：你问它问题，它给你答案。但是它没法直接操作你的电脑、访问你的文件、帮你发邮件。它只能给你一堆文字建议，然后你自己去执行。

OpenClaw 是"执行者"：它把 ChatGPT 这样的 AI 模型和你本地的系统连接起来。你跟它说"帮我整理桌面的文件"，它会：

先看看你桌面上有什么文件
分析哪些是重复的、哪些是临时文件
真的动手去移动、删除、重命名这些文件
最后给你一个整理报告

用一个公式来总结：

OpenClaw = Gateway（网关） + Agent Runtime（运行时） + Skills（技能） + Memory（记忆）

这四个词儿后面我会详细解释，现在你只需要知道：OpenClaw 是坐在 AI 模型和外部世界中间的一个"翻译官"兼"执行者"。

1.3 这个项目有多火？

既然是源码解读，我得先让你对这个项目有个直观的感受。

OpenClaw 的作者是奥地利工程师 Peter Steinberger，他是 PSPDFKit（一个 PDF 处理库）的创始人。这个项目最初叫 Clawdbot（是对 Claude 的谐音玩笑），后来因为商标问题改名叫 Moltbot，最后在 2026 年 1 月 30 日定名为 OpenClaw。

截止到 2026 年 4 月：

GitHub 星标：34.7 万+（史上增长最快的开源 AI 项目）
Fork 数：6.9 万+
贡献者：900+ 人
社区技能（Skills）：100+ 个预置技能，支持扩展

这个项目之所以这么火，我觉得核心原因是：它解决了 AI 从"能聊天"到"能干活"的最后一公里问题。

二、整体架构：像个洋葱一样一层一层剥开

2.1 先看一眼目录结构

OpenClaw 的源码是典型的 Monorepo（单体仓库）结构，意思就是把所有东西都放在一个仓库里。打开它的 GitHub 仓库，你会看到这样一个目录结构：

openclaw/ ├── src/ # 核心源码（TypeScript） │ ├── agents/ # Agent 运行时、工具、沙箱 │ ├── gateway/ # Gateway 服务器、协议实现 │ ├── channels/ # 各平台通道实现 │ ├── sessions/ # 会话管理 │ ├── memory/ # 记忆搜索与向量检索 │ ├── cli/ # 命令行接口 │ └── ... # 其他模块 ├── skills/ # 内置的默认技能 ├── apps/ # 配套原生应用（macOS/iOS/Android） ├── extensions/ # 扩展插件（Discord、飞书、Matrix 等） ├── ui/ # 控制面板前端 ├── docs/ # 官方文档 └── package.json # 项目依赖配置

这个目录结构其实已经暗示了 OpenClaw 的核心架构。让我用一张图来概括一下：

┌─────────────────────────────────────────────────────────┐ │ 用户入口层 │ │ Telegram / WhatsApp / Discord / Slack / iMessage 等 │ └─────────────────────┬───────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Channel 适配层 │ │ 把不同平台的消息格式统一成 OpenClaw 内部格式 │ └─────────────────────┬───────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Gateway 网关层 │ │ WebSocket 服务器 · 消息路由 · 会话管理 · 热重载 │ └─────────────────────┬───────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Agent 运行时层 │ │ Agent Runner · 工具调度 · 技能加载 · 上下文管理 │ └─────────────────────┬───────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ AI 模型层 │ │ Claude / GPT / Gemini / DeepSeek / 本地模型 │ └─────────────────────────────────────────────────────────┘

2.2 五层服务架构

OpenClaw 源码实现了清晰的五层服务分层，每一层职责分明、松耦合。我逐层来解释：

第 1 层：渠道适配层（Channel Adapter）

这一层负责把不同平台的消息"翻译"成 OpenClaw 内部统一的格式。

目前支持的平台有：

即时通讯：WhatsApp、Telegram、Discord、Slack、Signal、iMessage
企业平台：Microsoft Teams、飞书、钉钉
其他：Matrix、Nostr、Twitch、WebChat

每个平台都有自己的消息格式、API、连接方式。比如 Telegram 用 Bot API，WhatsApp 用 Baileys 库（一个逆向工程的库），Discord 用官方的 Bot API。OpenClaw 的做法是为每个平台写一个"适配器"（Adapter），把这些差异屏蔽掉。

举个例子，当你在 Telegram 发送消息时：

Telegram 的服务器会通过 Webhook 把消息推送给 OpenClaw
OpenClaw 的 Telegram 适配器收到消息
适配器把 Telegram 的消息格式转换成 OpenClaw 内部的统一格式
转换后的消息交给 Gateway 处理

第 2 层：网关服务层（Gateway Server）

这是 OpenClaw 的"心脏"。Gateway 是一个常驻运行的进程，暴露两个接口：

WebSocket（默认端口 18789）：主控制协议，所有方法调用、事件推送都走这里
HTTP（同端口）：处理 Webhook 回调、工具调用等

Gateway 的核心职责：

消息路由：收到消息后，根据会话键（Session Key）找到对应的 Agent 处理
会话管理：维护用户会话状态、上下文
热重载：支持配置文件修改后自动重新加载
插件管理：加载和管理各种插件

第 3 层：Agent Runner（智能体运行器）

这一层负责具体的任务执行。它会：

选择合适的 AI 模型（根据配置）
管理多个 API Key 的轮换和冷却
拼装完整的提示词（System Prompt + 上下文 + 用户输入）
管理 Token 上下文窗口

第 4 层：Agent Runtime / Agentic Loop

这是 OpenClaw 最核心的运行循环，遵循 ReAct（Reason + Act）范式。

简单说，就是这样一个循环：

接收任务
构建上下文（从会话历史和记忆中提取相关信息）
调用 AI 模型进行推理
模型决定：
- 如果需要更多信息 → 执行工具调用
- 如果已经有答案 → 生成文本回复
如果执行了工具，把工具结果塞回上下文，回到第 3 步
保存记忆
发送回复给用户

第 5 层：Memory & Skills（记忆与技能）

这是 Agent 的"经验"和"方法论"。

记忆系统：存储会话历史、重要事件、学习总结
技能系统：定义 Agent 能执行的各种操作

三、核心模块源码解析

现在我们来深入源码，看看这些模块具体是怎么实现的。

3.1 会话管理模块（Session Management）

会话（Session）是 OpenClaw 中一个核心概念。简单说，会话就是一次连续对话的上下文。

核心文件：

src/sessions/ ├── session-manager.ts # 会话管理器 ├── session-store.ts # 会话存储 └── context-builder.ts # 上下文构建器

会话的类型：

OpenClaw 的会话分为两类：

类型	说明	权限
main	主会话，用于与用户直接对话	拥有完整工具权限，可以执行任何操作
非 main	群组/渠道会话	可配置沙箱隔离，权限受限

会话键（Session Key）：

OpenClaw 用"会话键"来唯一标识一个会话。会话键的生成规则是：

session-key = agent-id + workspace-id + sender-id

这个三维设计确保了：

不同的 Agent 之间相互隔离
不同的工作区之间相互隔离
不同的发送者之间相互隔离

会话持久化：

会话数据存储在文件系统里，路径是：

~/.openclaw/sessions/<session-key>/ ├── messages.jsonl # 消息历史（JSON Lines 格式） ├── context.json # 当前上下文 └── state.json # 会话状态

这里有个设计细节值得注意：消息历史用 JSONL 格式存储。JSONL（JSON Lines）是每行一个 JSON 对象。这种格式的好处是：

可以逐行读取，不需要一次性加载整个文件
可以方便地追加新消息，不需要修改整个文件
即使文件损坏，也只会影响部分数据

3.2 工具调度模块（Tool Orchestrator）

工具（Tools）是 Agent 与外界交互的"手"。OpenClaw 内置了很多工具：

工具	说明
exec / bash	执行 Shell 命令，支持 PTY（伪终端）
read / write / edit	文件系统操作
browser	控制 Chrome/Chromium 浏览器（通过 CDP 协议）
canvas	Agent 驱动的可视化工作区
nodes	控制移动设备（相机、屏幕录制、位置）
sessions_*	多 Agent 协作工具
memory_search / memory_get	语义记忆检索
web_search / web_fetch	网络搜索与内容抓取

工具执行流程：

用户请求 → 权限检查 → 审批请求（如果需要） → 执行工具 → 记录日志 → 返回结果

权限分级：

OpenClaw 把操作分为三个风险等级：

风险等级	操作类型	处理方式
低风险	读取文件、搜索网络	自动执行
高风险	执行命令、发送消息	需要人工确认
禁止	危险操作（如格式化磁盘）	直接拦截

审批机制：

对于高风险操作，OpenClaw 会先暂停执行，向用户发送审批请求。用户可以选择：

批准：执行这次操作
拒绝：取消这次操作
信任：以后这类操作自动执行（慎用）

审批请求通过 WebSocket 推送到客户端，客户端弹窗让用户确认。

3.3 技能引擎模块（Skill Engine）

技能（Skills）是 OpenClaw 的扩展机制，也是它从"能聊天"进化到"能干活"的关键。

什么是 Skill？

简单说，Skill 就是一个"工作流描述 + 可选脚本"的组合。它告诉 Agent：

在什么情况下使用这个技能
使用这个技能需要什么权限
具体怎么执行

Skill 的三种类型：

类型	位置	说明
内置 Skills	skills/ 目录	随 OpenClaw 发布，开箱即用
托管 Skills	~/.openclaw/skills/	通过 ClawHub 安装
工作区 Skills	workspace/skills/	用户自定义

Skill 目录结构：

每个 Skill 是一个独立目录，核心是 SKILL.md 文件：

my-skill/ ├── SKILL.md # 技能定义（必需） ├── README.md # 使用说明 ├── scripts/ # 脚本目录 │ └── main.mjs # 执行脚本 └── references/ # 参考资料

SKILL.md 的格式：

SKILL.md 是一个 Markdown 文件，开头是 YAML 格式的元数据，后面是指令：

--- name: weather description: 获取天气信息 triggers: - 天气 - weather requires: - network --- # 天气技能 当用户询问天气时，使用此技能。 ## 执行步骤 1. 调用天气 API 获取数据 2. 格式化输出给用户 ## 注意事项 - 需要网络连接 - 默认使用用户的位置信息

Skill 的加载流程：

收到用户消息 → 匹配触发词 → 检查本地技能目录 → 如果没有，从 ClawHub 下载 → 验证技能 → 加载到内存

ClawHub：

ClawHub 是 OpenClaw 的技能市场，类似 npm 或 PyPI。用户可以通过命令安装技能：

openclaw skill install weather

四、记忆系统：AI 的"长期记忆"

4.1 为什么需要记忆系统？

如果你用过 ChatGPT，你可能会发现：每次开启新对话，它都不记得之前聊过什么。这是因为 ChatGPT 的对话是独立的，没有"长期记忆"。

但对于一个个人 AI 助手来说，长期记忆是必须的。你希望你的助手：

记住你的偏好（比如你喜欢的编程语言）
记住你的重要信息（比如你的邮箱地址）
记住之前的对话（避免重复询问）

OpenClaw 的记忆系统就是为了解决这个问题。

4.2 三层记忆架构

OpenClaw 采用三层记忆架构：

层级	存储位置	内容	生命周期
短期记忆	会话内存	当前对话上下文	会话结束即销毁
长期记忆	MEMORY.md	精选重要信息	持久化存储
每日记忆	memory/YYYY-MM-DD.md	每日对话原始记录	持久化存储

MEMORY.md：

这是最重要的记忆文件，存放在 ~/.openclaw/MEMORY.md。它的格式是：

# 长期记忆 ## 用户信息 - 名字：张三 - 邮箱：[email protected] - 常用编程语言：Python、TypeScript ## 重要事件 - 2026-03-15：开始学习 OpenClaw - 2026-03-20：完成第一个 Skill 开发 ## 学习总结 - 用户喜欢简洁的回答 - 用户习惯用中文交流

Agent 在每次对话时，会自动读取这个文件，把其中的信息注入到上下文中。

每日记忆：

每日记忆存放在 ~/.openclaw/memory/ 目录下，每天一个文件：

~/.openclaw/memory/ ├── 2026-04-01.md ├── 2026-04-02.md ├── 2026-04-03.md └── ...

每日记忆记录当天的所有对话原始内容。它的作用是：

作为长期记忆的候选来源
支持按日期回溯查询

4.3 记忆的读取和写入

读取流程：

收到用户消息 → 读取 MEMORY.md → 读取当日记忆文件 → 构建完整上下文 → 发送给 AI 模型

写入流程：

AI 模型回复后，OpenClaw 会：

把对话追加到当日记忆文件
如果有重要信息（如用户告知邮箱），更新 MEMORY.md

写入 MEMORY.md 的逻辑比较复杂，OpenClaw 会：

提取对话中的关键信息
与已有记忆合并（去重、更新）
按类别整理（用户信息、重要事件、学习总结等）

五、配置文件体系：用 Markdown 定义 Agent 人格

OpenClaw 有一个非常独特的设计：用 Markdown 文件而不是 JSON/YAML 来配置 Agent。

这个设计背后的理念是：配置文件应该易于阅读和编辑，而 Markdown 是最适合人类阅读的格式。

5.1 核心配置文件

OpenClaw 定义了一组核心配置文件，每个文件负责一个方面：

文件	职责	示例内容
AGENTS.md	核心任务、工作流程、常用命令	如何处理用户请求的标准流程
SOUL.md	工作风格、对话风格、人格设定	你是一个友好、专业、简洁的助手
IDENTITY.md	智能体在系统中的职责定位	你是 OpenClaw 的主 Agent
USER.md	用户使用场景和目标	用户是一个程序员，主要用 OpenClaw 辅助开发
TOOLS.md	环境特定的工具配置信息	可用的工具列表、权限设置
HEARTBEAT.md	周期性唤醒与健康检查	每天早上 8 点提醒用户今日待办
BOOTSTRAP.md	初始化配置	第一次启动时的引导流程
MEMORY.md	长期记忆、重要事件、学习总结	用户个人信息、重要事件

5.2 SOUL.md 示例

SOUL.md 是定义 Agent 人格的核心文件。一个典型的 SOUL.md 内容如下：

# Soul 定义 ## 核心人格 你是一个名叫 Molty 的 AI 助手，你的吉祥物是一只太空龙虾。 ## 对话风格 - 友好但不谄媚 - 专业但不生硬 - 简洁但信息完整 - 喜欢用表情符号 🦞 ## 工作原则 1. 用户隐私第一：绝不主动询问或记录敏感信息 2. 效率优先：能用一句话说清楚的事，绝不用两句 3. 诚实透明：不知道就说不知道，不编造信息 4. 主动负责：发现问题主动提醒用户 ## 能力边界 - 你不能访问用户的银行账户 - 你不能替用户做重要决定（如投资、医疗） - 你不能执行危险操作（如 rm -rf /）

5.3 为什么用 Markdown？

用 Markdown 而非 JSON/YAML 来配置 Agent，有几个好处：

可读性：Markdown 是人类最容易阅读的格式之一
可编辑性：任何文本编辑器都能编辑
可版本控制：可以放在 Git 仓库里，跟踪变更历史
AI 友好：AI 模型可以直接读取和理解 Markdown 内容

这个设计体现了 OpenClaw 的核心理念：朴素、可读、可版本控制。

六、安全架构：让 AI 安全地干活

让 AI 执行系统命令、操作文件，听起来很酷，但也带来了巨大的安全风险。如果 AI 被恶意利用，可能会：

删除重要文件
泄露隐私信息
执行恶意代码

OpenClaw 的安全架构就是围绕这些风险设计的。

6.1 信任边界（Trust Boundary）

OpenClaw 定义了明确的信任边界，把操作分为三类：

低风险操作：

读取文件（非敏感目录）
网络搜索
解析数据

这些操作可以自动执行，不需要用户确认。

高风险操作：

执行 Shell 命令
发送消息到外部平台
修改配置文件

这些操作需要用户明确批准。

禁止操作：

格式化磁盘
修改系统关键文件
访问其他用户的会话

这些操作直接拦截，即使用户批准也不执行。

6.2 沙箱隔离

对于群组/渠道会话（非 main 会话），OpenClaw 支持在 Docker 沙箱中执行：

┌─────────────────────────────────────┐ │ 主进程 │ │ ┌───────────┐ ┌───────────┐ │ │ │ main 会话 │ │ main 会话 │ │ │ └───────────┘ └───────────┘ │ └─────────────────────────────────────┘ ┌─────────────────────────────────────┐ │ Docker 沙箱 │ │ ┌───────────┐ ┌───────────┐ │ │ │ 群组会话 1 │ │ 群组会话 2 │ │ │ └───────────┘ └───────────┘ │ └─────────────────────────────────────┘

沙箱的好处是：

隔离文件系统访问
限制网络访问
防止恶意操作扩散

6.3 凭证管理

API Key、密码等敏感信息，OpenClaw 采用两种方式管理：

环境变量：

exportANTHROPIC_API_KEY=sk-xxx exportOPENAI_API_KEY=sk-xxx

加密配置文件：
OpenClaw 支持在配置文件中加密存储敏感信息，使用 AES-256 加密。

6.4 审计日志

所有工具调用都会记录审计日志，包括：

调用时间
调用的工具
调用参数
执行结果
是否经过审批

审计日志存放在 ~/.openclaw/logs/audit.log，支持通过 runId 追踪完整的调用链路。

七、源码阅读路线图

如果你想把 OpenClaw 的源码读一遍，我建议按以下路线：

7.1 第一阶段：理解启动流程

CLI 入口：src/cli/index.ts
- 看命令是如何解析和分发的
- 理解 openclaw gateway 命令做了什么
Gateway 启动：src/gateway/boot.ts
- 看 Gateway 是如何初始化的
- 理解配置加载、插件加载的顺序

7.2 第二阶段：理解消息处理

Channel 加载：src/channels/
- 选一个你熟悉的平台（比如 Telegram），看它的适配器是如何实现的
- 理解消息格式转换
消息路由：src/sessions/
- 看会话键是如何生成的
- 理解消息是如何路由到对应 Agent 的

7.3 第三阶段：理解核心循环

Agent Runner：src/agents/
- 看 Agent 是如何被调度的
- 理解模型选择、API Key 轮换
Agentic Loop：src/agents/pi-embedded-runner/run/attempt.ts
- 这是 OpenClaw 最核心的文件
- 理解 ReAct 循环是如何实现的

7.4 第四阶段：理解扩展机制

工具调用：src/agents/tools/
- 看工具是如何注册和调用的
- 理解权限检查和审批机制
Skills 执行：skills/
- 选一个内置 Skill，看它的 SKILL.md 是怎么写的
- 理解 Skill 是如何被加载和执行的

7.5 第五阶段：理解持久化

记忆写入：src/memory/
- 看记忆是如何存储和检索的
- 理解向量化检索（如果涉及）

八、总结：OpenClaw 的设计哲学

读完 OpenClaw 的源码，我最大的感受是：这是一个工程师友好的框架。

它的设计哲学可以总结为以下几点：

8.1 本地优先

所有数据都在用户设备上，不上传云端。这既是隐私保护，也是成本控制——你不需要为云端存储付费。

8.2 网关而非框架

OpenClaw 不是给你一个 SDK 让你在代码里调用，而是一个独立运行的服务。这种设计的好处是：

你可以用任何语言与它交互（通过 WebSocket）
它可以常驻运行，不需要每次启动都初始化

8.3 模型无关

OpenClaw 不绑定任何 AI 模型，你可以：

用 Claude、GPT、Gemini 等云端模型
用 Ollama、LM Studio 运行本地模型
甚至配置多个模型，让它们互相备份

8.4 插件化内核

Skills、Channels、Providers 都是可插拔的。这意味着：

你可以只安装你需要的功能
你可以自己开发插件扩展功能

8.5 Markdown 即配置

用 Markdown 文件定义 Agent 人格、记忆，而不是用 JSON/YAML 或数据库。这个设计体现了"朴素、可读、可版本控制"的工程哲学。

九、写在最后

OpenClaw 是一个很有野心的项目——它试图解决 AI 从"能聊天"到"能干活"的最后一公里问题。

读完源码，你会发现它的架构设计非常清晰，每一层职责分明。虽然代码量不小，但只要理解了核心架构，读起来并不会太困难。

如果你是 AI 应用开发者，我强烈建议你把 OpenClaw 的源码读一遍。它代表了一种可行的 AI Agent 架构范式——微内核 + 插件化 + 分布式。这种架构在未来可能会成为 AI 应用的标准模式。

最后，OpenClaw 的官方文档在 docs.openclaw.ai，社区在 Discord（discord.com/invite/clawd），有问题可以去那里问。

希望这篇文章对你有帮助。如果有什么不明白的地方，欢迎留言讨论。🦞