Plugin SDK 移行

OpenClaw は、広範な後方互換性レイヤーから、焦点を絞った文書化済み import を備えたモダンな Plugin アーキテクチャへ移行しました。Plugin が新しいアーキテクチャ以前に作られていた場合、このガイドが移行を支援します。

変更内容

古い Plugin システムは、Plugin が必要なものを単一のエントリポイントから何でも import できる、広く開かれた 2 つのサーフェスを提供していました。

• openclaw/plugin-sdk/compat - 数十個のヘルパーを再 export する単一の import です。 新しい Plugin アーキテクチャが構築されている間、古い hook ベースの Plugin を動かし続けるために導入されました。
• openclaw/plugin-sdk/infra-runtime - システムイベント、Heartbeat 状態、配信キュー、fetch/proxy ヘルパー、 ファイルヘルパー、承認タイプ、無関係なユーティリティを混在させた、広範なランタイムヘルパー barrel です。
• openclaw/plugin-sdk/config-runtime - 移行期間中、非推奨の直接 load/write ヘルパーをまだ含んでいる、 広範な設定互換 barrel です。
• openclaw/extension-api - 組み込みエージェントランナーのようなホスト側ヘルパーへ Plugin が直接アクセスできるようにする ブリッジです。
• api.registerEmbeddedExtensionFactory(...) - tool_result などの埋め込みランナーイベントを監視できた、 削除済みの埋め込みランナー専用バンドル extension hook です。

広範な import サーフェスは現在 非推奨 です。ランタイムではまだ動作しますが、 新しい Plugin は使用してはならず、既存の Plugin は次のメジャーリリースで削除される前に移行する必要があります。 埋め込みランナー専用の extension factory 登録 API は削除されました。代わりに tool-result middleware を使用してください。

OpenClaw は、置き換えを導入するのと同じ変更で、文書化済みの Plugin 動作を削除したり再解釈したりしません。 契約を破る変更は、まず互換アダプター、診断、ドキュメント、非推奨期間を経る必要があります。 これは SDK import、manifest フィールド、setup API、hook、ランタイム登録動作に適用されます。

変更理由

古いアプローチには問題がありました。

• 起動が遅い - 1 つのヘルパーを import すると、無関係なモジュールが数十個読み込まれる
• 循環依存 - 広範な再 export によって import cycle を作りやすかった
• API サーフェスが不明確 - どの export が安定していて、どれが内部向けなのか判断できなかった

モダンな Plugin SDK はこれを解決します。各 import パス（openclaw/plugin-sdk/\<subpath\>）は、 明確な目的と文書化済みの契約を持つ、小さく自己完結したモジュールです。

バンドル済み channel 向けのレガシーな provider convenience seam も廃止されました。 channel ブランドの helper seam はプライベートな monorepo ショートカットであり、安定した Plugin 契約ではありません。代わりに、狭い汎用 SDK subpath を使用してください。バンドル済み Plugin ワークスペース内では、provider 所有のヘルパーをその Plugin 自身の api.ts または runtime-api.ts に置いてください。

現在のバンドル済み provider 例:

• Anthropic は Claude 固有の stream ヘルパーを自身の api.ts / contract-api.ts seam に保持します
• OpenAI は provider builder、default-model ヘルパー、realtime provider builder を自身の api.ts に保持します
• OpenRouter は provider builder とオンボーディング/config ヘルパーを自身の api.ts に保持します

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

リアルタイム音声、テレフォニー、ミーティング、ブラウザーの Talk コードは、 サーフェスローカルの turn bookkeeping から、openclaw/plugin-sdk/realtime-voice が export する共有 Talk session controller へ移行しています。 新しい controller は、共通の Talk event envelope、active turn state、capture state、output-audio state、recent event history、stale-turn rejection を所有します。Provider Plugin は vendor 固有の realtime session を所有し続けるべきです。 surface Plugin は capture、playback、telephony、meeting の癖を所有し続けるべきです。

この Talk 移行は、意図的に breaking-clean です。

1. 共有 controller/runtime primitive を plugin-sdk/realtime-voice に保持します。
2. バンドル済み surface を共有 controller へ移行します: browser relay、 managed-room handoff、voice-call realtime、voice-call streaming STT、Google Meet realtime、native push-to-talk。
3. 古い Talk RPC family を最終版の talk.session.* と talk.client.* API に置き換えます。
4. Gateway hello-ok.features.events で 1 つの live Talk event channel を通知します: talk.event。
5. 古い realtime HTTP endpoint と、request-time instruction override path を削除します。

低レベル adapter または test fixture を実装している場合を除き、新しいコードは createTalkEventSequencer(...) を直接呼び出すべきではありません。 共有 controller を優先してください。これにより、turn id なしで turn-scoped event が emit されることを防ぎ、 stale な turnEnd / turnCancel 呼び出しが新しい active turn をクリアできなくなり、output-audio lifecycle event が telephony、meeting、browser relay、managed-room handoff、native Talk client 間で一貫します。

対象となる公開 API 形状は次のとおりです。

// Gateway-owned Talk session 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 }); // Client-owned provider session 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/provider-websocket session は talk.client.create を使用します。 これは、ブラウザーが provider negotiation と media transport を所有し、Gateway が credentials、instructions、tool policy を所有するためです。 talk.session.* は、gateway-relay realtime、gateway-relay transcription、managed-room native STT/TTS session のための共通の Gateway 管理 surface です。

talk.provider / talk.providers の横に realtime selector を置いていたレガシー config は、openclaw doctor --fix で修復する必要があります。ランタイムの Talk は、 speech/TTS provider config を realtime provider config として再解釈しません。

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

削除された method の対応表:

統一された control vocabulary も、意図的に狭くしています。

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

互換性ポリシー

外部 Plugin の互換性作業は、次の順序に従います。

1. 新しい契約を追加する
2. 古い動作を互換性アダプター経由で接続したままにする
3. 古いパスと置き換え先を明示する診断または警告を出す
4. 両方のパスをテストでカバーする
5. 非推奨化と移行パスを文書化する
6. 通知済みの移行期間後、通常はメジャーリリースでのみ削除する

メンテナーは現在の移行キューを pnpm plugins:boundary-report で監査できます。 コンパクトな件数には pnpm plugins:boundary-report:summary を、単一の Plugin または互換性オーナーには --owner <id> を、 期限到来の互換性レコード、オーナーをまたぐ予約済み SDK インポート、または未使用の予約済み SDK サブパスで CI ゲートを失敗させる必要がある場合は pnpm plugins:boundary-report:ci を使用します。レポートは、削除日ごとに非推奨の 互換性レコードをグループ化し、ローカルコード/ドキュメント参照を数え、 オーナーをまたぐ予約済み SDK インポートを表面化し、プライベートな memory-host SDK ブリッジを要約するため、互換性のクリーンアップを 場当たり的な検索に頼るのではなく明示的に保てます。予約済み SDK サブパスには追跡されたオーナー使用が必要です。 未使用の予約済みヘルパーエクスポートは、公開 SDK から削除する必要があります。

manifest フィールドがまだ受け入れられている場合、Plugin 作者は ドキュメントと診断が別のことを示すまで使い続けられます。新しいコードでは文書化された 置き換え先を優先すべきですが、既存の Plugin が通常のマイナー リリース中に壊れてはなりません。

移行方法

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

// OpenClaw and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

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

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Only set this for trusted compatibility callers that intentionally  // accept shell-mediated fallback.  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/

// Before (deprecated backwards-compatibility layer)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // After (modern focused imports)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";

// Before (deprecated extension-api bridge)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

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

この表は、SDK サーフェス全体ではなく、意図的に共通の移行サブセットに絞っています。コンパイラのエントリポイントインベントリは scripts/lib/plugin-sdk-entrypoints.json にあり、パッケージのエクスポートは公開サブセットから生成されます。

予約済みのバンドル Plugin ヘルパーの継ぎ目は、公開 SDK エクスポートマップから廃止されました。ただし、公開済みの @openclaw/discord@2026.3.13 パッケージ向けに保持されている非推奨の plugin-sdk/discord シムのような、明示的に文書化された互換性ファサードは例外です。所有者固有のヘルパーは、それを所有する Plugin パッケージ内にあります。共有ホストの動作は、plugin-sdk/gateway-runtime、plugin-sdk/security-runtime、plugin-sdk/plugin-config-runtime のような汎用 SDK コントラクトを通す必要があります。

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

有効な非推奨項目

Plugin SDK、プロバイダーコントラクト、ランタイムサーフェス、マニフェスト全体に適用される、より範囲の狭い非推奨項目です。いずれも現在はまだ動作しますが、将来のメジャーリリースで削除されます。各項目の下のエントリは、古い API を正規の置き換え先に対応付けています。

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

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

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

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

削除タイムライン

すべてのコアプラグインはすでに移行済みです。外部プラグインは 次のメジャーリリースまでに移行する必要があります。

警告を一時的に抑制する

移行作業中は、これらの環境変数を設定します。

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

関連

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