Plugin SDKの移行

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

何が変わるのか

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

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

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

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

なぜ変更されたのか

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

• 起動が遅い - 1 つのヘルパーを import すると、数十個の無関係なモジュールが読み込まれる
• 循環依存 - 広範な再エクスポートにより import サイクルを作りやすかった
• 不明確な API サーフェス - どの export が安定版で、どれが内部用かを判別する方法がなかった

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

バンドルチャンネル向けのレガシーなプロバイダー利便性シームも削除されました。 チャンネル名付きのヘルパーシームは、安定した Plugin 契約ではなく、非公開のモノレポ内 ショートカットでした。代わりに、狭い汎用 SDK サブパスを使用してください。バンドル Plugin ワークスペース内では、プロバイダー所有のヘルパーをその Plugin 自身の api.ts または runtime-api.ts に置いてください。

現在のバンドルプロバイダー例:

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

Talk と realtime 音声の移行計画

Realtime 音声、電話、会議、ブラウザー Talk コードは、サーフェスローカルなターン管理から、 openclaw/plugin-sdk/realtime-voice が export する共有 Talk セッションコントローラーへ移行しています。 新しいコントローラーは、共通の Talk イベントエンベロープ、アクティブターン状態、キャプチャ状態、 出力音声状態、最近のイベント履歴、古いターンの拒否を所有します。プロバイダー Plugin は ベンダー固有の realtime セッションを引き続き所有し、サーフェス Plugin はキャプチャ、再生、 電話、会議の癖を引き続き所有する必要があります。

この Talk 移行は、意図的に破壊的かつクリーンなものです。

1. 共有コントローラー/ランタイムプリミティブを plugin-sdk/realtime-voice に保持します。
2. バンドルサーフェスを共有コントローラーへ移動します: ブラウザーリレー、 managed-room ハンドオフ、voice-call realtime、voice-call streaming STT、Google Meet realtime、ネイティブ push-to-talk。
3. 古い Talk RPC ファミリーを最終的な talk.session.* と talk.client.* API に置き換えます。
4. Gateway hello-ok.features.events で 1 つのライブ Talk イベントチャンネル talk.event を通知します。
5. 古い realtime HTTP エンドポイントと、リクエスト時の instruction override パスを削除します。

新しいコードは、低レベルアダプターまたはテストフィクスチャを実装している場合を除き、 createTalkEventSequencer(...) を直接呼び出すべきではありません。共有コントローラーを優先してください。 これにより、ターン ID なしでターンスコープイベントが送信されることを防ぎ、古い turnEnd / turnCancel 呼び出しが新しいアクティブターンを消去することを防ぎ、出力音声ライフサイクル イベントを電話、会議、ブラウザーリレー、managed-room ハンドオフ、ネイティブ Talk クライアント間で 一貫させます。

対象となる公開 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 });

ブラウザー所有の WebRTC/provider-websocket セッションは talk.client.create を使用します。 これは、ブラウザーがプロバイダーのネゴシエーションとメディアトランスポートを所有し、Gateway が 認証情報、instructions、ツールポリシーを所有するためです。talk.session.* は、gateway-relay realtime、 gateway-relay transcription、managed-room ネイティブ STT/TTS セッション向けの共通 Gateway 管理サーフェスです。

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

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

削除されたメソッド対応表:

統一された制御語彙も、意図的に狭くなっています。

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

互換性ポリシー

外部 Plugin の互換性対応は、次の順序に従う。

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

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

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

移行方法

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

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

{  "contracts": {    "agentToolResultMiddleware": ["pi", "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 { runEmbeddedPiAgent } from "openclaw/extension-api";const result = await runEmbeddedPiAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

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

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

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

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

有効な非推奨

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

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

{  "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";

削除タイムライン

すべてのコア Plugin はすでに移行済みです。外部 Plugin は次のメジャーリリース前に移行してください。

警告を一時的に抑制する

移行作業中は、これらの環境変数を設定してください。

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

関連

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