2026年🦞 OpenClaw (原ClawdBot) 开源项目深度分析

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

本文档是对 OpenClaw (原 ClawdBot) 项目的全面技术分析，旨在帮助开发者深入理解其实现原理。

📝 项目更名历史：

Clawdbot (2025.11.25 - 2026.1.27) — 最初的项目名称

Moltbot (2026.1.27 - ?) — 第一次更名，寓意”蜕变”

OpenClaw (当前) — 最终更名为开源版本名称

OpenClaw 是一个功能强大的个人 AI 助手平台，它允许用户在自己的设备上运行 AI 助手，并通过多种即时通讯渠道（WhatsApp、Telegram、Discord、Slack 等）与之交互。

语言: TypeScript (ESM)
运行时: Node.js 22+ / Bun
包管理: pnpm
构建工具: TypeScript Compiler
测试框架: Vitest
代码规范: Oxlint + Oxfmt

本章聚焦于回答一个核心问题：当用户运行后，发生了什么？

我们将按照代码实际执行顺序，追踪从命令行输入到 Agent 接收消息的完整链路。

文件:

这是整个程序的第一个执行点，负责环境准备：

入口层做了什么？

文件:

入口层完成后，进入 CLI 层进行命令解析和路由：

设计亮点：

延迟加载: 子命令按需，加快启动速度
跨平台兼容: Windows 参数处理有特殊逻辑
快速路由: 简单命令无需加载完整框架

当用户执行时，CLI 路由到。

文件:

这是整个系统的控制中心，命令最终会调用：

Gateway 核心组件：

当 Gateway 启动完成后，各渠道开始监听消息。以 Telegram 为例：

消息流转路径：

关键代码片段（Telegram 消息处理）：

渠道抽象机制：

所有渠道都实现统一的接口，使得 Agent 无需关心消息来源：

小结：本章梳理了从到消息进入 Agent 的完整链路。理解了这条主线后，下一章我们将深入 Agent 内部，看看它是如何处理消息、调用工具、生成回复的。

OpenClaw 本质上是一个 AI Agent 系统，其核心在于实现了一个完整的 Agent 循环。这一节我们深入分析 Agent 的核心实现机制。

文件:

这是 Agent 运行的主入口函数：

关键设计点:

文件:

这是单次 Agent 执行的核心逻辑：

Agent 会话创建后，上下文管理是保证长对话正常运行的核心机制。

4.4.1 架构总览

4.4.2 会话存储机制

存储格式: JSON Lines ()

存储路径:

每行是一个独立的 JSON 对象：

设计优势:

增量写入: 每条消息追加写入，避免重写整个文件
容错性强: 单行损坏不影响其他消息
流式读取: 可以逐行读取处理大文件

4.4.3 Token 管理与估算

文件:

关键常量:

4.4.4 上下文窗口保护

文件:

4.4.5 Context Pruning (上下文裁剪)

这是核心的实时裁剪机制，在每次 Agent 运行时执行。

文件:

两级裁剪策略

软裁剪 (Soft Trim):

硬清除 (Hard Clear):

裁剪流程图:

4.4.6 Compaction Safeguard (压缩安全机制)

当会话需要进行主动压缩（生成历史摘要）时触发。

文件:

4.4.7 分阶段摘要生成 (summarizeInStages)

文件:

摘要生成流程:

4.4.8 历史轮次限制

文件:

Agent 使用事件驱动模型处理 LLM 的流式响应。这是一个发布-订阅模式的实现。

4.5.1 为什么需要事件驱动？

当 LLM 生成回复时，它不是一次性返回完整内容，而是逐字符/逐 Token 流式输出。为了实时处理这些内容，系统需要：

订阅 LLM 的输出流
监听各种事件（开始、更新、结束、工具调用等）
分发事件到对应的处理器

4.5.2 订阅会话事件

关键概念：

4.5.3 事件分发器原理

文件:

分发原理图解：

4.5.4 事件类型详解

4.5.5 message_update 处理详解（最核心）

文件:

流式处理示意：

4.5.6 处理器文件组织

文件:

当 LLM 决定调用工具时的处理流程：

工具调用的本质：LLM 返回一个结构化的工具调用请求（包含工具名和参数），Agent 框架执行该工具，然后将结果返回给 LLM 继续处理。

工具调用完整示例

以用户问”当前目录有什么文件？“为例：

关键理解点：

本质：LLM 本身不能执行代码或访问文件系统，它只能”说”要做什么。Agent 框架负责”听懂”并”执行”，然后把结果”告诉” LLM。

文件:

OpenClaw 提供了丰富的内置工具：

核心内置工具:

Agent 循环的本质：用户消息 → LLM 思考 → (可选)调用工具 → 工具结果返回 LLM → LLM 继续思考 → &mldr; → 最终回复

OpenClaw 的 Agent 核心依赖于以下外部库：

这些库提供了：

统一的 LLM 调用接口：支持多个模型提供商
会话管理和持久化：保存对话历史
工具定义和执行框架：标准化的工具接口
上下文压缩机制：处理超长对话

系统提示词（System Prompt）是 Agent 的”灵魂”，它决定了 Agent 的身份、能力边界、行为规范。OpenClaw 采用模块化设计，将系统提示词拆分为多个独立的构建函数。

文件:

主构建函数：

① 工具部分 (Tooling)

⚠️ 重要说明：System Prompt 中的工具部分只包含工具名称和简短描述，完整的参数定义（入参/出参 Schema）是通过 API 的参数单独传递给 LLM 的，不在 system prompt 文本中。

📌 技术原理：OpenClaw 使用的是 LLM 的 Function Calling（函数调用） 功能，这是 OpenAI、Claude、Gemini 等主流 LLM 都支持的标准能力。Function Calling 让 LLM 能够以结构化 JSON 格式”调用”预定义的函数，而不是只输出自然语言文本。

Function Calling 工作原理：

Function Calling vs 普通对话：

工具信息传递的两个通道：

② 安全规则 (Safety)

这是 Agent 安全的核心约束：

③ Skills 系统

告诉 Agent 如何检索和使用 Skills：

④ 记忆系统

⑤ 项目上下文（最重要！）

这是让 Agent 了解项目特定规则的核心机制：

常见的上下文文件包括：

- 项目级 Agent 行为指南
- Agent 人格设定
- 工具使用指南

⑥ 运行时信息

生成示例：

内置 Skills 示例 (52+ 个):

示例:

&mldr;

文件:

资格检查流程图:

文件:

生成的提示词格式:

Agent 的 Skills 检索是基于描述的语义匹配，而不是关键词搜索。

5.6.1 检索原理详解

⚠️ 重要澄清：Skills 检索不使用向量嵌入或语义搜索算法，而是完全依赖 LLM 自身的语言理解能力来匹配用户意图和 Skill 描述。

核心机制：

为什么叫”语义匹配”？

Skills 使用的是第三种方式——让 LLM 自己理解和匹配。

5.6.2 完整检索流程示例

5.6.3 为什么不用向量搜索？

OpenClaw 的选择：由于 Skills 数量通常在几十个以内，直接让 LLM 扫描所有描述是最简单高效的方案。

5.6.4 System Prompt 中的检索指令

检索规则:

扫描 description: Agent 首先扫描所有 skill 的描述
单一匹配: 如果只有一个明确匹配，直接使用
多重匹配: 选择最具体的那个
无匹配: 不读取任何 SKILL.md，直接处理

5.6.5 与记忆系统检索的对比

文件:

当 Skills 文件变化时，自动刷新快照版本，下次 Agent 运行时会加载最新的 Skills。

记忆管理系统（Memory System）是 OpenClaw 的跨会话持久化知识检索机制，与上下文工程管理形成互补。

简单理解：

上下文工程管理解决的是”这轮对话太长了怎么办”
记忆管理系统解决的是”上周我让你做的那个任务叫什么”

文件:

支持的记忆源

文件分块机制

文件: ,

记忆文件格式示例

系统支持三种类型的记忆文件，每种有不同的用途和格式：

1. 主记忆文件（手动维护的长期记忆）

这是用户/Agent 手动维护的长期记忆文件，格式自由：

2. 每日记忆文件（手动/自动）

按日期组织的日志式记忆，可由 Agent 自动写入或手动维护：

3. 自动生成的会话记忆

由 Hook 在用户执行命令时自动生成（详见下文）：

记忆文件来源

系统支持两种记忆文件来源：

记忆文件扫描逻辑

记忆文件自动生成（session-memory Hook）

当用户执行命令开始新会话时， Hook 会自动保存上一个会话的内容：

触发条件：用户发送命令

生成流程：

生成的记忆文件格式：

文件命名规则：

记忆压缩刷新（Memory Flush）

文件:

当会话接近上下文窗口限制时，系统会触发记忆刷新，提示 Agent 将重要信息持久化：

记忆刷新时机：

记忆文件索引与同步

记忆文件被索引到 SQLite 数据库中，支持增量同步：

索引流程：

文件:

嵌入提供者

嵌入存储

文件:

系统采用向量搜索 + 关键词搜索的混合策略，先执行两路并行搜索，再融合结果排序：

整体搜索流程：

两种搜索技术对比

向量搜索：使用扩展进行语义相似度计算
关键词搜索：使用 SQLite 内置的 FTS5（Full-Text Search 5）全文索引引擎，支持 BM25 相关性排序

💡 FTS5 是 SQLite 原生支持的全文搜索功能，通过创建虚拟表，使用语法进行全文查询，无需额外的搜索引擎依赖。

默认权重配置

混合结果合并排序算法

文件: 的函数

混合搜索的核心是加权线性组合（Weighted Linear Combination）算法：

算法步骤：

BM25 分数归一化

FTS5 的函数返回负数排名值（越负越相关，如 -10 比 -2 更相关），需要转换为 0-1 范围的正分数：

📝 注意：由于 FTS5 返回负数表示相关，会将所有负数（高相关）都归一化为 0，最终得分为 1.0。这是一种简化处理，确保 BM25 命中的结果都获得高分。

合并逻辑图解

为什么这种算法有效？

💡 设计理念：向量搜索擅长理解语义（“推送”≈“发送”），关键词搜索擅长精确匹配（“FTS5”必须完全匹配）。70:30 的权重偏向语义搜索，同时保留关键词精确匹配的能力。

记忆文件不是在每次对话时自动全量加载到上下文中，而是按需查询。主要有以下几种查看时机：

Agent 主动调用（最常见）

当 LLM 需要回答涉及历史信息的问题时，会主动调用和工具。

系统提示词中的记忆召回指令：

触发场景：

查询流程图：

索引同步时机（后台自动）

记忆文件的索引会在以下时机自动同步（但不是加载到对话上下文）：

CLI 手动查询

用户可以通过命令行主动查询记忆：

关键设计理念

💡 这种设计避免了将所有记忆文件塞进上下文造成的 token 浪费，同时保证了 Agent 能在需要时准确召回相关信息。

文件:

memory_search 工具

memory_get 工具

使用流程：

文件:

配置示例 ():

所有渠道和扩展功能都通过插件系统实现，插件可注册的扩展点包括：

Gateway 使用事件驱动模型进行实时通信：

文件:

使用 Lane (车道) 概念进行并发控制（详见）：

会话级队列: 同一会话的消息串行处理，避免并发冲突
全局队列: 全局资源（如模型调用）的并发限制

上下文管理

Skills 系统

记忆系统

构建一个完整的 Agent 系统需要从以下四个核心维度考虑：

OpenClaw 在这四个维度的实现：

从一个完整 Agent 系统的视角，OpenClaw 的架构可以分为以下层次：

技术选型总结：

通过分析 OpenClaw，我们可以总结出构建生产级 Agent 系统需要关注的关键点：

1. 上下文工程（Context Engineering）

2. 记忆系统（Memory System）

3. 可扩展性（Extensibility）

4. 可靠性（Reliability）

5. 安全性（Security）

6. 可观测性（Observability）

OpenClaw 作为一个生产级 Agent 系统，涵盖了 Agent 开发的核心知识领域：

建议的学习路径：

总结：OpenClaw 展示了一个现代 Agent 系统应有的完整形态——不仅是调用 LLM 的简单封装，而是一个考虑了感知、推理、记忆、行动全链路，兼顾可扩展性、可靠性、安全性、可观测性的生产级系统。

文档生成时间: 2026-02-02