コンテキストエンジン

コンテキストエンジンは、OpenClaw が各実行のモデルコンテキストをどのように構築するかを制御します。どのメッセージを含めるか、古い履歴をどのように要約するか、サブエージェント境界をまたいでコンテキストをどのように管理するかを扱います。

OpenClaw には組み込みの legacy エンジンが付属しており、デフォルトで使用されます。ほとんどのユーザーはこれを変更する必要はありません。異なる組み立て、コンパクション、またはセッション横断の想起動作が必要な場合にのみ、プラグインエンジンをインストールして選択してください。

クイックスタート

openclaw doctor# or inspect config directly: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", // must match the plugin's registered engine id    },    entries: {      "lossless-claw": {        enabled: true,        // Plugin-specific config goes here (see the plugin's docs)      },    },  },}

仕組み

OpenClaw がモデルプロンプトを実行するたびに、コンテキストエンジンは4つのライフサイクルポイントに関与します。

同梱の非 ACP Codex ハーネスでは、OpenClaw は組み立て済みコンテキストを Codex 開発者指示と現在のターンプロンプトに投影することで、同じライフサイクルを適用します。Codex は引き続き、ネイティブのスレッド履歴とネイティブのコンパクターを所有します。

サブエージェントのライフサイクル（任意）

OpenClaw は2つの任意のサブエージェントライフサイクルフックを呼び出します。

システムプロンプトの追加

assemble メソッドは systemPromptAddition 文字列を返せます。OpenClaw はこれを実行のシステムプロンプトの先頭に追加します。これにより、エンジンは静的なワークスペースファイルを必要とせずに、動的な想起ガイダンス、検索指示、コンテキスト認識型のヒントを注入できます。

legacy エンジン

組み込みの legacy エンジンは、OpenClaw の元の動作を保持します。

• 取り込み: 何もしません（セッションマネージャーがメッセージの永続化を直接処理します）。
• 組み立て: パススルーです（ランタイム内の既存の sanitize → validate → limit パイプラインがコンテキスト組み立てを処理します）。
• コンパクト化: 組み込みの要約コンパクションに委譲します。これは古いメッセージの単一の要約を作成し、最近のメッセージをそのまま保持します。
• ターン後: 何もしません。

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 }) {      // Store the message in your data store      return { ingested: true };    },     async assemble({ sessionId, messages, tokenBudget, availableTools, citationsMode }) {      // Return messages that fit the budget      return {        messages: buildContext(messages, tokenBudget),        estimatedTokens: countTokens(messages),        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,        }),      };    },     async compact({ sessionId, force }) {      // Summarize older context      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.sessionId と result.sessionFile は次のリトライまたはターンが使用する必要のある後継セッションを識別します。

任意メンバー:

ランタイム設定

OpenClaw 内で実行されるライフサイクルフックは、任意の runtimeSettings オブジェクトを受け取ります。これはバージョン付きの読み取り専用の内部 プロデューサー/コンシューマー API サーフェスです。OpenClaw が選択されたコンテキスト エンジン向けに生成し、コンテキストエンジンがライフサイクルフック内で消費します。これは ユーザーに直接表示されず、専用のレポートサーフェスも作成しません。

• schemaVersion: 現在は 1
• runtime: OpenClaw ホスト、ランタイムモード（normal、fallback、または degraded）、および任意のハーネス/ランタイム ID
• contextEngineSelection: 選択されたコンテキストエンジン ID と選択ソース
• executionHost: フックを呼び出しているサーフェスのホスト ID とラベル
• model: 要求されたモデル、解決済みモデル、プロバイダー、および任意のモデルファミリー
• limits: 既知の場合のプロンプトトークン予算と最大出力トークン数
• diagnostics: 既知の場合の閉じたフォールバックと劣化理由コード

不明になり得るフィールドは null として表されます。ランタイムモードや選択ソースなどの判別子フィールドは非 null のままです。古いエンジンは引き続き互換性があります。厳密な legacy エンジンが runtimeSettings を不明なプロパティとして拒否した場合、OpenClaw はエンジンを隔離する代わりに、それなしでライフサイクル呼び出しを再試行します。

ホスト要件

コンテキストエンジンは info.hostRequirements でホスト機能要件を宣言できます。 OpenClaw は操作を開始する前にこれらの要件をチェックし、選択されたランタイムが満たせない場合は説明的なエラーでフェイルクローズします。

エージェント実行では、エンジンが assemble() を通じて実際のモデルプロンプトを制御する必要がある場合、assemble-before-prompt を宣言します。

info: {  id: "my-context-engine",  name: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "Use the native Codex or OpenClaw embedded runtime, or select the legacy context engine.",    },  },}

ネイティブ Codex と OpenClaw 埋め込みエージェント実行は assemble-before-prompt を満たします。 汎用 CLI バックエンドは満たさないため、それを要求するエンジンは CLI プロセスの開始前に拒否されます。

障害の分離

OpenClaw は、選択された Plugin エンジンをコアの返信パスから分離します。非 legacy エンジンが見つからない、コントラクト検証に失敗する、ファクトリ作成中に例外を投げる、またはライフサイクルメソッドから例外を投げる場合、OpenClaw は現在の Gateway プロセスでそのエンジンを隔離し、コンテキストエンジン処理を組み込みの legacy エンジンにダウングレードします。エラーは失敗した操作とともにログに記録されるため、オペレーターはエージェントが応答しなくなることなく、Plugin を修復、更新、または無効化できます。

ホスト要件の失敗は異なります。エンジンが、ランタイムに必要な機能がないと宣言した場合、OpenClaw は実行を開始する前にフェイルクローズします。これにより、サポートされていないホストで実行すると状態を破損するエンジンを保護します。

ownsCompaction

ownsCompaction は、OpenClaw ランタイム組み込みの試行内自動 Compaction を、その実行で有効なままにするかどうかを制御します。

つまり、有効な Plugin パターンは 2 つあります。

no-op の compact() は、アクティブな非所有エンジンでは安全ではありません。そのエンジンスロットの通常の /compact とオーバーフロー回復 Compaction パスを無効化してしまうためです。

設定リファレンス

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

Compaction とメモリとの関係

ヒント

• openclaw doctor を使用して、エンジンが正しくロードされていることを確認します。
• エンジンを切り替える場合、既存のセッションは現在の履歴のまま続行されます。新しいエンジンは将来の実行から引き継ぎます。
• エンジンエラーはログに記録され、選択された Plugin エンジンは現在の Gateway プロセスで隔離されます。返信を継続できるよう、OpenClaw はユーザーターンで legacy にフォールバックしますが、それでも壊れた Plugin を修復、更新、無効化、またはアンインストールする必要があります。
• 開発では、コピーせずにローカル Plugin ディレクトリをリンクするために openclaw plugins install -l ./my-engine を使用します。

関連

• Compaction - 長い会話の要約
• コンテキスト - エージェントターンのコンテキストがどのように構築されるか
• Plugin アーキテクチャ - コンテキストエンジン Plugin の登録
• Plugin マニフェスト - Plugin マニフェストフィールド
• Plugin - Plugin の概要