OpenClaw ContextEngineプラグイン開発ガイド｜完全解説

⚡ 3秒でわかる！この記事のポイント

ContextEngineプラグインでエージェントに動的なコンテキストを注入可能
v2026.3.7で導入された新インターフェースにより開発が大幅に簡素化
外部ナレッジベース連携やユーザープロファイル切替が実装できる

「OpenClawのエージェントに社内ドキュメントの知識を持たせたい」「ユーザーごとに異なるコンテキストを動的に切り替えたい」

こうしたニーズに応えるのが、OpenClawのContextEngineプラグインです。エージェントのシステムプロンプトに動的なコンテキストを注入するこの仕組みにより、汎用エージェントを特定ドメインに特化させることが可能になります。

この記事では、OpenClaw完全攻略シリーズEp.16として、ContextEngineプラグインの開発方法と実践的な活用パターンを解説します。

この記事でわかること

ContextEngineプラグインの仕組みと役割
プラグインのアーキテクチャとライフサイクル
カスタムプラグインの実装手順
外部ナレッジベース連携の実装例
最新モデル対応のポイント

ContextEngineプラグインとは

OpenClawのコンテキスト管理の仕組み

OpenClawのエージェントは、セッション開始時に複数のコンテキストソースからシステムプロンプトを構築します。

システムプロンプト構築フロー:
1. SOUL.md（エージェントの人格・トーン）
2. AGENTS.md（ワークスペースルール）
3. USER.md（ユーザー情報）
4. TOOLS.md（ツール設定）
5. [ContextEngineプラグイン] ← ここに動的コンテキストを注入
6. メッセージ履歴

ContextEngineプラグインは、このフローの中で動的なコンテキストを注入するポイントとして機能します。静的なファイル（SOUL.md等）だけでは対応できない、リアルタイムな情報や外部データソースからの知識を、エージェントに提供できます。

v2026.3.7で導入された新インターフェース

従来のOpenClawでもコンテキスト注入は可能でしたが、仕組みが複雑でした。v2026.3.7で導入されたContextEngine Plugin Interfaceにより、標準化されたAPIでプラグインを開発できるようになりました。

主な改善点：

TypeScript型定義の提供: 型安全なプラグイン開発が可能
ライフサイクルフックの充実: 初期化・セッション開始・メッセージ処理等のフックを提供
優先度制御: 複数プラグインの実行順序を制御可能
キャッシュ機構: コンテキスト生成のパフォーマンスを最適化

ContextEngineプラグインのアーキテクチャ

プラグインのライフサイクル

ContextEngineプラグインは、以下のライフサイクルで動作します。

1. init()        → プラグイン初期化（DB接続、API認証等）
2. onSession()   → セッション開始時のコンテキスト生成
3. onMessage()   → メッセージ受信時のコンテキスト更新（オプション）
4. onHeartbeat() → ハートビート時のコンテキスト更新（オプション）
5. destroy()     → プラグイン終了時のクリーンアップ

最も重要なのは onSession() フックで、セッション開始時にエージェントに渡すコンテキストを生成する役割を担います。

コンテキスト注入のタイミングと優先度

複数のContextEngineプラグインが登録されている場合、**優先度（priority）**に基づいて実行順序が決定されます。

// 優先度の低い数値ほど先に実行される
export const pluginConfig = {
  name: 'my-context-plugin',
  priority: 100, // デフォルトは100
  maxTokens: 2000, // このプラグインが使用する最大トークン数
};

トークン予算の管理も重要です。各プラグインは maxTokens でコンテキストサイズの上限を宣言し、OpenClawのコンテキストマネージャーが全体のトークンバジェット内で配分します。

カスタムContextEngineプラグインの作成

プロジェクト構成とboilerplate

ContextEngineプラグインのプロジェクト構成は以下の通りです。

my-context-plugin/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts        # プラグインエントリポイント
│   └── provider.ts     # コンテキストプロバイダー実装
└── tests/
    └── provider.test.ts

package.json の設定：

{
  "name": "openclaw-context-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "openclaw": {
    "type": "context-engine",
    "version": "1.0"
  },
  "dependencies": {
    "@openclaw/plugin-sdk": "^2026.3.0"
  }
}

コンテキストプロバイダーの実装

基本的なプラグインの実装例：

// src/index.ts
import { ContextEnginePlugin, SessionContext } from '@openclaw/plugin-sdk';

export default class MyContextPlugin implements ContextEnginePlugin {
  name = 'my-context-plugin';
  priority = 100;
  maxTokens = 2000;

  async init(): Promise<void> {
    // DB接続やAPI認証の初期化
    console.log('MyContextPlugin initialized');
  }

  async onSession(ctx: SessionContext): Promise<string> {
    // セッション開始時のコンテキスト生成
    const userProfile = await this.fetchUserProfile(ctx.userId);
    const relevantDocs = await this.searchKnowledgeBase(ctx.recentMessages);

    return `
## ユーザープロファイル
${userProfile}

## 関連ドキュメント
${relevantDocs}
    `.trim();
  }

  async onMessage(ctx: SessionContext): Promise<string | null> {
    // メッセージ受信時の追加コンテキスト（オプション）
    return null; // 更新不要な場合はnullを返す
  }

  async destroy(): Promise<void> {
    // クリーンアップ処理
  }

  private async fetchUserProfile(userId: string): Promise<string> {
    // ユーザープロファイルの取得ロジック
    return `ユーザーID: ${userId}`;
  }

  private async searchKnowledgeBase(messages: string[]): Promise<string> {
    // ナレッジベース検索ロジック
    return '関連ドキュメントなし';
  }
}

テストとデバッグ

OpenClaw Plugin SDKにはテストユーティリティが含まれており、プラグインの動作を簡単にテストできます。

// tests/provider.test.ts
import { createTestContext } from '@openclaw/plugin-sdk/testing';
import MyContextPlugin from '../src/index';

describe('MyContextPlugin', () => {
  it('should generate context on session start', async () => {
    const plugin = new MyContextPlugin();
    await plugin.init();

    const ctx = createTestContext({
      userId: 'test-user',
      recentMessages: ['プロジェクトの進捗を教えて'],
    });

    const context = await plugin.onSession(ctx);
    expect(context).toContain('ユーザーID: test-user');
  });
});

プラグインのデバッグには、OpenClawのログ機能が利用できます。

# プラグインのデバッグログを有効化
OPENCLAW_LOG_LEVEL=debug openclaw gateway start

実践ユースケース

外部ナレッジベースの動的注入

最も一般的なユースケースが、社内ドキュメントやFAQをエージェントに動的に注入するパターンです。

async onSession(ctx: SessionContext): Promise<string> {
  // ユーザーの最新メッセージに基づいてベクトル検索
  const query = ctx.recentMessages[ctx.recentMessages.length - 1];
  const results = await this.vectorDB.search(query, { limit: 5 });

  return results.map(doc =>
    `### ${doc.title}\n${doc.content}`
  ).join('\n\n');
}

このパターンにより、エージェントは常に最新の社内情報を参照しながら回答できるようになります。SES現場では、プロジェクト固有のドキュメントや仕様書をエージェントに持たせることで、オンボーディングの効率化にも活用できます。

ユーザープロファイルに基づくコンテキスト切替

マルチユーザー環境では、ユーザーの属性や権限に基づいてコンテキストを切り替えることが重要です。

async onSession(ctx: SessionContext): Promise<string> {
  const user = await this.userDB.findById(ctx.userId);

  if (user.role === 'admin') {
    return '管理者権限でアクセスしています。すべての機能が利用可能です。';
  } else if (user.role === 'developer') {
    return `開発者としてアクセス中。担当プロジェクト: ${user.projects.join(', ')}`;
  }
  return 'ゲストとしてアクセス中。閲覧のみ可能です。';
}

GPT-5.4 / Gemini 3.1 Flash対応のポイント

最新のLLMモデルでContextEngineプラグインを最大限活用するためのポイントを紹介します。

トークンバジェットの最適化: GPT-5.4やGemini 3.1 Flashはコンテキストウィンドウが大きいが、コストとのバランスを考慮
構造化コンテキスト: XMLタグやMarkdown見出しで構造化すると、モデルの理解精度が向上
必要最小限の原則: 多すぎるコンテキストは逆効果。関連性の高い情報に絞る

出典: OpenClaw公式ドキュメント「ContextEngine Plugin Development Guide」（v2026.3.7）に基づいた解説です。

まとめ：ContextEngineでエージェントの知識を拡張する

ContextEngineプラグインは、OpenClawエージェントの知識と能力を無限に拡張できる強力な仕組みです。

活用のステップ

まずはシンプルなプラグインで仕組みを理解する
社内ドキュメントの検索機能を実装してみる
ユーザーごとのコンテキスト切替を追加する
パフォーマンスを最適化してプロダクション投入

ContextEngineプラグインを活用することで、汎用AIエージェントを自社専用のドメインエキスパートに変えることができます。

関連記事: