Skip to main content
これは OpenClaw コア開発者向けの コントリビューターガイド です。外部 Plugin を 構築する場合は、代わりに Plugin の構築を参照してください。 詳細なアーキテクチャリファレンス（ケイパビリティモデル、所有権、 読み込みパイプライン、ランタイムヘルパー）については、Plugin の内部構造を参照してください。
OpenClaw に、埋め込み、画像生成、動画生成、将来のベンダー依存の機能領域など、新しい共有ドメインが必要な場合に使用します。 ルール：
  • Plugin = 所有権の境界
  • ケイパビリティ = 共有コアコントラクト
ベンダーをチャンネルやツールに直接接続しないでください。まずケイパビリティを定義します。

​
ケイパビリティを作成するタイミング

次の条件を すべて 満たす場合にのみ、新しいケイパビリティを作成します：
  1. 複数のベンダーが実装できる可能性が十分にある。
  2. チャンネル、ツール、または機能 Plugin が、ベンダーを意識せずに利用できる必要がある。
  3. フォールバック、ポリシー、設定、または配信動作をコアが所有する必要がある。
作業がベンダー固有で、共有コントラクトがまだ存在しない場合は、まずコントラクトを定義します。

​
標準的な手順

  1. 型付きコアコントラクトを定義する。
  2. そのコントラクトの Plugin 登録を追加する。
  3. 共有ランタイムヘルパーを追加する。
  4. 実証として、実際のベンダー Plugin を 1 つ接続する。
  5. 機能やチャンネルのコンシューマーをランタイムヘルパーへ移行する。
  6. コントラクトテストを追加する。
  7. オペレーター向けの設定と所有権モデルを文書化する。

​
各レイヤーの役割

​
プロバイダーとハーネスの接続点

動作が汎用エージェントループではなく、モデルプロバイダーのコントラクトに属する場合は、プロバイダーフックを使用します。たとえば、トランスポート選択後のプロバイダー固有のリクエストパラメーター、認証プロファイルの優先設定、プロンプトオーバーレイ、モデル／プロファイルのフェイルオーバー後の後続フォールバックルーティングなどです。 動作がターンを実行するランタイムに属する場合は、エージェントハーネスフックを使用します。ハーネスは、出力なし、表示可能な出力を伴わない推論、最終回答のない構造化プランなど、明示的なプロトコル結果を分類できるため、外側のモデルフォールバックポリシーが再試行を判断できます。 どちらの接続点も限定的に保ちます：
  • コアは再試行／フォールバックポリシーを所有する。
  • プロバイダー Plugin は、プロバイダー固有のリクエスト／認証／ルーティングのヒントを所有する。
  • ハーネス Plugin は、ランタイム固有の試行分類を所有する。
  • サードパーティー Plugin は、コア状態を直接変更するのではなく、ヒントを返す。

​
ファイルチェックリスト

新しいケイパビリティでは、次の領域を変更することになります：
  • src/<capability>/types.ts
  • src/<capability>/...registry/runtime.ts
  • src/plugins/types.ts
  • src/plugins/registry.ts
  • src/plugins/captured-registration.ts
  • src/plugins/contracts/registry.ts
  • src/plugins/runtime/types-core.ts
  • src/plugins/runtime/index.ts
  • src/plugin-sdk/<capability>.ts
  • src/plugin-sdk/<capability>-runtime.ts
  • 1 つ以上のバンドルされた Plugin パッケージ。
  • 設定、ドキュメント、テスト。

​
実例：画像生成

画像生成は標準的な構成に従います：
  1. コアが ImageGenerationProvider を定義する。
  2. コアが registerImageGenerationProvider(...) を公開する。
  3. コアが api.runtime.imageGeneration.generate(...) と .listProviders(...) を公開する。
  4. ベンダー Plugin（comfy、deepinfra、fal、google、litellm、microsoft-foundry、minimax、openai、openrouter、vydra、xai）が、ベンダー依存の実装を登録する。
  5. 将来のベンダーは、チャンネルやツールを変更せずに同じコントラクトを登録する。
設定キーは、意図的に画像解析のルーティングとは分離されています：
  • agents.defaults.imageModel は画像を解析する。
  • agents.defaults.mediaModels.image は画像を生成する。
フォールバックとポリシーを明示的に保つため、これらを分離してください。

​
埋め込みプロバイダー

再利用可能なベクトル埋め込みプロバイダーには、registerEmbeddingProvider(...)／コントラクト embeddingProviders を使用します。このコントラクトは意図的にメモリよりも広い範囲を対象としています。ツール、検索、取得、インポーター、将来の機能 Plugin は、メモリエンジンに依存せずに埋め込みを利用できます。メモリ検索も汎用の embeddingProviders を利用します。 以前のメモリ固有の登録 API と memoryEmbeddingProviders コントラクトは非推奨です。新しいすべての埋め込みプロバイダーには、registerEmbeddingProvider と embeddingProviders を使用してください。

​
レビューチェックリスト

新しいケイパビリティをリリースする前に、次を確認します：
  • チャンネル／ツールがベンダーコードを直接インポートしていない。
  • ランタイムヘルパーが共有パスになっている。
  • 少なくとも 1 つのコントラクトテストで、バンドルされた実装の所有権を検証している。
  • 設定ドキュメントに新しいモデル／設定キーが記載されている。
  • Plugin のドキュメントで所有権の境界が説明されている。
PR がケイパビリティレイヤーを省略し、ベンダーの動作をチャンネル／ツールにハードコードしている場合は、差し戻して、まずコントラクトを定義してください。

​
関連項目

  • Plugin の内部構造 — ケイパビリティモデル、所有権、読み込みパイプライン、ランタイムヘルパー。
  • Plugin の構築 — 最初の Plugin のチュートリアル。
  • SDK の概要 — インポートマップと登録 API のリファレンス。
  • Skills の作成 — 関連するコントリビューター向けサーフェス。