コンテキストエンジン

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

OpenClaw には組み込みの legacy エンジンが付属し、デフォルトで使用されます。アセンブリ、Compaction、またはセッションをまたぐ記憶の動作を変更したい場合にのみ、Plugin エンジンをインストールして選択してください。

クイックスタート

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", // Plugin に登録されたエンジン ID と一致する必要があります    },    entries: {      "lossless-claw": {        enabled: true,        // Plugin 固有の設定をここに記述します（Plugin のドキュメントを参照）      },    },  },}

仕組み

OpenClaw がモデルプロンプトを実行するたびに、コンテキストエンジンはライフサイクルの4つの時点で処理に参加します。

エンジンは、ブートストラップ後、ターンの正常完了後、または Compaction 後にトランスクリプトを保守するための任意の maintain() メソッドも実装できます（runtimeContext.rewriteTranscriptEntries() を介した安全な書き換え）。応答をブロックせず遅延処理として実行するには、info.turnMaintenanceMode: "background" を設定します。

バンドルされた非 ACP Codex ハーネスでは、OpenClaw はアセンブル済みコンテキストを Codex の開発者向け指示と現在のターンのプロンプトへ投影することで、同じライフサイクルを適用します。Codex は引き続き、ネイティブのスレッド履歴とネイティブのコンパクターを管理します。

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

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

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

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

レガシーエンジン

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

• 取り込み：何もしません（セッションマネージャーがメッセージの永続化を直接処理します）。
• アセンブル：そのまま渡します（ランタイム内の既存のサニタイズ → 検証 → 制限パイプラインがコンテキストのアセンブリを処理します）。
• Compact：組み込みの要約 Compaction に委譲します。これは古いメッセージの単一の要約を作成し、最近のメッセージをそのまま維持します。
• ターン後：何もしません。

レガシーエンジンはツールを登録せず、systemPromptAddition も提供しません。

plugins.slots.contextEngine が設定されていない場合（または "legacy" に設定されている場合）、このエンジンが自動的に使用されます。

Plugin エンジン

Plugin API を使用して、Plugin からコンテキストエンジンを登録できます。

 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 の値が含まれるため、Plugin は最初のライフサイクル呼び出し前に、エージェント単位またはワークスペース単位の状態を初期化できます。 非レガシーの assemble() 呼び出しの前に、ホストは登録済みの非同期メモリプロンプト準備を完了します。 同期の buildMemorySystemPromptAddition(...) ヘルパーは、その不変の実行スナップショットを読み取ります。 提供されたツール、引用、エージェント、およびセッションのコンテキストは変更せずに渡してください。

次に、設定で有効にします。

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

ContextEngine インターフェース

必須メンバー：

assemble は、次の内容を持つ AssembleResult を返します。

compact は CompactResult を返します。Compaction によってアクティブなセッション ID が変わる場合、result.sessionTarget（セッション ID とストアのスコープを保持する型付きの 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: "My Context Engine",  hostRequirements: {    "agent-run": {      requiredCapabilities: ["assemble-before-prompt"],      unsupportedMessage:        "ネイティブ Codex または OpenClaw 組み込みランタイムを使用するか、レガシーコンテキストエンジンを選択してください。",    },  },}

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

障害の分離

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

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

ownsCompaction

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

したがって、有効な Plugin パターンは 2 つあります。

何もしない compact() は、アクティブな非所有エンジンでは安全ではありません。そのエンジンスロットの通常の /compact およびオーバーフロー回復 Compaction パスが無効になるためです。

設定リファレンス

{  plugins: {    slots: {      // アクティブなコンテキストエンジンを選択します。デフォルト: "legacy"。      // Plugin エンジンを使用するには、Plugin ID を設定します。      contextEngine: "legacy",    },  },}

Compaction およびメモリとの関係

ヒント

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

関連項目

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