从ReAct到OpenClaw：Harness Engineering、四层记忆与Skills渐进式加载实战解析

本文以OpenClaw小龙虾项目为载体完整讲解Harness‑Engineering顶层架构思想、四层持久化记忆系统、Skills渐进式披露加载三大核心理论再通过简易小龙虾工程案例落地演示整套生产级Agent框架的运行逻辑。第一部分 理论篇OpenClaw智能体三大核心体系1.1 Harness Engineering顶层架构思想1.1.1 Prompt、Context、Harness Engineering三层演进第一层Prompt Engineering提示工程核心问题如何把任务说清楚Role Prompting 角色提示Few‑shot 示例引导Chain‑of‑Thought 思维链ReAct推理‑行动‑观测适用场景单轮问答、意图对齐边界短板无私域知识、无持续记忆无法执行、无错误恢复第二层Context Engineering上下文工程核心问题模型关键时刻看到什么RAG私有知识注入Tools连接外部世界Memory跨轮记忆管理State当前任务状态适用场景多工具、长对话、知识密集边界短板缺执行约束、无错误恢复难以量化输出质量第三层Harness Engineering管控/框架工程核心问题模型在什么机制里运行目标边界与停止条件隐性知识暴露给 Agent反馈回路测试/日志记录系统docs / git适用场景生产级、长任务、多Agent定位包含并超越前两层让AI稳定交付三者不是替代关系而是外延逐层扩大 — Prompt 是 Context 的组成部分Context 是 Harness 的组成部分1.1.2 OpenClaw范式转移从对话闭环走向执行闭环传统聊天机器人ChatGPT / Claude模块能力说明大脑LLM 理解 回答对话问答即止无后续行动记忆窗口关闭上下文消失工具无法搜索 / 写文件 / 发消息渠道仅 Web 或 AppOpenClaw Agent 平台小龙虾模块能力说明大脑LLM 理解 推理 决策小脑Agent 编排规划 调度 记忆双手工具调用搜索 / 文件 / API接口10 渠道WhatsApp / 飞书 / Slack记忆短期 长期越用越懂你小龙虾是一套开箱可用的生产级 Agent 平台由网关、节点引擎、技能插件、控制面板、记忆系统五大模块组成内置 ReAct 推理循环、多渠道接入、长短时记忆、海量社区技能库补齐了 LangChain 等开发框架缺失的生产基建最终实现从对话闭环‑说了就算到执行闭环‑说了就做的跃迁可落地个人助手、企业内网 Agent、自动化工作流等多种场景。1.1.3 Fat‑Gateway网关与Lane Queue会话串行机制简要的说Fat‑Gateway 网关主要完成两项核心工作一是通过 Channel‑Adapter 适配器屏蔽 WhatsApp、飞书、Telegram 等各类聊天平台的协议差异实现消息接口统一同时保留原始报文保障渠道专属交互能力二是依靠 Lane Queue 为每个会话分配独立通道做到会话隔离、任务串行执行从根源上避免并发读写引发的上下文错乱保障会话状态稳定。1.1.4 ReAct执行引擎与Context Engine上下文管理器OpenClaw 将理论上的 ReAct推理‑行动‑观察循环落地为runAgentTurnWithFallback()六阶段流水线依次完成上下文组装、调用大模型、解析工具调用、执行技能工具、追加返回结果、判断循环终止条件。内置统一模型适配层兼容 20 余款大模型同时增加失败兜底重试逻辑解决原生 ReAct 缺少工程容错的短板。配套的Context Engine 上下文管理器专门应对 Agent 长循环带来的上下文窗口溢出问题它提供可插拔的程序接口支持 Token 预估、溢出检测以及会话压缩。内置截断、语义压缩、滑动窗口、混合策略四种上下文精简方案默认采用混合策略以此控制多轮 ReAct 循环后暴涨的 Token 开销在尽可能保留历史信息的前提下规避上下文溢出。Compaction策略优点缺点截断 Truncation简单快速零开销可能丢失早期信息压缩 Compaction语义损失最小需额外LLM略慢滑动窗口始终保最新上下文早期信息完全丢弃混合策略默认兼顾各种情况实现最复杂1.1.5 HEARTBEAT心跳从被动问答转向主动执行传统聊天机器人仅能在用户下发消息后被动响应而心跳模块赋予 Agent 后台常驻、自主运行的主动能力。系统定时器周期性触发读取HEARTBEAT.md中以自然语言编写的定时任务指令并注入系统提示词无需用户输入即可启动 Agent 循环。相较于传统 Cron 定时任务只能机械执行固定命令心跳机制依靠大模型理解上下文条件智能判断任务是否需要执行完成消息提醒、日程推送、周期性归档等主动工作。实现原理定时器每 30 分钟触发读取 HEARTBEAT.md 文件内容注入为 system prompt启动 Agent 循环不传入任何用户消息Agent 读取记忆、判断条件、调用工具并执行对应任务1.1.6 OpenClaw三层安全防护方案OpenClaw 基准安全通过率仅 58.9%风险根源来自 Skill 具备系统级操作权限、大模型输出存在不确定性、缺少意图边界校验。为此框架搭建了 L1‑L3 纵深三层防护体系L1 工具白名单通过allowedTools配置限定 Agent 可调用的工具集合L2 参数约束利用blockedPaths、allowedDomains、maxSize等规则限制文件路径、访问域名、资源大小L3 运行时审计开启全量操作日志记录敏感动作触发告警高危操作支持人工审批拦截。除此之外 Harness 工程还在传统 ReAct 基础之上额外增加常驻进程调度、会话串行隔离、Markdown 配置、四层记忆架构、MCP 工具生态、渠道适配器等能力进一步加固 Agent 运行安全。1.2 四层记忆系统解决LLM无状态遗忘难题1.2.1 L1‑L4四层记忆分层模型详解层级名称存储实现容量读取速度生命周期L1Working Memory工作记忆Context Window 中的 messages[]~128K tokens即时当前会话L2Short‑term Memory短期记忆SQLite/PG 会话历史 memory/YYYY‑MM‑DD.md数 MB~5ms当天~数天L3Long‑term Memory长期记忆MEMORY.md USER.md IDENTITY.md数十 KB~1ms永久L4Vector Search语义记忆向量数据库所有历史的向量化表示数 GB~10‑50ms永久四层协作Working → Short → Long → Vector按需检索越用越懂你1.2.2 Markdown记忆文件载体分工SOUL / USER / MEMORY等文件名功能说明补充描述SOUL.mdAgent 人格 / 行为准则每次对话注入 system promptAGENTS.md操作手册 / 工作边界定义怎么做、不能做什么IDENTITY.md身份档案 / 能力清单Agent 自我介绍、部署信息USER.md用户偏好 / 历史背景持续更新个性化核心HEARTBEAT.md定时任务大脑每 30min 读取执行MEMORY.md跨会话持久记忆关键决策和事件永久有效memory/*.md每日工作记忆每天新建次日仍可读比如用户在周一说以后用python写代码不要用c写agent就把这条信息写入memory.md周三用户再让agent写代码时agent从memory.md里面获得信息用户要python写的代码就给出py的代码了。1.2.3 Memory Flush记忆落盘与Compaction上下文压缩Memory Flush四种触发时机序号触发时机说明①会话结束时最高频对话结束后 Agent 自动提取关键信息写入 MEMORY.md 和每日日志②Compaction 发生时Context 85%触发压缩同步把关键信息 flush 到 MEMORY.md③Agent 主动判断对话中识别到重要信息立即调用 file_write不等会话结束④心跳任务触发HEARTBEAT 定时汇总当天日志定期更新 MEMORY.mdFlush 与 Compaction 互补关系项目CompactionMemory Flush目的释放 Context 空间保存重要信息操作压缩旧对话为摘要提取关键信息写文件结果Context 变小MEMORY.md 更新触发Context 85%多种时机Compaction 释放空间Flush 保存价值 —— 两者是同一过程的两个目标1.2.4 成本递增式分层记忆检索策略记忆检索策略按「成本递增、范围递增」顺序检索 —— 先查最近最便宜的找不到再查更远更贵的层级记忆类型检索数据源速度成本说明L1Working Memory当前对话messages[]即时成本 0直接从 Context 中获取L2Short‑term今日 memory/日期.md~5ms成本低加载当日日志和近期会话历史L3Long‑termMEMORY.md USER.md~1ms成本低加载长期记忆和用户偏好L4Vector Search全部历史向量库~50ms成本高按相似度检索找不到精确就找相关1.2.5 多个 MD 文件的加载时机与顺序文件加载时机序号加载时机加载文件说明①进程启动时一次性SOUL.md、AGENTS.md常驻内存每次对话均注入 system prompt②新会话开始时MEMORY.md、USER.md注入会话上下文段个性化 持久记忆③拼接对话历史memory/YYYY‑MM‑DD.md当天日志补全还原近期操作上下文④定时触发每 30 分钟HEARTBEAT.md无需用户消息主动触发 Agent 执行每次 LLM 调用前的 Context 组装顺序哪怕你只发一句 “你好”还没开始任务这一堆 md 文件全量塞进 Prompt文件内容作用SOUL.md人格 / 行为准则AGENTS.md操作手册 / 工作边界MEMORY.md跨会话持久记忆摘要USER.md用户偏好 / 历史背景messages[]对话历史 工具返回结果1.3 Skills模块化体系与渐进式披露加载机制1.3.1 Function Call、MCP、RAG、Skills四者概念辨析1.3.1.1 Function Call 工具调用的基础机制定义和特点调用形式大模型输出一段结构化的 JSON 指令由程序框架识别之后执行对应的函数。交互流程一轮完整交互模型发起工具调用 → 执行工具 → 工具结果返回给大模型。定义方式在提示词里提前写明工具清单包含工具名称、入参、功能说明。短板局限工具数量一多全部工具说明会占用大量 Token模型很难从中选出合适工具。Function Call 属于 Skills 的底层执行基础Skills 在它之上补充了流程逻辑和上下文管控。1.3.1.2 MCP 工具生态标准化协议核心价值统一协议标准规定一套通用的工具注册、查找、调用格式不同 Agent 之间可以共用工具。远端托管工具工具业务逻辑运行在远程服务端Agent 客户端只需要对接接口不用实现工具代码。运行时动态发现Agent 在执行的时候才去查询可用工具不需要一开始就把所有工具写死在代码里。和 Function Call 的关系MCP 是 Function Call 的标准化扩展底层本质依旧是函数调用。四层架构自上而下大模型 / AgentMCP‑Client协议转发层MCP‑Server工具服务真实工具、接口、数据库MCP 解决了不同工具互相调用兼容的问题但是无法解决上下文越来越膨胀、任务流程语义复杂的问题这一块空缺由 Skills 补齐。1.3.1.3 RAG 动态知识检索注入核心机制检索触发收到用户提问先去向量数据库查询相关资料片段。上下文注入把检索出来的资料拼进提示词给模型补充外部知识背景。拓展知识边界用来弥补大模型训练截止日期之后缺失的新知识。局限性回答准确度取决于向量嵌入效果检索回来大量内容塞进上下文会消耗很多 Token。执行流程用户提问 → 向量检索获取匹配内容 → 检索材料拼入提示词 → 大模型生成答案RAG 可以嵌入到 Skill 的执行步骤当中获取知识二者属于互补关系不存在互相替代。1.3.1.4 Skills 模块化认知单元核心特征行为封装把一整套任务流程、判断逻辑、工具调用打包成一个独立可命名的能力单元。知识内聚Skill 自身就携带对应领域的背景知识、操作规则约束。按需加载只有任务需要这个能力的时候才把它载入上下文闲置的时候仅保留简要信息不占用 Token。多层组合一个 Skill 可以调用别的 Skill搭建出分层、复杂的任务能力。Skill 任务行为逻辑 内嵌领域知识 工具调用能力 上下文渐进管控一个 Skill 的任务示例能力名称代码审查触发条件用户提出审查代码的请求执行步骤读取变更过的代码文件检查代码风格、业务逻辑、安全漏洞检索相关技术文档调用RAG启动代码检测工具Function Call / MCP输出一份结构化审查报告1.3.1.5 四者之间的关系Function Call底层执行指令由 Skill 在合适时机发起调用。MCP提供一套通用工具调用协议Skill 不需要关心底层细节直接使用远端工具。RAG作为获取外部资料的子步骤内嵌到 Skill 的任务流程中。Skills处在最上层统一管控任务语义、上下文生命周期调度前面三种能力完成任务。总结四个技术互不冲突。Skills 是上层调度者Function Call、MCP、RAG 都是它可选的执行模块。1.3.2 渐进式披露按需加载核心原理与上下文优化收益1.3.2.1 长Prompt一次性全量加载带来的问题在传统Agent实现方案中上下文Context由4个部分共同组成用户指令约15%任务本身的描述内容对话历史约20%保障多轮对话上下文连续性工具定义约35%所有工具、函数的Schema描述系统Prompt约30%任务规则、行为约束说明一次性加载全部工具能力定义会带来三项高昂代价超过65%的上下文空间被和当前任务无关的内容占用请求调用成本会随着工具数量增长呈现2‑3倍的增幅模型的有效推理深度下降约40%核心痛点所有工具能力一次性载入上下文大量Token资源浪费在当前任务并不会用到的工具定义上。1.3.2.2 渐进式披露Progressive Disclosure核心思想渐进式披露采用分层加载策略将 Skill 能力划分为常驻层、触发层、执行层做到 “平时只占目录位用到才读全文”常驻层Always Loaded内存常驻SKILLS.md索引文件每一项 Skill 仅保留一行简短摘要名称 一句话功能描述 触发关键词整体 Token 占用小于 200 tokens全程保留在上下文当中让模型知道 “有哪些能力可用”。触发层On Demand当用户输入匹配预设触发关键词或模型根据任务意图判定需要某个 Skill 时才将对应 Skill 的完整定义加载进上下文单次加载占用 500‑2000 tokens。执行层In ContextSkill 完整定义在任务执行期间驻留在上下文任务结束后立刻释放不再占用 Token 空间回到仅常驻索引的状态。1.3.2.3 Skill完整加载生命周期整个流程一共分为5个阶段伴随上下文占用动态变化用户发送消息 → 上下文仅加载常驻索引MEMORY.md触发条件匹配检测 → 不新增Token消耗加载Skill完整定义 → 上下文追加该Skill的Token内容执行Skill任务流程 → Skill定义全程驻留上下文任务完成、释放Skill → 移除完整Skill定义回到仅常驻索引的状态方案收益更低成本节省30‑50%的Token消耗量更长推理上下文空间留给任务推理链推理深度提升更加清晰只载入当前任务相关的Skill减少无关能力对模型的干扰1.3.2.4 上下文优化量化对比20个Skills场景方案初始加载Token单次请求Token有效推理空间全量加载~12000 tokens~12000 tokens很少渐进式披露~200 tokens1000 tokens充足节省量-11800 tokens-11000 tokens推理空间提升约10倍三大实际收益成本收益Token消耗节省60‑90%节省比例随Skill总量上升而提高质量收益模型注意力聚焦任务相关内容支持更深层次推理响应速度收益Prompt处理耗时缩短接口延迟降低1.3.2.5 上下文管理策略横向对比全量加载优势实现最简单不需要额外调度逻辑缺点Token浪费严重、工具越多上下文膨胀越严重干扰模型推理适用场景小规模Agent工具数量小于5个工具过滤优势依靠关键词筛掉一部分无关工具缺点过滤规则容易误判对于语义相近的工具区分效果差适用场景各个工具功能差异非常明显的项目渐进式披露优势常驻索引开销极低按需精准加载Skill可控性强缺点需要设计触发匹配规则拆分Skill文档存在一定工程开发成本适用场景中大型Agent项目、基于Skills能力体系开发动态检索(RAG)优势完全动态获取外部知识适合大规模知识库缺点检索存在延迟、召回精度不稳定不适合加载结构化的工具行为定义适用场景知识密集业务通常可以和渐进式披露方案互补使用1.3.3 Skill完整结构元数据、执行流程、内嵌知识、QA自检钩子1.3.3.1 Skill四大组成模块一份标准结构化Skill文档一共由4个核心部分构成Frontmatter元数据存放Skill基础元信息名称、功能描述、触发关键词、版本号。作用供给MEMORY.md生成常驻索引同时也是渐进式披露方案中Skill被触发加载的判断依据。指令主体Skill完整的业务操作流程描述包含执行步骤序列、条件分支逻辑、工具调用规范、最终输出格式约束。内嵌知识存放该业务专属的领域规则、判断标准、业务常见模式。知识会跟随Skill加载进入上下文任务执行过程中无需额外调用RAG检索获取。QA钩子自检清单内置执行校验清单定义每一步操作完成后模型需要主动验证的条件用来保障Skill最终的执行质量。1.3.3.2 Skill文档实例解析飞书feishu示例--- name: feishu description: 飞书文档/表格操作 trigger: feishu | 飞书 | wiki --- ## 操作规范 - 读取doc_read(doc_id) - 写入doc_append(markdown) - 搜索search_docs(query) ## 内嵌知识 - wiki URL 格式/wiki/TOKEN - 禁止直接 WebFetch 飞书链接 ## 自检 - [ ] token 有效性确认 - [ ] 写入后读回验证1.3.3.3 结构化 Skill 带来的工程收益结构化的 Skill 定义能够让 Agent 行为做到可预期、可测试、可版本管理。可预期固定的流程、约束规则减少模型随机发挥输出行为稳定可控可测试QA 自检钩子提供校验点便于自动化验证 Skill 执行结果是否正确可版本管理Skill 为独立 Markdown 文件可使用 Git 进行更新迭代、回溯历史版本1.3.4 Skills四种形态划分与高质量Skill设计原则1.3.4.1 纯代码工具封装 Python/Shell 脚本对外提供可调用接口。Skill本质是一个可执行的工具包装自带输入校验、异常错误处理以及标准输出格式。典型场景文件格式转换、数据清洗、API封装1.3.4.2 工作流编排将多个执行步骤、条件分支、循环逻辑组合成一条命名流程。该类型Skill不含代码纯粹用来描述、约束Agent的行为执行序列。典型场景代码审查流程、文档生成流程1.3.4.3 知识复合型领域知识与操作流程融为一体。Skill内部嵌入专业判断规则Agent运行时不需要额外查询外部知识库就可以直接做出业务决策。典型场景安全审计、医疗问诊、法律合规检查1.3.4.4 元技能用于管理、调度其他子Skill的上层技能。负责识别当前任务需要启用哪些子Skill、编排各个子任务的执行顺序、汇总合并最终结果是多‑Agent架构当中的核心组件。典型场景项目经理Skill、多Agent协调器1.3.4.5 形态之间的关系说明四种形态之间互不排斥同一个Skill可以同时兼具多种特征例如同时拥有工作流编排逻辑 内嵌业务知识构成复合型技能。第二部分 实战篇简易OpenClaw小龙虾项目落地实践2.1 记忆系统前置知识在1.2.4。重点介绍下文件存放的内容、如何更新、作用存储对象存放内容更新时机作用memory/USER.md用户画像、稳定不变的基础事实档案姓名、职业、常住地、固定偏好等会话关闭执行flush记忆冲刷LLM识别出新的用户信息后整篇覆盖重写保存长期不变的用户基础档案会话初始化时加载给到大模型保持用户信息认知一致memory/MEMORY.md提炼后的长期记忆条目包含fact/preference/event/decision分类、标题、正文、记录时间1.会话flush新记忆追加到文档末尾2.记忆压缩Compaction条目≥50条压缩旧记忆后整篇重写长期记忆唯一真相源FAISS、memory_fts索引的数据源头召回记忆时读取完整文本注入上下文memory/YYYY‑MM‑DD.md 每日日志当日新生成的记忆条目记录每次flush成功产出新记忆以追加模式写入文件近端短期记忆缓冲会话启动加载最近两天日志提供48小时内对话上下文连续性SQLite‑sessions表会话元数据会话id、开始时间、结束时间、flushed标记新建会话时插入记录关闭会话更新结束时间flush完成后设置flushed1管理聊天会话生命周期标记已冲刷会话避免重复提取记忆不参与记忆检索SQLite‑messages表原始完整对话流水用户提问大模型回复每一轮对话结束实时追加写入存储全部原始聊天记录会话关闭后读取这份对话交给MemoryFlusher提炼长期记忆不参与记忆检索SQLite‑memory_ftsMEMORY.md导出的记忆标题正文文本1.flush新增记忆后增量添加条目2.记忆压缩后全量清空重建BM25关键词检索索引副本通过字面关键词匹配召回记忆id加速检索非数据源FAISS向量索引文件每条记忆对应的Embedding浮点向量记忆id映射无原文1.flush新增记忆增量添加向量2.记忆压缩后全量清空重建语义相似度检索计算用户问题与记忆的向量相似度召回语义相近的记忆id加速检索非数据源在这个项目里第一次发给llm的是这些Layer 3a SOUL.md人格定义 Layer 2 每日日志今天 昨天 Layer 3b USER.md用户画像 Layer 3c AGENTS.md操作规范 Layer 3d 最新一部分的 MEMORY.md长期记忆 skills的摘要核心就是MEMORY.md 是长期记忆唯一真相源SQLite‑memory_fts 用于bm25索引FAISS用于语义索引。其他的比如如何组织语言发给llm、上下文过长后如何压缩都可以根据业务需求来。实现业务的时候注意保证MEMORY.md的内容要与 faiss 和 memory_fts 同步。2.2 heartbeat目的是定时触发任务让agent主动给用户推送消息。HEARTBEAT.md 定义任务 trigger: */1 * * * * ← 何时执行cron每分钟 action: send_message ← 做什么 prompt: 生成一条简短的测试问候 │ ▼ ① 启动时agent 读 HEARTBEAT.md把 cron 注册进 APScheduler [scheduler.py] _register_task → CronTrigger(minute*/1) │ ▼ ② 到点APScheduler 精确触发 agent不是轮询是定时器到点 [scheduler.py] _execute_task(task) │ ▼ ③ 分发agent 读 task[action]用 if/elif 决定调哪个函数 [scheduler.py] action send_message → _action_send_message │ ▼ ④ 执行agent 读 USER.md 画像 prompt组装 messages 调 LLM [scheduler.py] client.chat.completions.create(...) ← 唯一一次 LLM 交互 │ ▼ ⑤ 生成LLM 返回一句问候文本纯文本转换无决策权 │ ▼ ⑥ 推送agent 拿到文本broadcast → SSE 主动推给前端 [scheduler.py] broadcast(heartbeat_message, ...)agent 和 LLM 的交互只有一种方式agent 把精心组装的 messages记忆 历史 指令发给 LLMLLM 返回文本agent 再解析/落地这段文本。 决策权在代码LLM 是无状态的大脑只提供文本生成这一种能力。2.3 skills渐近式加载一开始只把SKILL.md的开头发给llm等到llm需要调用skill时再读取完整的skill。启动 │ ├─ Phase 1 预加载skill_registry._scan │ 遍历 skills/*/SKILL.md │ 正则只抠第一对 --- 之间的 frontmatter │ 解析出 name description含块标量 - / | 支持 │ → 存成 SkillMeta{name, description, path} │ → meta_summary() 拼成 ~100 token 清单注入系统提示 │ ├─ LLM 看到清单 → 选定某几个 skill如 flash-card │ ├─ Phase 2 懒加载load_full / load_multiple │ 命中 _full_cache → 直接返回 │ 未命中 → 才 read_text 读完整 SKILL.md 并缓存 │ → 完整说明注入告诉 LLM「这个 skill 怎么用」 │ └─ 执行skill_executor.execute exists(name) → 只查 meta 字典校验合法 script_dir(name) → 只靠 SkillMeta.path 定位 scripts/ 不碰全文直接跑脚本