深入解析OpenClaw：揭秘生产级Agent的上下文工程与记忆系统

April 5, 2026

我们之前探讨过，构建一个基础的Agent框架或许并不复杂，但若想实现真正智能化的记忆与上下文管理，则完全是另一回事。

例如，如果你只是想打造一个Agent来执行几个预设的技能，用于完成自媒体选题或在社交平台自动发布内容，这相对简单。然而，如果你期望这个Agent能够随着使用时间的增长而变得更加贴心、更懂你，这就颇具挑战了。它会引出一系列深层问题，比如：Agent如何准确追溯你前天的活动？它又是如何清晰记忆事务的先后顺序而不至于混乱？

要解决上述所有问题，就不得不深入研究Agent的上下文工程。在早期的人工智能开发阶段，这项技术被视为核心机密。而OpenClaw的开源，则为我们清晰地展示了生产级别的记忆系统究竟是如何设计与实现的。

因此，如果你询问OpenClaw最具价值的部分是什么，我会毫不犹豫地建议你深入研读其记忆模块的源代码，这无疑是技术进阶的利器。当然，考虑到大家时间有限，我们今天将共同拆解OpenClaw的记忆模块与上下文工程。

理解上下文工程

许多人一听到上下文，第一反应便是提示词或检索增强生成技术。这种理解虽非全错，但略显片面，就如同将编写几行代码等同于完整的软件工程。

在我看来，上下文工程是一套系统性的方法论，旨在构建、管理与注入与当前任务高度相关的背景信息。简而言之：

上下文工程，就是为大语言模型设计一套高可用、可治理且能长期稳定运行的输入供给系统。

那么，更具体地说，什么是上下文？其本质依然是提示词，它代表模型在当前轮次推理或提示词中所能获取的全部信息总和。

上下文 = 系统提示词
  + 用户输入
  + 历史对话记录
  + 工具调用返回结果
  + 检索获取的内容
  + 长期记忆

所有上述信息经过整合，才构成了模型进行思考、决策并最终输出答案的完整依据。

上下文工程的核心目标

大语言模型存在若干固有短板，而上下文工程正是为弥补这些短板而生的：

应对信息幻觉问题

模型在训练阶段从海量互联网数据中学习了广泛的知识，但若缺乏有效引导，其回答可能流于空泛、不够精确，甚至凭空捏造事实。上下文工程的核心任务之一，便是将模型所不知道的、最新的、或专属的精准信息有效地“喂”给它。

突破长度限制

任何模型都有其固定的Token处理上限，复杂的任务很容易撑满上下文窗口。过长的内容会导致模型注意力分散、抓不住重点，甚至直接引发错误。上下文工程需要做的，就是在有限的预算内，筛选并保留最关键的信息。

解决信息可读性问题

如果输入的信息缺乏逻辑、格式混乱、杂乱无章，模型将难以进行有效解读。上下文工程需要将这些信息整理成模型易于理解的结构化格式。

明确的工程目标

综上，上下文工程需要达成以下目标：

引导与约束模型：通过设定背景、规则和示例，为模型划定明确的思考与输出边界。
提升回答准确性：通过注入最新数据、内部知识库和实时信息，从根源上减少模型产生“幻觉”的可能性。
实现复杂任务分解：将无法单次完成的复杂任务，拆解为多轮对话、思维链或系列工具调用，引导模型逐步推理并最终完成任务。

上下文工程的实现路径

首先，提示词工程是上下文工程最核心与基础的部分。它专注于研究如何运用最精确、最有效的语言来构建提问与指令。

其次是知识检索与注入。对于模型不了解或不擅长的领域，上下文工程会通过RAG等技术手段，先检索出相关信息，再将其与用户问题一同打包提供给模型。

接着是记忆管理。在多轮对话中，系统需要有效过滤无关的历史信息，保留关键记忆节点，防止模型遗忘重要前提或被冗长的历史记录所干扰。

最后是输出格式化。明确要求模型以特定的结构输出结果，例如JSON对象或Markdown表格，以便后续的程序能够自动处理。

这里需要特别区分上下文工程与提示词工程。两者关系密切但层次不同：

提示词工程：关注如何优化提问本身，包括指令的设计、格式和具体措辞。
上下文工程：关注为模型提供什么样的背景信息，涉及外部知识的筛选、加工和注入流程。

由此可见，两者并非对立，而是上下层协作关系。标准的工作流通常是：

上下文工程先行：通过RAG、记忆系统、工具调用等方式，筛选出最相关的背景资料。
提示词工程收尾：将这些资料与用户问题，通过精心设计的模板组装起来，最终提交给模型。

为了更直观地理解，我们来看一个真实例子：

用户提问：华为最新的旗舰手机是哪一款，什么价格？
- 上下文工程：从新闻数据库或网页中搜索关于华为最新旗舰手机的型号、发布信息及价格。
- 提示词工程：设计最终模板 → “根据以下资料：{{检索到的上下文}}，请回答用户的问题：{{用户查询}}”

至此，我们对上下文工程的基本概念已有所了解。接下来，我们将深入OpenClaw的具体实现。

OpenClaw的上下文工程架构

OpenClaw的上下文工程采用了清晰的流水线架构。整个提示词的组装过程如同工厂流水线，原始数据从一端输入，经过一系列标准化处理步骤，最终的成品（即完整的提示词）从另一端输出。

从架构解析的角度，可以分为三层：

第一层：资源管理层

此层负责管理所有上下文信息的来源，其核心工作是决策：哪些信息必须保留，哪些可以剔除，以及当信息冲突时如何处理。信息来源包括：

用户配置
工作区文档（如AGENTS.md、TOOLS.md等）
对话历史记录
可用工具列表
长期记忆内容

第二层：组装层

此层负责将收集到的所有资源，按照预定义的固定格式和顺序进行拼装。它需要处理：

不同模型间的格式兼容性问题
历史消息中的脏数据清理
在Token预算限制内进行信息的取舍与权衡

第三层：保护层

此层确保系统能够安全稳定地运行，核心职责包括：

检测上下文是否即将溢出
在必要时自动触发压缩机制
防止系统因上下文过大而崩溃

核心模块的实现细节

上下文引擎：可插拔的设计

OpenClaw定义了标准化的上下文引擎接口，明确了上下文管理全生命周期的契约。系统默认提供传统引擎，同时支持开发者进行自定义扩展，例如接入专有的RAG系统。

接下来，我们将按照流程图的顺序逐一展开说明。

系统提示词构建器

该模块负责生成Agent的“身份说明书”，即一段高质量的系统提示词，它直接决定了Agent的能力上限。其内容通常涵盖：

你是什么（身份与角色）
你能做什么（核心功能）
你应该遵循什么规则（行为准则）
你的工作目录在哪里（操作环境）

Bootstrap加载器：该组件读取工作区内的特殊配置文件，并将其内容自动注入到系统提示词中。这些文件包括：

AGENTS.md：定义项目内的行为规则。
TOOLS.md：说明工具的使用方法与规范。
MEMORY.md：记录需要长期记忆的关键信息。
SOUL.md：设定Agent的人格风格与语气。

会话清理器：此组件负责修复历史消息中存在的各种问题，确保提交给模型的历史记录是干净、合规且兼容的。处理内容包括：

删除无效或已废弃的工具调用记录。
压缩超出限制的图片Base64编码。
修复因异步等原因导致的消息顺序错乱。
处理跨会话传递消息的特殊标记。

上下文压缩器：当系统检测到上下文即将达到Token上限时，该组件会自动启动，对历史消息进行“瘦身”处理，在压缩过程中力求不丢失关键信息。

上下文组装流程详解

确定上下文窗口大小

在开始组装任何内容之前，系统必须首先确定目标模型的上下文窗口大小，即模型单次能处理的最大Token数量。不同模型的窗口差异巨大，小模型可能仅有32K，而大模型可达200K甚至更多。

OpenClaw通过四个来源获取此数值，并遵循明确的优先级：

1. 配置文件显式指定：开发者可在 `models.providers.{provider}.models[].contextWindow` 中明确设定，此优先级最高。
2. 模型元数据：OpenClaw的模型发现系统会自动从提供商处获取元数据，其中包含上下文窗口信息。
3. 默认值：如果以上来源均不可用，则使用 200,000 作为默认值。
4. 配置上限：最后，系统会检查 `agents.defaults.contextTokens` 配置。如果该值小于前面计算出的值，则会使用这个更小的值作为实际上限，以防止配置过大导致内存问题。

确定窗口大小后，系统会执行保护性检查。这里有一个关键细节：配置上限的覆盖作用。即使你在模型配置中明确指定了contextWindow，agents.defaults.contextTokens这个全局安全上限仍然会生效。

保护检查的阈值如下：

硬性最小值（16,000 tokens）：若上下文窗口低于此值，系统将直接阻止运行并抛出错误，因为此空间无法支持有意义的对话。
警告阈值（32,000 tokens）：若低于此值，系统会记录警告日志，提醒用户上下文可能不足，但不会中断运行。

加载项目上下文信息

在确定上下文窗口后，系统开始收集项目特定的上下文信息。这些信息来源于工作区中的特殊文件，被称为“Bootstrap文件”。

Bootstrap文件是开发者提供给Agent的“项目说明书”，例如：

- AGENTS.md：告知Agent在本项目中的行为规范与特殊规则。
- TOOLS.md：解释项目中使用的特殊工具或自定义命令。
- MEMORY.md（或memory.md）：记录重要的项目决策、约定或历史信息。
- SOUL.md：定义Agent的人格特质与回复语气，确保一致性。
- IDENTITY.md：定义项目的核心身份与边界范围。
- USER.md：提供用户特定的偏好与习惯，使Agent更个性化。
- HEARTBEAT.md：用于定时检查任务的指令集。
- BOOTSTRAP.md：仅在新工作区首次运行时提供初始化引导。

系统会按优先级加载这些文件：主会话加载全部文件，而子Agent或心跳任务通常只加载核心文件（AGENTS.md， TOOLS.md， SOUL.md）。加载时需考虑以下问题：

一、文件大小控制：单个文件可能非常大，系统会为每个文件设置字符上限（默认20，000字符）。同时，所有文件的总大小也有上限（默认150，000字符），超出时将停止加载新文件。

二、会话过滤：系统支持根据会话键来过滤应加载的文件。例如，某个AGENTS.md文件可能只对特定会话生效。

三、上下文模式：系统支持三种模式：

完整模式：加载所有Bootstrap文件。
轻量模式：仅加载最基本的信息，甚至可能完全跳过Bootstrap加载，常用于子Agent。
无模式：完全不注入任何项目上下文。

管理记忆内容

你可能会好奇，Agent如何知晓我前天做了什么？它如何记住各种决策和约定？这正是记忆系统的职责所在。

首先，需要明确一个重要区别：OpenClaw的记忆分为两层。

第一层：工作区Markdown文件。这是记忆的原始数据来源。文件结构通常如下：

~/.openclaw/workspace/
├── MEMORY.md          # 长期记忆（项目约定、重要决策等持久化事实）
└── memory/
    ├── 2026-03-20.md  # 每日日志
    ├── 2026-03-21.md  # 今日记录
    └── ...

MEMORY.md（或小写memory.md）：存放需要持久化的内容，如项目核心约定、关键决策。
memory/YYYY-MM-DD.md：每日流水日志，记录当天的笔记、临时讨论等。

第二层：向量索引。此层使得Agent能够“搜索”这些文件内容。系统会监控上述文件的变更，将其切分成小块，并使用嵌入模型将每块文本转换为向量。这些向量索引存储在SQLite数据库中，位置通常为~/.openclaw/memory/<agentId>.sqlite。

搜索时，系统采用混合检索策略：

向量检索：负责“理解语义”。例如，当询问“那个网络配置的事”，它能找到关于“router”、“VLAN”的讨论，即使原文并未出现完全相同的词汇。
BM25关键词检索：负责“精确匹配”。对于ID、代码符号、特定错误信息等需要完全匹配的内容，此方法更为有效。两者结果会按权重融合（默认向量占70%，关键词占30%），并可选择性地应用时间衰减（近期内容权重更高）和MMR算法进行去重，以避免返回大量重复内容。

Agent访问记忆的具体方式

并非所有记忆都会自动注入上下文，那样会迅速耗尽Token。系统仅在主会话中自动注入MEMORY.md的内容。而memory/*.md中的每日记忆，则是通过特定的工具按需访问的：

memory_search：进行语义搜索，返回相关的记忆片段。
memory_get：精确读取某个特定文件的指定行范围。

因此，当Agent需要了解“上次我们如何处理这个问题”时，它会先调用memory_search找到相关片段，再决定是否使用memory_get读取更完整的上下文。

长期记忆：通过Bootstrap系统在Agent启动时直接注入到系统提示词中，每次对话都会完整加载。 每日记忆：通过记忆搜索工具按需检索。系统会在每日记忆文件中查找匹配内容，并按时间衰减计算相关性（越新的内容权重越高）。

加载可用工具列表

工具列表并非静态写死，而是根据当前配置动态生成的。工具来源广泛：

核心工具：OpenClaw内置的基础工具，如read、write、exec、grep、web_search等。
插件工具：由各功能插件提供的工具，例如memory-core插件的memory_search、memory_get。
渠道工具：由消息渠道插件提供的工具，如Discord、Telegram插件的message工具。

然而，并非所有可用工具都会塞给模型，这既是出于Token节省的考虑，也是为了保证工具调用的稳定性。系统在调用模型之前，会通过一套分层工具策略进行筛选：

策略层级从粗到细：

Profile策略：最粗粒度，例如minimal模式只提供最基本的工具，coding模式提供开发相关工具，messaging模式提供消息处理工具。
允许/拒绝列表：明确允许或禁止使用特定工具。
沙箱限制：在沙箱环境下，某些具有潜在风险的工具会被自动禁用。
子Agent限制：子Agent不能使用如gateway、cron等系统级管理工具。
群组策略：不同用户群组可以配置不同的工具使用权限。

最终筛选出的工具会被格式化并注入系统提示词，格式如下：

## 可用工具
工具可用性（已按策略过滤）：
- read: 读取文件内容
- write: 创建或覆盖文件
- edit: 对文件进行精确编辑
- grep: 在文件内容中搜索指定模式
...

每个工具占据一行，包含名称与简短描述。这告知Agent该工具的用途及适用场景。工具在代码中按功能分组，但在提示词中以平铺方式列出，以保持紧凑。

加载可用技能（Skills）

Skills的来源非常丰富：

这些来源会按照明确的优先级进行合并，优先级从低到高为：额外来源+插件 < 内置技能 < 用户安装的技能 < Agents通用技能 < 项目专属技能 < 工作区本地技能。这意味着，你在工作区本地定义的技能会覆盖系统自带的同名技能，这符合项目个性化定制的逻辑。

加载Skills时，系统会执行以下操作：

扫描目录：从所有来源路径收集包含SKILL.md文件的目录。
解析Frontmatter：读取每个Skill的元数据，如名称、描述、是否允许模型直接调用等。
过滤筛选：根据配置过滤掉不应启用的Skill。
去重合并：同名Skill只保留优先级最高的一个。
Token预算检查：
- 首先尝试以完整格式（名称+描述+路径）加载。
- 若超出预算，则切换到紧凑格式（仅名称+路径）。
- 若仍超出，则进行截断，仅保留列表前部的部分技能。

最终生成的Skills提示词格式如下：

<available_skills>
  <skill>
    <name>commit</name>
    <location>~/.openclaw/skills/commit/SKILL.md</location>
    <description>按照项目规范创建git提交</description>
  </skill>
  <skill>
    <name>review-pr</name>
    <location>~/.openclaw/skills/review-pr/SKILL.md</location>
    <description>审核并合并Pull Request，附带质量检查</description>
  </skill>
  ...
</available_skills>

这个列表会被注入到系统提示词的Skills部分，并附带指令：

在回复前：扫描<available_skills>中的<description>条目。如果恰好有一个技能明确适用于当前任务：使用`read`工具读取其<location>处的SKILL.md文件，然后遵循该技能的指导。

构建最终的系统提示词

系统提示词是发送给大模型的“首条消息”，它定义了Agent的基础身份与行为准则。OpenClaw的系统提示词构建器会生成一个结构化的提示词，包含以下部分：

1. 基础身份声明：以“You are a personal assistant running inside OpenClaw.”等简单句子确立Agent的基本定位。
2. 工具列表：列出经过策略筛选后的可用工具，为每个工具提供名称和简洁的功能描述。
3. 工具调用风格指南：指导Agent如何调用工具。OpenClaw遵循“默认不叙述”原则，对于常规、低风险的操作应直接调用工具，无需向用户解释。仅在复杂多步任务或执行敏感操作（如删除文件）时，才需要说明意图。
4. 安全指令：定义Agent的安全边界，明确指出Agent不应有独立目标，需优先考虑安全与人类监督，在指令冲突时应暂停并询问。这部分规则受Anthropic AI安全宪法的启发。
5. 技能引导：指示Agent在回复前扫描可用技能列表，若发现明确适用的单个技能，则读取其文档并遵循指导。
6. 记忆召回指令：如果启用了记忆搜索，则指导Agent在回答关于历史工作、决策、偏好等问题时，应先运行记忆搜索。
7. 工作区信息：告知Agent其工作目录路径，并说明在沙箱模式下文件操作与命令执行的路径差异。
8. 运行时元数据：附加Agent ID、主机名、操作系统、当前模型等调试信息，便于问题诊断。

系统提示词的构建还区分不同模式：主Agent使用“完整模式”包含所有部分；子Agent使用“精简模式”只保留核心内容；最简单的场景可使用“无模式”。

清理会话历史记录

从会话文件中读取的历史消息不能直接发送给模型，它们可能包含格式问题、不兼容内容或过时信息。系统需要对每条消息进行仔细的清理与修复：

1. 跨会话消息标记：为来自其他会话的消息添加“[Inter-session message]”前缀及来源信息，以便Agent区分。
2. 图像处理：检查并压缩消息中的图像块，确保其像素和字节数在限制内，防止因单张过大图片导致上下文溢出。
3. 思考块处理：根据策略决定是否移除模型回复中用于展示内部推理的<thinking>块。
4. 工具调用清理：验证历史记录中的工具调用是否仍存在于当前允许列表中，修复或移除无效调用，并确保工具调用与结果消息的正确配对。
5. 工具结果详情剥离：选择性剥离工具结果中的详细日志，仅保留核心成功/失败信息以节省Token。
6. Usage快照处理：清理过时的token使用数据快照，确保每个assistant消息都有有效的usage字段。
7. 提供商特定处理：针对不同模型提供商的特殊要求进行调整。例如，为Google/Gemini模型确保对话不以assistant消息开头；为OpenAI Responses API降级处理推理块格式。
8. 模型变更检测：记录最后使用的模型信息，当检测到模型变更时，相应调整消息清理策略。

执行最终的上下文组装

在收集好系统提示词并清理完历史消息后，系统进入最终的组装阶段。此阶段的核心工作是消息排序，确保所有消息按正确的时间顺序排列，以便模型理解对话的因果关系。

同时，系统会进行Token预算检查。估算系统提示词与所有历史消息的总Token数，并与预算对比。如果超出，系统将触发压缩或截断最旧的消息。无论采取何种策略，最近的几轮对话总是被完整保留，因为它们与当前任务最相关。

最终，上下文引擎会返回一个组装结果，包含有序的消息数组、估计的Token数量，以及可能的系统提示词附加内容。

进行最终验证

在将组装好的上下文发送给大模型之前，系统执行最后一次验证，确保一切符合目标模型的要求：

提供商验证：根据目标提供商（如Anthropic、OpenAI）的特定规则验证消息格式和顺序。
Schema清理：对于某些提供商（如Google），移除工具参数定义中不支持的JSON Schema关键字。
魔法字符串清理：检测并替换可能导致Anthropic模型拒绝响应的特定“魔法字符串”。

经过以上六个阶段的处理，原始的用户输入被转换成了一个结构完整、内容高度相关、格式完全兼容的提示词，准备就绪，可发送给大语言模型进行推理。

注：这套流程看似复杂，从实现功能的角度或许只需实现部分环节，但若想达到工程级别的稳定性，就必须完整走通整个链路。

上下文压缩机制详解

长期对话必然会导致上下文窗口被填满。一旦达到临界点，系统便会触发压缩机制：

压缩的触发条件：

自动触发 - 上下文溢出：当大模型API返回上下文溢出错误时，系统立即触发压缩。这是最常见的情景。
自动触发 - 预算阈值：每次运行后，系统检查当前上下文大小。若超过预算的一定比例（如90%），则主动触发压缩，防患于未然。
手动触发：用户可通过发送 /compact 命令手动触发压缩，此时会跳过阈值检查强制执行。

压缩策略等级

OpenClaw提供了三级压缩策略：

1. 摘要压缩（智能压缩）：最智能的策略。系统使用大模型为早期的对话生成摘要，保留关键任务、决策和重要标识符（如文件名）。随后用摘要替换原始详细消息，大幅减少Token占用，同时保持对话连贯性。
2. 截断压缩（直接丢弃）：最简单的策略。系统直接丢弃早期的消息，仅保留最近的部分。此策略速度快，无需额外模型调用，但会永久丢失被丢弃的信息。
3. 混合压缩：结合上述两种策略。对非常早期的消息使用摘要压缩，对中期消息可能直接截断，完整保留最近的消息，以平衡信息保留与性能。

压缩的执行流程

当压缩被触发时，系统执行以下步骤：

1. 计算Token用量：使用最近模型调用返回的实时Token数，或估算历史消息的总Token数。
2. 设定压缩目标：默认目标是将上下文压缩至Token预算的80%，留出安全边际。
3. 生成高质量摘要：提取早期消息，构造包含明确指令的摘要请求发送给大模型。
4. 构建新历史：以包含摘要的compactionSummary消息开头，其后接上未压缩的近期消息。
5. 原子替换会话历史：清空原会话文件并写入新的消息历史，确保过程原子性，避免损坏原始文件。
6. 安全保护：为压缩操作设置安全超时（通常几分钟）。若超时未完成则取消操作。同时通过事件机制捕获未预期的压缩失败，触发会话恢复流程。

上下文引擎的可扩展设计

OpenClaw的上下文工程系统围绕可插拔接口设计。开发者可以实现自定义的上下文引擎来替换默认行为，无需修改核心代码。

上下文引擎接口

上下文引擎通过 ContextEngine 接口定义，该接口覆盖了上下文管理的完整生命周期：

引导阶段：在新会话创建时执行初始化。
消息摄入：当新消息产生时，引擎可将其存储、索引或处理。
上下文组装：在每次调用模型前，引擎返回将用作模型上下文的消息列表。
上下文压缩：实现自定义的压缩算法。
轮次后处理：每次模型调用完成后执行清理或更新。
子代理管理：支持为子Agent准备隔离上下文及结束时聚合结果。
资源释放：在会话结束或应用关闭时释放资源。

传统引擎的实现

OpenClaw默认提供的 LegacyContextEngine 是一个保持向后兼容的最小化实现。对于大多数方法，它执行空操作或透传，仅 compact 方法具有实际实现，它将压缩请求委托给现有的压缩逻辑。这种设计允许新引擎逐步被采用。

配置选项与调优建议

OpenClaw的上下文工程系统提供了丰富的配置选项，允许开发者根据需求调整行为。

核心配置包括：

contextTokens：上下文Token总预算（默认200,000，建议设为模型窗口的80%~90%）。
bootstrapMaxChars：单个Bootstrap文件的最大字符数限制。
bootstrapTotalMaxChars：所有Bootstrap文件的总字符数上限。
compaction.mode：压缩模式（自动/手动/关闭）。
compaction.target：压缩激进程度（基于预算/基于阈值）。

此外，可以在模型配置中为每个模型单独指定上下文窗口大小，以覆盖自动发现的值：

"models": {
  "providers": {
    "anthropic": {
      "models": [
        {
          "id": "claude-sonnet-4-20250514",
          "contextWindow": 200000
        }
      ]
    }
  }
}

调优建议：

监控Token使用：避免频繁触发压缩，影响对话连续性。
精简Bootstrap文件：删除冗余内容，保持文件聚焦。
利用子Agent分解任务：将复杂任务拆分子Agent执行，减轻主上下文压力。
根据业务调整压缩阈值：在对话连续性与系统性能之间找到最佳平衡点。

结语

OpenClaw的上下文工程系统，其核心思想在于：在有限的Token预算内，通过系统化的工程方法，将最相关、最关键的信息高效地组织并呈现给大语言模型。

它首先定义了系统提示词的标准结构，明确了工具、记忆、技能等信息的存放位置，使得系统只需按部就班地填充数据即可。整个架构灵活、稳定且易于调试。开发者可以通过实现 ContextEngine 接口，轻松地将自定义的上下文管理逻辑集成到系统中。

今天的内容已足够丰富，建议读者逐步消化。后续的重点将转向OpenClaw的 Skills系统 与 多Agent协作机制。