OpenClaw Context Engine 設定指南：自訂模型上下文管理

當你在開發 AI 代理程式時，最頭痛的往往不是模型本身，而是怎麼處理那堆長到爆炸的對話紀錄。當 Context Window 快要滿出來，或是你想讓模型更聰明地回顧過去的對話時，你一定會希望有一個更靈活的方式來管理這些資訊。

這就是 Context Engine 發揮作用的地方。它控制 OpenClaw 如何為每次執行建立模型 context，決定要包含哪些訊息、如何總結舊歷史，以及如何管理跨子代理（subagent）邊界的 context。OpenClaw 內建了 legacy 引擎，但你也可以透過外掛註冊其他的引擎來取代預設的生命週期。

Context Engine

快速開始 (Quick start)

先檢查一下目前哪個引擎正在運作：

openclaw doctor
# or inspect config directly:
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

安裝 Context Engine 外掛

Context engine 外掛的安裝方式跟其他 OpenClaw 外掛一樣。先安裝，然後在 slot 中選擇該引擎：

# Install from npm
openclaw plugins install @martian-engineering/lossless-claw

# Or install from a local path (for development)
openclaw plugins install -l ./my-context-engine

接著啟用外掛，並在你的設定檔中將它設為作用中的引擎：

openclaw.json

{
  plugins: {
    slots: {
      contextEngine: "lossless-claw", // must match the plugin's registered engine id
    },
    entries: {
      "lossless-claw": {
        enabled: true,
        // Plugin-specific config goes here (see the plugin's docs)
      },
    },
  },
}

安裝並設定好後，記得重啟 Gateway。

如果你想換回內建引擎，只需將 contextEngine 設為 "legacy"（或者直接刪除這個 key，因為 "legacy" 是預設值）。

運作原理 (How it works)

每當 OpenClaw 執行模型 prompt 時，context engine 會參與四個生命週期節點：

1. Ingest — 當新訊息加入 session 時呼叫。引擎可以將訊息儲存或索引到自己的資料庫中。
2. Assemble — 在每次模型執行前呼叫。引擎會回傳一組排序好的訊息（以及選填的 systemPromptAddition），並確保它們符合 token 預算。
3. Compact — 當 context 視窗滿了，或使用者執行 /compact 時呼叫。引擎會總結舊歷史以釋放空間。
4. After turn — 在執行完成後呼叫。引擎可以持久化狀態、觸發背景壓縮或更新索引。

子代理生命週期（選填）

OpenClaw 目前會呼叫一個子代理生命週期 hook：

• onSubagentEnded — 當子代理 session 完成或被清理時進行後續處理。

prepareSubagentSpawn hook 雖然也是介面的一部分，供未來使用，但目前 runtime 還不會呼叫它。

System prompt 附加內容

assemble 方法可以回傳一個 systemPromptAddition 字串。OpenClaw 會將它加在該次執行的 system prompt 前面。這讓引擎可以注入動態的檢索指南、提取指令或 context 提示，而不需要手動修改靜態的 workspace 檔案。

Legacy 引擎 (The legacy engine)

內建的 legacy 引擎保留了 OpenClaw 原始的行為：

• Ingest: no-op（session 管理器會直接處理訊息持久化）。
• Assemble: pass-through（由 runtime 中現有的 sanitize → validate → limit 流程處理 context 組裝）。
• Compact: 委派給內建的總結壓縮功能，它會為舊訊息建立單一總結，並保留最近的訊息。
• After turn: no-op。

Legacy 引擎不會註冊工具，也不會提供 systemPromptAddition。

當沒有設定 plugins.slots.contextEngine（或設為 "legacy"）時，系統會自動使用這個引擎。

外掛引擎 (Plugin engines)

外掛可以使用 plugin API 註冊 context engine：

export default function register(api) {
  api.registerContextEngine("my-engine", () => ({
    info: {
      id: "my-engine",
      name: "My Context Engine",
      ownsCompaction: true,
    },

    async ingest({ sessionId, message, isHeartbeat }) {
      // Store the message in your data store
      return { ingested: true };
    },

    async assemble({ sessionId, messages, tokenBudget }) {
      // Return messages that fit the budget
      return {
        messages: buildContext(messages, tokenBudget),
        estimatedTokens: countTokens(messages),
        systemPromptAddition: "Use lcm_grep to search history...",
      };
    },

    async compact({ sessionId, force }) {
      // Summarize older context
      return { ok: true, compacted: true };
    },
  }));
}

然後在設定中啟用它：

{
  plugins: {
    slots: {
      contextEngine: "my-engine",
    },
    entries: {
      "my-engine": {
        enabled: true,
      },
    },
  },
}

ContextEngine 介面

必要成員：

成員	類型	用途
info	屬性	引擎 id、名稱、版本，以及它是否自行管理壓縮 (compaction)
ingest(params)	方法	儲存單一訊息
assemble(params)	方法	為模型執行建立 context（回傳 AssembleResult）
compact(params)	方法	總結或縮減 context

assemble 會回傳一個 AssembleResult，包含：

• messages — 要傳送給模型的排序訊息。
• estimatedTokens（必要，number） — 引擎對組裝後 context 總 token 數的估計。OpenClaw 會用它來決定壓縮門檻和診斷報告。
• systemPromptAddition（選填，string） — 附加在 system prompt 前面的內容。

選填成員：

成員	類型	用途
bootstrap(params)	方法	初始化 session 的引擎狀態。當引擎第一次看到某個 session 時呼叫（例如匯入歷史紀錄）。
ingestBatch(params)	方法	批次處理完成的輪次。在一次執行結束後呼叫，同時傳入該輪次的所有訊息。
afterTurn(params)	方法	執行後的生命週期工作（持久化狀態、觸發背景壓縮）。
prepareSubagentSpawn(params)	方法	為子 session 設定共享狀態。
onSubagentEnded(params)	方法	子代理結束後的清理工作。
dispose()	方法	釋放資源。在 Gateway 關閉或外掛重新載入時呼叫，而非每個 session 呼叫。

ownsCompaction

ownsCompaction 控制 Pi 內建的自動壓縮功能在執行時是否保持啟用：

• true — 引擎自行管理壓縮行為。OpenClaw 會停用該次執行的內建自動壓縮，引擎的 compact() 實作需負責處理 /compact、溢位復原壓縮以及任何它想在 afterTurn() 執行的主動壓縮。
• false 或未設定 — 內建自動壓縮在 prompt 執行期間仍可能運作，但當使用者執行 /compact 或需要溢位復原時，仍會呼叫作用中引擎的 compact() 方法。

ownsCompaction: false 並不代表 OpenClaw 會自動退回到 legacy 引擎的壓縮路徑。

這意味著有兩種有效的外掛模式：

• 主導模式 (Owning mode) — 實作你自己的壓縮演算法並設定 ownsCompaction: true。
• 委派模式 (Delegating mode) — 設定 ownsCompaction: false，並在 compact() 中從 openclaw/plugin-sdk/core 呼叫 delegateCompactionToRuntime(...) 來使用 OpenClaw 內建的壓縮行為。

對於非主導模式的引擎，如果 compact() 是一個 no-op（空操作）是很危險的，因為它會導致該引擎 slot 的正常 /compact 和溢位復原路徑失效。

設定參考 (Configuration reference)

{
  plugins: {
    slots: {
      // Select the active context engine. Default: "legacy".
      // Set to a plugin id to use a plugin engine.
      contextEngine: "legacy",
    },
  },
}

這個 slot 在執行時是排他的 — 對於特定的執行或壓縮操作，只會解析出一個註冊的 context engine。其他啟用的 kind: "context-engine" 外掛仍可以載入並執行其註冊程式碼，但 plugins.slots.contextEngine 決定了 OpenClaw 在需要 context engine 時會選用哪一個。

與壓縮及記憶的關係 (Relationship to compaction and memory)

• 壓縮 (Compaction) 是 context engine 的職責之一。Legacy 引擎委派給 OpenClaw 內建的總結功能。外掛引擎可以實作任何壓縮策略（例如 DAG 總結、向量檢索等）。
• 記憶外掛 (Memory plugins) (plugins.slots.memory) 與 context engine 是分開的。記憶外掛提供搜尋與檢索功能；context engine 則控制模型實際看到的內容。它們可以協作 — context engine 在組裝時可以使用記憶外掛的資料。
• Session 修剪 (Session pruning)（在記憶體中修剪舊的工具執行結果）不論哪個 context engine 在運作都會執行。

小撇步 (Tips)

• 使用 openclaw doctor 來確認你的引擎是否正確載入。
• 如果切換引擎，現有的 session 會保留目前的歷史紀錄，新引擎會接手後續的執行。
• 引擎錯誤會被記錄並顯示在診斷資訊中。如果外掛引擎註冊失敗或找不到選定的引擎 id，OpenClaw 不會自動退回預設值，執行會失敗直到你修復外掛或將 plugins.slots.contextEngine 改回 "legacy"。
• 開發時，使用 openclaw plugins install -l ./my-engine 來連結本地外掛目錄，不需要每次複製檔案。

也可以參考：Compaction, Context, Plugins, Plugin manifest。

相關內容 (Related)

• Context — 了解如何為 agent 輪次建立 context
• Plugin Architecture — 註冊 context engine 外掛
• Compaction — 總結長對話的機制

想要更深入了解如何設定你的開發環境嗎？快來問問我們的 AI Setup Assistant！