上下文引擎

上下文引擎控制 OpenClaw 如何為每次執行建立模型上下文：要包含哪些訊息、如何摘要較舊的歷史記錄，以及如何跨子代理邊界管理上下文。

OpenClaw 內建 legacy 引擎，並預設使用它。只有當你需要不同的組裝、壓縮或跨工作階段回憶行為時，才安裝並選取外掛引擎。

快速開始

openclaw doctor# 或直接檢查設定：cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

openclaw plugins install @martian-engineering/lossless-claw

openclaw plugins install -l ./my-context-engine

// openclaw.json{  plugins: {    slots: {      contextEngine: "lossless-claw", // 必須符合外掛註冊的引擎 id    },    entries: {      "lossless-claw": {        enabled: true,        // 外掛專屬設定放在這裡（請參閱外掛文件）      },    },  },}

運作方式

每當 OpenClaw 執行模型提示詞時，上下文引擎會參與四個生命週期階段：

引擎也可以實作選用的 maintain() 方法，在啟動載入、成功完成回合或壓縮後維護逐字記錄（透過 runtimeContext.rewriteTranscriptEntries() 安全地重寫）。設定 info.turnMaintenanceMode: "background" 可將其作為延後工作執行，而不會阻塞回覆。

對於隨附的非 ACP Codex 控制框架，OpenClaw 會將組裝後的上下文投射至 Codex 開發人員指示與目前回合提示詞，以套用相同的生命週期。Codex 仍負責管理其原生執行緒歷史記錄與原生壓縮器。

子代理生命週期（選用）

OpenClaw 會呼叫兩個選用的子代理生命週期掛鉤：

系統提示詞附加內容

assemble 方法可以傳回 systemPromptAddition 字串。OpenClaw 會將它加到該次執行的系統提示詞前方。這讓引擎無須依賴靜態工作區檔案，即可注入動態回憶指引、擷取指示或具上下文感知能力的提示。

legacy 引擎

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

• 擷取：不執行任何作業（工作階段管理員會直接處理訊息持久化）。
• 組裝：直接傳遞（執行階段中現有的清理 → 驗證 → 限制管線會處理上下文組裝）。
• 壓縮：委派給內建的摘要壓縮功能，此功能會將較舊的訊息建立為單一摘要，並完整保留近期訊息。
• 回合後：不執行任何作業。

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

未設定 plugins.slots.contextEngine（或將其設為 "legacy"）時，會自動使用此引擎。

外掛引擎

外掛可以使用外掛 API 註冊上下文引擎：

  export default function register(api) {  api.registerContextEngine("my-engine", (ctx) => ({    info: {      id: "my-engine",      name: "My Context Engine",      ownsCompaction: true,    },     async ingest({ sessionId, message, isHeartbeat }) {      // 將訊息儲存至你的資料儲存區      return { ingested: true };    },     async assemble({      sessionId,      sessionKey,      messages,      tokenBudget,      availableTools,      citationsMode,    }) {      // 傳回符合預算的訊息      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // 摘要較舊的上下文      return { ok: true, compacted: true };    },  }));}

工廠函式的 ctx 包含選用的 config、agentDir 和 workspaceDir 值，讓外掛能在第一個生命週期掛鉤執行前，初始化各代理或各工作區的狀態。

接著在設定中啟用它：

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

ContextEngine 介面

必要成員：

assemble 會傳回包含下列項目的 AssembleResult：

compact 會傳回 CompactResult。當壓縮變更目前使用中的工作階段識別資訊時，result.sessionTarget（帶有工作階段識別資訊與儲存區範圍的型別化 ContextEngineSessionTarget）會識別下一次重試或回合必須使用的後繼工作階段；result.sessionId 則會映照後繼工作階段的 id。

選用成員：

執行階段設定

在 OpenClaw 內執行的生命週期掛鉤會收到選用的 runtimeSettings 物件。它是具版本且唯讀的內部 生產者／消費者 API 介面：OpenClaw 會為所選上下文 引擎產生它，而上下文引擎會在生命週期掛鉤中使用它。它不會 直接呈現給使用者，也不會建立專用的報告介面。

• schemaVersion：目前為 1
• runtime：OpenClaw 主機、執行階段模式（normal、fallback 或 degraded），以及選用的控制框架／執行階段 id
• contextEngineSelection：所選上下文引擎 id 與選取來源
• executionHost：叫用掛鉤之介面的主機 id 與標籤
• model：要求的模型、解析後的模型、供應商，以及選用的模型系列
• limits：已知時的提示詞權杖預算與最大輸出權杖數
• diagnostics：已知時的封閉式後援與降級原因代碼

可能為未知的欄位以 null 表示；執行階段模式和選取來源等辨別欄位仍不可為 null。舊版引擎仍維持相容：如果嚴格的舊版引擎因 runtimeSettings 是未知屬性而拒絕它，OpenClaw 會在不含該屬性的情況下重試生命週期呼叫，而不是隔離該引擎。

主機需求

情境引擎可以在 info.hostRequirements 上宣告主機能力需求。OpenClaw 會在開始作業前檢查這些需求；當所選執行階段無法滿足需求時，會拒絕執行並提供描述性錯誤。

對於代理程式執行，若引擎必須透過 assemble() 控制實際的模型提示詞，請宣告 assemble-before-prompt：

info: {  id: "my-context-engine",  name: "我的情境引擎",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "請使用原生 Codex 或 OpenClaw 內嵌執行階段，或選取舊版情境引擎。",    },  },}

原生 Codex 和 OpenClaw 內嵌代理程式執行皆滿足 assemble-before-prompt。一般命令列介面後端則不滿足，因此需要此能力的引擎會在命令列介面程序啟動前遭到拒絕。

失敗隔離

OpenClaw 會將所選外掛引擎與核心回覆路徑隔離。若非舊版引擎缺失、未通過合約驗證、在建立工廠時擲回例外，或從生命週期方法擲回例外，OpenClaw 會在目前的閘道程序中隔離該引擎，並將情境引擎工作降級至內建的 legacy 引擎。錯誤會連同失敗的作業一起記錄，讓操作者可以修復、更新或停用外掛，而不會使代理程式停止回應。

主機需求失敗則有所不同：當引擎宣告執行階段缺少必要能力時，OpenClaw 會在開始執行前拒絕執行。這可保護那些若在不支援的主機中執行便會損毀狀態的引擎。

ownsCompaction

ownsCompaction 控制該次執行是否仍啟用 OpenClaw 執行階段內建的單次嘗試內自動壓縮：

這表示有兩種有效的外掛模式：

對作用中的非自主管理引擎而言，無操作的 compact() 並不安全，因為它會停用該引擎插槽的一般 /compact 與溢位復原壓縮路徑。

設定參考

{  plugins: {    slots: {      // 選取作用中的情境引擎。預設值："legacy"。      // 設為外掛 ID 以使用外掛引擎。      contextEngine: "legacy",    },  },}

與壓縮和記憶體的關係

提示

• 使用 openclaw doctor 驗證你的引擎是否正確載入。
• 切換引擎時，現有工作階段會沿用其目前的歷史記錄。新引擎會接管後續執行。
• 引擎錯誤會被記錄，且所選外掛引擎會在目前的閘道程序中遭到隔離。OpenClaw 會在使用者輪次回復使用 legacy，使回覆得以繼續，但你仍應修復、更新、停用或解除安裝故障的外掛。
• 開發時，請使用 openclaw plugins install -l ./my-engine 連結本機外掛目錄，而不進行複製。

相關內容

• 壓縮——摘要長篇對話
• 情境——如何為代理程式輪次建構情境
• 外掛架構——註冊情境引擎外掛
• 外掛資訊清單——外掛資訊清單欄位
• 外掛——外掛概覽