---
read_when:
    - 新しいコア機能とPlugin登録インターフェースの追加
    - コードをコア、ベンダーPlugin、機能Pluginのどこに配置するかの判断
    - チャネルまたはツール向けの新しいランタイムヘルパーの接続
sidebarTitle: Adding capabilities
summary: OpenClaw Pluginシステムに新しい共有機能を追加するためのコントリビューターガイド
title: 機能の追加（コントリビューターガイド）
x-i18n:
    generated_at: "2026-07-11T22:24:32Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 3534b7521ab8183d91399cded8a3b397be46bf9bd18f2fdb88a8947bad67ffaa
    source_path: plugins/adding-capabilities.md
    workflow: 16
---

<Info>
  これは OpenClaw コア開発者向けの**コントリビューターガイド**です。外部 Plugin を
  構築する場合は、代わりに[Plugin の構築](/ja-JP/plugins/building-plugins)を参照してください。
  詳細なアーキテクチャリファレンス（ケイパビリティモデル、所有権、
  読み込みパイプライン、ランタイムヘルパー）については、[Plugin の内部構造](/ja-JP/plugins/architecture)を参照してください。
</Info>

OpenClaw に、埋め込み、画像生成、動画生成、将来のベンダー提供機能領域などの新しい共有ドメインが必要な場合に使用します。

原則：

- **Plugin** = 所有権の境界
- **ケイパビリティ** = 共有コアコントラクト

ベンダーをチャンネルやツールに直接接続しないでください。まずケイパビリティを定義します。

## ケイパビリティを作成する条件

以下の条件を**すべて**満たす場合にのみ、新しいケイパビリティを作成します。

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. コアが `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 の内部構造](/ja-JP/plugins/architecture) — ケイパビリティモデル、所有権、読み込みパイプライン、ランタイムヘルパー。
- [Plugin の構築](/ja-JP/plugins/building-plugins) — 最初の Plugin のチュートリアル。
- [SDK の概要](/ja-JP/plugins/sdk-overview) — インポートマップと登録 API のリファレンス。
- [Skills の作成](/ja-JP/tools/creating-skills) — 関連するコントリビューター向けサーフェス。