​

プラグイン内部

​

公開機能モデル

​

外部互換性の方針

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

• 機能登録 API は意図された方向性です
• 移行期間中、従来のフックは外部プラグインにとって最も安全で破壊的変更のない経路のままです
• エクスポートされたヘルパーのサブパスはすべて同等ではありません。偶発的に露出した ヘルパーではなく、文書化された限定的なコントラクトを優先してください

​

プラグインの形態

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

​

従来のフック

• 動作し続けるようにする
• 従来方式として文書化する
• モデル / プロバイダーの上書きには before_model_resolve を優先する
• プロンプト変更には before_prompt_build を優先する
• 実際の使用量が減少し、フィクスチャカバレッジによって移行の安全性が証明されるまでは 削除しない

​

互換性シグナル

​

アーキテクチャ概要

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

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

• 検出 + 設定検証は、プラグインコードを実行せずに、 マニフェスト / スキーマメタデータ から動作できるべきです
• ネイティブのランタイム動作は、プラグインモジュールの register(api) パスから得られます

​

Channel Plugins と共有 message ツール

• core は、共有 message ツールホスト、プロンプト配線、セッション / スレッドの 管理、および実行ディスパッチを所有します
• チャネルプラグインは、スコープ付きアクション検出、機能検出、および任意の チャネル固有スキーマ断片を所有します
• チャネルプラグインは、会話 ID がどのようにスレッド ID をエンコードするか、 または親会話から継承するかといった、プロバイダー固有のセッション会話文法を所有します
• チャネルプラグインは、自身のアクションアダプターを通じて最終アクションを実行します

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

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

​

機能所有権モデル

• 会社プラグインは通常、その会社に関する OpenClaw 向けサーフェスをすべて所有するべきです
• 機能プラグインは通常、自らが導入する機能サーフェス全体を所有するべきです
• チャネルは、プロバイダーの振る舞いを場当たり的に再実装するのではなく、 共有された core 機能を利用するべきです

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

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

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

1. core に不足している機能を定義する
2. それを型付きで plugin API / ランタイムを通じて公開する
3. その機能に対してチャネル / 機能を接続する
4. ベンダープラグインに実装を登録させる

​

機能レイヤリング

• core capability layer: 共有オーケストレーション、ポリシー、フォールバック、設定の マージルール、配信セマンティクス、および型付きコントラクト
• vendor plugin layer: ベンダー固有 API、認証、モデルカタログ、音声合成、画像生成、 将来の動画バックエンド、使用量エンドポイント
• channel/feature plugin layer: core の機能を利用し、それをサーフェス上に提示する Slack / Discord / voice-call などの統合

• core は、返信時の 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 つのプラグインがベンダーのサーフェスを所有する
• それでも core は機能コントラクトを所有する
• チャネルと機能プラグインは、ベンダーコードではなく api.runtime.* ヘルパーを利用する
• コントラクトテストでは、プラグインが自ら所有すると主張する機能を登録したことを 検証できる

​

機能の例: 動画理解

1. core が media-understanding コントラクトを定義する
2. ベンダープラグインが、該当するものとして describeImage、transcribeAudio、 describeVideo を登録する
3. チャネルと機能プラグインは、ベンダーコードに直接接続するのではなく、 共有された core の振る舞いを利用する

​

コントラクトと強制

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

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

​

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

• 型付き
• 小さい
• 機能固有
• core が所有する
• 複数のプラグインで再利用できる
• ベンダー知識なしでチャネル / 機能が利用できる

• core に隠されたベンダー固有ポリシー
• レジストリを迂回する一回限りのプラグイン用 escape hatch
• ベンダー実装へ直接入り込むチャネルコード
• OpenClawPluginApi または api.runtime の一部ではない場当たり的なランタイムオブジェクト

​

実行モデル

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

• plugins.allow は plugin ids を信頼し、ソースの来歴は信頼しません。
• バンドル済みプラグインと同じ id を持つ workspace プラグインは、その workspace プラグインが有効化 / allowlist されると、意図的にバンドル済みコピーを上書きします。
• これは通常のことであり、ローカル開発、パッチテスト、ホットフィックスに便利です。

​

エクスポート境界

• バンドル済みプラグイン固有のヘルパーサブパス
• 公開 API を意図していないランタイム配線サブパス
• ベンダー固有の convenience helper
• 実装詳細である setup / オンボーディングヘルパー

​

読み込みパイプライン

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

​

Manifest-first の振る舞い

• プラグインを識別する
• 宣言されたチャネル / Skills / 設定スキーマ、または bundle の機能を検出する
• plugins.entries.<id>.config を検証する
• Control UI のラベル / プレースホルダーを拡張する
• install / catalog メタデータを表示する
• プラグインランタイムを読み込まずに、軽量な activation および setup descriptor を保持する

​

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

• 検出結果
• 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 レジストラ
• バックグラウンドサービス
• プラグイン所有コマンド

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

​

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

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" または "denied"
• decision: "allow-once"、"allow-always"、または "deny"
• binding: 承認された要求に対する解決済みバインディング
• request: 元の要求の要約、detach ヒント、送信者 id、および 会話メタデータ

​

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

• manifest メタデータ: ランタイム読み込み前に軽量なプロバイダー env 認証参照を行うための providerAuthEnvVars、認証を共有するプロバイダーバリアント向けの providerAuthAliases、ランタイム読み込み前に軽量なチャネル env / setup 参照を行うための channelEnvVars、およびランタイム読み込み前に軽量な オンボーディング / auth-choice ラベルと CLI フラグメタデータを提供する providerAuthChoices
• 設定時フック: catalog / 従来の discovery、および applyConfigDefaults
• ランタイムフック: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, resolveExternalAuthProfiles, 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、 プロバイダーファミリーのヒント、auth 修復ガイダンス、使用量エンドポイント統合、 prompt-cache 適格性、auth 対応 config デフォルト、Claude の デフォルト / 適応的 thinking ポリシー、および beta ヘッダー、 /fast / serviceTier、context1m に対する Anthropic 固有の stream shaping を所有しているためです。
• Anthropic の Claude 固有 stream helper は、現時点ではバンドル済みプラグイン自身の 公開 api.ts / contract-api.ts シームに留まっています。そのパッケージサーフェスは、 ある 1 つのプロバイダーの beta-header ルールに合わせて汎用 SDK を広げるのではなく、 wrapAnthropicProviderStream、resolveAnthropicBetas、 resolveAnthropicFastMode、resolveAnthropicServiceTier、 およびより低レベルの Anthropic wrapper builder をエクスポートします。
• 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 ヘッダー、/fast / serviceTier、 テキスト verbosity、ネイティブ Codex web search、 reasoning-compat ペイロード整形、および Responses のコンテキスト管理のための、 共有ネイティブ OpenAI Responses wrapper を所有します。
• OpenRouter は catalog に加えて resolveDynamicModel と prepareDynamicModel を使います。これは、このプロバイダーが pass-through であり、 OpenClaw の静的 catalog 更新前に新しい model id を公開することがあるためです。 また、プロバイダー固有のリクエストヘッダー、ルーティングメタデータ、 reasoning patch、prompt-cache ポリシーを core の外に保つために、 capabilities、wrapStreamFn、isCacheTtlEligible も使います。 その replay policy は passthrough-gemini family から来ており、 openrouter-thinking stream family は、proxy reasoning 注入と、 未対応モデル / auto のスキップを所有します。
• GitHub Copilot は catalog、auth、resolveDynamicModel、 capabilities に加えて prepareRuntimeAuth と fetchUsageSnapshot を使います。これは、プロバイダー所有のデバイスログイン、モデルのフォールバック動作、 Claude transcript の癖、GitHub token -> Copilot token 交換、 およびプロバイダー所有の使用量エンドポイントが必要なためです。
• OpenAI Codex は catalog、resolveDynamicModel、 normalizeResolvedModel、refreshOAuth、augmentModelCatalog に加えて prepareExtraParams、resolveUsageAuth、fetchUsageSnapshot を使います。これは、依然として core の OpenAI transport 上で動作しつつも、 transport / base URL の正規化、OAuth refresh のフォールバックポリシー、 デフォルト transport 選択、synthetic な Codex catalog 行、および ChatGPT の使用量エンドポイント統合を所有しているためです。 直接の 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 sanitation、タグ付き reasoning-output mode、 modern-model マッチングを所有し、google-thinking stream family が Gemini thinking ペイロード正規化を所有するためです。 Gemini CLI OAuth はさらに、トークン整形、トークン解析、quota エンドポイント配線のために formatApiKey、resolveUsageAuth、fetchUsageSnapshot も使用します。
• Anthropic Vertex は anthropic-by-model replay family を通じて buildReplayPolicy を使用します。これにより、Claude 固有の replay cleanup は、 すべての 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 は、 passthrough-gemini replay family を通じて buildReplayPolicy を使用します。これは、Gemini モデルを OpenAI 互換 transport 経由で proxy し、ネイティブ Gemini replay 検証や bootstrap 書き換えなしで Gemini thought-signature sanitation を必要とするためです。
• MiniMax は hybrid-anthropic-openai replay family を通じて buildReplayPolicy を使用します。これは、1 つのプロバイダーが Anthropic-message と OpenAI 互換の両方のセマンティクスを所有するためです。 Anthropic 側では Claude 専用の thinking-block drop を維持しつつ、 reasoning output mode をネイティブへ上書きします。また、 minimax-fast-mode stream family は、共有 stream path 上での fast-mode モデル書き換えを所有します。
• Moonshot は catalog に加えて wrapStreamFn を使います。 これは、共有 OpenAI transport を依然として使用しつつ、 プロバイダー所有の thinking ペイロード正規化が必要なためです。 moonshot-thinking stream family は、config と /think 状態を そのネイティブな binary thinking ペイロードへマップします。
• Kilocode は catalog、capabilities、wrapStreamFn、 isCacheTtlEligible を使います。これは、プロバイダー所有のリクエストヘッダー、 reasoning ペイロード正規化、Gemini transcript ヒント、 Anthropic cache-TTL ゲーティングが必要なためです。 kilocode-thinking stream family は、共有 proxy stream path 上で Kilo thinking 注入を維持しつつ、kilo/auto や、明示的な reasoning ペイロードをサポートしないほかの proxy model id をスキップします。
• Z.AI は resolveDynamicModel、prepareExtraParams、wrapStreamFn、 isCacheTtlEligible、isBinaryThinking、isModernModelRef、 resolveUsageAuth、fetchUsageSnapshot を使います。これは、 GLM-5 フォールバック、tool_stream デフォルト、binary thinking UX、 modern-model マッチング、および使用量 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 エイリアス書き換え、デフォルト tool_stream、 strict-tool / reasoning-payload のクリーンアップ、プラグイン所有ツール向けの フォールバック auth 再利用、forward-compat な Grok モデル解決、 および xAI の tool-schema profile、未対応スキーマキーワード、 ネイティブ web_search、HTML entity 化された tool-call 引数のデコードといった、 プロバイダー所有の compat patch を所有しているためです。
• Mistral、OpenCode Zen、OpenCode Go は、transcript / tooling の癖を core の外に保つために capabilities のみを使います。
• byteplus、cloudflare-ai-gateway、huggingface、kimi-coding、 nvidia、qianfan、synthetic、together、venice、 vercel-ai-gateway、volcengine のような catalog のみの バンドル済みプロバイダーは、catalog のみを使います。
• Qwen はテキストプロバイダー向けに catalog を使い、マルチモーダルな サーフェス向けに共有の media-understanding と video-generation 登録も行います。
• MiniMax と Xiaomi は catalog に加えて usage フックを使います。 これは、推論自体は共有 transport を通じて実行される一方で、 /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 は、ファイル / ボイスノート向けサーフェスに対する通常の core TTS 出力ペイロードを返します。
• core の messages.tts 設定とプロバイダー選択を使用します。
• PCM 音声バッファー + サンプルレートを返します。プラグイン側で プロバイダー向けに再サンプリング / エンコードする必要があります。
• listVoices はプロバイダーごとに任意です。ベンダー所有の voice picker または setup フローに使ってください。
• 音声一覧には、locale、gender、personality tag のような、プロバイダー対応 picker 向けのより豊富なメタデータを含めることができます。
• 現時点で電話向けに対応しているのは 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 ポリシー、フォールバック、および返信配信は core に保持してください。
• ベンダー所有の音声合成の振る舞いには 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: "..." }),
});

• オーケストレーション、フォールバック、設定、チャネル配線は core に保持してください。
• ベンダーの振る舞いはプロバイダープラグインに保持してください。
• 加算的な拡張は、型付きのままにしてください。新しい任意メソッド、新しい任意の 結果フィールド、新しい任意の機能、という形です。
• 動画生成もすでに同じパターンに従っています。
  • core が機能コントラクトとランタイムヘルパーを所有する
  • ベンダープラグインが 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,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* は、画像 / 音声 / 動画理解のための 推奨される共有サーフェスです。
• core の 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,
  },
});

• プロバイダー選択、認証情報解決、および共有リクエストセマンティクスは core に保持してください。
• ベンダー固有の検索トランスポートには 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 でない限り拒否され、 1 つのプラグインが別のプラグインのルートを置き換えることもできません。
• auth レベルが異なる重複ルートは拒否されます。exact / prefix の フォールスルーチェーンは、同じ auth レベル内だけにしてください。
• auth: "plugin" ルートは、オペレーターのランタイムスコープを自動的には受け取りません。 これは特権付き Gateway helper 呼び出しではなく、プラグイン管理 webhook / 署名検証のためのものです。
• 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 認証付きプラグインルートを暗黙の管理者サーフェスだと 想定しないでください。ルートで管理者専用の振る舞いが必要なら、ID 付き認証モードを 必須にし、明示的な x-openclaw-scopes ヘッダー契約を文書化してください。

​

Plugin SDK の import パス

• プラグイン登録プリミティブには openclaw/plugin-sdk/plugin-entry。
• 汎用の共有プラグイン向けコントラクトには openclaw/plugin-sdk/core。
• ルート openclaw.json Zod スキーマエクスポート（OpenClawSchema）には openclaw/plugin-sdk/config-schema。
• 共有 setup / auth / reply / webhook 配線には、 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 のような安定したチャネルプリミティブを使用します。channel-inbound は、 debounce、mention マッチング、受信 mention-policy helper、 envelope 整形、受信 envelope コンテキスト helper の共有ホームです。 channel-setup は限定的な optional-install setup シームです。 setup-runtime は、setupEntry / 遅延起動で使われるランタイム安全な setup サーフェスであり、import-safe な setup patch adapter を含みます。 setup-adapter-runtime は env 対応の account-setup adapter シームです。 setup-tools は、小さな CLI / archive / docs helper シーム （formatCliCommand、detectBinary、extractArchive、 resolveBrewExecutable、formatDocsLink、CONFIG_DIR）です。
• 共有ランタイム / 設定 helper には、 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-gateway-runtime、 openclaw/plugin-sdk/approval-handler-adapter-runtime、 openclaw/plugin-sdk/approval-handler-runtime、 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 のようなドメインサブパスを使用します。 telegram-command-config は Telegram カスタムコマンドの正規化 / 検証のための 限定的な公開シームであり、バンドル済み Telegram コントラクトサーフェスが一時的に 利用できない場合でも利用可能です。 text-runtime は、assistant-visible-text の除去、markdown の レンダリング / 分割 helper、redaction helper、directive-tag helper、 safe-text utility を含む、共有の text / markdown / logging シームです。
• 承認固有のチャネルシームでは、プラグイン上の 1 つの approvalCapability コントラクトを優先してください。すると core は、承認 auth、配信、レンダリング、 ネイティブルーティング、遅延ネイティブハンドラーの振る舞いを、無関係な プラグインフィールドへ混在させるのではなく、その単一の機能を通じて読み取れます。
• openclaw/plugin-sdk/channel-runtime は非推奨であり、古いプラグイン向けの 互換 shim としてのみ残されています。新しいコードは、より限定的な汎用プリミティブを import すべきであり、repo コードもこの shim への新しい import を追加すべきではありません。
• バンドル済み拡張の内部実装は非公開のままです。外部プラグインは openclaw/plugin-sdk/* サブパスのみを使用してください。OpenClaw の core / test コードは、プラグインパッケージルート配下の repo 公開エントリポイント index.js、api.js、runtime-api.js、setup-entry.js、 login-qr-api.js のような限定ファイルを使用できます。core からも、 ほかの拡張からも、プラグインパッケージの src/* を import してはいけません。
• repo エントリポイント分割: <plugin-package-root>/api.js は helper / types barrel、 <plugin-package-root>/runtime-api.js はランタイム専用 barrel、 <plugin-package-root>/index.js はバンドル済みプラグインエントリ、 <plugin-package-root>/setup-entry.js は setup プラグインエントリです。
• 現在のバンドル済みプロバイダー例:
  • Anthropic は api.js / contract-api.js を使って、 wrapAnthropicProviderStream、beta-header helper、 service_tier 解析のような Claude stream helper を提供します。
  • OpenAI は api.js を使って、provider builder、default-model helper、 realtime provider builder を提供します。
  • OpenRouter は api.js を使って、その provider builder と onboarding / config helper を提供し、一方で register.runtime.js は、 repo ローカル用途として汎用の plugin-sdk/provider-stream helper を 再エクスポートし続けることができます。
• facade によって読み込まれる公開エントリポイントは、アクティブなランタイム設定 スナップショットが存在する場合はそれを優先し、OpenClaw がまだランタイム スナップショットを提供していない場合は、ディスク上の解決済み設定ファイルへ フォールバックします。
• 汎用の共有プリミティブは、引き続き推奨される公開 SDK コントラクトです。 バンドル済みチャネルにブランド化された helper シームの小規模な予約済み互換セットは 依然として存在します。これらは、バンドル保守 / 互換性シームとして扱ってください。 新しいサードパーティ import 対象ではありません。新しいクロスチャネルコントラクトは、 引き続き汎用 plugin-sdk/* サブパス、またはプラグインローカルの 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 サブパスは、新しいバンドル済みおよび外部プラグイン作業向けの意図された コントラクトです。 ターゲットの解析 / マッチングは 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 シームは、チャネルブランド付きではなく、汎用であるべきです。 共有ターゲット解析は openclaw/plugin-sdk/channel-targets に属し、 チャネル固有の内部実装は、所有するプラグインのローカル api.js または runtime-api.js シームの背後に留めてください。
• image-generation、media-understanding、speech のような 機能固有サブパスが存在するのは、現在それらをバンドル済み / ネイティブプラグインが 使用しているためです。だからといって、エクスポートされたすべての helper が 長期的に凍結された外部コントラクトであることを意味するわけではありません。

​

Message tool スキーマ

• ボタングリッド形式のペイロードには createMessageToolButtonsSchema()
• 構造化 card ペイロードには createMessageToolCardSchema()

​

チャネルターゲット解決

• messaging.inferTargetChatType({ to }) は、正規化されたターゲットを ディレクトリ参照前に direct、group、channel のどれとして扱うべきかを決定します。
• messaging.targetResolver.looksLikeId(raw, normalized) は、ある入力が ディレクトリ検索ではなく id 風の解決へ直行すべきかを core に伝えます。
• messaging.targetResolver.resolveTarget(...) は、正規化後または ディレクトリ未検出後に、core が最終的なプロバイダー所有の解決を必要とする場合の プラグイン側フォールバックです。
• messaging.resolveOutboundSessionRoute(...) は、ターゲットが解決された後の プロバイダー固有セッションルート構築を所有します。

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

​

設定ベースのディレクトリ

• allowlist 駆動の DM peer
• 設定済み channel / group マップ
• アカウントスコープの静的ディレクトリフォールバック

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

​

プロバイダーカタログ

• 1 つの provider エントリに対して { provider }
• 複数の provider エントリに対して { providers }

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

• discovery は従来の別名として引き続き動作します
• catalog と discovery の両方が登録された場合、OpenClaw は catalog を使います

​

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

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

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

​

パッケージパック

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

• チャネル登録そのもの
• gateway が listen を開始する前に利用可能でなければならない HTTP ルート
• 同じ時間枠に存在しなければならない gateway method、tool、service

• 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: 選択サーフェス用コピー制御
• markdownCapable: outbound 整形判断のために、そのチャネルが markdown 対応であることを示す
• exposure.configured: false に設定すると、設定済みチャネル一覧サーフェスから そのチャネルを隠す
• exposure.setup: false に設定すると、対話型 setup / configure picker から そのチャネルを隠す
• exposure.docs: docs ナビゲーションサーフェスにおいて、そのチャネルを internal / private として示す
• showConfigured / showInSetup: 互換性のために引き続き受け付ける従来の別名です。 exposure を優先してください
• quickstartAllowFrom: そのチャネルを標準のクイックスタート allowFrom フローにオプトインする
• forceAccountBinding: アカウントが 1 つしか存在しない場合でも、 明示的なアカウントバインディングを必須にする
• preferSessionLookupForAnnounceTarget: announce ターゲット解決時に セッション検索を優先する

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

​

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

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

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, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  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, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

新しい機能を追加する

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

​

機能チェックリスト

• src/<capability>/types.ts の core コントラクト型
• src/<capability>/runtime.ts の core runner / ランタイムヘルパー
• 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/ のオペレーター / プラグイン 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"]);

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