機能の追加（コントリビューターガイド）

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.imageGenerationModel は画像を生成する。

フォールバックとポリシーを明示的に保つため、両者を分離してください。

埋め込みプロバイダー

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

以前のメモリ固有の登録 API と memoryEmbeddingProviders コントラクトは非推奨です。すべての新しい埋め込みプロバイダーでは、registerEmbeddingProvider と embeddingProviders を使用してください。

レビューチェックリスト

新しいケイパビリティをリリースする前に、以下を確認してください。

• チャンネル／ツールがベンダーコードを直接インポートしていない。
• ランタイムヘルパーが共有経路になっている。
• 少なくとも 1 つのコントラクトテストでバンドル済みの所有権を検証している。
• 設定ドキュメントに新しいモデル／設定キーが記載されている。
• Plugin ドキュメントで所有権の境界が説明されている。

PR がケイパビリティレイヤーを省略し、ベンダー動作をチャンネル／ツールにハードコードしている場合は、差し戻して最初にコントラクトを定義してください。

関連項目

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