---
title: "05 · Context 管理：為什麼 AI 會忘記、截斷和壓縮"
description: "理解 OpenClaw 如何組裝上下文、統計 token、注入 workspace 檔案，並透過 compaction 與 pruning 控制視窗壓力。"
verifiedAt: "2026-05-06"
---

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

這兩件事必須分開：

> [!TIP]
> Memory 是可持久化的材料；Context 是模型這一次執行時實際看到的視窗。

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

## 1. Context 到底是什麼

官方定義很清楚：

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

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

| 部分 | 包含什麼 |
| --- | --- |
| System prompt | OpenClaw 構建的規則、工具、skills list、時間、執行時資訊、注入的 workspace 檔案 |
| Conversation history | 當前 session 裡的使用者訊息和 assistant 訊息 |
| Tool calls/results + attachments | 命令輸出、檔案讀取、搜尋結果、圖片、音訊、檔案等 |

```mermaid
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 裡的最後一塊。

> [!IMPORTANT]
> Context window 不是聊天視窗長度。system prompt、workspace、tools、schemas、history 和附件都在搶同一塊預算。

## 2. 先用命令看見上下文

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

| 命令 | 用途 |
| --- | --- |
| `/status` | 快速看視窗占用和 session 設定 |
| `/context list` | 看注入了什麼，以及粗略大小 |
| `/context detail` | 看每個檔案、tool schema、skill entry、system prompt 的更細分大小 |
| `/usage tokens` | 在普通回覆後追加 token 使用資訊 |
| `/compact` | 把舊歷史摘要成 compact entry，釋放視窗空間 |

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

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

```text
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 等。

```mermaid
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.md` | 操作規則和專案說明 |
| `SOUL.md` | 人格、邊界、語氣 |
| `TOOLS.md` | 工具使用習慣 |
| `IDENTITY.md` | Agent 名稱和身份 |
| `USER.md` | 使用者資料 |
| `HEARTBEAT.md` | 心跳提示，滿足條件才注入 |
| `BOOTSTRAP.md` | 只在 brand-new workspace 首次使用 |
| `MEMORY.md` | 存在時注入長期記憶 |

大檔案會被截斷。官方當前預設值是：`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 佔比異常高。

> [!WARNING]
> Bootstrap 檔案不是越全越好。它們每輪都可能進入 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`。

這是一種按需載入設計。

```mermaid
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。

> [!NOTE]
> Slash command 先由 Gateway 處理，不要把 `/status`、`/context list`、`/compact` 當成普通使用者 prompt。

## 9. Compaction 是摘要舊歷史

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

官方定義：

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

關鍵點：

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

```mermaid
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
```

手動例子：

```text
/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。

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

```mermaid
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 仍然儲存在磁碟上。

```mermaid
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 的區別

這張表必須記住：

| 維度 | Compaction | Pruning |
| --- | --- | --- |
| 處理物件 | 舊 conversation turns | old tool results |
| 方式 | 摘要成 compact entry | soft-trim 或 hard-clear |
| 是否寫回 transcript | 是，summary 存進 transcript | 否，隻影響本輪 prompt view |
| 是否保留完整歷史 | 原始歷史仍在磁碟上 | 原始 transcript 不改 |
| 解決問題 | 對話歷史太長 | 工具輸出膨脹 |

兩者互補。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：

```text
请检查当前会话上下文：
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. 接下來去哪

<Cards>
  <Card href="/zh-Hant/docs/openclaw/understanding/06-workspace" title="06 · Workspace" description="繼續看 workspace 檔案如何決定 Agent 身份、邊界、工具習慣和長期協作方式。" />
  <Card href="/zh-Hant/docs/openclaw/understanding/04-memory-system" title="04 · 記憶系統" description="回到 Memory 篇，對照 Context 和 Memory 的持久化邊界。" />
  <Card href="/zh-Hant/docs/openclaw/official/01-gateway-runtime/agents" title="官方教程：Agents" description="對照官方 Agents 頁繼續核對 Agent runtime、workspace 和執行邊界。" />
</Cards>

## 18. 官方資料

- [Context](https://docs.openclaw.ai/concepts/context)
- [System Prompt](https://docs.openclaw.ai/concepts/system-prompt)
- [Compaction](https://docs.openclaw.ai/concepts/compaction)
- [Session Pruning](https://docs.openclaw.ai/concepts/session-pruning)
- [Context Engine](https://docs.openclaw.ai/concepts/context-engine)
- [Memory Overview](https://docs.openclaw.ai/concepts/memory)
