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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw に、画像生成、動画生成、または将来のベンダー支援機能領域のような新しい共有ドメインが必要な場合にこれを使用します。 ルール:

• plugin = 所有権境界
• capability = 共有コアコントラクト

ベンダーをチャネルやツールに直接接続するところから始めないでください。ケイパビリティを定義するところから始めます。

​

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

次の すべて が当てはまる場合に、新しいケイパビリティを作成します。

1. 複数のベンダーがそれを実装できる可能性がある。
2. チャネル、ツール、または機能 Plugin が、ベンダーを意識せずにそれを利用できるべきである。
3. コアがフォールバック、ポリシー、設定、または配信動作を所有する必要がある。

作業がベンダー専用で、共有コントラクトがまだ存在しない場合は、いったん止めて先にコントラクトを定義してください。

​

標準的な順序

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

​

何をどこに置くか

コア:

• リクエスト/レスポンス型。
• プロバイダーレジストリと解決。
• フォールバック動作。
• ネストされたオブジェクト、ワイルドカード、配列アイテム、合成ノードに伝播された title / description ドキュメントメタデータを持つ設定スキーマ。
• ランタイムヘルパーのサーフェス。

ベンダー Plugin:

• ベンダー API 呼び出し。
• ベンダー認証処理。
• ベンダー固有のリクエスト正規化。
• ケイパビリティ実装の登録。

機能/チャネル Plugin:

• api.runtime.* または対応する plugin-sdk/*-runtime ヘルパーを呼び出す。
• ベンダー実装を直接呼び出してはならない。

​

プロバイダーとハーネスの継ぎ目

動作が汎用エージェントループではなくモデルプロバイダーコントラクトに属する場合は、プロバイダーフック を使用します。例には、トランスポート選択後のプロバイダー固有リクエストパラメーター、認証プロファイルの優先、プロンプトオーバーレイ、モデル/プロファイルのフェイルオーバー後のフォローアップフォールバックルーティングが含まれます。 動作がターンを実行しているランタイムに属する場合は、エージェントハーネスフック を使用します。ハーネスは、空、推論のみ、計画のみのレスポンスなど、成功したが使用できない試行結果を分類できるため、外側のモデルフォールバックポリシーが再試行の判断を行えます。 両方の継ぎ目は狭く保ちます。

• コアが再試行/フォールバックポリシーを所有する。
• プロバイダー 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. コアが runtime.imageGeneration.generate(...) を公開する。
4. openai、google、fal、minimax の Plugin がベンダー支援実装を登録する。
5. 将来のベンダーは、チャネル/ツールを変更せずに同じコントラクトを登録する。

設定キーは、意図的に視覚分析ルーティングとは分けられています。

• agents.defaults.imageModel は画像を分析する。
• agents.defaults.imageGenerationModel は画像を生成する。

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

​

レビューチェックリスト

新しいケイパビリティを出荷する前に、次を確認してください。

• チャネル/ツールがベンダーコードを直接インポートしていない。
• ランタイムヘルパーが共有パスである。
• 少なくとも 1 つのコントラクトテストがバンドル済み所有権をアサートしている。
• 設定ドキュメントが新しいモデル/設定キーの名前を示している。
• Plugin ドキュメントが所有権境界を説明している。

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

​

関連

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