05 · Context 管理：為什麼 AI 會忘記、截斷和壓縮

上一篇講 Memory：資訊儲存到磁碟，未來才有機會找回。本篇講 Context：本輪真正傳送給模型的內容。

這兩件事必須分開：

很多“AI 忘了”的問題，根因不是記憶沒寫，而是它沒有進入本輪 context；很多“上下文爆了”的問題，也不是聊天太長，而是系統提示、工具 schema、workspace 檔案和工具結果一起把視窗吃滿了。

1. Context 到底是什麼

官方定義很清楚：

Context is everything OpenClaw sends to the model for a run.

它受模型 context window，也就是 token limit 限制。初學者可以把它分成三塊：

flowchart TD
  A[System prompt] --> C[Context window]
  B[Conversation history] --> C
  D[Tool calls and results] --> C
  E[Attachments] --> C
  F[Compaction summaries] --> C
  G[Provider wrappers] --> C
  C --> M[Model run]

這也解釋了為什麼你只發一句短訊息，模型實際處理的 token 仍然很多。你的訊息只是 context 裡的最後一塊。

2. 先用命令看見上下文

OpenClaw 提供了幾個直接觀察 context 的命令：

從排障角度，第一步不是猜，而是跑 /context list。

官方示例裡，/context list 會顯示類似資訊：

Context breakdown
Workspace: <workspaceDir>
Bootstrap max/file: 12,000 chars
System prompt (run): 38,412 chars (~9,603 tok)

Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars | injected 1,742 chars
- TOOLS.md: TRUNCATED | raw 54,210 chars | injected 20,962 chars

Skills list: 2,184 chars
Tool schemas: 31,988 chars
Session tokens: 14,250 total / ctx=32,000

這些數字會隨模型、provider、tool policy、workspace 內容而變。不要背數字，要學會看哪個部分最大。

3. System prompt 每次執行都會重建

OpenClaw 的 system prompt 是 OpenClaw-owned，每次 Agent run 都會組裝並注入。它不是 pi-coding-agent 的預設 prompt。

它通常包含：

• Tooling：工具使用規則和當前工具能力。
• Execution Bias：可執行請求要在本輪推進，阻塞時說明。
• Safety：基礎安全約束。
• Skills：可用技能列表和按需讀取規則。
• OpenClaw Self-Update：如何安全檢視和修改配置。
• Workspace：工作目錄。
• Documentation：本地或公開文件路徑。
• Workspace Files：注入的專案上下文。
• Sandbox：沙箱狀態。
• Current Date & Time：使用者時區相關資訊。
• Heartbeats：心跳相關上下文。
• Runtime：host、OS、model、thinking 等。

flowchart LR
  A[OpenClaw runtime] --> B[Build system prompt]
  C[Workspace files] --> B
  D[Tools and schemas] --> B
  E[Skills list] --> B
  F[Runtime metadata] --> B
  B --> G[Model context]

這裡有一個關鍵判斷：system prompt 裡的安全約束是 advisory，指導模型行為；真正的硬邊界要靠 tool policy、exec approvals、sandboxing、channel allowlists。

4. Workspace 檔案會進入 Project Context

OpenClaw 會把一組 bootstrap files 修剪後注入 Project Context，讓模型不用顯式讀取檔案，也能看到身份、使用者和工作規則。

預設注入的檔案包括：

大檔案會被截斷。官方當前預設值是：agents.defaults.bootstrapMaxChars 為 12000 chars，控制單個 bootstrap 檔案最大注入字元數；agents.defaults.bootstrapTotalMaxChars 為 60000 chars，控制所有 bootstrap 檔案合計注入上限；agents.defaults.bootstrapPromptTruncationWarning 為 once，控制截斷時是否在 Project Context 注入警告。

這就是為什麼 TOOLS.md、MEMORY.md、AGENTS.md 不能無限寫。它們越長，越容易導致：

• 本輪可用視窗變小。
• 關鍵內容被截斷。
• compaction 更頻繁。
• /context list 中 Project Context 佔比異常高。

5. Daily memory 不等於普通 bootstrap

上一篇講過 memory/YYYY-MM-DD.md。這裡補一個重要邊界：

memory/*.md daily files are not part of the normal bootstrap Project Context.

普通回合裡，daily notes 透過 memory_search 和 memory_get 按需訪問，不會自動吃掉 context window。例外是裸 /new 和 /reset 回合，runtime 可以把最近 daily memory 作為一次性 startup-context block prepend 進去。

這點解釋了兩個現象：你寫了 daily note，但普通回覆沒引用，通常是因為它沒有自動注入，Agent 需要搜尋或讀取；MEMORY.md 太大會影響上下文，是因為它屬於 bootstrap 注入檔案，存在時會進入 context。

所以長期穩定資訊放 MEMORY.md 要剋制；大量工作流水放 daily notes，再靠搜尋召回。

6. Skills 有兩種上下文成本

Skills 不會預設把完整 SKILL.md 全部塞進 system prompt。

官方當前機制是：

• system prompt 注入 compact skills list：name、description、location。
• 具體 skill instructions 不預設注入。
• 模型需要用某個 skill 時，再用 read 讀取對應 SKILL.md。

這是一種按需載入設計。

flowchart LR
  A[Skills folder] --> B[Compact skills list]
  B --> C[System prompt]
  C --> D{Need skill?}
  D -- Yes --> E[read SKILL.md]
  D -- No --> F[No full skill text loaded]

如果技能很多，skills list 本身也有成本。不要把 skill description 寫成小作文；description 應該讓模型判斷何時使用，而不是替代完整手冊。

7. Tools 的隱藏成本更大

Tools 對 context 有兩種成本：Tool list text 可在 system prompt 報告中看到，是簡短工具描述；Tool schemas JSON 不作為普通文本展示，但計入 context，用來讓模型知道如何呼叫工具。

官方 /context detail 會列出最大的 tool schemas。這個很重要，因為你可能看不到它們，但它們確實消耗 token。

典型情況：

• 瀏覽器工具 schema 很大。
• exec / process 這類工具引數複雜，也會佔空間。
• 工具越多，模型呼叫能力越強，但基礎上下文成本也越高。

這就是 tool policy 的另一個作用：不只是安全，也是上下文預算治理。

8. Slash command 不一定會進入模型

Context 文件還強調了 slash command 的三種行為：

• Standalone commands：訊息只有 /...，由 Gateway 作為命令執行。
• Directives：/think、/verbose、/trace、/reasoning、/elevated、/model、/queue 等會在模型前被剝離。
• Inline shortcuts：允許的傳送者在普通訊息裡觸發某些 /...，執行後再剝離。

這說明 /status、/context list、/compact 這類操作不等同於“告訴模型一句話”。它們先被 Gateway 處理。

排障時要分清：

• 是使用者訊息進了模型，但模型沒理解。
• 還是 slash command 被 Gateway 提前處理，根本不是普通 prompt。

9. Compaction 是摘要舊歷史

Compaction 解決的是會話歷史太長的問題。

官方定義：

1. 舊 conversation turns 被摘要成 compact entry。
2. 摘要儲存在 session transcript。
3. 最近訊息保持原樣。

關鍵點：

• 完整歷史仍在磁碟上。
• Compaction 只改變下一輪模型看到什麼。
• Auto-compaction 預設開啟。
• 當接近 context limit，或 provider 返回 context-overflow error 時觸發。
• /compact 可以手動觸發，並可附加指導語。

flowchart TD
  A[Long session history] --> B[Older turns]
  A --> C[Recent turns]
  B --> D[Compaction summary]
  D --> E[Session transcript]
  C --> F[Kept intact]
  E --> G[Next model context]
  F --> G

手動例子：

/compact Focus on the API design decisions

Compaction 質量取決於摘要模型。可以設定 agents.defaults.compaction.model 使用專門模型；未設定時從 active session model 開始，並可能走現有 fallback chain。顯式 compaction model override 是精確值。

10. Memory flush 發生在 compaction 前

Before compacting，OpenClaw can run a silent memory flush turn to store durable notes to disk。

這一步的目的不是壓縮上下文本身，而是在壓縮前搶救值得長期儲存的資訊。

flowchart LR
  A[Near overflow] --> B[Memory flush]
  B --> C[Write durable notes]
  C --> D[Compaction]
  D --> E[Compact context]

所以它和上一篇的 Memory 形成閉環：Memory flush 寫入 memory files，避免重要內容只留在即將被摘要的歷史裡；Compaction 寫入 session transcript summary，減少下一輪模型看到的歷史長度。

不要把 memory flush 當成普通自動記憶系統。它是 compaction 前的 silent housekeeping。

11. Pruning 是修剪舊工具結果

Pruning 解決的是工具輸出過大，而不是普通聊天過長。

官方定義：

Session pruning trims old tool results from the context before each LLM call.

它有幾個硬邊界：

• 只修剪 old tool results。
• 不重寫普通 conversation text。
• in-memory only。
• 不修改 on-disk session transcript。
• full history 仍然儲存在磁碟上。

flowchart TD
  A[Session transcript on disk] --> B[Build prompt view]
  B --> C{Old tool result too large?}
  C -- Yes --> D[Soft trim head and tail]
  D --> E[Hard clear remaining old results]
  C -- No --> F[Keep as is]
  E --> G[LLM call]
  F --> G

Pruning 預設對 Anthropic profiles 自動啟用；非 Anthropic providers 預設 off，可透過 contextPruning 開啟。

12. Compaction 和 Pruning 的區別

這張表必須記住：

兩者互補。Pruning 讓工具結果不那麼容易把視窗頂滿；Compaction 在歷史整體接近上限時建立摘要。

13. Context Engine 決定如何組裝上下文

大多數使用者用預設 legacy engine 就夠了。官方說：OpenClaw ships with a built-in legacy engine and uses it by default。

Context engine 的職責是：

• 選哪些 messages 進入模型。
• 如何摘要舊歷史。
• 如何跨 subagent 邊界管理 context。

每次 OpenClaw 執行 model prompt，context engine 參與四個生命週期點：

• Ingest：新訊息進入 session 時，engine 可儲存或索引。
• Assemble：模型執行前，返回適配 token budget 的有序 messages。
• Compact：視窗滿或使用者 /compact 時，摘要舊歷史。
• After turn：執行結束後，持久化狀態、觸發後臺壓縮或更新索引。

Legacy engine 的行為：

• Ingest：no-op。
• Assemble：由現有 runtime pipeline 處理。
• Compact：委託內建 summarization compaction。
• After turn：no-op。

只有當你需要不同的 assembly、compaction 或 cross-session recall 策略，才考慮外掛化 context engine。

14. 常見誤解

常見誤解可以按這組邊界校正：

• 記憶寫了不等於本輪一定可見。只有被注入、載入或搜尋回來才在 context 裡。
• 200K window 不等於 200K 聊天空間。system prompt、tools、schemas、workspace、history 都佔視窗。
• memory/*.md 不是每輪都會自動載入。普通回合按需搜尋或讀取，裸 /new 和 /reset 有例外。
• Skill 不是安裝越多越好。skills list 有成本，完整說明按需讀取。
• Tool schema 不可見也佔 token。schema 計入 context，只是不作為普通文本展示。
• Pruning 不會刪歷史。pruning 隻影響 in-memory prompt，不改 transcript。
• /compact 不是清空會話。compaction 寫摘要並保留 recent messages，不是 /new。

15. 給 Agent 的實踐任務

把下面任務交給你的 OpenClaw Agent：

请检查当前会话上下文：
1. 执行 /context list，指出最大的 3 个上下文来源。
2. 执行 /context detail，说明 tool schemas 和 skills list 的大致占比。
3. 判断是否有 bootstrap 文件被 TRUNCATED。
4. 说明 MEMORY.md 和 memory/*.md 在本轮上下文里的差异。
5. 如果上下文压力很大，给出 pruning、compaction、缩短 bootstrap 文件、收紧 tool policy 的处理顺序。

你要看的不是它有沒有給一堆泛泛建議，而是能不能用 /context 的實際輸出定位最大成本。

16. 本章自檢

讀完這一篇，你應該能回答：

1. Context 和 Memory 的區別是什麼？
2. /context list 和 /context detail 分別看什麼？
3. 為什麼 workspace bootstrap 檔案太長會導致截斷？
4. Skill 為什麼是列表注入、說明按需讀取？
5. Tool schema 為什麼是隱藏但真實的上下文成本？
6. Compaction 和 Pruning 的持久化差異是什麼？
7. Context engine 的四個生命週期點是什麼？

能回答這些問題，再進入 Workspace 篇，你就能理解為什麼 OpenClaw 把 AGENTS.md、SOUL.md、TOOLS.md、USER.md 這類檔案作為長期工作容器。

17. 接下來去哪

18. 官方資料

• Context
• System Prompt
• Compaction
• Session Pruning
• Context Engine
• Memory Overview