情境引擎

上下文引擎控制 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 引擎會保留 OpenClaw 的原始行為：

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

舊版引擎不會註冊工具，也不提供 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,          agentSessionKey: sessionKey,        }),      };    },     async compact({ sessionId, force }) {      // 摘要較舊的上下文      return { ok: true, compacted: true };    },  }));}

工廠函式 ctx 包含選用的 config、agentDir 和 workspaceDir 值，讓外掛能在第一次生命週期呼叫前初始化每個代理或每個工作區的狀態。在非舊版 assemble() 呼叫前，主機會完成 已註冊的非同步記憶提示準備。同步 buildMemorySystemPromptAddition(...) 輔助函式會讀取該不可變的執行快照； 請原封不動地傳遞所提供的工具、引用、代理和工作階段上下文。

接著在設定中啟用：

{  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 連結本機外掛目錄，無須複製。

相關內容

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