​

プラグイン内部

​

公開ケイパビリティモデル

​

外部互換性に関する方針

• 既存の外部プラグイン: フックベースの統合を動作させ続けること。 これを互換性のベースラインとして扱います
• 新しいバンドル済み / ネイティブプラグイン: ベンダー固有の直接参照や 新しいhook-only設計よりも、明示的なケイパビリティ登録を優先します
• ケイパビリティ登録を採用する外部プラグイン: 許可されますが、 ドキュメントでコントラクトが安定していると明示されない限り、 ケイパビリティ固有のヘルパーサーフェスは進化中のものとして扱ってください

• ケイパビリティ登録APIは意図された方向性です
• レガシーフックは、移行期間中の外部プラグインにとって 破壊的変更を避ける最も安全な経路のままです
• exportされたヘルパーsubpathはすべて同等ではありません。 偶発的なヘルパーexportではなく、狭く文書化された コントラクトを優先してください

​

プラグインの形状

• plain-capability — ちょうど1つのケイパビリティ種別だけを登録します（たとえば mistralのようなプロバイダー専用プラグイン）
• hybrid-capability — 複数のケイパビリティ種別を登録します（たとえば openaiはテキスト推論、音声、メディア理解、画像 生成を所有します）
• hook-only — フックのみを登録し（型付きまたはカスタム）、 ケイパビリティ、ツール、コマンド、サービスは登録しません
• non-capability — ツール、コマンド、サービス、またはルートを登録しますが、 ケイパビリティは登録しません

​

レガシーフック

• 動作させ続ける
• レガシーとして文書化する
• モデル / プロバイダーのオーバーライド作業にはbefore_model_resolveを優先する
• プロンプト変更作業にはbefore_prompt_buildを優先する
• 実際の利用が減り、フィクスチャカバレッジが移行の安全性を証明した後にのみ削除する

​

互換性シグナル

​

アーキテクチャ概要

1. マニフェスト + 検出 OpenClawは、設定されたパス、ワークスペースルート、 グローバル拡張ルート、およびバンドル済み拡張から候補プラグインを見つけます。 検出では、まずネイティブopenclaw.plugin.jsonマニフェストと、サポートされたバンドルマニフェストを読み込みます。
2. 有効化 + 検証 コアは、検出されたプラグインが有効、無効、ブロック済み、 またはメモリーのような排他的スロットに選択されたものかを決定します。
3. ランタイム読み込み ネイティブOpenClawプラグインは、jitiを介してプロセス内で読み込まれ、 中央レジストリにケイパビリティを登録します。互換性のあるバンドルは、 ランタイムコードをimportせずにレジストリレコードへ正規化されます。
4. サーフェス消費 OpenClawの他の部分はレジストリを読んで、ツール、チャネル、プロバイダー セットアップ、フック、HTTPルート、CLIコマンド、およびサービスを公開します。

• parse時メタデータはregisterCli(..., { descriptors: [...] })から取得されます
• 実際のプラグインCLIモジュールは遅延のままにでき、最初の呼び出し時に登録できます

• 検出 + config検証は、プラグインコードを実行せずに manifest/schemaメタデータから機能するべきです
• ネイティブのランタイム挙動は、プラグインモジュールのregister(api)経路から来ます

​

チャネルプラグインと共有messageツール

• コアは共有messageツールホスト、プロンプト配線、セッション / スレッド の記録、および実行ディスパッチを所有します
• チャネルプラグインはスコープ付きアクション検出、ケイパビリティ検出、および 任意のチャネル固有schemaフラグメントを所有します
• チャネルプラグインは、スレッドIDを会話IDがどのようにエンコードするか、 または親会話から継承するかといった、 プロバイダー固有のセッション会話文法を所有します
• チャネルプラグインは、そのアクションアダプターを通じて最終アクションを実行します

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• 信頼された受信requesterSenderId

• outbound.sendPollは、共通の pollモデルに適合するチャネル向けの共有ベースラインです
• actions.handleAction("poll")は、チャネル固有の pollセマンティクスまたは追加のpollパラメーター向けの推奨経路です

​

ケイパビリティ所有権モデル

• 企業プラグインは、通常、その企業のOpenClaw向け サーフェスをすべて所有するべきです
• 機能プラグインは、通常、導入する機能サーフェス全体を所有するべきです
• チャネルは、プロバイダー挙動をアドホックに再実装するのではなく、 共有コアケイパビリティを消費するべきです

• バンドル済みopenaiプラグインは、OpenAIのモデルプロバイダー挙動と、OpenAIの 音声 + リアルタイム音声 + メディア理解 + 画像生成の挙動を所有します
• バンドル済みelevenlabsプラグインは、ElevenLabsの音声挙動を所有します
• バンドル済みmicrosoftプラグインは、Microsoftの音声挙動を所有します
• バンドル済みgoogleプラグインは、Googleのモデルプロバイダー挙動に加えて、Googleの メディア理解 + 画像生成 + Web検索の挙動を所有します
• バンドル済みfirecrawlプラグインは、FirecrawlのWebフェッチ挙動を所有します
• バンドル済みminimax、mistral、moonshot、zaiプラグインは、 それぞれのメディア理解バックエンドを所有します
• voice-callプラグインは機能プラグインです。通話トランスポート、ツール、 CLI、ルート、およびTwilioメディアストリームのブリッジを所有しますが、 ベンダープラグインを直接importするのではなく、 共有音声 + リアルタイム文字起こし + リアルタイム音声ケイパビリティを消費します

• OpenAIは、テキストモデル、音声、画像、そして 将来の動画にまたがっても1つのプラグイン内に存在します
• 他のベンダーも、自身のサーフェス領域について同じことができます
• チャネルは、どのベンダープラグインがそのプロバイダーを所有しているかを気にしません。 コアが公開する共有ケイパビリティコントラクトを消費します

• plugin = 所有権境界
• capability = 複数のプラグインが実装または消費できるコアコントラクト

1. コアで不足しているケイパビリティを定義する
2. それをプラグインAPI / ランタイムを通じて型付きで公開する
3. チャネル / 機能をそのケイパビリティに対して配線する
4. ベンダープラグインに実装を登録させる

​

ケイパビリティのレイヤリング

• コアケイパビリティレイヤー: 共有オーケストレーション、ポリシー、フォールバック、config マージルール、配信セマンティクス、および型付きコントラクト
• ベンダープラグインレイヤー: ベンダー固有API、認証、モデルカタログ、音声 合成、画像生成、将来の動画バックエンド、利用量エンドポイント
• チャネル / 機能プラグインレイヤー: Slack / Discord / voice-callなどの統合。 コアケイパビリティを消費し、サーフェス上に提示します

• コアは返信時TTSポリシー、フォールバック順序、設定、チャネル配信を所有します
• openai、elevenlabs、microsoftは合成実装を所有します
• voice-callは電話向けTTSランタイムヘルパーを消費します

​

複数ケイパビリティを持つ企業プラグインの例

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";

const plugin: OpenClawPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;

• 1つのプラグインがベンダーサーフェスを所有する
• コアは依然としてケイパビリティコントラクトを所有する
• チャネルと機能プラグインは、ベンダーコードではなくapi.runtime.*ヘルパーを消費する
• コントラクトテストは、プラグインが所有すると主張するケイパビリティを 実際に登録したことを検証できる

​

ケイパビリティ例: 動画理解

1. コアがmedia-understandingコントラクトを定義する
2. ベンダープラグインが、該当するものとしてdescribeImage、transcribeAudio、 describeVideoを登録する
3. チャネルと機能プラグインは、ベンダーコードに直接配線するのではなく、 共有コア挙動を消費する

​

コントラクトと強制

• プラグイン作者は、1つの安定した内部標準を得られる
• コアは、2つのプラグインが同じ provider idを登録するような重複所有を拒否できる
• 起動時に、不正な登録に対する実用的な診断を提示できる
• コントラクトテストは、バンドル済みプラグインの所有権を強制し、 静かなドリフトを防げる

1. ランタイム登録の強制 プラグインレジストリは、プラグイン読み込み時に登録を検証します。例: 重複するprovider id、重複するspeech provider id、および不正な 登録は、未定義動作ではなくプラグイン診断を生成します。
2. コントラクトテスト バンドル済みプラグインは、テスト実行中にコントラクトレジストリへ捕捉されるため、 OpenClawは所有権を明示的に検証できます。現在、これはモデル プロバイダー、音声プロバイダー、Web検索プロバイダー、およびバンドル済み登録 所有権に使われています。

​

コントラクトに含めるべきもの

• 型付き
• 小さい
• ケイパビリティ固有
• コアが所有
• 複数のプラグインで再利用可能
• ベンダー知識なしにチャネル / 機能が消費可能

• コアに隠されたベンダー固有ポリシー
• レジストリを迂回する一回限りのプラグイン用エスケープハッチ
• ベンダー実装へ直接到達するチャネルコード
• OpenClawPluginApiまたは api.runtimeの一部ではないアドホックなランタイムオブジェクト

​

実行モデル

• ネイティブプラグインは、ツール、ネットワークハンドラー、フック、サービスを登録できます
• ネイティブプラグインのバグはgatewayをクラッシュさせたり不安定化させたりできます
• 悪意あるネイティブプラグインは、OpenClawプロセス内での任意コード実行と同等です

• plugins.allowはplugin idを信頼し、ソースの来歴は信頼しません。
• バンドル済みプラグインと同じidを持つワークスペースプラグインは、 そのワークスペースプラグインが有効化 / allowlist入りされている場合、 意図的にバンドル済みコピーをシャドウします。
• これは正常であり、ローカル開発、パッチテスト、ホットフィックスに役立ちます。

​

export境界

• バンドル済みプラグイン固有のhelper subpath
• 公開APIとして意図されていないランタイム配管subpath
• ベンダー固有のコンビニエンスヘルパー
• 実装詳細であるsetup / オンボーディングヘルパー

​

読み込みパイプライン

1. 候補プラグインルートを検出する
2. ネイティブまたは互換バンドルのマニフェストとパッケージメタデータを読み込む
3. 安全でない候補を拒否する
4. プラグイン設定を正規化する（plugins.enabled、allow、deny、entries、 slots、load.paths）
5. 各候補の有効化可否を決定する
6. 有効なネイティブモジュールをjiti経由で読み込む
7. ネイティブのregister(api)（またはactivate(api) — レガシーエイリアス）フックを呼び出し、登録をプラグインレジストリへ収集する
8. レジストリをコマンド / ランタイムサーフェスに公開する

​

Manifest-firstの挙動

• プラグインを識別する
• 宣言されたチャネル / Skills / config schemaまたはバンドル機能を検出する
• plugins.entries.<id>.configを検証する
• Control UIのラベル / プレースホルダーを拡張する
• インストール / カタログメタデータを表示する

​

ローダーがキャッシュするもの

• 検出結果
• manifestレジストリデータ
• 読み込み済みプラグインレジストリ

• これらのキャッシュを無効にするには、OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1または OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1を設定してください。
• キャッシュ期間はOPENCLAW_PLUGIN_DISCOVERY_CACHE_MSと OPENCLAW_PLUGIN_MANIFEST_CACHE_MSで調整できます。

​

レジストリモデル

• プラグインレコード（識別情報、ソース、出所、状態、診断）
• ツール
• レガシーフックと型付きフック
• チャネル
• プロバイダー
• Gateway RPCハンドラー
• HTTPルート
• CLI登録子
• バックグラウンドサービス
• プラグイン所有コマンド

• プラグインモジュール -> レジストリ登録
• コアランタイム -> レジストリ消費

​

会話バインディングコールバック

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // このプラグイン + 会話のバインディングが存在するようになりました。
        console.log(event.binding?.conversationId);
        return;
      }

      // リクエストは拒否されました。ローカルの保留状態を消去してください。
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved"または"denied"
• decision: "allow-once"、"allow-always"、または"deny"
• binding: 承認済みリクエストの解決済みバインディング
• request: 元のリクエスト概要、デタッチヒント、sender id、および 会話メタデータ

​

プロバイダーのランタイムフック

• manifestメタデータ: ランタイム読み込み前の 安価なenv認証参照用のproviderAuthEnvVars、およびランタイム読み込み前の 安価なオンボーディング / auth-choice ラベルやCLIフラグメタデータ用のproviderAuthChoices
• config時フック: catalog / レガシーdiscoveryおよびapplyConfigDefaults
• ランタイムフック: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, shouldDeferSyntheticProfileAuth, resolveDynamicModel, prepareDynamicModel, normalizeResolvedModel, contributeResolvedModelCompat, capabilities, normalizeToolSchemas, inspectToolSchemas, resolveReasoningOutputMode, prepareExtraParams, createStreamFn, wrapStreamFn, resolveTransportTurnState, resolveWebSocketSessionPolicy, formatApiKey, refreshOAuth, buildAuthDoctorHint, matchesContextOverflowError, classifyFailoverReason, isCacheTtlEligible, buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, isBinaryThinking, supportsXHighThinking, resolveDefaultThinkingLevel, isModernModelRef, prepareRuntimeAuth, resolveUsageAuth, fetchUsageSnapshot, createEmbeddingProvider, buildReplayPolicy, sanitizeReplayHistory, validateReplayTurns, onModelSelected

​

フック順序と使い方

​

プロバイダー例

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

組み込み例

• AnthropicはresolveDynamicModel、capabilities、buildAuthDoctorHint、 resolveUsageAuth、fetchUsageSnapshot、isCacheTtlEligible、 resolveDefaultThinkingLevel、applyConfigDefaults、isModernModelRef、 およびwrapStreamFnを使います。これはClaude 4.6のforward-compat、 provider-familyヒント、auth修復ガイダンス、usage endpoint統合、 prompt-cache適格性、auth対応configデフォルト、Claudeの default / adaptive thinkingポリシー、およびbeta header、/fast / serviceTier、context1m向けのAnthropic固有stream shapingを所有するためです。
• AnthropicのClaude固有stream helperは、現時点では バンドル済みプラグイン自身の公開api.ts / contract-api.tsシーム内に留まっています。そのパッケージサーフェスは wrapAnthropicProviderStream、resolveAnthropicBetas、 resolveAnthropicFastMode、resolveAnthropicServiceTier、およびより低レベルの Anthropic wrapper builderをexportしており、1つのプロバイダーのbeta-headerルールのために 汎用SDKを広げていません。
• OpenAIはresolveDynamicModel、normalizeResolvedModel、 capabilitiesに加えて、buildMissingAuthMessage、suppressBuiltInModel、 augmentModelCatalog、supportsXHighThinking、isModernModelRefを使います。 これはGPT-5.4のforward-compat、直接のOpenAI openai-completions -> openai-responses正規化、Codex対応auth ヒント、Spark抑制、syntheticなOpenAI list行、およびGPT-5のthinking / live-modelポリシーを所有するためです。openai-responses-defaults stream familyは、 attribution header、 /fast / serviceTier、text verbosity、ネイティブCodex Web検索、 reasoning-compat payload shaping、およびResponses context管理向けの 共有ネイティブOpenAI Responses wrapperを所有します。
• OpenRouterはcatalogに加えてresolveDynamicModelと prepareDynamicModelを使います。これはプロバイダーがパススルーであり、 OpenClawの静的カタログが更新される前に新しい model idを公開しうるためです。また、 provider固有リクエストヘッダー、ルーティングメタデータ、reasoningパッチ、および prompt-cacheポリシーをコアの外に保つために、 capabilities、wrapStreamFn、isCacheTtlEligibleも使います。そのreplay policyは passthrough-gemini familyから来ており、openrouter-thinking stream familyは proxy reasoning注入と未対応モデル / autoスキップを所有します。
• GitHub Copilotはcatalog、auth、resolveDynamicModel、 capabilitiesに加えてprepareRuntimeAuthとfetchUsageSnapshotを使います。 これは、プロバイダー所有のdevice login、モデルフォールバック挙動、Claudeのtranscriptの癖、 GitHub token -> Copilot token交換、およびプロバイダー所有のusage endpointが必要なためです。
• OpenAI Codexはcatalog、resolveDynamicModel、 normalizeResolvedModel、refreshOAuth、augmentModelCatalogに加えて prepareExtraParams、resolveUsageAuth、fetchUsageSnapshotを使います。 これは依然としてコアOpenAIトランスポート上で動作しつつ、 そのトランスポート / base URL正規化、OAuth refreshフォールバックポリシー、 デフォルトトランスポート選択、syntheticなCodexカタログ行、およびChatGPT usage endpoint統合を所有するためです。 direct OpenAIと同じopenai-responses-defaults stream familyを共有します。
• Google AI StudioとGemini CLI OAuthはresolveDynamicModel、 buildReplayPolicy、sanitizeReplayHistory、 resolveReasoningOutputMode、wrapStreamFn、isModernModelRefを使います。これは google-gemini replay familyがGemini 3.1のforward-compatフォールバック、 ネイティブGemini replay検証、bootstrap replay sanitization、tagged reasoning-output mode、およびmodern-model matchingを所有し、 google-thinking stream familyがGemini thinking payload正規化を所有するためです。 Gemini CLI OAuthはさらに、トークン整形、トークン解析、およびquota endpoint 配線のためにformatApiKey、resolveUsageAuth、fetchUsageSnapshotも使います。
• Anthropic Vertexは、 anthropic-by-model replay familyを通じてbuildReplayPolicyを使います。これにより、 Claude固有replayクリーンアップが、すべてのanthropic-messages transportではなく、 Claude idに限定されます。
• Amazon BedrockはbuildReplayPolicy、matchesContextOverflowError、 classifyFailoverReason、resolveDefaultThinkingLevelを使います。これは Anthropic-on-Bedrockトラフィック向けのBedrock固有 throttle / not-ready / context-overflowエラー分類を所有するためです。 そのreplay policyは、依然として同じ Claude専用anthropic-by-modelガードを共有します。
• OpenRouter、Kilocode、Opencode、Opencode GoはbuildReplayPolicyを passthrough-gemini replay family経由で使います。これは OpenAI互換トランスポートを通じてGeminiモデルをプロキシし、 ネイティブGemini replay検証や bootstrapリライトなしにGemini thought-signature sanitizationを必要とするためです。
• MiniMaxは、 hybrid-anthropic-openai replay family経由でbuildReplayPolicyを使います。これは 1つのプロバイダーがAnthropic-messageとOpenAI互換セマンティクスの両方を所有するためです。 Anthropic側ではClaude専用thinking-block除去を維持しつつ、 reasoning output modeをネイティブへ上書きし、 minimax-fast-mode stream familyが共有stream path上の fast-mode modelリライトを所有します。
• Moonshotはcatalogに加えてwrapStreamFnを使います。これは依然として共有 OpenAI transportを使いながら、プロバイダー所有のthinking payload正規化を必要とするためです。 moonshot-thinking stream familyは、configと/think状態を ネイティブbinary thinking payloadへマッピングします。
• Kilocodeはcatalog、capabilities、wrapStreamFn、 isCacheTtlEligibleを使います。これはプロバイダー所有のrequest header、 reasoning payload正規化、Gemini transcriptヒント、およびAnthropic cache-TTLゲーティングを必要とするためです。kilocode-thinking stream familyは、 kilo/autoやその他の 明示的reasoning payloadをサポートしないproxy model idをスキップしつつ、 共有proxy stream path上でKilo thinking注入を保持します。
• Z.AIはresolveDynamicModel、prepareExtraParams、wrapStreamFn、 isCacheTtlEligible、isBinaryThinking、isModernModelRef、 resolveUsageAuth、fetchUsageSnapshotを使います。これはGLM-5フォールバック、 tool_streamデフォルト、binary thinking UX、modern-model matching、および usage auth + quota取得の両方を所有するためです。tool-stream-default-on stream familyは、 デフォルトオンのtool_stream wrapperをプロバイダーごとの手書き glueの外へ保ちます。
• xAIはnormalizeResolvedModel、normalizeTransport、 contributeResolvedModelCompat、prepareExtraParams、wrapStreamFn、 resolveSyntheticAuth、resolveDynamicModel、isModernModelRefを使います。 これはネイティブxAI Responses transport正規化、Grok fast-mode aliasリライト、デフォルトtool_stream、strict-tool / reasoning-payload クリーンアップ、plugin所有ツール向けのフォールバックauth再利用、 forward-compatなGrokモデル解決、およびxAI tool-schema profile、未対応schema keyword、ネイティブweb_search、HTML entity tool-call引数デコードのような、プロバイダー所有compat patchを所有するためです。
• Mistral、OpenCode Zen、OpenCode Goは、transcript / toolingの癖を コアの外に保つためにcapabilitiesのみを使います。
• byteplus、cloudflare-ai-gateway、 huggingface、kimi-coding、nvidia、qianfan、 synthetic、together、venice、vercel-ai-gateway、volcengineのような カタログ専用バンドル済みプロバイダーは、catalogのみを使います。
• Qwenは、テキストプロバイダー向けのcatalogに加えて、 そのマルチモーダルサーフェス向けに共有media-understandingと video-generation登録を使います。
• MiniMaxとXiaomiは、推論自体は共有トランスポートを通って動作するものの、 その/usage挙動がプラグイン所有であるため、 catalogに加えてusageフックも使います。

​

ランタイムヘルパー

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeechは、ファイル / ボイスノートサーフェス向けの通常のコアTTS出力ペイロードを返します。
• コアのmessages.tts設定とプロバイダー選択を使用します。
• PCM音声バッファー + サンプルレートを返します。プラグイン側でプロバイダー向けにリサンプリング / エンコードする必要があります。
• listVoicesは、プロバイダーごとに任意です。ベンダー所有の音声ピッカーやセットアップフローに使ってください。
• 音声一覧には、プロバイダー対応ピッカー向けに、locale、gender、personality tagなどのより豊富なメタデータを含められます。
• 電話対応は現時点でOpenAIとElevenLabsがサポートします。Microsoftはサポートしません。

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• TTSポリシー、フォールバック、返信配信はコアに維持してください。
• ベンダー所有の合成挙動にはspeech providerを使ってください。
• レガシーMicrosoftのedge入力は、microsoft provider idへ正規化されます。
• 推奨される所有権モデルは企業指向です。OpenClawが これらのケイパビリティコントラクトを追加していくにつれ、1つのベンダープラグインが テキスト、音声、画像、将来のメディアプロバイダーを所有できます。

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• オーケストレーション、フォールバック、config、チャネル配線はコアに維持してください。
• ベンダー挙動はプロバイダープラグインに維持してください。
• 加法的拡張は型付きのままであるべきです。新しい任意メソッド、新しい任意 結果フィールド、新しい任意ケイパビリティの形にしてください。
• 動画生成はすでに同じパターンに従います。
  • コアがケイパビリティコントラクトとランタイムヘルパーを所有する
  • ベンダープラグインがapi.registerVideoGenerationProvider(...)を登録する
  • 機能 / チャネルプラグインがapi.runtime.videoGeneration.*を消費する

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // MIMEを確実に推測できない場合は任意:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.*は、 画像 / 音声 / 動画理解向けの推奨共有サーフェスです。
• コアのmedia-understanding音声設定（tools.media.audio）とプロバイダーフォールバック順序を使用します。
• 文字起こし出力が生成されない場合（たとえばスキップ / 未対応入力）は、{ text: undefined }を返します。
• api.runtime.stt.transcribeAudioFile(...)は互換性エイリアスとして残っています。

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• providerとmodelは、永続的なセッション変更ではなく、実行ごとの任意オーバーライドです。
• OpenClawは、それらのオーバーライドフィールドを信頼された呼び出し元に対してのみ受け付けます。
• プラグイン所有のフォールバック実行については、運用者がplugins.entries.<id>.subagent.allowModelOverride: trueで明示的にオプトインする必要があります。
• 信頼されたプラグインを特定の正規provider/modelターゲットに制限するにはplugins.entries.<id>.subagent.allowedModelsを使い、任意ターゲットを明示的に許可するには"*"を使ってください。
• 信頼されていないプラグインのsubagent実行も動作しますが、オーバーライド要求は黙ってフォールバックされるのではなく拒否されます。

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• プロバイダー選択、認証情報解決、および共有リクエストセマンティクスはコアに維持してください。
• ベンダー固有検索トランスポートにはWeb検索プロバイダーを使ってください。
• api.runtime.webSearch.*は、エージェントツールラッパーに依存せずに 検索挙動を必要とする機能 / チャネルプラグイン向けの推奨共有サーフェスです。

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): 設定された画像生成プロバイダーチェーンを使って画像を生成します。
• listProviders(...): 利用可能な画像生成プロバイダーとそのケイパビリティを一覧表示します。

​

Gateway HTTPルート

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: gateway HTTPサーバー配下のルートパス。
• auth: 必須。通常のgateway認証を要求するには"gateway"、プラグイン管理の認証 / webhook検証には"plugin"を使います。
• match: 任意。"exact"（デフォルト）または"prefix"。
• replaceExisting: 任意。同じプラグインが自分自身の既存ルート登録を置き換えることを許可します。
• handler: ルートがリクエストを処理した場合はtrueを返します。

• api.registerHttpHandler(...)は削除されており、プラグイン読み込みエラーになります。代わりにapi.registerHttpRoute(...)を使ってください。
• プラグインルートはauthを明示的に宣言する必要があります。
• 同一のpath + match競合は、replaceExisting: trueがない限り拒否され、あるプラグインが別のプラグインのルートを置き換えることはできません。
• authレベルが異なる重複ルートは拒否されます。exact / prefixのフォールスルーチェーンは同じauthレベル内にのみ保ってください。
• auth: "plugin"ルートは、運用者ランタイムスコープを自動では受け取りません。これはプラグイン管理のwebhook / 署名検証向けであり、特権Gatewayヘルパー呼び出し向けではありません。
• auth: "gateway"ルートはGatewayリクエストランタイムスコープ内で実行されますが、そのスコープは意図的に保守的です。
  • 共有シークレットbearer認証（gateway.auth.mode = "token" / "password"）では、呼び出し元がx-openclaw-scopesを送信しても、プラグインルートのランタイムスコープはoperator.writeに固定されます
  • 信頼されたID付きHTTPモード（たとえばtrusted-proxyや、プライベートingress上のgateway.auth.mode = "none"）では、x-openclaw-scopesヘッダーが明示的に存在する場合にのみそれを尊重します
  • それらのID付きプラグインルートリクエストでx-openclaw-scopesが存在しない場合、ランタイムスコープはoperator.writeへフォールバックします
• 実践的なルール: gateway-authプラグインルートを暗黙の管理者サーフェスだと思わないでください。ルートが管理者専用挙動を必要とするなら、ID付き認証モードを要求し、明示的なx-openclaw-scopesヘッダー契約を文書化してください。

​

Plugin SDK importパス

• プラグイン登録プリミティブにはopenclaw/plugin-sdk/plugin-entry。
• 汎用の共有プラグイン向けコントラクトにはopenclaw/plugin-sdk/core。
• ルートopenclaw.json Zod schema export（OpenClawSchema）にはopenclaw/plugin-sdk/config-schema。
• openclaw/plugin-sdk/channel-setup、 openclaw/plugin-sdk/setup-runtime、 openclaw/plugin-sdk/setup-adapter-runtime、 openclaw/plugin-sdk/setup-tools、 openclaw/plugin-sdk/channel-pairing、 openclaw/plugin-sdk/channel-contract、 openclaw/plugin-sdk/channel-feedback、 openclaw/plugin-sdk/channel-inbound、 openclaw/plugin-sdk/channel-lifecycle、 openclaw/plugin-sdk/channel-reply-pipeline、 openclaw/plugin-sdk/command-auth、 openclaw/plugin-sdk/secret-input、および openclaw/plugin-sdk/webhook-ingressのような安定したチャネルプリミティブは、 共有setup / auth / reply / webhook 配線向けです。channel-inboundは、debounce、mentionマッチング、 envelope整形、および受信envelope context helperの共有ホームです。 channel-setupは狭いoptional-install setupシームです。 setup-runtimeは、setupEntry / 遅延起動で使われるランタイム安全なsetupサーフェスであり、 import安全なsetup patch adapterを含みます。 setup-adapter-runtimeはenv対応account-setup adapterシームです。 setup-toolsは、小さなCLI / archive / docs helperシーム（formatCliCommand、 detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR）です。
• openclaw/plugin-sdk/channel-config-helpers、 openclaw/plugin-sdk/allow-from、 openclaw/plugin-sdk/channel-config-schema、 openclaw/plugin-sdk/telegram-command-config、 openclaw/plugin-sdk/channel-policy、 openclaw/plugin-sdk/approval-runtime、 openclaw/plugin-sdk/config-runtime、 openclaw/plugin-sdk/infra-runtime、 openclaw/plugin-sdk/agent-runtime、 openclaw/plugin-sdk/lazy-runtime、 openclaw/plugin-sdk/reply-history、 openclaw/plugin-sdk/routing、 openclaw/plugin-sdk/status-helpers、 openclaw/plugin-sdk/text-runtime、 openclaw/plugin-sdk/runtime-store、および openclaw/plugin-sdk/directory-runtimeのようなドメインsubpathは、 共有ランタイム / config helper向けです。 telegram-command-configは、Telegramカスタム コマンド正規化 / 検証向けの狭い公開シームであり、 バンドル済みTelegramコントラクトサーフェスが一時的に利用不能な場合でも利用可能なままです。 text-runtimeは、assistant-visible-text除去、 markdown render / chunking helper、redaction helper、directive-tag helper、およびsafe-text utilityを含む、 共有text / markdown / loggingシームです。
• 承認固有チャネルシームでは、プラグイン上の1つのapprovalCapability コントラクトを優先してください。するとコアは、その1つのケイパビリティを通じて approval auth、delivery、render、およびnative-routing挙動を読み取り、 approval挙動を無関係なプラグインフィールドへ混ぜる必要がなくなります。
• openclaw/plugin-sdk/channel-runtimeは非推奨で、 古いプラグイン向けの互換性shimとしてのみ残っています。新しいコードでは、 代わりにより狭い汎用プリミティブをimportするべきであり、repoコードでも このshimへの新規importを追加すべきではありません。
• バンドル済み拡張の内部は非公開のままです。外部プラグインは openclaw/plugin-sdk/* subpathのみを使うべきです。OpenClawのコア / テストコードは、 index.js、api.js、 runtime-api.js、setup-entry.js、および login-qr-api.jsのような狭く限定されたファイルなど、プラグインパッケージルート配下の repo公開エントリポイントを使えます。コアまたは別拡張から、 プラグインパッケージのsrc/*をimportしてはいけません。
• repoエントリポイント分割: <plugin-package-root>/api.jsはhelper / types barrel、 <plugin-package-root>/runtime-api.jsはruntime-only barrel、 <plugin-package-root>/index.jsはバンドル済みプラグインエントリー、 <plugin-package-root>/setup-entry.jsはsetupプラグインエントリーです。
• 現在のバンドル済みプロバイダー例:
  • Anthropicは、wrapAnthropicProviderStream、beta-header helper、service_tier 解析などのClaude stream helper向けにapi.js / contract-api.jsを使います。
  • OpenAIは、provider builder、default-model helper、realtime provider builder向けに api.jsを使います。
  • OpenRouterは、そのprovider builderに加えてonboarding / config helper向けにapi.jsを使い、register.runtime.jsは依然としてrepoローカル用途向けに 汎用plugin-sdk/provider-stream helperを再exportできます。
• facade読み込みされる公開エントリポイントは、利用可能な場合はアクティブな ランタイムconfigスナップショットを優先し、OpenClawがまだランタイム スナップショットを提供していない場合は、ディスク上の解決済みconfigファイルへフォールバックします。
• 汎用共有プリミティブは、引き続き推奨される公開SDKコントラクトです。 バンドル済みチャネルブランド付きhelperシームの小さな予約済み互換セットは今も存在します。これらは バンドル保守 / 互換性シームとして扱い、新しい サードパーティimportターゲットとしては扱わないでください。新しいクロスチャネルコントラクトは、 引き続き汎用plugin-sdk/* subpathまたはプラグインローカルのapi.js / runtime-api.js barrelに置くべきです。

• 新しいコードでは、ルートのopenclaw/plugin-sdk barrelは避けてください。
• まず狭い安定プリミティブを優先してください。新しいsetup / pairing / reply / feedback / contract / inbound / threading / command / secret-input / webhook / infra / allowlist / status / message-tool subpathが、新しい バンドル済みおよび外部プラグイン作業向けの意図されたコントラクトです。 target解析 / マッチングはopenclaw/plugin-sdk/channel-targetsに属します。 message action gateおよびreaction message-id helperは openclaw/plugin-sdk/channel-actionsに属します。
• バンドル済み拡張固有helper barrelは、デフォルトでは安定していません。 あるhelperがバンドル済み拡張にしか必要ない場合は、 openclaw/plugin-sdk/<extension>へ昇格させるのではなく、 その拡張のローカルapi.jsまたはruntime-api.jsシームの背後に保ってください。
• 新しい共有helperシームは、チャネルブランド付きではなく汎用であるべきです。共有target 解析はopenclaw/plugin-sdk/channel-targetsに属し、チャネル固有 内部は、そのプラグイン所有のローカルapi.jsまたはruntime-api.js シームの背後に留まります。
• image-generation、 media-understanding、speechのようなケイパビリティ固有subpathは、 バンドル済み / ネイティブプラグインが現在それらを使っているため存在します。 それらが存在すること自体は、exportされたすべてのhelperが 長期的に凍結された外部コントラクトであることを意味しません。

​

Messageツールschema

• ボタングリッド形式のpayloadにはcreateMessageToolButtonsSchema()
• 構造化カードpayloadにはcreateMessageToolCardSchema()

​

チャネルtarget解決

• messaging.inferTargetChatType({ to })は、正規化されたtargetを directory lookup前にdirect、group、またはchannelとして扱うべきかを決定します。
• messaging.targetResolver.looksLikeId(raw, normalized)は、ある入力が directory searchではなく、明示的 / ネイティブtarget id解決へ直接進むべきかどうかをコアに伝えます。
• messaging.targetResolver.resolveTarget(...)は、正規化後または directory miss後に、コアが最終的なプロバイダー所有解決を必要とする場合のプラグイン側フォールバックです。
• messaging.resolveOutboundSessionRoute(...)は、target解決後の プロバイダー固有セッションルート構築を所有します。

• peer / group検索前に行うべきカテゴリ判定にはinferTargetChatTypeを使う
• 「これを明示的 / ネイティブtarget idとして扱う」判定にはlooksLikeIdを使う
• resolveTargetは、広範なdirectory searchではなく、 プロバイダー固有の正規化フォールバックに使う
• chat id、thread id、JID、handle、room idのようなプロバイダーネイティブidは、 汎用SDKフィールドではなく、target値またはプロバイダー固有パラメーター内に保持する

​

configベースのdirectory

• allowlist駆動のDM peer
• 設定されたchannel / group map
• accountスコープの静的directoryフォールバック

• クエリフィルタリング
• limit適用
• dedupe / 正規化helper
• ChannelDirectoryEntry[]の構築

​

プロバイダーカタログ

• 1つのproviderエントリーには{ provider }
• 複数のproviderエントリーには{ providers }

• simple: 単純なAPIキーまたはenv駆動プロバイダー
• profile: auth profileが存在すると現れるプロバイダー
• paired: 複数の関連providerエントリーを合成するプロバイダー
• late: 最終パス。他の暗黙プロバイダーの後

• discoveryはレガシーエイリアスとして引き続き動作します
• catalogとdiscoveryの両方が登録されている場合、OpenClawはcatalogを使います

​

読み取り専用チャネル検査

• resolveAccount(...)はランタイム経路です。認証情報が 完全に具体化されていることを前提にでき、必要なシークレットが不足していれば 即座に失敗して構いません。
• openclaw status、openclaw status --all、 openclaw channels status、openclaw channels resolve、およびdoctor / config 修復フローのような読み取り専用コマンド経路では、 設定を説明するだけのためにランタイム認証情報を具体化する必要はありません。

• 記述的なaccount状態のみを返す
• enabledとconfiguredを保持する
• 関連する場合は、認証情報のsource / statusフィールドを含める。例:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• 読み取り専用の利用可能性を報告するためだけに、生のtoken値を返す必要はありません。 tokenStatus: "available"（および対応するsourceフィールド）を返せば、 status系コマンドには十分です。
• 認証情報がSecretRef経由で設定されているが、現在のコマンド経路では利用できない場合は configured_unavailableを使う

​

パッケージパック

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• チャネル登録そのもの
• gatewayがlisten開始前に利用可能であるべき任意のHTTPルート
• 同じウィンドウ内で存在すべき任意のgatewayメソッド、ツール、またはサービス

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

チャネルカタログメタデータ

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: より豊かなcatalog / statusサーフェス向けの二次ラベル
• docsLabel: docsリンクのリンクテキスト上書き
• preferOver: このcatalogエントリーが上位に置くべき低優先度plugin / channel id
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: selection-surfaceの文言制御
• markdownCapable: outbound整形判断のために、チャネルをmarkdown対応として示す
• showConfigured: falseに設定すると、configured-channel一覧サーフェスからそのチャネルを隠す
• quickstartAllowFrom: チャネルを標準クイックスタートallowFromフローへオプトインする
• forceAccountBinding: accountが1つしかなくても明示的account bindingを必須にする
• preferSessionLookupForAnnounceTarget: announce target解決時にsession lookupを優先する

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

コンテキストエンジンプラグイン

export default function (api) {
  api.registerContextEngine("lossless-claw", () => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", () => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

新しいケイパビリティの追加

1. コアコントラクトを定義する コアが所有すべき共有挙動を決めてください。ポリシー、フォールバック、configマージ、 ライフサイクル、チャネル向けセマンティクス、およびランタイムヘルパーの形状です。
2. 型付きプラグイン登録 / ランタイムサーフェスを追加する 最小限で有用な 型付きケイパビリティサーフェスでOpenClawPluginApiおよび / またはapi.runtimeを拡張します。
3. コア + チャネル / 機能コンシューマーを配線する チャネルと機能プラグインは、ベンダー実装を直接importするのではなく、 コアを通じて新しいケイパビリティを消費するべきです。
4. ベンダー実装を登録する その後、ベンダープラグインがそのケイパビリティに対してバックエンドを登録します。
5. コントラクトカバレッジを追加する 所有権と登録形状が時間とともに明示的に保たれるよう、テストを追加します。

​

ケイパビリティチェックリスト

• src/<capability>/types.tsのコアコントラクト型
• src/<capability>/runtime.tsのコアランナー / ランタイムヘルパー
• src/plugins/types.tsのプラグインAPI登録サーフェス
• src/plugins/registry.tsのプラグインレジストリ配線
• 機能 / チャネル プラグインがそれを消費する必要がある場合のsrc/plugins/runtime/*内のプラグインランタイム公開
• src/test-utils/plugin-registration.tsのcapture / test helper
• src/plugins/contracts/registry.tsの所有権 / コントラクト検証
• docs/の運用者 / プラグイン向けドキュメント

​

ケイパビリティテンプレート

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• コアがケイパビリティコントラクト + オーケストレーションを所有する
• ベンダープラグインがベンダー実装を所有する
• 機能 / チャネルプラグインがランタイムヘルパーを消費する
• コントラクトテストが所有権を明示的に保つ