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 ヘルパー、 ファイルヘルパー、承認型、無関係なユーティリティを混在させた、広範な runtime ヘルパー barrel です。
• openclaw/plugin-sdk/config-runtime - 移行期間中に非推奨の直接 load/write ヘルパーをまだ保持している、 広範な config 互換性 barrel です。
• openclaw/extension-api - embedded agent runner のような host 側ヘルパーへ Plugin が直接アクセスできるようにする bridge です。
• api.registerEmbeddedExtensionFactory(...) - tool_result などの embedded-runner イベントを監視できた、 削除済みの Pi 専用 bundled extension hook です。

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

OpenClaw は、置き換えを導入する同じ変更で、文書化済みの Plugin 動作を 削除したり再解釈したりしません。破壊的な contract 変更は、まず 互換 adapter、diagnostics、docs、非推奨期間を経る必要があります。 これは SDK import、manifest field、setup API、hook、runtime 登録動作に適用されます。

# 変更理由

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

• 起動が遅い - 1 つのヘルパーを import すると、数十個の無関係な module が load される
• 循環依存 - 広範な re-export により import cycle を作りやすい
• 不明瞭な API サーフェス - どの export が stable で、どれが internal か判別できない

最新の Plugin SDK はこれを解決します。各 import path (openclaw/plugin-sdk/\<subpath\>) は、明確な目的と文書化済み contract を持つ、小さく自己完結した module です。

bundled channel 向けの従来の provider convenience seam も廃止されました。 channel ブランドの helper seam は private mono-repo の shortcut であり、stable な Plugin contract ではありません。代わりに狭い generic SDK subpath を使用してください。bundled Plugin workspace 内では、provider 所有の helper をその Plugin 自身の api.ts または runtime-api.ts に保持してください。

現在の bundled provider の例:

• Anthropic は Claude 固有の stream helper を自身の api.ts / contract-api.ts seam に保持しています
• OpenAI は provider builder、default-model helper、realtime provider builder を自身の api.ts に保持しています
• OpenRouter は provider builder と onboarding/config helper を自身の api.ts に保持しています

# Talk と realtime voice の移行計画

Realtime voice、telephony、meeting、browser Talk code は、 surface-local な 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 の quirks を引き続き所有する必要があります。

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

1. 共有 controller/runtime primitive を plugin-sdk/realtime-voice に保持します。
2. bundled 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 を削除します。

新しい code は、low-level adapter または test fixture を実装している場合を除き、 createTalkEventSequencer(...) を直接呼び出すべきではありません。共有 controller を優先すると、 turn-scoped event が turn id なしで emit されることを防ぎ、古い turnEnd / turnCancel call がより新しい active turn を clear できず、telephony、meeting、browser relay、managed-room handoff、native Talk client 全体で output-audio lifecycle event の一貫性を保てます。

対象となる public API shape は次のとおりです。

// 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 });
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 });

browser 所有の WebRTC/provider-websocket session は talk.client.create を使用します。 browser が provider negotiation と media transport を所有し、 Gateway が credentials、instructions、tool policy を所有するためです。talk.session.* は、 gateway-relay realtime、gateway-relay transcription、managed-room native STT/TTS session 向けの共通 Gateway-managed surface です。

talk.provider / talk.providers の隣に realtime selector を置いていた legacy config は、openclaw doctor --fix で修復する必要があります。runtime Talk は speech/TTS provider config を realtime provider config として再解釈しません。

サポートされる talk.session.create の組み合わせは意図的に少数です。

削除された method map:

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

これを実現するために、core に provider や platform の special case を導入しないでください。 Core は Talk session semantics を所有します。Provider Plugin は vendor session setup を所有します。 Voice-call と Google Meet は telephony/meeting adapter を所有します。Browser と native app は device capture/playback UX を所有します。

# 互換性ポリシー

external Plugin では、互換性対応は次の順序に従います。

1. 新しい contract を追加する
2. 古い動作を compatibility adapter 経由で接続したままにする
3. 古い path と replacement を示す diagnostic または warning を emit する
4. 両方の path を test で cover する
5. 非推奨と移行 path を文書化する
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 作者は ドキュメントと診断が別の指示を出すまで使い続けられます。新しいコードではドキュメント化された 置き換えを優先するべきですが、既存の plugins が通常のマイナー リリース中に壊れないようにしてください。

# 移行方法

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

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

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

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const 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 build
pnpm test -- my-plugin/

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

この表は意図的に共通移行サブセットであり、SDK サーフェス全体ではありません。200 以上のエントリポイントの完全な一覧は scripts/lib/plugin-sdk-entrypoints.json にあります。

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

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

# 有効な非推奨項目

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

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

# 削除タイムライン

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

# 警告を一時的に抑制する

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

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

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

# 関連

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