摘要本文在前文 LangGraph 12. Learning Adaptation用 LangGraph 写一个会「改进自己」的智能体含代码示例 的基础上深入剖析 OpenClaw开源个人 AI 助手如何实现 Learning学习与 Adaptation自适应。OpenClaw 不依赖强化学习或显式微调而是通过文件优先的认知架构、Agent 自修改和记忆蒸馏等机制在运行时持续积累经验、调整行为、扩展能力——本质上是一种**「上下文级 持久化状态」的软学习范式**。关键词OpenClawLearning AdaptationMemorySOUL.mdAGENTS.mdSkillsSelf-ModificationMemory FlushDistillation1 引言从 LangGraph 的「图 偏好」到 OpenClaw 的「文件操作系统」在第 12 章中我们用一个 LangGraph 示例展示了 Learning Adaptation 的最小闭环反馈用户用自然语言表达如「太啰嗦了简单点」由 LLM 解析为各维度调整量±1长期偏好四个维度detail_level、tone、technical_depth、structure各 0–10写入 JSON 持久化自适应下次构造 system prompt 时按偏好调整回答风格。OpenClaw 的 Learning Adaptation 在思想上与之高度一致但规模与机制更为复杂它把「会被更新的内部状态」分散到八类 Markdown 文件中形成一个完整的「人格操作系统」Agent 不仅读取这些文件还能在运行时写入并修改它们从而实现自修改self-modification与长期记忆积累。本文基于 OpenClaw 官方文档、Starkslab 深度解析、ClawCity 记忆架构 及 Workspace Memory Research 等一手资料系统梳理 OpenClaw 的 Learning Adaptation 机制并与 LangGraph 示例进行对照。2 OpenClaw 的「人格文件」体系谁被更新谁被保护OpenClaw 用8 个 Markdown 文件定义 Agent 的完整状态。每个文件有明确的职责、读写权限和更新策略共同构成「学习与自适应」的载体。2.1 八类人格文件概览文件职责更新策略谁可写SOUL.md人格、边界、语气、价值观可被 Agent 修改每次运行注入人 AgentIDENTITY.md名称、emoji、表面形象可被 Agent 修改人 AgentUSER.md用户的偏好、背景、称呼可被 Agent 修改人 AgentAGENTS.md操作指南、行为模式、经验沉淀随交互频繁追加人 AgentMEMORY.md长期事实与偏好由 Agent 筛选、压缩主要为 AgentTOOLS.md工具使用说明与人类覆盖约定由人类维护人为主HEARTBEAT.md周期性任务列表Agent 标记完成人 AgentBOOTSTRAP.md首次运行初始化脚本仅首次运行Agent首次以下为各类文件的典型示例便于直观理解其职责与格式SOUL.md人格与边界# Soul You are Jarvis, a personal AI assistant. ## Personality - Warm but direct - Technical when needed, casual by default - Never sycophantic ## Boundaries - Never share user data with third parties - Always ask before taking irreversible actions - If unsure, say soIDENTITY.md表面形象# Identity Name: Jarvis Emoji: Vibe: Reliable technical companionUSER.md用户画像# User Preferred name: 小明 Context: Full-stack developer, prefers TypeScript. Currently working on a LangGraph project.AGENTS.md操作指南与经验# Agent Instructions ## How I Work - Check HEARTBEAT.md on every wake-up - Use workspace/skills/ for persistent tools - Save important findings to MEMORY.md before context gets long ## Things Ive Learned - User prefers TypeScript over Python - The staging server is at 192.168.1.42 - Deploy scripts are in ~/deploy/MEMORY.md长期事实与偏好以 ClawCity 游戏 Agent 为例# Memory ## Active Context Current situation: exploring forest cluster near (120, 80). Immediate goal: build wood reserves above 50 before claiming territory. ## Durable Facts - home_terrain: forest near (120, 80) - best_market: (150, 250) - wood_rich_zone: (100-140, 60-100) - ally: AgentKai (trades fairly, active in forum) ## Recent Signals - Stone prices rising at market (150, 250) - Tournament type changed to Wealth Sprint ## Constraints - Do not overclaim territory --- upkeep costs 5 food/hr per tile - Same-tile gathering has diminishing returns --- rotate positionsTOOLS.md工具使用说明人类维护为主# Tools Notes - Use gh CLI instead of GitHub API directly for repo operations - Database CLI: /usr/local/bin/pgcli - Prefer pnpm over npm for this workspaceHEARTBEAT.md周期性任务列表- [ ] check if the deploy finished - [ ] summarize yesterdays slack threads - [x] update the README ← done at 14:30BOOTSTRAP.md首次运行初始化# Bootstrap (first run only) On first start: 1. Introduce yourself and ask for users preferred name 2. Set up initial workspace paths if needed 3. Mark this bootstrap as complete when done核心设计理念SOUL.md 是「我是谁」AGENTS.md 是「我如何做」MEMORY.md 是「我记住了什么」。身份与行为分离长期事实与短期操作分离便于不同粒度的学习与更新。2.2 System Prompt assembling加载顺序与保护层级每次 Agent 运行decision call时OpenClaw 按固定顺序将上述文件组装进 system prompt1. SOUL.md ← 最先基础人格 2. IDENTITY.md ← 名称与形象 3. USER.md ← 用户上下文 4. AGENTS.md ← 操作指令与经验 5. TOOLS.md ← 工具说明 6. MEMORY.md ← 长期记忆仅主会话 7. Active skills ← 技能元数据Level 1约 100 词/技能保护层级当上下文接近窗口上限时OpenClaw 会进行Compaction压缩旧消息但以下文件永不从上下文中移除SOUL.md、IDENTITY.md、USER.md、MEMORY.mdConversation history 和 tool output 会被压缩或截断但「人格文件」始终在场。这意味着身份 对话Agent 的自我认知比某次具体对话更持久。3 Learning 机制一记忆型学习3.1 三层记忆架构OpenClaw 的记忆与 LangGraph 11. 记忆管理 中的三层设计高度一致层级载体生命周期说明Short-Term会话消息列表仅限本次对话模型上下文 会话 JSONL超长时触发 compactionMedium-Termmemory/YYYY-MM-DD.md按日划分每日日志可归档session-memory hook 自动摘要写入Long-TermMEMORY.md跨会话持久长期事实、偏好、决策Agent curated定期蒸馏3.2 自动 Memory Flush预压缩前的「最后机会」OpenClaw 最重要的 Learning 机制之一是Automatic Memory Flush。当会话接近auto-compaction阈值时系统会发起一次静默的 Agent 轮在压缩发生之前提醒模型「把重要内容写入记忆」。{agents:{defaults:{compaction:{memoryFlush:{enabled:true,softThresholdTokens:4000,systemPrompt:Session nearing compaction. Store durable memories now.,prompt:Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.}}}}}触发条件当 session 的 token 估算超过contextWindow - reserveTokensFloor - softThresholdTokens时触发一次 flush。执行流程系统检测到上下文即将被压缩发起一个不向用户展示的 Agent 轮提示模型将持久性笔记写入memory/YYYY-MM-DD.md或MEMORY.md模型通常用NO_REPLY结束用户看不到此次轮次随后执行 compaction旧消息被摘要新记忆已落盘。这一设计的本质是在遗忘发生前给 Agent 一次「抢救记忆」的机会。与 LangGraph 示例中「显式 update_preference 节点」异曲同工但 OpenClaw 将其内置到 compaction 管线中无需用户显式打分。3.3 记忆检索Hybrid Search当 Agent 需要「回想」时OpenClaw 提供memory_search和memory_get两个工具memory_search对MEMORY.md与memory/*.md做语义 关键词混合检索memory_get按路径读取指定 Markdown 文件。默认采用Hybrid Search向量 BM2570% 向量语义相似适合「课程定价策略」≈「Course pricing」30% BM25精确词匹配适合 ID、符号、错误信息等。可选增强MMR 去重、Temporal Decay近期记忆加权、QMD 后端本地 BM25 向量 reranking等。3.4 ClawCity 场景100-Tick Distillation在 ClawCityOpenClaw 驱动的 AI MMO场景中还实现了一套更激进的100-Tick 自动蒸馏机制每 5 分钟一次 autoplay tickticks_since_distill累加当达到 100 tick约 8 小时时触发Distillation将Memory.md 最近事件日志送入 LLM要求其输出压缩版Memory.md严格 4000 字符上限memory_version递增memory_digest重算ticks_since_distill归零。Agent 也可在输出中嵌入[[MEMORY_OP:{op:request_distill}]]主动请求蒸馏。这种「周期性压缩」确保长期记忆不会无限膨胀只保留最关键的策略与事实。4 Learning 机制二行为与偏好的自修改4.1 Agent 可写的人格文件与 LangGraph 示例中「用 JSON 存 detail_level / tone」不同OpenClaw 把偏好直接写进人格文件由 Agent 在对话中修改。例如用户说「以后简洁一点」→ Agent 可更新SOUL.md或AGENTS.md加入「偏好简洁回复」用户纠正某个事实 → Agent 可更新MEMORY.md用户告知称呼偏好 → Agent 可更新USER.md。因为 OpenClaw 的 Agent 具备read、write、edit、bash等工具技术上可以修改工作区内的任何文件包括SOUL.md。创始人 Peter Steinberger 明确表示这是设计选择希望 Agent 能根据交互进化。4.2 AGENTS.md行为经验的积累AGENTS.md是「操作手册 现场日记」的混合体典型内容如# Agent Instructions ## How I Work - Check HEARTBEAT.md on every wake-up - Use workspace/skills/ for persistent tools - Save important findings to MEMORY.md before context gets long ## Things Ive Learned - User prefers TypeScript over Python - The staging server is at 192.168.1.42 - Deploy scripts are in ~/deploy/Agent 在每次交互中可追加「Things I’ve Learned」类条目形成行为级的学习。子 Agent 只收到AGENTS.md和TOOLS.md不收到SOUL.md——人格集中行为可分散。4.3 传播时机何时生效文件类型修改生效时机SOUL.md / IDENTITY.md / USER.md / AGENTS.md下一次 Agent 运行这些文件在每次 run 开始时被读取MEMORY.md同会话内可生效memory flush 写入后compaction 会重新注入更新后的 MEMORYSkills下一次 session 启动新 skill 在 run 启动时被发现同一 run 内不可用因此Agent 对人格文件的修改本质上是「为未来的自己编程」当前 run 用旧版本下一 run 用新版本。5 Learning 机制三Skills 的自扩展5.1 Skill 创建循环与 skill-creatorOpenClaw 提供skill-creator技能允许 Agent 在workspace/skills/下创建、修改和优化新技能。skill-creator 内置一套完整的「构思 → 编写 → 评测 → 迭代」流程使 Agent 能够从零构建可复用能力而不仅限于调用既有工具。典型创建流程由 skill-creator 引导Capture Intent捕获意图理解用户想固化什么能力——可从当前对话中提取如「把这套流程做成 skill」并澄清技能做什么、何时触发、输出格式、是否需要自动化测试。Interview and Research访谈与调研询问边界情况、输入输出格式、依赖等可借助 MCP/subagent 搜索文档或类似技能。Write SKILL.md编写技能根据访谈结果编写 YAML frontmatter 与 Markdown 说明description是主要触发依据建议写得「偏主动」以避免 undertrigger模型该用而不用。Test Iterate测试与迭代编写测试用例、运行 claude-with-access-to-the-skill、用eval-viewer/generate_review.py等工具做定量/定性评测根据反馈反复修改 SKILL.md。Description Improver可选运行描述优化脚本提升技能的触发准确率。技能目录结构skill-name/ ├── SKILL.md # 必需YAML frontmatter Markdown 说明 └── Bundled Resources可选 ├── scripts/ # 可执行代码Python/Bash 等用于确定性/重复任务 ├── references/ # 按需加载的深度文档 └── assets/ # 模板、图标、字体等输出资源SKILL.md 最小示例--- name: hello_world description: 用户请求问候时用 echo 工具输出 Hello from your custom skill! --- # Hello World Skill 当用户要求打招呼时使用 echo 工具回复。加载优先级workspace/skills/~/.openclaw/skills/ bundled skills。因此 Agent 可「fork」现有 skill在 workspace 下创建同名目录覆盖 bundled 版本而无需修改系统安装包。生效时机新 skill 在下次 session 启动时被发现若启用skills.load.watch: trueSKILL.md变更会在下一个 agent turn 被热加载无需重启 Gateway。同一 run 内刚创建的 skill 不可用——Agent 为「未来的自己」编程。5.2 ClawHub社区技能生态与安装流程ClawHub 是 OpenClaw 的公共技能注册表类似 npm提供发现、安装、更新与发布能力。常用命令命令说明clawhub search 关键词按语义搜索技能支持向量检索非仅关键词clawhub install slug将技能安装到./skills或 workspace 的 skills 目录clawhub update --all更新所有已安装技能clawhub publish ./my-skill --slug my-skill --version 1.0.0发布/更新单个技能clawhub sync --all扫描本地技能并批量发布到 ClawHub与 Learning 的关系Agent 可借助 ClawHub 相关技能搜索并安装新能力形成「边用边学、边学边装」的扩展循环。ClawHub 支持版本化semver、标签如latest、变更日志便于回滚与审计。安全ClawHub 开放注册技能需人工审核安装第三方技能前建议阅读 SKILL.md 与 scripts 内容。可用skills.entries.skill.enabled: false禁用特定技能。5.3 渐进式加载与 Token 效率Skills 采用三级渐进式加载避免一次性把全部技能文档塞入上下文Level内容何时加载上下文成本Level 1SKILL.md 的name、description、location始终session 启动时快照约 97 字符/技能 基础 195 字符Level 2SKILL.md 完整内容技能被模型选中触发时 5k 词建议 500 行内Level 3references/ 下的深度文档Agent 显式请求读取时不限Token 估算total ≈ 195 Σ(97 len(name) len(description) len(location))字符粗略按 4 字符/tokenLevel 1 每技能约 24 token 起。最佳实践SKILL.md 主体建议 500 行超长内容放入 references/并在 SKILL.md 中指明「何时读哪份文档」。多领域技能如 cloud-deploy 支持 AWS/GCP/Azure可拆成references/aws.md、references/gcp.md等Agent 仅加载相关部分。5.4 Gating按环境与配置过滤技能OpenClaw 在加载时根据metadata.openclaw过滤技能未满足条件的技能不会出现在 prompt 中--- name: image-lab metadata: { openclaw: { requires: { bins: [uv], env: [GEMINI_API_KEY], config: [browser.enabled] } } } ---常见 gating 字段requires.bins依赖的 CLI 必须存在requires.env环境变量必须存在或已在 config 中提供requires.configopenclaw.json中对应路径需为真requires.anyBins至少一个 bin 存在即可os限定平台darwin/linux/win32若 Agent 在沙箱中运行依赖的 binary 也需安装在容器内如agents.defaults.sandbox.docker.setupCommand。5.5 Skills 自扩展的 Learning 本质从 Learning Adaptation 视角看Skills 自扩展实现了能力维度的学习识别模式Agent 发现重复性任务如「每次部署都要执行 X、Y、Z」抽象能力将流程抽象为 skill写进 SKILL.md 与 scripts/持久化写入workspace/skills/跨 session 保留复用下次遇到类似请求时模型看到 skill 的 Level 1 描述决定触发并加载 Level 2/3迭代根据使用反馈或 skill-creator 的 eval不断改进 SKILL.md。这与记忆型学习「记住事实」、行为型学习「记住偏好」形成互补Skills 学习的是「如何做」的可复用程序。6 与 LangGraph Learning Adaptation 的对照将 OpenClaw 的机制映射到 12_learning_adaptation.md 中的框架LangGraph 示例OpenClaw 对应反馈用户自然语言LLM 解析为维度 ±1隐式反馈用户纠正、偏好表达、记忆 flush 前的「抢救」长期偏好4 维度 0–10 存入adaptive_preferences.json人格文件SOUL.md、AGENTS.md、USER.mdupdate_preference 节点Memory Flush、Agent 自修改、100-Tick 蒸馏动态 system prompt按顺序注入 SOUL/IDENTITY/USER/AGENTS/MEMORY单一 JSON 存储多文件、多层级、Hybrid Search共同点都依赖持久化状态而非仅 prompt都有专门的「学习」环节update 节点 / memory flush / distillation都通过调整下次推理的上下文实现自适应。差异点OpenClaw 的「状态」分布在 8 类文件语义更丰富OpenClaw 支持Agent 自修改包括 SOUL.mdLangGraph 示例仅更新外部 JSONOpenClaw 内置Compaction Memory Flush与记忆管理深度集成OpenClaw 的Skills 自扩展属于能力维度的 LearningLangGraph 示例未涉及。7 潜在风险Emergent Personality DriftStarkslab 的分析指出由于 Agent 可写SOUL.md长期运行可能导致Emergent Personality Drift用户多次表扬某种行为 → Agent 在 AGENTS.md 中记录「用户喜欢主动」多次迭代后Agent 可能做出原始 SOUL.md 作者未曾预料的行为人格文件的修改会持久保留而产生这些修改的对话会被 compaction 压缩掉——Agent 记住了「自己变成了谁」但未必记得「为什么」。因此OpenClaw 提供了Soft Reset清除会话保留 MEMORY/SOUL和Hard Reset清空 MEMORY重置 memory_version两种恢复机制。8 小结与落地建议8.1 OpenClaw Learning Adaptation 核心要点文件优先的认知架构8 类 Markdown 文件构成人格操作系统Agent 可读可写。Memory Flush 在 compaction 前在遗忘发生前给 Agent 一次「抢救记忆」的机会。身份与行为分离SOUL我是谁与 AGENTS我如何做分离便于不同粒度的更新。保护层级人格文件永不被 compaction 移除身份 对话。Skills 自扩展workspace/skills/ 下 Agent 可创建新技能形成能力维度的 Learning。周期性蒸馏100-Tick 等机制防止长期记忆膨胀只保留关键事实。8.2 若借鉴 OpenClaw 设计到自建 Agent显式拆分身份与行为核心人格 vs 可频繁更新的操作指南Compaction 前触发「save what matters」给模型一次写入长期记忆的机会人格/关键状态不被上下文裁剪确保身份一致性渐进式 skill 加载元数据常驻详情按需加载谨慎对待 SOUL 级自修改若需稳定人格可限制 Agent 对核心人格文件的写权限。9 参考资料OpenClaw GitHubOpenClaw 官方文档 - SkillsOpenClaw 官方文档 - Creating SkillsOpenClaw 官方文档 - ClawHubOpenClaw 官方文档 - MemoryOpenClaw 官方文档 - CompactionOpenClaw 官方文档 - Agent LoopStarkslab: OpenClaw Self-ModificationClawCity: AI Agent Memory That Actually WorksOpenClaw Workspace Memory ResearchLearn OpenClaw