Plugin SDK の移行

OpenClaw は、広範な後方互換性レイヤーを、小規模で目的を絞ったインポートから構成される最新の Plugin アーキテクチャに置き換えました。お使いの Plugin がこの変更より前に作成されたものである場合、 このガイドに従って現在のコントラクトへ移行できます。

変更点

以前は、非常に広範なインポートサーフェスにより、Plugin は単一のエントリポイントから ほぼあらゆるものにアクセスできました。

• openclaw/plugin-sdk と openclaw/plugin-sdk/compat - 目的を絞った SDK の構築中に、 数十個のヘルパーを再エクスポートしていました。現在は両方のルートが削除されています。 代わりに、文書化されたサブパスをインポートしてください。
• openclaw/plugin-sdk/infra-runtime - システムイベント、Heartbeat の状態、 配信キュー、フェッチ／プロキシヘルパー、ファイルヘルパー、承認型、 および無関係なユーティリティを混在させていた広範なバレルです。
• openclaw/plugin-sdk/config-runtime - 後続の互換期間のためだけに維持されていた 広範な設定バレルです。ランタイムを直接読み書きするヘルパーは削除されています。
• openclaw/extension-api - 組み込みエージェントランナーなどの ホスト側ヘルパーへの直接アクセスを Plugin に提供していた、削除済みのブリッジです。
• api.registerEmbeddedExtensionFactory(...) - tool_result などの組み込みランナーイベントを 監視していた、組み込みランナー専用の削除済みフックです。代わりにエージェントの ツール結果ミドルウェアを使用してください（組み込みツール結果拡張機能を ミドルウェアへ移行するを参照）。

ルート SDK、互換バレル、拡張機能ブリッジ、および組み込み拡張機能ファクトリは 削除されました。infra-runtime と config-runtime は、個別に記録された後続の 互換期間のためだけに残されています。新しい Plugin では、目的を絞ったサブパスを使用してください。

OpenClaw は、代替機能を導入するのと同じ変更で、文書化された Plugin の動作を 削除したり再解釈したりすることはありません。コントラクトを破壊する変更には、 まず互換アダプター、診断、ドキュメント、および非推奨期間が設けられます。 これは SDK インポート、マニフェストフィールド、セットアップ API、フック、 およびランタイム登録の動作に適用されます。

理由

• 起動の遅延 - 1 つのヘルパーをインポートすると、数十個の無関係なモジュールが読み込まれていました。
• 循環依存 - 広範な再エクスポートにより、インポートサイクルが 容易に発生していました。
• 不明確な API サーフェス - 安定したエクスポートと内部用エクスポートを 区別する方法がありませんでした。

現在、各 openclaw/plugin-sdk/<subpath> は、文書化されたコントラクトを持つ 小規模で自己完結したモジュールになっています。

バンドルされたチャンネル向けの従来のプロバイダー便利機能も廃止されました。 チャンネル固有のヘルパーショートカットは、非公開のモノリポ用便利機能であり、 安定した Plugin コントラクトではありませんでした。代わりに、範囲の狭い汎用 SDK サブパスを使用してください。バンドルされた Plugin ワークスペース内では、 プロバイダー所有のヘルパーを、その Plugin 自身の api.ts または runtime-api.ts に配置してください。

• Anthropic は、Claude 固有のストリームヘルパーを自身の api.ts / contract-api.ts シームに保持します。
• OpenAI は、プロバイダービルダー、デフォルトモデルヘルパー、およびリアルタイムプロバイダー ビルダーを自身の api.ts に保持します。
• OpenRouter は、プロバイダービルダーおよびオンボーディング／設定ヘルパーを自身の api.ts に保持します。

互換性ポリシー

外部 Plugin の互換性対応は、次の順序で進めます。

1. 新しいコントラクトを追加する。
2. 互換アダプターを介して従来の動作を維持する。
3. 従来のパスと代替先を明記した診断または警告を出力する。
4. 両方のパスをテストで網羅する。
5. 非推奨化と移行手順を文書化する。
6. 告知した移行期間が終了した後、通常はメジャーリリースでのみ 削除する。

マニフェストフィールドが引き続き受け入れられている場合は、ドキュメントと 診断で別途指示されるまで使用を続けてください。新しいコードでは文書化された 代替機能を優先する必要がありますが、既存の Plugin が通常のマイナーリリースで 動作しなくなることはありません。

公開済みチャンネルセットアップの互換性

2026.7.1 を通じて公開された Slack、Discord、Signal、および Microsoft Teams パッケージは、openclaw/plugin-sdk/bundled-channel-config-schema からチャンネル固有の設定スキーマを インポートします。公開済みの Slack および Discord パッケージは、 openclaw/plugin-sdk/setup-runtime から createLegacyCompatChannelDmPolicy と promptLegacyChannelAllowFromForAccount もインポートします。

これらのエクスポートは、非推奨のランタイム互換アダプターとして引き続き利用できます。 新しい Plugin および再公開される Plugin は、channel-config-schema と setup-runtime の汎用プリミティブを使用し、設定スキーマとセットアップポリシーを ローカルで所有する必要があります。互換エクスポートを削除できるのは、 サポート対象となる公開済みパッケージの最小バージョンが、それらをインポートしなくなった後だけです。

チャンネルセットアップ入力フィールドの互換性

ChannelSetupInput では、チャンネル間で共通のセットアップエンベロープだけが 恒久的に型付けされるようになりました。チャンネル固有のフィールドは、 既存の外部 Plugin が引き続きコンパイルできるよう、Plugin 作成者がそれらのフィールドを Plugin ローカルのセットアップ入力型へ移行するまで、非推奨の互換性階層で型付けされます。

OpenClaw はメジャーリリースを提供しません。2026-07-22 のレジストリ調査では、 公開済みのツリー外チャンネル Plugin 426 個を検査し、読み取り元のない 21 個のフィールドを削除しました。 維持された 22 個のフィールドには、それぞれ既知の公開済み読み取り元があります。以後の各フィールドは、 公開済み Plugin から読み取られなくなり次第削除されます。Plugin 作成者が Plugin ローカルの セットアップ入力型へ移行するにつれて、維持されるフィールド群は縮小します。

同じ調査で、公開済みの依存先がない従来の未宣言アダプター昇格キー 23 個も削除されました。 一般的な 6 個のキーと、セットアップ専用の rooms キーは残されています。 公開済み Plugin が singleAccountKeysToMove を宣言するにつれて、このキー群も縮小します。

共有型にはインデックスシグネチャがありません。Plugin 所有のキーはランタイム入力オブジェクト上に 引き続き存在できますが、Plugin ローカルの交差型で宣言するか、所有する Plugin の セットアップスキーマを通じて絞り込んでください。

従来の未宣言アダプター昇格階層も、同じ読み取り元主導のポリシーに従います。 Plugin に追加の昇格キーが不要な場合は空配列を含めて singleAccountKeysToMove を宣言し、 共有フォールバックをキーごとに廃止できるようにしてください。

読み取り元の検証

1. 各 nextCursor を使用して https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100 をページ送りし、categories に channels が含まれるパッケージを保持します。
2. npm search --json --searchlimit=1000 "openclaw channel plugin" から npm の候補を追加します。openclaw/plugin-sdk/channel-setup、openclaw/plugin-sdk/setup、および openclaw/plugin-sdk/core を対象とした GitHub コード検索から、ソースのみの候補を追加します。
3. 各候補の公開済み最新バージョンを特定します。npm pack <package>@<version> --json --pack-destination <temp-dir> を実行して展開し、出荷された dist の JavaScript と宣言を調べ、フィールドの直接読み取りまたは分割代入による読み取りを確認します。パッケージに npm リリースがない場合は、ClawHub アーティファクトをダウンロードします。
4. パッケージ、バージョン、フィールドまたは昇格キー、および一致したファイルを記録します。フィールドまたはキーを削除できるのは、公開済みの Plugin アーティファクトから読み取られていない場合だけです。維持されるフィールドおよびキーのリストの横にあるコードコメント内の読み取り元名を、調査結果と同期させてください。

これはソース／型の互換性に関する記録だけです。ランタイムのセットアップ入力オブジェクトと セットアップ動作は変更されていないため、ランタイムアダプターや互換性レジストリの エントリはありません。

現在の移行キューを pnpm plugins:boundary-report で監査します。

pnpm plugins:boundary-report:ci は、3 つすべての失敗フラグを指定して実行されます。非推奨の レコードには通常、曖昧な「次のメジャーリリース」ではなく、明示的な removeAfter 日付が設定されます。所有者が日付を承認していないレコードでは、 removeAfter が存在せず、no-date として表示され、削除対象にはなりません。 レポートは非推奨レコードを日付別にグループ化し、ローカルのコード／ドキュメント参照を数え、 所有者をまたぐ予約済み SDK インポートを表示し、非公開のメモリホスト SDK ブリッジを 要約します。予約済み SDK サブパスには、追跡対象となる所有者の使用実績が必要です。 使用されていない予約済みエクスポートは、公開 SDK から削除する必要があります。

メディアの従来形式への投影

media-legacy-projection 互換性レコードは、従来の並列メディアフィールド、 ペイロードビルダー、フックメタデータのエイリアス、およびメディアテンプレート名を対象とします。 承認済みの removeAfter 日付は 2026-10-01 です（ファクト優先の代替機能が 出荷されてから 2 回のリリース周期後）。削除には、その時点で公開済み Plugin アーティファクトの調査結果がクリーンであることも必要です。日付より前に移行してください。

チャンネルの受信処理では、単数形／複数形の MediaPath、MediaUrl、 MediaType、MediaPaths、MediaUrls、MediaTypes、 MediaTranscribedIndexes、MediaWorkspaceDir、および MediaStaged を、順序付きの ファクトに置き換えてください。

 const media = toInboundMediaFacts([  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },]); const ctx = finalizeInboundContext({ Body: caption, media });

inbound_claim および message_received フックでは event.media を使用してください。 リモートメディアがローカルにステージングされていない場合、識別／診断には event.originalMedia を使用し、event.media を待機してください。 event.mediaStagingPending はその状態を区別します。event.metadata から非推奨の 単数形／複数形プロパティを読み取らないでください。

CLI メディアモデルでは、{{MediaPath}}、{{MediaUrl}}、{{MediaType}}、 および {{MediaDir}} を、{{AttachmentPath}}、{{AttachmentUrl}}、 {{AttachmentContentType}}、および {{AttachmentDir}} に置き換えてください。 添付ファイルの位置が重要な場合は、{{AttachmentIndex}} を使用してください。

ローカルメディアの読み取りポリシーには、openclaw/plugin-sdk/media-local-roots から getAgentScopedMediaLocalRoots(...) または getAgentScopedMediaLocalRootsForSources(...) をインポートしてください。 openclaw/plugin-sdk/agent-media-payload ファサードと、その buildAgentMediaPayload(...) 投影は非推奨です。

移行方法

await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

// OpenClaw ランタイムツールと Codex ランタイムの動的ツール（結果は// 変換される場合があります）。Codex ネイティブのツール結果も監視用に中継されますが、// 変換後の出力がモデルに届くことはありません。Codex の// PostToolUse フック契約では、ネイティブツールの応答を置き換えられないためです。api.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"]  }}

// 変更前const program = applyWindowsSpawnProgramPolicy({ candidate }); // 変更後const program = applyWindowsSpawnProgramPolicy({  candidate,  // シェルを介したフォールバックを意図的に許容する、信頼済みの  // 互換性維持用呼び出し元でのみ設定してください。  allowShellFallback: true,});

grep -r "plugin-sdk/compat" my-plugin/grep -r "plugin-sdk/infra-runtime" my-plugin/grep -r "plugin-sdk/config-runtime" my-plugin/grep -r "openclaw/extension-api" my-plugin/

// 変更前（非推奨の後方互換レイヤー）import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // 変更後（最新の用途別インポート）import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";

// 変更前（非推奨の extension-api ブリッジ）import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // 変更後（注入されたランタイム）const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

インポートパスのリファレンス

インポート可能な SDK サブパスについては、公開パッケージのエクスポートマップが 信頼できる唯一の情報源です。SDK の概要からリンクされている トピック別 SDK ガイドを使用し、文書化された公開サブパスのうち最も限定的なものを 優先してください。scripts/lib/plugin-sdk-entrypoints.json のコンパイラインベントリには、 バンドル済み Plugin のビルドに使用されるプライベートローカルエントリも含まれますが、 そこに存在していても公開パッケージのエクスポートにはなりません。

この表は一般的な移行対象の一部であり、SDK サーフェス全体ではありません。 コンパイラのエントリポイントインベントリは scripts/lib/plugin-sdk-entrypoints.json にあり、 パッケージのエクスポートは公開対象のサブセットから生成されます。

バンドル済み Plugin 専用として予約されていたヘルパー境界は、公開 SDK エクスポートマップから廃止されました。ただし、公開済みの @openclaw/discord パッケージを引き続き直接インポートする外部 Plugin のために保持されている、 非推奨の plugin-sdk/discord シムなど、明示的に文書化された互換性ファサードは 除きます。所有者固有のヘルパーは、その所有元の Plugin パッケージ内に配置されます。 共有ホスト動作は、plugin-sdk/gateway-runtime、plugin-sdk/security-runtime、 注入された Plugin API などの汎用 SDK 契約を通じて提供されます。

用途に合致する最も限定的なインポートを使用してください。エクスポートが見つからない場合は、 src/plugin-sdk/ のソースを確認するか、どの汎用契約が所有すべきかを メンテナーに確認してください。

削除された互換性サーフェス

2026 年 7 月の整理では、ルート SDK および compat バレル、extension API ブリッジ、期限切れの SDK サブパスエイリアス、未使用の SDK サブパス、 バンドル専用 SDK モジュールの公開エクスポートが削除されました。バンドル専用モジュールは、 プライベートローカルのビルドマッピングを通じてリポジトリ内の所有者が引き続き利用できますが、 公開パッケージからはインポートできません。

プロセスグローバルな API プロバイダーの公開

registerApiProvider(...) と unregisterApiProviders(...) は、 openclaw/plugin-sdk/llm から削除されました。これらは API トランスポートを プロセスグローバル状態へ公開していたため、ライフサイクルによって所有されるモデルランタイムが、 準備済みの各レジストリへコピーする必要がありました。

プロバイダー Plugin は、api.registerProvider(...) を通じて テキスト推論プロバイダーを登録してください。ApiRegistry を構築する ホスト所有のコードとテストは、そのレジストリへ直接登録し、プロバイダーの所有権と 破棄処理が準備済みランタイムのスコープ内に収まるようにしてください。

プライベートテスト用バレル

openclaw/plugin-sdk/testing はリポジトリローカルであり、配布パッケージの 成果物から除外されていたため、2026-07-28 の removeAfter 日より前に 削除されました。リポジトリのテストでは、plugin-sdk/plugin-test-runtime、 plugin-sdk/channel-test-helpers、plugin-sdk/channel-target-testing、 plugin-sdk/test-env、plugin-sdk/test-fixtures などの用途別サブパスを使用します。

移行リファレンス

これらのマッピングは、2026年7月に削除されたサーフェスと、それ以降の期間に有効な非推奨項目の両方を対象としています。マッピングは移行ガイダンスであり、古いサーフェスが引き続き利用可能であることを示すものではありません。現在の状態については、互換性レジストリと削除タイムラインを参照してください。

// 変更前import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // 変更後import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// 変更前api.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // 変更後api.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// 変更前api.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // 変更後api.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

// 変更前const flow = api.runtime.tasks.flow.fromToolContext(ctx);// 変更後const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// 変更前import type { OpenClawSchemaType } from "openclaw/plugin-sdk";// 変更後import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

Talk とリアルタイム音声の移行

リアルタイム音声、電話、会議、およびブラウザの Talk コードは、 openclaw/plugin-sdk/realtime-voice によってエクスポートされる単一の Talk セッションコントローラーを共有します。このコントローラーは、共通の Talk イベントエンベロープ、 アクティブなターン状態、キャプチャ状態、出力音声状態、最近のイベント履歴、 および古いターンの拒否を管理します。プロバイダー Plugin はベンダー固有のリアルタイムセッションを 管理します。ブラウザ会議 Plugin は、セッション、ブラウザ、音声、Node ホスト、 エージェント相談、および音声通話の仕組みに openclaw/plugin-sdk/meeting-runtime を使用し、その後、 URL ルール、DOM スクリプト、手動アクションのマッピング、字幕、作成、およびダイヤルイン プランのために MeetingPlatformAdapter を実装します。プラットフォームの REST API、 OAuth、アーティファクト、セレクター、およびワイヤー名は Plugin 内に残ります。 ブラウザ権限プランは要求された会議 URL を受け取り、各プラットフォームが正確にサポートする オリジンだけを許可できるようにします。セッションランタイムは、ブラウザからの退出が確認された後、 プラットフォーム固有のライブ健全性も正規化する必要があります。過去の文字起こしフィールドは 残っていてもかまいませんが、退出後に字幕と音声の準備状態がアクティブなままであってはなりません。

すべてのバンドル済みサーフェスは共有コントローラー上で動作します。対象はブラウザリレー、 管理対象ルームへの引き継ぎ、音声通話リアルタイム、音声通話ストリーミング STT、Google Meet リアルタイム、およびネイティブのプッシュトゥトークです。Gateway は hello-ok.features.events で単一のライブ Talk イベントチャネル talk.event を通知します。

低レベルのアダプターまたはテストフィクスチャを実装する場合を除き、新しいコードから createTalkEventSequencer(...) を直接呼び出さないでください。共有コントローラーを使用することで、 ターン ID なしにターンスコープのイベントが発行されること、古い turnEnd / turnCancel 呼び出しがより新しいアクティブなターンをクリアすることを防ぎ、 電話、会議、ブラウザリレー、管理対象ルームへの引き継ぎ、およびネイティブ Talk クライアント間で 出力音声のライフサイクルイベントの一貫性を維持できます。

公開 API の形状は次のとおりです。

// Gateway が所有する Talk セッション API。await gateway.request("talk.session.create", {  mode: "realtime",  transport: "gateway-relay",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "working" },  options: { willContinue: true },});await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "already_delivered" },  options: { suppressResponse: true },});await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });await gateway.request("talk.session.close", { sessionId }); // クライアントが所有するプロバイダーセッション API。await gateway.request("talk.client.create", {  mode: "realtime",  transport: "webrtc",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

ブラウザが所有する WebRTC／プロバイダー WebSocket セッションでは talk.client.create を使用します。これは、ブラウザがプロバイダーとのネゴシエーションと メディア転送を所有し、Gateway が認証情報、指示、およびツールポリシーを所有するためです。 talk.session.* は、Gateway リレーのリアルタイム、Gateway リレーの文字起こし、 および管理対象ルームのネイティブ STT／TTS セッションに共通する Gateway 管理サーフェスです。

talk.provider / talk.providers の横にリアルタイムセレクターを 配置しているレガシー設定は、openclaw doctor --fix で修復する必要があります。ランタイムの Talk は、音声／TTS プロバイダー設定をリアルタイムプロバイダー設定として再解釈しません。

サポートされる talk.session.create の組み合わせは、意図的に少数に限定されています。

古い talk.realtime.* / talk.transcription.* / talk.handoff.* ファミリー（すべて削除済み）から移行する読者向けのメソッド対応表です。

統合された制御用語も、意図的に狭く限定されています。

これを機能させるために、コアへプロバイダーまたはプラットフォームの特殊ケースを導入しないでください。 コアは Talk セッションのセマンティクスを所有します。プロバイダー Plugin はベンダーセッションのセットアップを 所有します。音声通話と Google Meet は電話／会議アダプターを所有します。ブラウザアプリとネイティブ アプリはデバイスのキャプチャ／再生 UX を所有します。

削除タイムライン

以下の残りの公開 SDK サブパスには、レジストリに基づく削除猶予期間があります。 7月30日の行は、メンテナーが事前承認した早期整理の後に削除されました。 未使用のサブパスと以前の互換性エイリアスは削除され、 バンドル専用モジュールはプライベートなローカルビルドマッピングに降格されました。

すべてのコア Plugin はすでに移行済みです。外部 Plugin は、 次回のメジャーリリースまでに移行する必要があります。Plugin が使用しているサーフェスについて、 期限が最も近い互換性レコードを確認するには pnpm plugins:boundary-report を実行してください。

警告を一時的に抑制する

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

これは一時的な回避策であり、恒久的な解決策ではありません。

関連項目

• はじめに - 最初の Plugin を構築する
• SDK の概要 - サブパスインポートの完全なリファレンス
• チャンネル Plugin - チャンネル Plugin の構築
• プロバイダー Plugin - プロバイダー Plugin の構築
• Plugin の内部構造 - アーキテクチャの詳細解説
• Plugin マニフェスト - マニフェストスキーマのリファレンス