基于LLM的系统设计与实现

Agent Memory 原理

Mon, 01 Jan 0001 00:00:00 +0000

Agent Memory 原理 #

本文是《大模型 Agent 和应用》Agent Memory 系列的上篇，聚焦定义、生命周期与架构模式。下篇《Agent Memory 实践》将深入关键技术、工业实践与选型指南。

本章导读 #

如果你用过 ChatGPT、Claude 或者任何大语言模型，你一定经历过这种挫败——你花了三个小时跟它讨论一个技术方案，关掉浏览器，第二天重新打开，它对你昨天说的一切一无所知。

这不是因为它"变笨了"，而是因为它根本没有记忆。它每次醒来都是一个新的会话，带着同一套预训练知识，却对你们的共同历史一无所知。

这就引出了本文的核心问题：如果记忆是人类智能的基石，为什么 Agent 的记忆系统直到 2023 年才成为一个独立的研究方向？ 而在短短两年内，它又如何从一个简单的"把对话历史塞进 prompt"的朴素做法，演变成一个包含分层存储、向量检索、文件系统范式、反思学习的复杂工程体系？

本文将回答以下问题：

什么是 Agent Memory？它与模型知识、对话上下文有什么本质区别？
Agent Memory 的"生命周期"是怎样的——写入、存储、检索、遗忘各自面临什么挑战？
业界出现了哪几种典型的 Memory 架构模式？它们各自的权衡是什么？

0. 引子：没有记忆的 Agent 会怎样？ #

想象一下这个场景：

你正在用 Agent 帮你写一个分布式系统的方案设计。第一轮对话，你告诉它系统的规模、用户量、延迟要求。第二轮，你让它分析几种存储方案。第三轮，你指出方案三的某个问题，它做了修改。第四轮，你问：“记得我们一开始说的那个延迟要求吗？”

它回答：“什么延迟要求？”

这不是假设。这就是 2023 年之前绝大多数 LLM Agent 的真实状态。

0.1 一个"金鱼"Agent 的日常 #

LLM 的本质是一个无状态函数（stateless function）：给它一段文本（prompt），它返回下一段文本。不记住上一次交互，不记住上一次交互的结果，不记住上一次交互中你纠正过的错误。

在没有 Memory 系统的情况下，Agent 的行为特征与人类的"顺行性遗忘"（anterograde amnesia）惊人地相似——它能调用训练中学到的一切知识（相当于"长期语义记忆"），却无法形成任何新的情景记忆（episodic memory）。

0.2 人类记忆的启发 #

人类的记忆不是一块"硬盘"。认知神经科学将人类记忆分为至少三个层次：

Agent Memory 实践

Mon, 01 Jan 0001 00:00:00 +0000

Agent Memory 实践 #

本文是《大模型 Agent 和应用》Agent Memory 系列的下篇，聚焦关键技术、工业实践与选型指南。上篇《Agent Memory 原理》可参见 chapter-part1-principles.md。

导读 #

上篇《Agent Memory 原理》我们讨论了 Agent Memory 的定义、生命周期和五种经典架构模式。本文将进入实践层面：

记忆压缩、向量检索、跨模态记忆等关键技术是如何工作的？
MemOS、Mem0、Letta、OpenViking、Claude Code、OpenClaw、Hermes Agent 等真实系统是怎么做的？
为什么"本地文件系统存储"正成为 Agent Memory 的主流选择？
如何为你的 Agent 选择合适的 Memory 方案？

4. 关键技术深潜 #

4.1 记忆压缩（Prompt Compression） #

4.1.1 为什么需要压缩 #

token 经济学是驱动记忆压缩的核心力量。如果每次请求都携带完整的记忆，成本会随对话轮数呈 O(n²) 增长。压缩的本质是用更少的 token 承载相同的信息量。

4.1.2 LongLLMLingua：问题感知的压缩 #

LongLLMLingua（arXiv:2310.06839）的核心洞察是：不是所有文本都同等重要——重要性取决于你要回答什么问题。

传统摘要压缩的做法是把文本无差别地压缩到固定长度。LongLLMLingua 则根据用户的问题，保留与问题最相关的信息，丢弃无关内容。它通过计算每个 token 相对于问题的"困惑度增益"（perplexity gain）来决定保留哪些 token。

实验数据显示，LongLLMLingua 可以将 40K-100K 的上下文压缩到原来的 1/4 到 1/8，同时保持甚至提升下游任务的性能。

Claude Code 长程任务稳定性

Mon, 01 Jan 0001 00:00:00 +0000

Claude Code 长程任务稳定性：如何在 50+ 轮迭代中不迷失、不失控、不崩溃 #

摘要：本文深度解析 Claude Code 如何在长程编程任务（数十轮 API 往返、数小时运行、数十万 token 消耗）中保持稳定。涵盖上下文生命周期管理、5 级压缩流水线、Session 持久化与回滚、Subagent 上下文隔离、错误恢复降级链、CLAUDE.md 双记忆系统、Hooks 预处理降本、Token 预算硬限制、Checkpointing 快照等 9 大稳定机制。所有结论均以 Claude Code 官方文档、逆向可运行源码（oboard/claude-code-rev）、学术论文（VILA-Lab, arXiv:2604.14228）、递进式教学（shareAI-lab/learn-claude-code）和 17 篇深度解析（openedclaude/claude-reviews-claude）为交叉验证依据。

目录 #

1. 引言：长程任务的"死亡之谷" #

1.1 什么是长程任务？ #

在 Claude Code 的实践中，任务的复杂度可以从单行 Bug 修复到整个代码库的架构重构。根据任务的规模，我们可以将其分为以下几个等级：

Mon, 01 Jan 0001 00:00:00 +0000

第 X 章 Agent Memory：让 Agent 记住、反思与成长 #

本章对应参考文献：arXiv:2512.13564, arXiv:2603.07670, arXiv:2304.03442, arXiv:2310.08560, arXiv:2303.11366, arXiv:2310.06839, arXiv:2312.03815, arXiv:2505.22101, arXiv:2507.03724, arXiv:2504.19413, arXiv:2309.02427

本章导读 #

这不是因为它"变笨了"，而是因为它根本没有记忆。它每次醒来都是一个新的会话，带着同一套预训练知识，却对你们的共同历史一无所知。

这就引出了本章的核心问题：如果记忆是人类智能的基石，为什么 Agent 的记忆系统直到 2023 年才成为一个独立的研究方向？ 而在短短两年内，它又如何从一个简单的"把对话历史塞进 prompt"的朴素做法，演变成一个包含分层存储、向量检索、文件系统范式、反思学习的复杂工程体系？

本章将沿着一条从问题到解决方案的路径，回答以下问题：

什么是 Agent Memory？它与模型知识、对话上下文有什么本质区别？
Agent Memory 的"生命周期"是怎样的——写入、存储、检索、遗忘各自面临什么挑战？
业界出现了哪几种典型的 Memory 架构模式？它们各自的权衡是什么？
向量检索、Prompt 压缩、跨模态记忆等关键技术是如何工作的？
MemOS、Mem0、Letta、OpenViking、Claude Code、OpenClaw、Hermes Agent 等真实系统是怎么做的？
为什么"本地文件系统存储"正成为 Agent Memory 的主流选择？
如何为你的 Agent 选择合适的 Memory 方案？

0. 引子：没有记忆的 Agent 会怎样？ #

想象一下这个场景：

你正在用 Agent 帮你写一个分布式系统的方案设计。第一轮对话，你告诉它系统的规模、用户量、延迟要求。第二轮，你让它分析几种存储方案。第三轮，你指出方案三的某个问题，它做了修改。第四轮，你问：“记得我们一开始说的那个延迟要求吗？”

Mon, 01 Jan 0001 00:00:00 +0000

第 X 章 Agent Memory：让 Agent 记住、反思与成长 #

本章大纲 — 2026-04-29 v3

本章导读 #

0. 引子：没有记忆的 Agent 会怎样？ #

一个每次对话都从零开始的 Agent 的尴尬场景
人类记忆类比：工作记忆 vs 长期记忆 vs 肌肉记忆
核心问题提出：如何让 Agent 像人一样"从经验中学习"？

1. 什么是 Agent Memory？ #

1.1 定义与边界 #

Agent Memory vs 模型参数（Knowledge）——“记住昨天的对话"和"训练时学到的知识"不是一回事
Agent Memory vs 对话历史（Context）——上下文窗口 ≠ 记忆
类比：RAM 中的数据 vs 硬盘中的文件 vs 刻在芯片里的固件

1.2 为什么 LLM 需要额外的 Memory？ #

上下文窗口的物理限制（即使 1M tokens 也不等于"无限记忆”）
注意力稀释问题（Lost in the Middle 效应）
成本考量：每次携带全部历史 = 指数级 token 开销

1.3 Memory 的分类体系（基于 arXiv:2512.13564 / arXiv:2603.07670） #

Forms（形态）：明文记忆、向量记忆、参数记忆、结构化记忆（KG）
Functions（功能）：存储、检索、遗忘、更新、整合
Dynamics（动态演化）：记忆的生成、衰减、巩固、迁移

📊 图 X-1 [Mermaid] Agent Memory 三维度分类框架图（Forms × Functions × Dynamics） 📋 表 X-1 四种 Memory 形态的对比（存储介质、读写方式、持久性、典型场景）

Mon, 01 Jan 0001 00:00:00 +0000

《大模型 Agent 和应用》— Agent Memory 章节参考文献 #

一、学术论文 #

1.1 综述 #

[arXiv:2512.13564] “Memory in the Age of AI Agents” — 全面梳理 Agent Memory 的形态（Forms）、功能（Functions）和动态演化（Dynamics），定义了 Memory 在 Agent 架构中的系统性地位。
[arXiv:2603.07670] Du, P. “Memory for Autonomous LLM Agents: Mechanisms, Evaluation, and Emerging Frontiers” (2026) — 系统梳理自主 LLM Agent 记忆的机制设计、评估方法和新兴前沿方向，聚焦 Agent 在长周期、多轮次场景下如何构建、维护和利用记忆以克服上下文窗口限制。

1.2 开创性工作 #

[arXiv:2304.03442] Park, J.S. et al. “Generative Agents: Interactive Simulacra of Human Behavior” — 提出 Memory-Reflection-Planning 循环，在虚拟小镇中展示 25 个 Agent 的长期记忆、社交互动和自发行为。
[arXiv:2310.08560] Packer, C. et al. “MemGPT: Towards LLMs as Operating Systems” — 提出虚拟上下文管理（Virtual Context Management），将操作系统分层内存思想引入 LLM，实现文档分析和多轮对话中的长期记忆。后演变为 Letta 项目。
[arXiv:2303.11366] Shinn, N. et al. “Reflexion: Language Agents with Verbal Reinforcement Learning” — 提出语言层面的反射式自我修正，Agent 通过记忆失败教训并生成反思来持续改进策略。
[arXiv:2309.02427] CoALA 框架 — 提出认知架构的统一框架，系统化梳理 Agent 中 Learning 与 Acting 的协同机制。

1.3 上下文与检索优化 #

[arXiv:2310.06839] Jiang, H. et al. “LongLLMLingua: Accelerating and Enhancing LLMs in Long Context Scenarios via Prompt Compression” — 通过问题感知的 prompt 压缩，在长上下文场景下降低 token 消耗同时保持关键信息。
[arXiv:2312.03815] AIOS: LLM Agent Operating System — 将 LLM 视为操作系统的核，提供上下文管理、权限控制、资源调度等 OS 级基础设施。

二、工业实践 #

2.1 MemOS / MemoryOS #

[arXiv:2505.22101] Li, Z. et al. “MemOS: An Operating System for Memory-Augmented Generation (MAG) in Large Language Models” (2025) — 首次将 Memory 提升为 LLM 的一等公民资源，统一参数记忆、激活记忆和明文记忆的表示、组织和治理机制。核心抽象为 MemCube，支持异构记忆的追踪、融合和迁移。
[arXiv:2507.03724] Li, Z. et al. “MemOS: A Memory OS for AI System” (2025) — MemOS 的系统级扩展，将记忆视为可管理系统资源，统一 plaintext、activation-based 和 parameter-level 三种记忆的调度与演化，引入 MemCube 封装记忆内容与元数据（provenance、versioning），支持记忆的组成、迁移和融合。

2.2 Mem0 #

[arXiv:2504.19413] Chhikara, P. et al. “Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory” (2025) — Mem0 团队的官方技术论文，详细阐述 Mem0 架构设计、可扩展长期记忆的构建方法、在生产环境中的实践经验和效果评估。
官方网站: https://mem0.ai/
文档: https://docs.mem0.ai/
GitHub: https://github.com/mem0ai/mem0
Mem0（YC-backed）提供面向 AI 应用的 Memory 基础设施，核心能力包括：（1）基于对话的增量记忆提取与更新（Add → Learn → Retrieve 三步流程）；（2）单层 pass 的分层蒸馏压缩引擎，自动将聊天历史压缩为紧凑记忆，降低 token 消耗和延迟；（3）跨 session 和跨 agent 的记忆持久化；（4）支持多模态记忆（文本、图像、音频）。在 Healthcare、Education、CRM 等领域有落地案例。提供 Python/Node.js SDK 和云端 API。

2.3 Letta（原 MemGPT） #

[arXiv:2310.08560] Packer, C. et al. “MemGPT: Towards LLMs as Operating Systems” (2023) — 开创性工作，提出虚拟上下文管理，启发了后续 Letta 项目。
官方网站: https://www.letta.com/
GitHub: https://github.com/letta-ai/letta
Letta 诞生于 UC Berkeley Sky Computing Lab 的 MemGPT 研究，定位为"Memory-first Agent"平台。核心特性：（1）持久化 Agent，每个 Agent 拥有独立经验和人格，可随交互持续进化；（2）后台 Memory Subagent 自动改进 prompt、上下文和技能；（3）Memory Palace 可透明查看和修改 Agent 记忆；（4）记忆可跨模型和跨提供商迁移（port memory across models）；（5）支持在任意设备上运行，通过 letta server 远程控制。

2.4 OpenViking #

GitHub: https://github.com/volcengine/OpenViking
官方网站: https://openviking.ai/
字节跳动（火山引擎）开源的 AI Agent Context Database，专为 Agent（如 OpenClaw）设计。核心设计哲学：摒弃传统 RAG 的碎片化向量存储模式，采用文件系统范式统一管理 Agent 所需的记忆、资源和技能。
- 文件系统管理范式：基于文件系统层级结构统一管理记忆（Memory）、资源（Resources）和技能（Skills），解决上下文碎片化问题。
- L0/L1/L2 三级上下文加载：按需加载，显著降低 token 消耗。
- 目录递归检索：结合目录定位与语义搜索，实现递归式精准上下文获取，突破扁平检索的局限。
- 可视化检索轨迹：支持目录检索轨迹可视化，可观测检索路径，解决传统 RAG 的黑盒问题。
- 自动会话管理：自动压缩对话内容、资源引用、工具调用等，提取长期记忆，实现上下文自迭代。
- 原生支持 OpenClaw 等 Agent 平台，提供 pip install openviking 一键安装。

2.5 阿里 ReMe #

阿里巴巴推出的 Retrieval-enhanced Memory 系统，面向长周期 Agent 的持续记忆管理。核心设计：（1）基于检索增强的记忆存取架构，将交互历史转化为可检索的结构化记忆单元；（2）支持记忆的自动摘要、去重和冲突解决；（3）与通义系列大模型深度集成，在电商客服、智能助手等场景中有大规模应用验证。

2.6 Claude Code 的 Memory 实现 #

官方文档: https://code.claude.com/docs/en/agent-sdk/sessions
Claude Code（Anthropic）通过 Session 机制实现对话记忆的持久化管理：（1）自动将 Agent 的完整对话历史（prompt、tool calls、tool results、responses）写入磁盘，支持后续恢复；（2）resume 可按 session ID 恢复特定历史会话，fork 可复制当前会话创建分支用于探索不同方向；（3）SystemMessage(subtype="compact_boundary") 标记上下文压缩边界，压缩后仅保留摘要；（4）支持文件级 checkpoint，在重要操作前手动快照文件系统状态；（5）Memory 能力本身需外部实现（Claude Code 不内置长期记忆层），通过 Session + 外部存储组合实现。
[Deep Dive: Claude Code Memory Architecture] Snowan “Deep Dive: Claude Code Memory Architecture” — 深入解析 Claude Code 的 Memory 架构设计，包括 Session 持久化机制、resume/fork 实现原理、compact_boundary 的上下文压缩策略。（URL: https://snowan.gitbook.io/study-notes/ai-blogs/claude-code-memory-architecture）

2.7 OpenClaw 的 Memory 实现 #

官方文档: https://docs.openclaw.ai/
GitHub: https://github.com/openclaw/openclaw
OpenClaw 作为自托管 AI 网关，提供多层 Memory 架构：（1）短期记忆基于会话上下文窗口，通过 Agent Loop 内维护对话状态；（2）长期记忆采用文件持久化方案（MEMORY.md、USER.md、TOOLS.md、SOUL.md 等结构化 Markdown 文件），每次会话启动时自动加载；（3）memory/ 目录按日期存储每日笔记（YYYY-MM-DD.md），支持原始日志和精炼长期记忆的分离；（4）Heartbeat 机制定期执行记忆维护——将日记中的关键洞察蒸馏到 MEMORY.md，淘汰过时信息；（5）结合向量数据库（如 LanceDB）实现语义记忆检索。整体设计借鉴操作系统的"缓存 → 主存 → 磁盘"分层策略。
[InfoQ] 熊飞宇（MemTensor 创始人 & CEO）“从上下文到经验资产：OpenClaw 热潮下的 Agent 记忆系统工程实践” — 从工程实践视角分析 OpenClaw 的记忆系统设计，探讨如何将对话上下文转化为可沉淀的经验资产。（URL 待补充）
[Deep Dive: How OpenClaw’s Memory System Works] Snowan “Deep Dive: How OpenClaw’s Memory System Works” — 深入解析 OpenClaw 的记忆系统架构，包括 Markdown 文件分层、Heartbeat 机制、LanceDB 向量检索等核心组件的设计与实现。（URL: https://snowan.gitbook.io/study-notes/ai-blogs/openclaw-memory-system-deep-dive）

2.8 Hermes Agent 的 Memory 实现 #

GitHub: https://github.com/NousResearch/hermes-agent
文档: https://hermes-agent.docs.nousresearch.com/
Hermes Agent（NousResearch）的 Memory 系统有以下独特设计：（1）基于 SQLite + FTS5 全文索引的轻量级会话存储，无需外部向量数据库（如 Milvus/Pinecone），对轻量级部署友好；（2）集成 Honcho 用户建模系统，通过辩证交互（主动提问验证和更新用户理解）构建深层用户画像；（3）闭环学习（Closed Learning Loop）系统：Agent 不仅使用工具，还能产出训练数据，用于后续 RL 训练；（4）通过 MEMORY.md / USER.md 等结构化文件实现跨会话记忆，并设有记忆字符上限强制 Agent 学会"什么值得记"；（5）内置 47 个工具分布在 19 个 toolsets 中，可按平台（CLI vs 消息渠道）动态启用不同记忆相关工具。

三、删除的条目 #

以下条目已从本列表中移除：

Mon, 01 Jan 0001 00:00:00 +0000

Deep Research 文章大纲 #

1. 引言：什么是 Deep Research？ #

1.1 定义与演进（从 Web Search → Agentic Search → Deep Research）
1.2 与传统搜索/问答的本质区别（单次检索 vs 多轮自主探索）
1.3 为什么 Deep Research 是大模型应用的重要分水岭

2. 技术架构深度解析 #

2.1 整体架构分层
- 感知层（Perception）：Web 搜索、页面爬取、API 调用、文档解析
  - 搜索引擎接入（Google/Bing/SearXNG 等）
  - 网页内容提取（Readability / Jina Reader / Firecrawl）
  - 多源数据整合（学术论文、新闻、代码仓库、私有知识库）
- 认知层（Cognition）：信息理解、推理、知识整合
  - LLM 作为推理引擎（推理模型 vs 通用模型的选择）
  - 信息抽取与结构化（实体、关系、时间线）
  - 知识图谱构建与利用
- 决策层（Decision）：策略制定、路径规划、迭代控制
  - 任务分解策略（自上而下 vs 自下而上）
  - 搜索路径优化（广度优先 vs 深度优先 vs 自适应）
  - 资源预算分配（token 预算、时间预算、API 调用限制）
- 执行层（Action）：工具调用、搜索执行、报告输出
  - 工具调用框架（Function Calling / MCP / ReAct）
  - 报告生成与引用标注
  - 人机交互（中间状态反馈、方向修正）
2.2 核心组件详解

Mon, 01 Jan 0001 00:00:00 +0000

Harness 工程深潜：从 Agent Loop 到生产级架构的实战拆解——OpenClaw vs Claude Code vs Hermes Agent #

写在前面的话：本文不是概念科普，而是从源码和工程实践出发，拆解"Harness"到底是什么、怎么实现的、有哪些坑。以 OpenClaw、Claude Code 和 Hermes Agent 三个典型实现为案例，穿插通用设计模式。

一、什么是 Harness #

在大模型应用开发中，“Harness”（线束/支架）指的是围绕 LLM API 调用构建的工程基础设施层。它把裸模型变成可用的 Agent 系统。

如果把 LLM 比作引擎，Harness 就是底盘、传动系统、仪表板和安全气囊的总和。没有它，引擎再好也跑不起来。

一个完整的 Harness 至少包含以下模块：

┌─────────────────────────────────────────────┐
│                  Harness                     │
│  ┌──────────┐  ┌─────────┐  ┌────────────┐  │
│  │Agent Loop│  │Tool     │  │Context     │  │
│  │(ReAct)   │  │Dispatch │  │Management  │  │
│  └────┬─────┘  └────┬────┘  └─────┬──────┘  │
│       │              │              │         │
│  ┌────┴──────────────┴──────────────┴──────┐ │
│  │          Session & State Layer          │ │
│  └─────────────────────────────────────────┘ │
│  ┌──────────┐  ┌─────────┐  ┌────────────┐  │
│  │Security &│  │Multi-   │  │Observ-     │  │
│  │Sandbox   │  │Agent    │  │ability     │  │
│  │          │  │Routing  │  │            │  │
│  └──────────┘  └─────────┘  └────────────┘  │
└─────────────────────────────────────────────┘
         │
         ▼
   ┌───────────┐
   │  LLM API  │
   └───────────┘

每个框都不是概念——都是要实打实写代码的子系统。下面逐个拆解。

Mon, 01 Jan 0001 00:00:00 +0000

OpenClaw 安全执行环境：沙箱、审批、策略管道与深度防御体系 #

基于 OpenClaw v2026.4.21 源码深度分析 作者：小伟 | 2026-04-30

导读 #

LLM Agent 最危险的操作是什么？执行不受控的命令。OpenClaw 面对这个问题的答案不是"信任模型"，而是构建了一套多层纵深防御体系（Defense in Depth）：从 Docker 沙箱隔离 → exec 安全策略 → 命令审批 → 文件系统保护 → SSRF 防护 → 工具策略管道，每一层都独立有效，合在一起构成完整的安全执行环境。

本文将从源码级别完整拆解这套体系。

1. 总览：纵深防御架构 #

┌─────────────────────────────────────────────────────────────────────────┐
│                    OpenClaw 安全执行环境                                 │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐ │
│  │  第1层：沙箱隔离（Sandbox Isolation）                               │ │
│  │  Docker Container: readOnlyRoot, capDrop ALL, network none        │ │
│  │  SSH Backend: 严格 Host Key 校验 + 独立 workspaceRoot             │ │
│  └───────────────────────────────────────────────────────────────────┘ │
│                                │                                       │
│  ┌─────────────────────────────▼─────────────────────────────────────┐ │
│  │  第2层：Exec 安全策略（Exec Safety）                                │ │
│  │  Shell 元字符检测 + 安全可执行值判断                               │ │
│  │  Safe Bin Profile（仅允许白名单命令）                               │ │
│  └─────────────────────────────┬─────────────────────────────────────┘ │
│                                │                                       │
│  ┌─────────────────────────────▼─────────────────────────────────────┐ │
│  │  第3层：命令审批（Exec Approval）                                   │ │
│  │  命令 → 用户确认 → 允许/拒绝/allowlist                             │ │
│  │  iOS Push / Channel 推送 / Web 界面                               │ │
│  └─────────────────────────────┬─────────────────────────────────────┘ │
│                                │                                       │
│  ┌─────────────────────────────▼─────────────────────────────────────┐ │
│  │  第4层：文件系统安全（Filesystem Safety）                           │ │
│  │  readFileWithinRoot / writeFileWithinRoot                         │ │
│  │  Path Alias Guards / Hardlink Guards                              │ │
│  │  Path Safety（穿越/符号链接/越界检测）                               │ │
│  └─────────────────────────────┬─────────────────────────────────────┘ │
│                                │                                       │
│  ┌─────────────────────────────▼─────────────────────────────────────┐ │
│  │  第5层：网络与 SSRF 防护（Network & SSRF）                          │ │
│  │  Sandbox network=none + SSRF Policy                               │ │
│  │  Fetch Guard（内网 IP 拦截 + 端口限制）                              │ │
│  └─────────────────────────────┬─────────────────────────────────────┘ │
│                                │                                       │
│  ┌─────────────────────────────▼─────────────────────────────────────┐ │
│  │  第6层：工具策略管道（Tool Policy Pipeline）                        │ │
│  │  Allowlist / Denylist / Owner-Only / Profile / FS Policy          │ │
│  └───────────────────────────────────────────────────────────────────┘ │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

2. 第1层：沙箱隔离（Sandbox Isolation） #

2.1 沙箱配置解析 #

源码：sandbox/config.ts

Mon, 01 Jan 0001 00:00:00 +0000

OpenClaw 如何保证长程任务的稳定性：从架构到源码实现 #

OpenClaw v2026.4.21，源码版本分析。所有结论来自官方文档与 openclaw npm 包源码（TypeScript → ESM bundle），源码路径标注格式为 src/<path>。

概览 #

OpenClaw 不是简单地把一个 LLM API 调用丢出去就完了。它在 Gateway 层构建了一整套 任务生命周期管理 + 可靠性机制，涵盖任务账本、超时保护、队列串行化、文件级写锁、上下文压缩、进程守护等多层防护。

1. Background Tasks — 任务生命周期账本 #

1.1 状态机 #

所有脱离主会话的工作（ACP runs、subagent spawns、cron 执行、CLI agent 命令）都会创建一条 Task 记录，经历完整状态机：

queued → running → succeeded / failed / timed_out / cancelled / lost

1.2 源码实现 #

任务执行器（src/tasks/task-executor.ts）定义了 6 个核心操作：

// src/tasks/task-executor.ts
function createQueuedTaskRun(params) { /* → status: "queued" */ }
function createRunningTaskRun(params) { /* → status: "running" */ }
function startTaskRunByRunId(params)  { /* markTaskRunningByRunId */ }
function recordTaskRunProgressByRunId(params) { /* 进度更新 */ }
function completeTaskRunByRunId(params) { /* → status: "succeeded" */ }
function failTaskRunByRunId(params)     { /* → status: "failed" */ }

分离任务运行时（src/tasks/detached-task-runtime.ts）封装了这些操作，并提供 可插拔的生命周期钩子：

Mon, 01 Jan 0001 00:00:00 +0000

OpenClaw 对话状态管理：从 Session 存储到 Context Engine 的源码级拆解 #

基于 OpenClaw v2026.4.21 源码深度分析 作者：小伟 | 2026-04-30

导读 #

一个 LLM Agent 能"记住"什么、如何管理对话上下文、如何在有限的 context window 中塞入最有价值的信息，这些是 Agent 系统的核心挑战。OpenClaw 的对话状态管理不是简单的"把历史消息传给模型"，而是一个分层架构：从持久化存储 → Session 生命周期 → Session Manager → Context Engine → Compaction → Transcript Repair，每一层各司其职。

本文将从源码级别完整拆解这一架构。

1. 总览：对话状态管理架构 #

┌──────────────────────────────────────────────────────────────────────────┐
│                    OpenClaw 对话状态管理体系                                │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │  存储层：持久化                                                       │ │
│  │  Session Store (sessions.json) + JSONL Transcript (session.jsonl)   │ │
│  │  + Session Store Cache + Session Write Lock                          │ │
│  └────────────────────────────────┬───────────────────────────────────┘ │
│                                   │                                     │
│  ┌────────────────────────────────▼───────────────────────────────────┐ │
│  │  会话层：Session 生命周期                                              │ │
│  │  Session 创建 / 路由 / 分组 / 维护（prune/rotate/maintenance）      │ │
│  └────────────────────────────────┬───────────────────────────────────┘ │
│                                   │                                     │
│  ┌────────────────────────────────▼───────────────────────────────────┐ │
│  │  引擎层：Session Manager + Context Engine                             │ │
│  │  SessionManager (pi-coding-agent) + Context Engine (assemble/ingest)│ │
│  │  + Context Window Guard + Token Estimation                          │ │
│  └────────────────────────────────┬───────────────────────────────────┘ │
│                                   │                                     │
│  ┌────────────────────────────────▼───────────────────────────────────┐ │
│  │  维护层：Compaction + Maintenance                                     │ │
│  │  Context Engine Maintenance + Compaction + Session Truncation       │ │
│  │  + Transcript Rewrite + Tool Result Truncation                      │ │
│  └────────────────────────────────┬───────────────────────────────────┘ │
│                                   │                                     │
│  ┌────────────────────────────────▼───────────────────────────────────┐ │
│  │  安全层：Repair + Guard                                               │ │
│  │  Session File Repair + Tool Result Context Guard                    │ │
│  │  + Tool Use/Result Pairing Sanitize + Thinking Block Repair         │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

2. 存储层：Session Store + JSONL Transcript #

2.1 双存储结构 #

OpenClaw 使用两种文件格式来管理对话状态：

Mon, 01 Jan 0001 00:00:00 +0000

OpenClaw 工具调用全流程：从模型输出到结果回传的源码级拆解 #

基于 OpenClaw v2026.4.21 源码深度分析 作者：小伟 | 2026-04-30

导读 #

OpenClaw 的工具调用系统是其 Agent 能力的核心。模型输出 tool_calls 后，OpenClaw 并不是简单地"找到函数然后调用"，而是经历了一整套严密的流程：工具发现 → 策略过滤 → 参数归一化 → before_tool_call 钩子 → 分类分发执行 → 结果截断与媒体提取 → after_tool_call 钩子 → 写回 transcript → 下一轮 LLM 调用。

本文将从源码级别完整拆解这一流程。

1. 总览：工具调用架构图 #

┌─────────────────────────────────────────────────────────────────────┐
│                        OpenClaw Gateway                             │
│                                                                     │
│  ┌─────────┐    ┌──────────────┐    ┌──────────────────────────┐   │
│  │  Model   │───▶│ Tool Policy  │───▶│  Tool Definition         │   │
│  │  Stream  │    │  Pipeline    │    │  Builder                 │   │
│  └─────────┘    └──────────────┘    └──────────────────────────┘   │
│                                    │                                │
│                                    ▼                                │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │              Agent Loop (selection-DmkxuIQC.js)              │   │
│  │                                                              │   │
│  │  1. 接收 assistant tool_calls                                │   │
│  │  2. buildEmbeddedAttemptToolRunContext() 构建执行上下文      │   │
│  │  3. before_tool_call 钩子（loop 检测、诊断）                 │   │
│  │  4. dispatchToolExecution() 分类分发执行                     │   │
│  │  5. sanitizeToolResult() 结果清洗 + truncation               │   │
│  │  6. after_tool_call 钩子                                     │   │
│  │  7. 写入 session transcript (JSONL)                          │   │
│  │  8. 触发下一轮 LLM 调用                                      │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                    │                                │
│                                    ▼                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐   │
│  │  exec    │  │  read    │  │ message  │  │  channel tools   │   │
│  │  process │  │  write   │  │  send    │  │  MCP / plugin    │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

2. 工具发现与注册 #

2.1 工具来源分类 #

OpenClaw 的工具来自 4 个渠道：