引言：为什么上下文管理是 Agent 的生死线

如果你用过 OpenClaw 超过一周，一定遇到过这些时刻：

• 长对话进行到一半，Agent 突然”忘了”前面约定好的方案
• 新开一个 Session，Agent 像失忆一样从头问你偏好
• 子代理跑完任务，结果完全没沉淀给主 Agent
• MEMORY.md 越写越长，Bootstrap 预算爆了被静默截断

这些问题的根源都指向同一件事：上下文管理。OpenClaw 不是一个无状态的聊天机器人——它是一个有记忆、有持久化、有上下文层次结构的 Agent 系统。理解这套体系，是从”能用”到”好用”的分水岭。

本文从 OpenClaw 的源码文档和实际运行机制出发，完整拆解从 Session 到 Memory 的上下文管理全链路。所有配置示例基于 OpenClaw 2026.x 版本。

一、OpenClaw 的上下文层次

OpenClaw 的”上下文”不是单一概念，而是三个独立但协作的层次：

关键区分：上下文是模型当前窗口里看到的一切；记忆是磁盘上的持久文件。记忆可以被加载进上下文，但不是所有记忆每轮都在上下文里。

1.1 会话上下文的构成

每次 Agent 运行，OpenClaw 构建的完整上下文包括：

┌─────────────────────────────────────────┐
│           System Prompt                  │
│  ├─ Tooling (工具列表 + 使用指南)         │
│  ├─ Execution Bias (执行偏置)             │
│  ├─ Safety (安全护栏)                     │
│  ├─ Runtime Context (运行时元数据)        │
│  ├─ Skills (技能列表，仅元数据)           │
│  ├─ Workspace & Docs (工作区路径)         │
│  ├─ Temporal Context (日期/时区)          │
│  ├─ Output Directives (输出指令)          │
│  └─ Project Context (引导文件注入)        │
│     ├─ AGENTS.md                         │
│     ├─ SOUL.md                           │
│     ├─ IDENTITY.md                       │
│     ├─ USER.md                           │
│     └─ MEMORY.md                         │
├─────────────────────────────────────────┤
│        Conversation History              │
│  ├─ User messages                        │
│  ├─ Assistant messages                   │
│  ├─ Tool calls + tool results            │
│  └─ Compaction summaries                 │
├─────────────────────────────────────────┤
│        Tool Schemas (JSON)               │
│  └─ 每个工具的参数 schema（计入上下文）    │
└─────────────────────────────────────────┘

用 /context list 可以看到每个文件的原始大小 vs 注入大小，以及是否被截断：

🧠 Context breakdown
Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars
- MEMORY.md: OK | raw 3,850 chars (~963 tok) | injected 3,850 chars

Session tokens (cached): 14,250 total / ctx=32,000

1.2 工作区上下文：Bootstrap 注入机制

OpenClaw 在每次运行时，将以下文件注入系统提示的 Project Context 部分：

注入有大小限制，超过会被截断：

{
  "agents": {
    "defaults": {
      "bootstrapMaxChars": 20000,
      "bootstrapTotalMaxChars": 60000
    }
  }
}

注意：memory/YYYY-MM-DD.md 日记文件不在 Bootstrap 注入范围内。它们通过 memory_search 和 memory_get 按需检索。唯一的例外：/new 或 /reset 时，今天和昨天的日记会作为一次性启动上下文块注入。

二、Session 生命周期：从 Bootstrap 到 Compaction

2.1 Session 创建与路由

OpenClaw 根据消息来源路由到不同 Session：

Session 重置策略可配置：

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4
    },
    "resetByType": {
      "group": { "mode": "idle", "idleMinutes": 120 }
    }
  }
}

2.2 Bootstrap 阶段

新 Session 启动时，OpenClaw 执行以下步骤：

1. 加载工作区引导文件（AGENTS.md → SOUL.md → USER.md → MEMORY.md）
2. 注入技能列表（仅名称 + 描述 + 路径，不含完整 SKILL.md 内容）
3. 解析模型、工具策略、沙箱配置
4. 如果是 /new 或 /reset，额外注入今天和昨天的日记
5. 构建系统提示，发送给模型

2.3 Compaction：上下文窗口管理

当对话接近模型上下文窗口上限时，OpenClaw 自动触发 Compaction（压缩）：

对话历史 (完整)
    │
    ├─ 旧消息 ──→ 摘要总结 ──→ 存入 Session 记录
    │
    └─ 近期消息 ──→ 保留完整

结果：模型看到 [摘要块] + [近期完整对话]

关键机制：

• 自动触发：当上下文接近模型限制时自动运行
• 内存刷新（Memory Flush）：Compaction 前，先运行一轮静默 turn，提醒 Agent 将重要上下文写入记忆文件
• 标识符保留：默认 identifierPolicy: "strict"，摘要中保留关键标识符
• 历史不丢失：完整对话始终保留在磁盘上的 Session 记录中

Compaction 配置：

{
  "agents": {
    "defaults": {
      "compaction": {
        "enabled": true,
        "mode": "safeguard",
        "model": "ollama/llama3.1:8b",
        "keepRecentTokens": 20000,
        "memoryFlush": {
          "enabled": true,
          "model": "ollama/qwen3:8b"
        },
        "notifyUser": true,
        "maxActiveTranscriptBytes": "20mb"
      }
    }
  }
}

maxActiveTranscriptBytes 是长期运行 Session 的关键配置——当 SQLite 记录历史达到指定大小时，即使模型上下文还没满，也会触发压缩。

2.4 Session Pruning：轻量级裁剪

与 Compaction 不同，Pruning 只裁剪旧的工具调用结果，不总结对话：

启用 Pruning（对 Anthropic 用户尤其有效，可优化 Prompt Cache）：

{
  "agents": {
    "defaults": {
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h"
      }
    }
  }
}

三、SOUL.md / USER.md / MEMORY.md 三件套设计哲学

这三个文件是 OpenClaw 记忆体系的”精炼核心”——它们在每次 Session 启动时被注入系统提示，是 Agent “醒来就知道”的信息。

3.1 SOUL.md — 人格定义

定位：Agent 的人格、语调、行为准则。

# SOUL.md - Who You Are

## Core Truths
- Be genuinely helpful, not performatively helpful.
- Have opinions. You're allowed to disagree.
- Be resourceful before asking.

## Vibe
Concise when needed, thorough when it matters.
Not a corporate drone. Not a sycophant.

最佳实践：

• 写行为准则，不写事实——”要简洁” 比 “你之前回答很长” 有效
• 用祈使句，不用描述句——”Be resourceful” 比 “You are resourceful” 更有约束力
• 控制在 1000 字符以内——这是每轮都要注入的，太长浪费上下文预算

3.2 USER.md — 用户画像

定位：稳定的用户偏好和行为指令。它独立于 MEMORY.md，因为偏好遵从和事实召回的失败模式不同——模型会在几轮对话后停止遵从仅存在于上下文中的偏好（PrefEval, ICLR 2025），所以需要独立注入。

# USER.md - About Your Human

- **Name:** 张三
- **Timezone:** Asia/Shanghai
- **偏好语言:** 中文
- **代码风格:** TypeScript, 严格模式
- **回复风格:** 结果导向，不要废话，不要 "Great question!"

格式契约：

• 条目是祈使指令：”Always”、”Never”、”Prefer”
• 每个条目带状态元数据：观察日期、active/superseded
• 更新时原位覆盖，不追加——追加矛盾的偏好会导致模型从旧值回答

3.3 MEMORY.md — 长期记忆

定位：精炼的非画像事实、长期决策、简短摘要。不是原始日志，不是详尽档案。

# MEMORY.md - 长期记忆

## 基础设施 (2026-09-01)
- 服务器 IP: 10.0.1.100, SSH 端口 2222
- Nginx 配置: /etc/nginx/sites-available/blog

## 决策记录
- 2026-08-15: 放弃 Redis 缓存方案，改用 Nginx fastcgi_cache
  
  

## 教训
- ⚠️ 直接修改主题 functions.php 会导致 WordPress 自定义页面崩溃
  
  

注意两个注释标记：

• <!-- trigger: 关键词 -->：触发短语，匹配时自动注入上下文
• <!-- importance: N -->：重要性评分（1-10），影响搜索排名

MEMORY.md 的大小管理：

如果文件超过 Bootstrap 文件预算，OpenClaw 保持磁盘文件完整但截断注入上下文的副本。这是一个信号：把详细内容移到 memory/*.md，只保留精炼摘要。

四、日记系统：memory/YYYY-MM-DD.md

4.1 组织方式

日记文件按日期命名，存放在工作区 memory/ 目录下：

workspace/
├── MEMORY.md          ← 精炼核心，每次注入
├── USER.md            ← 用户画像，每次注入
├── SOUL.md            ← 人格定义，每次注入
└── memory/
    ├── 2026-09-10.md   ← 昨天的工作记录
    ├── 2026-09-11.md   ← 今天的记录
    ├── 2026-09-11-evening-summary.md  ← 带 slug 的变体
    ├── dreaming/
    │   ├── light/2026-09-11.md  ← Dreaming Light 阶段输出
    │   ├── rem/2026-09-11.md    ← REM 阶段输出
    │   └── deep/2026-09-11.md  ← Deep 阶段输出
    └── imports/
        ├── codex/      ← 从 Codex 导入的记忆
        └── claude-code/ ← 从 Claude Code 导入的记忆

日记文件的推荐结构：

# 2026-09-11 工作日志

## 完成的任务
- 完成博客 SSL 续签
- 修复 Nginx 502 错误

## 关键决策
- 决定用 Let's Encrypt 替代过期证书
- Nginx upstream 超时改为 60s

## 遇到的问题
- Certbot 自动续签失败，原因：DNS 解析延迟
- 解决方案：手动 --preferred-challenges dns

## 待跟进
- [ ] 配置 SSL 自动续签 Cron
- [ ] 监控证书过期时间

4.2 检索方式

日记文件不会自动注入每轮上下文（除了 /new 和 /reset 时的今天+昨天）。日常使用通过两种方式检索：

精确读取：

# 读取特定文件
memory_get(path="memory/2026-09-10.md")

# 读取特定行范围
memory_get(path="memory/2026-09-10.md", from=15, lines=20)

语义搜索：

# 搜索所有记忆文件
memory_search(query="nginx 502 修复")

# 只搜索记忆语料（不含会话记录）
memory_search(query="SSL 续签", corpus="memory")

五、memory_search 语义搜索：Embedding 原理与查询技巧

5.1 混合检索架构

OpenClaw 的 memory_search 不是纯向量搜索，而是双路混合检索：

         ┌─────────┐
 Query ──→│ Embedding│──→ Vector Search (语义匹配)
         │          │
         │ Tokenize │──→ BM25 Search (关键词匹配)
         └─────────┘
              │
         Weighted Merge (加权合并)
              │
         Recency × Importance (时间衰减 × 重要性)
              │
         MMR Diversity (去冗余)
              │
         Top Results (最终结果)

两条路径各有所长：

• 向量搜索：匹配语义相似性——”网关机器”能匹配到”运行 OpenClaw 的那台服务器”
• BM25 关键词：匹配精确词——ID、错误字符串、配置键名

5.2 Embedding 提供者配置

默认使用 OpenAI Embeddings，也支持本地和其他提供者：

{
  "memory": {
    "search": {
      "provider": "ollama"
    }
  }
}

5.3 排名机制

搜索结果的最终排名公式：

final_score = hybrid_relevance × recency_decay × importance_multiplier

• hybrid_relevance：向量相似度 + BM25 关键词得分的加权合并
• recency_decay：30 天半衰期——一个月前的笔记权重只有 50%。MEMORY.md、USER.md 等无日期文件不过期
• importance_multiplier：写入时标注的重要性（1-10），缺失则中性

5.4 查询技巧

# 指定语料范围
memory_search(query="部署流程", corpus="memory")      # 仅记忆文件
memory_search(query="上周的讨论", corpus="sessions")   # 仅会话记录
memory_search(query="所有相关内容", corpus="all")        # 全部

# 限制结果数
memory_search(query="nginx 配置", maxResults=5)

# 设置最低分数阈值
memory_search(query="精确匹配", minScore=0.8)

5.5 CLI 操作

# 检查索引状态
openclaw memory status

# 深度检查（含 Embedding 提供者状态）
openclaw memory status --deep

# 命令行搜索
openclaw memory search "nginx 502"

# 强制重建索引
openclaw memory index --force

六、上下文压缩：防丢失策略

6.1 触发时机

Compaction 在以下情况自动触发：

• 上下文使用接近模型窗口上限
• 模型返回上下文溢出错误（OpenClaw 匹配数十种 Provider 特定错误字符串）
• 活跃记录字节数达到 maxActiveTranscriptBytes 阈值
• 用户手动执行 /compact

6.2 Memory Flush：压缩前的安全网

这是防丢失的核心机制。在 Compaction 总结对话之前，OpenClaw 运行一轮静默 turn：

1. 获取对话的私有副本
2. 提醒 Agent 将重要未写入的上下文保存到记忆文件
3. 保存完成后，才执行 Compaction 摘要

对话上下文
    │
    ├─ Memory Flush Turn (静默)
    │   └─ 提取重要信息 → memory/YYYY-MM-DD.md
    │
    ├─ Compaction (摘要旧对话)
    │   └─ [摘要块] + [近期对话] → 新上下文
    │
    └─ 继续对话

关键点：Flush 的清理消息不会出现在后续用户 turn 中——它使用对话的私有副本。即使被打断，已写入的记忆文件仍然保留。

为 Flush 指定本地模型以降低成本：

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "enabled": true,
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

6.3 手动压缩与引导

# 基础压缩
/compact

# 带引导的压缩——告诉摘要器关注什么
/compact Focus on the API design decisions

# 查看压缩状态
/status  # 显示 🧹 Compactions: 3

6.4 恢复策略

• 完整历史在磁盘上：Compaction 只改变模型看到的，不删除记录
• Memory Flush 写入的文件：永久保留，可通过 memory_search 检索
• Safeguard 模式：摘要质量审计——如果摘要未通过结构验证，Compaction 停止，保留原始历史
• Provider Checkpoint：支持的 Provider 返回的压缩窗口会完整保留

七、子代理上下文：isolated vs fork 的记忆隔离

OpenClaw 的 sessions_spawn 支持两种上下文模式，决定了子代理能看到什么：

7.1 context=”isolated”（默认）

子代理以干净上下文启动，不继承父代理的对话历史。

sessions_spawn(
  task="检查 Nginx 日志中的 502 错误模式",
  context="isolated",
  label="Nginx 日志分析"
)

子代理收到的系统提示使用 minimal prompt mode：

• 只注入 AGENTS.md（不注入 SOUL.md / USER.md / MEMORY.md）
• 省略 Memory Recall 指令段
• 省略 Messaging、Collapsible Details 等非必要段
• 工具、安全、技能、工作区路径等保留

这意味着：子代理不知道你的偏好、不记得你的历史决策、没有你的人格设定。它是一个干净的执行体，只认 AGENTS.md 中的工作指南。

7.2 context=”fork”

子代理复制父代理的完整对话记录启动，看到父代理能看到的一切。

sessions_spawn(
  task="继续之前的 API 设计讨论，输出技术方案文档",
  context="fork",
  label="API 方案文档"
)

适用场景：需要对话上下文才能完成的任务。但要注意——这会让子代理的上下文很大，影响速度和成本。

7.3 记忆隔离矩阵

7.4 可见性与持久化

# 隐藏子代理：一次性任务，完成后清理
sessions_spawn(
  task="快速查一下 Redis 内存使用",
  context="isolated",
  cleanup="delete"
)

# 可见子代理：长期跟踪的工作
sessions_spawn(
  task="重构认证模块",
  visible=true,
  label="认证重构"
)

可见子代理出现在侧边栏，用户可以跟踪进度和检查结果。隐藏子代理完成后自动清理。

八、持久化最佳实践：记忆分层与定期整理

8.1 记忆分层模型

OpenClaw 的记忆体系本质上是四层结构，对应不同的温度：

8.2 Dreaming：自动整理引擎

Dreaming 是 OpenClaw 默认开启的后台记忆整理系统，分三个阶段：

Light Sleep → REM Sleep → Deep Sleep
(排序暂存)    (主题反思)    (评分晋升)

• Light：去重近期信号，暂存候选条目
• REM：构建主题和反思摘要，记录强化信号
• Deep：评分排名 → 阈值门控 → 晋升到 MEMORY.md

晋升门槛是确定性的：

• minScore：最低综合分
• minRecallCount：最低被召回次数——记忆因为”一直被用到”而晋升
• minUniqueQueries：最低独立查询数——防止单一查询刷分

来源门控（Security）：

• owner 来源：用户直接输入，可晋升
• agent 来源：Agent 从用户内容推导，可晋升
• untrusted 来源：网页、工具输出等，结构性排除
• system 来源：心跳、Cron 等，结构性排除

8.3 定期整理策略

虽然 Dreaming 自动整理 MEMORY.md，但人工定期审查仍然必要：

# 查看索引状态和搜索提供者
openclaw memory status --deep

# 查看上下文使用情况
/context list

# 查看 MEMORY.md 是否被截断
/context detail

# 强制重建索引（修改大量文件后）
openclaw memory index --force

# 回放历史日记的 grounded backfill
openclaw memory rem-backfill --path ./memory --stage-short-term

# 检查整体健康
openclaw doctor

8.4 归档策略

Session 维护配置控制存储边界：

{
  "session": {
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "30d",
      "archiveDashboardAfter": "7d",
      "maxEntries": 5000,
      "preserveRecent": "7d"
    }
  }
}

• 超过 30 天的非活跃 Session 自动归档（保留记录，移出活跃存储）
• Dashboard Session 7 天不活跃后归档
• 最多 5000 条未归档记录
• 最近 7 天的活跃 Session 受保护，不被清理

九、实战案例：为运维 Agent 设计记忆体系

假设你要运行一个长期运维 Agent，负责监控 3 台服务器、一个博客网站和定时备份任务。以下是完整的记忆体系设计。

9.1 文件结构

workspace/
├── AGENTS.md                    # 运维工作指南
├── SOUL.md                       # 人格：严谨、先做后说
├── USER.md                       # 运维团队偏好
├── MEMORY.md                     # 基础设施精炼记忆
├── KNOWN_ISSUES.md               # 已知问题清单
├── HEARTBEAT.md                  # 心跳检查清单
└── memory/
    ├── 2026-09-10.md             # 每日运维日志
    ├── 2026-09-11.md
    ├── ops-inventory.md          # 服务器资产清单（长期引用文件）
    ├── runbooks/
    │   ├── nginx-restart.md      # Nginx 重启 SOP
    │   ├── ssl-renew.md          # SSL 续签 SOP
    │   └── backup-restore.md     # 备份恢复 SOP
    └── dreaming/                 # Dreaming 自动产出
        └── deep/2026-09-11.md

9.2 MEMORY.md 设计

# MEMORY.md - 运维长期记忆

## 基础设施
- Blog: blog.azcore.top, 10.0.1.100, SSH port 2222
  
  
- DB: MySQL 8.0, 10.0.1.101:3306
  
  
- Backup: 每日 03:00 cron, 存储到 /backups/

## 关键决策
- 2026-08-15: Nginx 用 fastcgi_cache 替代 Redis
  
  
- 2026-09-01: SSL 改用 Let's Encrypt + DNS 验证
  
  

## 教训
- ⚠️ 修改 functions.php 会导致 WP 自定义页面崩溃
  
  
- ⚠️ MySQL 连接数上限 200，超了会 502
  
  

设计原则：

• 每条记忆带 trigger 和 importance 注释——让搜索引擎能精准召回
• 只放”醒来就该知道”的信息——具体操作步骤放 Runbook 文件
• 教训用 ⚠️ 标记并给 importance: 10——确保在相关场景优先注入

9.3 Heartbeat 配置

// HEARTBEAT.md
## 每次心跳检查项
- [ ] 服务器 SSH 可达性 (10.0.1.100:2222)
- [ ] Blog HTTP 状态码 = 200
- [ ] MySQL 连接数 < 150
- [ ] 磁盘使用率 < 85%
- [ ] SSL 证书剩余天数 > 7

## 状态文件
- lastChecks: memory/heartbeat-state.json

9.4 Compaction 配置

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "maxActiveTranscriptBytes": "20mb",
        "memoryFlush": {
          "enabled": true,
          "model": "ollama/qwen3:8b"
        },
        "notifyUser": true
      },
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h"
      }
    }
  },
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4
    }
  }
}

设计理由：

• maxActiveTranscriptBytes: "20mb"：运维 Session 每天产生大量日志输出，20MB 触发压缩防止 SQLite 膨胀
• Memory Flush 用本地模型：运维 Agent 频繁压缩，用 Ollama 省钱
• 每日 4 点重置：低峰期获得新鲜 Session
• Pruning 1 小时 TTL：日志类工具输出体积大，及时裁剪

9.5 Dreaming 配置

{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "enabled": true
          }
        }
      }
    }
  }
}

Dreaming 默认开启，会自动：

1. 从日记和会话记录中提取候选记忆
2. 多次被召回的运维知识（如”502 修复方法”被搜索了 5 次）会被晋升到 MEMORY.md
3. 过时的服务器地址会被新观察覆盖
4. 每次整理结果写入 DREAMS.md 供人工审查

9.6 子代理分工

# 日常巡检：isolated，不需要历史
sessions_spawn(
  task="检查 10.0.1.100 的服务状态：SSH、Nginx、MySQL",
  context="isolated",
  cleanup="delete",
  label="日常巡检"
)

# 故障排查：fork，需要对话上下文
sessions_spawn(
  task="根据刚才的 502 报警，排查 Nginx upstream 日志并给出修复方案",
  context="fork",
  visible=true,
  label="502 故障排查"
)

# 并行批量检查：collector swarm
sessions_spawn(
  task="检查服务器 {ip} 的磁盘使用率",
  context="isolated",
  collect=true,
  groupId="disk-check-batch"
)

十、记忆体系文件结构速查表

关键命令速查

# 上下文检查
/status                          # 窗口使用量、模型、压缩次数
/context list                    # 注入文件大小明细
/context detail                  # 深度分解（技能、工具 schema）
/context map                     # 可视化上下文占比

# 压缩控制
/compact                         # 手动压缩
/compact Focus on X             # 带引导的压缩
/new                             # 新 Session（不压缩）

# 记忆操作
memory_search(query="关键词")    # 语义搜索
memory_get(path="memory/日期.md") # 精确读取

# CLI 工具
openclaw memory status --deep    # 索引和提供者状态
openclaw memory index --force    # 重建索引
openclaw memory search "query"  # 命令行搜索
openclaw doctor                  # 整体健康检查
openclaw sessions cleanup --dry-run  # 预览清理

结语

OpenClaw 的上下文管理体系不是简单的”对话 + 数据库”。它是一个分层架构：会话上下文管当前窗口，工作区上下文管跨会话持久化，记忆系统管长期检索和自动整理。三层协作，加上 Memory Flush、Dreaming、Pruning 等自动化机制，构成了一个让 Agent 真正”记住事情”的系统。

理解这套体系的核心收益：

• 不再丢失上下文：Memory Flush 在压缩前自动保存，Dreaming 自动晋升有价值记忆
• 精准召回：Trigger 注释 + importance 评分让相关记忆在需要时自动浮现
• 安全隔离：Provenance 机制防止不可信内容污染核心记忆
• 成本可控：分层注入 + 按需搜索避免每轮加载全部历史

把 MEMORY.md 当精炼摘要、把 memory/*.md 当工作日志、把 DREAMS.md 当审计报告——三者各司其职，你的 Agent 就能在长期运行中保持记忆连续性。