コンテキストエンジン

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

OpenClaw には組み込みの legacy エンジンが同梱され、デフォルトで使用されます - ほとんどのユーザーはこれを変更する必要はありません。異なるアセンブリ、Compaction、またはセッション横断の想起動作が必要な場合にのみ、Plugin エンジンをインストールして選択してください。

# クイックスタート

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 の元の動作を維持します。

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

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

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

# Plugin エンジン

Plugin は Plugin 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 値が含まれるため、Plugin は最初のライフサイクルフックが実行される前に エージェント単位またはワークスペース単位の状態を初期化できます。

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

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

# ContextEngine インターフェース

必須メンバー:

assemble は次を含む AssembleResult を返します。

compact は CompactResult を返します。Compaction がアクティブな トランスクリプトをローテーションする場合、result.sessionId と result.sessionFile は次の再試行またはターンで使用する必要がある後継セッションを識別します。

任意メンバー:

# ownsCompaction

ownsCompaction は、Pi の組み込み試行内自動 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 エンジンの登録に失敗した場合、または選択されたエンジン id を解決できない場合、OpenClaw は自動的にフォールバックしません。Plugin を修正するか、plugins.slots.contextEngine を "legacy" に戻すまで、実行は失敗します。
• 開発では、openclaw plugins install -l ./my-engine を使用して、ローカル Plugin ディレクトリをコピーせずにリンクします。

# 関連

• Compaction - 長い会話の要約
• コンテキスト - エージェントターンのコンテキストを構築する方法
• Plugin アーキテクチャ - コンテキストエンジン Plugin の登録
• Plugin マニフェスト - Plugin マニフェストのフィールド
• Plugin - Plugin の概要