跳转至

Agent State Management

by zhenliang · 2026.04 · 基于 Claude Code 与 OpenClaw 源码

LLM 是无状态的，但 Agent 不是。这份报告研究的是：Agent 在 LLM 之外维护的那些状态——它们如何注入、更新、丢弃，以保证决策的连贯性和正确性。

我的视角

Agent 在执行任务的全生命周期中需要维护大量状态——Context、Memory、工具集、Skill、Sub-agent 等。这些状态如何被注入、更新、丢弃和恢复，直接决定了 Agent 决策的连贯性和正确性。

本报告基于 Claude Code 和 OpenClaw 的源码，从State Management角度回答以下问题：

我们关心的

  • 注入什么：每次 LLM 调用时，system prompt 里有什么？哪些工具可见？哪些 Skill 被列出？哪些Memory 被召回？
  • 何时更新：工具集在什么场景下动态变化？Skill 何时被自动激活？Memory 何时被自动提取？
  • 如何丢弃：Context 快满时，用什么策略压缩？压缩后如何恢复关键信息？怎么防止「失忆」？
  • 怎么维持连贯：跨会话的知识怎么持久化？Sub-agent 之间的状态怎么隔离又共享？

我们不关心的

本报告聚焦于 Agent 状态的生命周期，不深入以下底层工程实现：

  • 运行时架构：Bun 打包、React/Ink TUI 渲染、Gateway WebSocket RPC、插件系统四层生命周期
  • API 调用层：流式响应处理、重试策略（指数退避、rate limit）、错误恢复
  • 认证与安全：OAuth 流程、JWT token、IDE Bridge 双向通信协议
  • 部署与运维：Docker 部署、GitHub Actions CI、K8s 配置、多实例负载均衡
  • UI 与交互：Vim 模式状态机、Voice 模式门控、Doctor 诊断、终端渲染优化
  • 应用状态存储：34 行 pub/sub Store、Feature Flags（Bun DCE / GrowthBook）、AppState 类型定义

这些是重要的工程工作，但它们不直接影响「Agent 在某个时刻能看到什么信息、做出什么决策」这个核心问题。

目录

分析框架

  • 分析框架 — 什么是 Agent State？由哪些组件构成？注入、更新、丢弃、恢复四类操作如何影响 State？

Claude Code 专题分析

  • 概览 — 单进程 CLI，内存优先，一切为了 Prompt Cache 命中
  • Context Management — Context 的五个组成部分及变化频率；静态/动态 Prompt 分区保缓存；六层渐进式压缩如何在缓存和空间之间做 trade-off
  • Memory 系统 — CLAUDE.md 五层体系记什么、谁来写；后台 Fork Agent 自动提取四种Memory 类型；Sonnet 并行预取三步召回
  • Tool Management — 三源组装工具池、内置优先防覆盖；LLM 看到 Schema 看不到行为标记；Sub-agent 过滤和 Coordinator 裁剪如何改变工具集
  • Skill 系统 — 完整 frontmatter 元数据及 LLM 可见性；三通道注入（system prompt 指导 + Attachment listing + SkillTool prompt）；1% 预算与三级降级
  • Sub-agent — Fork vs Normal 的 11 项状态继承/隔离决策；同步返回、120s 后台化、异步通知三种状态回传；Coordinator 的状态分治
  • Attachment 系统 — 第三条状态注入通道：每 turn 并行计算 30+ 类动态 Context；两个触发时机；Delta 增量与频率控制

OpenClaw 专题分析

  • 概览 — Gateway 多渠道架构，磁盘优先，防御性编程层层设防
  • Context Management — 每次 run 从磁盘恢复 + sanitize；五步压缩安全网（先 Flush 保存、再压缩、后补注入关键约束、支持检查点回滚）
  • Memory 系统 — 文件即 Memory，职责分离（MEMORY/SOUL/AGENTS.md）；Memory Flush 在压缩前自动写盘；被动向量检索 vs Claude Code 的主动预取
  • Tool Management — 五类工具源多源合并；7 层配置驱动的策略管道逐层过滤；MCP 三角色（消费 + 暴露 + 网关）
  • Skill 系统 — 与 Claude Code 格式兼容但无路径触发和 Fork 执行；ClawHub 远程注册表；Skill-Tool 桥接模糊 Skill 和工具的边界
  • Sub-agent — 基于独立 Session 的状态隔离（无缓存共享）；Steer 机制运行时修改 Agent 状态；4 种队列策略决定消息如何影响当前状态

对比分析

  • 对比分析 — 「用模型解决问题 vs 用工程解决问题」——从状态持久化、注入通道、压缩哲学、Memory 召回、Sub-agent 继承五个角度分析核心分歧与行业共识

分析基础

项目 版本 / 来源 规模
Claude Code v2.1.88（npm source map） 1,884 个 .ts/.tsx，~512K 行
OpenClaw GitHub 开源 11,295 个 .ts/.js，~2.15M 行