OpenClaw コンテキストエンジンの設定方法：カスタムプラグイン導入ガイド

AIとの長い会話を続けていると、モデルが前の内容を忘れてしまったり、トークン制限に達してエラーになったりすること、ありますよね。コンテキストの管理は、開発者にとって常に悩みの種です。

OpenClawでは、この重要なプロセスを「Context Engine」という仕組みでスマートに制御できます。モデルに何を伝え、古い履歴をどう要約するか、その司令塔となるのがこのエンジンです。

Context Engine

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

OpenClawには標準で legacy エンジンが組み込まれています。プラグインを使用することで、アクティブなContext Engineのライフサイクルを置き換える別のエンジンを登録することも可能です。

クイックスタート

現在どのエンジンがアクティブかを確認するには、以下のコマンドを実行します。

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

Context Engine プラグインのインストール

Context Engine プラグインのインストール方法は、他の OpenClaw プラグインと同じです。まずインストールを行い、次にスロットでそのエンジンを選択します。

# 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" に設定するか、キー自体を削除してください（デフォルトは "legacy" です）。

仕組み

OpenClaw がモデルのプロンプトを実行するたびに、Context Engine は以下の 4 つのライフサイクルポイントで動作します。

1. Ingest — 新しいメッセージがセッションに追加されたときに呼び出されます。エンジンはメッセージを独自のデータストアに保存したり、インデックスを作成したりできます。
2. Assemble — 各モデルの実行前に呼び出されます。エンジンは、トークン予算内に収まるように整理されたメッセージセット（およびオプションの systemPromptAddition）を返します。
3. Compact — コンテキストウィンドウがいっぱいになったとき、またはユーザーが /compact を実行したときに呼び出されます。エンジンは古い履歴を要約してスペースを確保します。
4. After turn — 実行が完了した後に呼び出されます。エンジンは状態を保存したり、バックグラウンドでの Compaction をトリガーしたり、インデックスを更新したりできます。

サブエージェントのライフサイクル（オプション）

現在、OpenClaw は 1 つのサブエージェント・ライフサイクル・フックを呼び出します。

• onSubagentEnded — サブエージェントのセッションが完了したとき、または破棄されたときにクリーンアップを行います。

prepareSubagentSpawn フックは将来的な使用のためにインターフェースに含まれていますが、現在のランタイムではまだ呼び出されません。

System prompt addition

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

レガシーエンジン

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

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

レガシーエンジンはツールを登録したり、systemPromptAddition を提供したりすることはありません。

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

プラグインエンジン

プラグインは、プラグイン 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)	メソッド	モデル実行用のコンテキストを構築する（AssembleResult を返す）
compact(params)	メソッド	コンテキストを要約・削減する

assemble は以下の内容を含む AssembleResult を返します。

• messages — モデルに送信される整理されたメッセージ。
• estimatedTokens（必須、number） — 組み立てられたコンテキスト内の合計トークン数の推定値。OpenClaw はこれを Compaction のしきい値判定や診断レポートに使用します。
• systemPromptAddition（オプション、string） — システムプロンプトの先頭に付加される文字列。

オプションのメンバー：

メンバー	種類	目的
bootstrap(params)	メソッド	セッションのエンジン状態を初期化する。エンジンが最初にセッションを認識したとき（履歴のインポート時など）に一度だけ呼び出される。
ingestBatch(params)	メソッド	完了したターンをバッチとして取り込む。実行完了後、そのターンのすべてのメッセージを一度に渡して呼び出される。
afterTurn(params)	メソッド	実行後のライフサイクル処理（状態の保存、バックグラウンド Compaction のトリガーなど）。
prepareSubagentSpawn(params)	メソッド	子セッション用の共有状態をセットアップする。
onSubagentEnded(params)	メソッド	サブエージェント終了後のクリーンアップ。
dispose()	メソッド	リソースを解放する。Gateway のシャットダウン時やプラグインのリロード時に呼び出される（セッションごとではない）。

ownsCompaction

ownsCompaction は、実行中に Pi の組み込み自動 Compaction を有効のままにするかどうかを制御します。

• true — エンジンが Compaction の動作を所有します。OpenClaw はその実行において Pi の組み込み自動 Compaction を無効にします。エンジンの compact() 実装が、/compact、オーバーフロー回復のための Compaction、および afterTurn() で行いたいプロアクティブな Compaction に責任を持ちます。
• false または未設定 — プロンプト実行中に Pi の組み込み自動 Compaction が実行される可能性がありますが、アクティブなエンジンの compact() メソッドも /compact やオーバーフロー回復のために呼び出されます。

ownsCompaction: false は、OpenClaw が自動的にレガシーエンジンの Compaction パスにフォールバックすることを意味するわけではありません。

つまり、プラグインには 2 つの有効なパターンがあります。

• 所有モード (Owning mode) — 独自の Compaction アルゴリズムを実装し、ownsCompaction: true に設定します。
• 委譲モード (Delegating mode) — ownsCompaction: false に設定し、compact() 内で openclaw/plugin-sdk/core の delegateCompactionToRuntime(...) を呼び出して、OpenClaw 組み込みの Compaction 動作を使用します。

アクティブな非所有エンジンにおいて、何もしない compact() を実装するのは安全ではありません。そのエンジンスロットに対する通常の /compact やオーバーフロー回復パスが無効になってしまうからです。

設定リファレンス

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

このスロットは実行時に排他的です。特定の実行または Compaction 操作に対して、登録された Context Engine は 1 つだけ解決されます。他の有効な kind: "context-engine" プラグインも登録コードをロードして実行することは可能ですが、plugins.slots.contextEngine は、OpenClaw が Context Engine を必要とするときにどの登録済みエンジン ID を解決するかを選択するだけです。

Compaction と Memory との関係

• Compaction は Context Engine の責任の 1 つです。レガシーエンジンは OpenClaw 組み込みの要約機能に委譲します。プラグインエンジンは、任意の Compaction 戦略（DAG 要約、ベクトル検索など）を実装できます。
• Memory プラグイン (plugins.slots.memory) は Context Engine とは別物です。Memory プラグインは検索・取得機能を提供し、Context Engine はモデルが何を見るかを制御します。これらは連携可能です。例えば、Context Engine が組み立て（Assemble）時に Memory プラグインのデータを使用するといった具合です。
• セッションのプルーニング（メモリ内の古いツール実行結果のトリミング）は、どの Context Engine がアクティブであっても実行されます。

ヒント

• openclaw doctor を使用して、エンジンが正しくロードされているか確認しましょう。
• エンジンを切り替えても、既存のセッションは現在の履歴を保持したまま継続されます。新しいエンジンは、それ以降の実行から処理を引き継ぎます。
• エンジンのエラーはログに記録され、診断情報に表示されます。プラグインエンジンの登録に失敗したり、選択したエンジン ID が解決できなかったりした場合、OpenClaw は自動的にフォールバックしません。プラグインを修正するか、plugins.slots.contextEngine を "legacy" に戻すまで、実行は失敗します。
• 開発時は、openclaw plugins install -l ./my-engine を使用して、コピーせずにローカルのプラグインディレクトリをリンクするのが便利です。

こちらのドキュメントも参考にしてください：Compaction, Context, Plugins, Plugin manifest

関連情報

• Context — エージェントのターンでコンテキストがどのように構築されるか
• Plugin Architecture — Context Engine プラグインの登録方法
• Compaction — 長い会話の要約について

次のステップ

さらに詳しく知りたい場合は、以下のリンクもチェックしてみてください。

• AI Setup Assistant
• Context の概念
• Compaction の詳細