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

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

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

​
標準的な手順

  1. 型付きのコア契約を定義する。
  2. その契約のプラグイン登録を追加する。
  3. 共有ランタイムヘルパーを追加する。
  4. 実証として 1 つの実ベンダープラグインを配線する。
  5. 機能/チャンネルの利用側をランタイムヘルパーに移行する。
  6. 契約テストを追加する。
  7. オペレーター向けの設定と所有権モデルを文書化する。

​
何をどこに置くか

レイヤー所有するもの
コアリクエスト/レスポンス型、プロバイダーレジストリと解決、フォールバック動作、ネストされたオブジェクト、ワイルドカード、配列項目、合成ノードに伝播される title/description ドキュメントメタデータを含む設定スキーマ、ランタイムヘルパーサーフェス。
ベンダープラグインベンダー API 呼び出し、ベンダー認証処理、ベンダー固有のリクエスト正規化、ケイパビリティ実装の登録。
機能/チャンネルプラグインapi.runtime.* または対応する plugin-sdk/*-runtime ヘルパーを呼び出す。ベンダー実装を直接呼び出してはいけません。

​
プロバイダーとハーネスの接合部

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

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

新しいケイパビリティでは、次の領域に触れることを想定してください。
  • 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 つ以上のバンドル済みプラグインパッケージ。
  • 設定、ドキュメント、テスト。

​
実例: 画像生成

画像生成は標準的な形に従います。
  1. コアが ImageGenerationProvider を定義する。
  2. コアが registerImageGenerationProvider(...) を公開する。
  3. コアが api.runtime.imageGeneration.generate(...) と .listProviders(...) を公開する。
  4. ベンダープラグイン（comfy, deepinfra, fal, google, litellm, microsoft-foundry, minimax, openai, openrouter, vydra, xai）がベンダー支援の実装を登録する。
  5. 将来のベンダーは、チャンネル/ツールを変更せずに同じ契約を登録する。
設定キーは、意図的にビジョン分析ルーティングとは分離されています。
  • agents.defaults.imageModel は画像を分析します。
  • agents.defaults.imageGenerationModel は画像を生成します。
フォールバックとポリシーを明示的なままにするため、これらを分離しておきます。

​
埋め込みプロバイダー

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

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

新しいケイパビリティを出荷する前に、次を確認します。
  • チャンネル/ツールがベンダーコードを直接インポートしていない。
  • ランタイムヘルパーが共有パスである。
  • 少なくとも 1 つの契約テストがバンドル済みの所有権を検証している。
  • 設定ドキュメントが新しいモデル/設定キーの名前を示している。
  • Plugin ドキュメントが所有権の境界を説明している。
PR がケイパビリティ層を省略し、ベンダー動作をチャンネル/ツールにハードコードしている場合は、差し戻して先に契約を定義してください。

​
関連

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