メインコンテンツへスキップ
OpenClawは、広範な後方互換性レイヤーを、小さく焦点を絞ったインポートで構成された現代的なPlugin アーキテクチャに置き換えました。あなたのPluginがその変更以前のものである場合、このガイドはそれを現在のコントラクトへ移行するためのものです。

変更点

以前は、2つの広く開かれたインポート面により、Pluginは単一のエントリポイントからほぼ何にでもアクセスできました。
  • openclaw/plugin-sdk/compat - 新しいアーキテクチャの構築中に、古いフックベースのPluginを動作させ続けるため、数十個のヘルパーを再エクスポートしていました。
  • openclaw/plugin-sdk/infra-runtime - システムイベント、Heartbeat状態、配信キュー、fetch/proxyヘルパー、ファイルヘルパー、承認型、無関係なユーティリティを混在させた広範なバレルでした。
  • openclaw/plugin-sdk/config-runtime - 移行期間中に非推奨の直接load/writeヘルパーをまだ含んでいた、広範なconfigバレルでした。
  • openclaw/extension-api - 埋め込みエージェントランナーなど、ホスト側ヘルパーへの直接アクセスをPluginに与えるブリッジでした。
  • api.registerEmbeddedExtensionFactory(...) - tool_resultなどの埋め込みランナーイベントを監視する、削除済みの埋め込みランナー専用フックです。代わりにエージェントのtool-resultミドルウェアを使用してください(埋め込みtool-result拡張をミドルウェアへ移行するを参照)。
これらの面は非推奨です。まだ動作しますが、新しいPluginは使用してはならず、既存のPluginも次のメジャーリリースで削除される前に移行する必要があります。registerEmbeddedExtensionFactoryはすでに削除されています。レガシー登録はもうロードされません。
後方互換性レイヤーは将来のメジャーリリースで削除されます。 これらの面からまだインポートしているPluginは、その時点で壊れます。
OpenClawは、置き換えを導入する同じ変更で、ドキュメント化されたPluginの動作を削除または再解釈しません。破壊的なコントラクト変更は、まず互換性アダプター、診断、ドキュメント、非推奨期間を経由します。これはSDKインポート、manifestフィールド、セットアップAPI、フック、ランタイム登録の動作に適用されます。

理由

  • 起動が遅い - 1つのヘルパーをインポートすると、数十個の無関係なモジュールがロードされていました。
  • 循環依存 - 広範な再エクスポートにより、インポートサイクルを簡単に作成できました。
  • 不明確なAPI面 - 安定したエクスポートと内部用エクスポートを見分ける方法がありませんでした。
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はプロバイダービルダーとオンボーディング/configヘルパーを自身のapi.tsに保持します。

互換性ポリシー

外部Pluginの互換性作業は、次の順序に従います。
  1. 新しいコントラクトを追加する。
  2. 互換性アダプターを通して古い動作を接続したままにする。
  3. 古いパスと置き換え先を示す診断または警告を出す。
  4. 両方のパスをテストでカバーする。
  5. 非推奨化と移行パスをドキュメント化する。
  6. 発表された移行期間の後、通常はメジャーリリースでのみ削除する。
manifestフィールドがまだ受け付けられる場合は、ドキュメントと診断が別の指示を出すまで使い続けてください。新しいコードではドキュメント化された置き換えを優先する必要がありますが、既存のPluginは通常のマイナーリリース中に壊れるべきではありません。 現在の移行キューをpnpm plugins:boundary-reportで監査します。
フラグ効果
--summary(またはpnpm plugins:boundary-report:summary完全な詳細ではなくコンパクトな件数を表示します。
--json機械可読なレポート。
--owner <id>1つのPluginまたは互換性所有者に絞り込みます。
--fail-on-cross-owner所有者をまたぐ予約済みSDKインポートで非ゼロ終了します。
--fail-on-eligible-compat非推奨compatレコードのremoveAfter日付が過ぎている場合に非ゼロ終了します。
--fail-on-unclassified-unused-reserved未使用の分類されていない予約済みSDKシムで非ゼロ終了します。
pnpm plugins:boundary-report:ciは3つすべてのfailフラグを付けて実行されます。各互換性レコードには、曖昧な「次のメジャーリリース」ではなく、明示的なremoveAfter日付があります。レポートは非推奨レコードをその日付でグループ化し、ローカルのコード/ドキュメント参照を数え、所有者をまたぐ予約済みSDKインポートを表示し、プライベートなmemory-host SDKブリッジを要約します。予約済みSDKサブパスには、追跡された所有者利用が必要です。未使用の予約済みエクスポートは公開SDKから削除する必要があります。

移行方法

1

Migrate runtime config load/write helpers

バンドルされたPluginは、api.runtime.config.loadConfig()api.runtime.config.writeConfigFile(...)を直接呼び出すのをやめる必要があります。アクティブな呼び出しパスにすでに渡されているconfigを優先してください。現在のプロセススナップショットが必要な長寿命ハンドラーはapi.runtime.config.current()を使用できます。長寿命のエージェントツールは、config書き込み前に作成されたツールでも更新済みconfigを見られるように、execute内でctx.getRuntimeConfig()を読む必要があります。config書き込みは、明示的な書き込み後ポリシーを持つトランザクションヘルパーを通します。
await api.runtime.config.mutateConfigFile({
  afterWrite: { mode: "auto" },
  mutate(draft) {
    draft.plugins ??= {};
  },
});
変更にクリーンなgateway再起動が必要な場合はafterWrite: { mode: "restart", reason: "..." }を使用し、呼び出し元が後続処理を所有し、意図的にリロードプランナーを抑制する場合にのみafterWrite: { mode: "none", reason: "..." }を使用してください。ミューテーション結果には、テストとログ用の型付きfollowUp要約が含まれます。gatewayは引き続き、再起動の適用またはスケジュールを担当します。loadConfigwriteConfigFileは外部Plugin向けの非推奨互換性ヘルパーとして残り、runtime-config-load-write互換性コードで一度だけ警告します。バンドルされたPluginとリポジトリランタイムコードは、pnpm check:deprecated-api-usagepnpm check:no-runtime-action-load-configでガードされています。新しい本番Plugin利用は即座に失敗し、直接config書き込みは失敗し、gatewayサーバーメソッドはリクエストランタイムスナップショットを使用する必要があり、ランタイムチャンネルのsend/action/clientヘルパーは境界からconfigを受け取る必要があり、長寿命ランタイムモジュールでは周囲のloadConfig()呼び出しをゼロにする必要があります。新しいPluginコードでは、広範なopenclaw/plugin-sdk/config-runtimeバレルを避ける必要があります。用途に合った狭いサブパスを使用してください。
必要なものインポート
OpenClawConfigなどのconfig型openclaw/plugin-sdk/config-contracts
ロード済みconfigアサーションとPluginエントリconfig検索openclaw/plugin-sdk/plugin-config-runtime
現在のランタイムスナップショットの読み取りopenclaw/plugin-sdk/runtime-config-snapshot
config書き込みopenclaw/plugin-sdk/config-mutation
セッションストアヘルパーopenclaw/plugin-sdk/session-store-runtime
Markdownテーブルconfigopenclaw/plugin-sdk/markdown-table-runtime
グループポリシーランタイムヘルパーopenclaw/plugin-sdk/runtime-group-policy
secret入力解決openclaw/plugin-sdk/secret-input-runtime
モデル/セッションのオーバーライドopenclaw/plugin-sdk/model-session-runtime
バンドルされたPluginとそのテストは、インポートとモックが必要な動作に対してローカルに保たれるよう、広範なバレルに対してスキャナーでガードされています。バレルは外部互換性のためにまだ存在しますが、新しいコードはそれに依存すべきではありません。
2

Migrate embedded tool-result extensions to middleware

バンドルされたPluginは、埋め込みランナー専用の api.registerEmbeddedExtensionFactory(...) tool-resultハンドラーを、ランタイム中立なミドルウェアに置き換える必要があります。
// OpenClaw and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});
同時にPlugin manifestを更新します。
{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"]
  }
}
インストール済みPluginも、明示的に有効化され、対象となるすべてのランタイムがcontracts.agentToolResultMiddlewareで宣言されている場合、tool-resultミドルウェアを登録できます。宣言されていないインストール済みミドルウェア登録は拒否されます。
3

Migrate approval-native handlers to capability facts

承認対応チャンネルPluginは、approvalCapability.nativeRuntimeと共有runtime-contextレジストリを通じて、ネイティブ承認動作を公開します。
  • approvalCapability.handler.loadRuntime(...)approvalCapability.nativeRuntimeに置き換えます。
  • 承認固有のauth/deliveryをレガシーのplugin.auth / plugin.approvals配線から外し、approvalCapabilityへ移します。
  • ChannelPlugin.approvalsは公開channel-pluginコントラクトから削除されました。delivery/native/renderフィールドをapprovalCapabilityへ移してください。
  • plugin.authはチャンネルlogin/logoutフロー専用として残ります。coreはもうそこで承認authフックを読みません。
  • チャンネル所有のランタイムオブジェクト(clients、tokens、Bolt apps)はopenclaw/plugin-sdk/channel-runtime-contextを通じて登録します。
  • ネイティブ承認ハンドラーからPlugin所有の再ルーティング通知を送信しないでください。coreは実際の配信結果に基づく別ルート通知を所有します。
  • channelRuntimecreateChannelManager(...)へ渡す場合は、本物のcreatePluginRuntime().channel面を提供してください。部分スタブは拒否されます。
現在の承認capabilityレイアウトについては、Channel Pluginsを参照してください。
4

Audit Windows wrapper fallback behavior

あなたのPluginがopenclaw/plugin-sdk/windows-spawnを使用している場合、解決できないWindowsの.cmd/.batラッパーは、明示的にallowShellFallback: trueを渡さない限り、現在はfail closedします。
// 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,
});
呼び出し元がshell fallbackに意図的に依存していない場合は、allowShellFallbackを設定せず、代わりにスローされたエラーを処理してください。
5

Find deprecated imports

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/
6

Replace with focused imports

古い面の各エクスポートは、特定の現代的なインポートパスに対応します。
// 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";
ホスト側ヘルパーには、直接 import する代わりに、注入された Plugin ランタイムを使用します。
// 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 });
他のレガシーブリッジヘルパーにも同じパターンを適用します。
古い importモダンな同等機能
resolveAgentDirapi.runtime.agent.resolveAgentDir
resolveAgentWorkspaceDirapi.runtime.agent.resolveAgentWorkspaceDir
resolveAgentIdentityapi.runtime.agent.resolveAgentIdentity
resolveThinkingDefaultapi.runtime.agent.resolveThinkingDefault
resolveAgentTimeoutMsapi.runtime.agent.resolveAgentTimeoutMs
ensureAgentWorkspaceapi.runtime.agent.ensureAgentWorkspace
セッションストアヘルパーapi.runtime.agent.session.*
7

広範な infra-runtime import を置き換える

openclaw/plugin-sdk/infra-runtime は外部互換性のためにまだ存在しますが、新しいコードでは実際に必要な集約されたサーフェスを import してください。
必要なものImport
システムイベントキューヘルパーopenclaw/plugin-sdk/system-event-runtime
Heartbeat の wake、イベント、可視性ヘルパーopenclaw/plugin-sdk/heartbeat-runtime
保留中の配信キューの drainopenclaw/plugin-sdk/delivery-queue-runtime
チャネルアクティビティのテレメトリopenclaw/plugin-sdk/channel-activity-runtime
インメモリおよび永続バックエンド付き dedupe キャッシュopenclaw/plugin-sdk/dedupe-runtime
安全なローカルファイル/メディアパスヘルパーopenclaw/plugin-sdk/file-access-runtime
Dispatcher 対応 fetchopenclaw/plugin-sdk/runtime-fetch
プロキシおよびガード付き fetch ヘルパーopenclaw/plugin-sdk/fetch-runtime
SSRF dispatcher ポリシー型openclaw/plugin-sdk/ssrf-dispatcher
承認リクエスト/解決型openclaw/plugin-sdk/approval-runtime
承認返信ペイロードおよびコマンドヘルパーopenclaw/plugin-sdk/approval-reply-runtime
エラー整形ヘルパーopenclaw/plugin-sdk/error-runtime
トランスポート準備完了待機openclaw/plugin-sdk/transport-ready-runtime
セキュアトークンヘルパーopenclaw/plugin-sdk/secure-random-runtime
境界付き非同期タスク並行実行openclaw/plugin-sdk/concurrency-runtime
数値変換openclaw/plugin-sdk/number-runtime
プロセスローカル非同期ロックopenclaw/plugin-sdk/async-lock-runtime
ファイルロックopenclaw/plugin-sdk/file-lock
バンドル Plugin は infra-runtime に対してスキャナーでガードされているため、リポジトリ内コードが広範な barrel に戻ることはできません。
8

チャネルルートヘルパーを移行する

新しいチャネルルートコードでは openclaw/plugin-sdk/channel-route を使用します。古い route-key 名と comparable-target 名は互換エイリアスとして残っています。
古いヘルパーモダンなヘルパー
channelRouteIdentityKey(...)channelRouteDedupeKey(...)
channelRouteKey(...)channelRouteCompactKey(...)
ComparableChannelTargetChannelRouteParsedTarget
comparableChannelTargetsMatch(...)channelRouteTargetsMatchExact(...)
comparableChannelTargetsShareRoute(...)channelRouteTargetsShareConversation(...)
モダンなルートヘルパーは、ネイティブ承認、返信抑制、受信 dedupe、Cron 配信、セッションルーティング全体で { channel, to, accountId, threadId } を一貫して正規化します。plugin-sdk/channel-routeChannelMessagingAdapter.parseExplicitTarget、パーサーバックの loaded-route ヘルパー(parseExplicitTargetForLoadedChannelresolveRouteTargetForLoadedChannel)、または resolveChannelRouteTargetWithParser(...) の新しい使用は追加しないでください。これらは非推奨で、古い Plugin のためだけに残っています。新しいチャネル Plugin は、target-id 正規化とディレクトリ未検出時のフォールバックには messaging.targetResolver.resolveTarget(...) を、core が早期に peer 種別を必要とする場合には messaging.inferTargetChatType(...) を、provider ネイティブのセッションおよびスレッド identity には messaging.resolveOutboundSessionRoute(...) を使用してください。
9

ビルドとテスト

pnpm build
pnpm test my-plugin/

Import パスリファレンス

インポートパス目的主なエクスポート
plugin-sdk/plugin-entry正規のPluginエントリヘルパーdefinePluginEntry
plugin-sdk/coreチャンネルエントリ定義/ビルダー向けのレガシー包括再エクスポートdefineChannelPluginEntry, createChatChannelPlugin
plugin-sdk/config-schemaルート設定スキーマのエクスポートOpenClawSchema
plugin-sdk/provider-entry単一プロバイダーエントリヘルパーdefineSingleProviderPluginEntry
plugin-sdk/channel-core焦点を絞ったチャンネルエントリ定義とビルダーdefineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase
plugin-sdk/setup共有セットアップウィザードヘルパーセットアップトランスレーター、allowlistプロンプト、セットアップステータスビルダー
plugin-sdk/setup-runtimeセットアップ時ランタイムヘルパーcreateSetupTranslator, インポート安全なセットアップパッチアダプター、lookup-noteヘルパー、promptResolvedAllowFrom, splitSetupEntries, 委譲セットアッププロキシ
plugin-sdk/setup-adapter-runtime非推奨のセットアップアダプターエイリアスplugin-sdk/setup-runtime を使用
plugin-sdk/setup-toolsセットアップツールヘルパーformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
plugin-sdk/account-core複数アカウントヘルパーアカウントリスト/設定/アクションゲートヘルパー
plugin-sdk/account-idアカウントIDヘルパーDEFAULT_ACCOUNT_ID, アカウントID正規化
plugin-sdk/account-resolutionアカウント検索ヘルパーアカウント検索 + デフォルトフォールバックヘルパー
plugin-sdk/account-helpers範囲を絞ったアカウントヘルパーアカウントリスト/アカウントアクションヘルパー
plugin-sdk/channel-setupセットアップウィザードアダプターcreateOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, および DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries
plugin-sdk/channel-pairingDMペアリングプリミティブcreateChannelPairingController
plugin-sdk/channel-reply-pipeline返信プレフィックス、入力中表示、ソース配信の配線createChannelReplyPipeline, resolveChannelSourceReplyDeliveryMode
plugin-sdk/channel-config-helpers設定アダプターファクトリーとDMアクセスヘルパーcreateHybridChannelConfigAdapter, resolveChannelDmAccess, resolveChannelDmAllowFrom, resolveChannelDmPolicy, normalizeChannelDmPolicy, normalizeLegacyDmAliases
plugin-sdk/channel-config-schema設定スキーマビルダー共有チャンネル設定スキーマプリミティブと汎用ビルダーのみ
plugin-sdk/bundled-channel-config-schemaバンドル設定スキーマOpenClaw管理のバンドルPluginのみ。新しいPluginはPluginローカルスキーマを定義する必要があります
plugin-sdk/channel-config-schema-legacy非推奨のバンドル設定スキーマ互換性エイリアスのみ。保守対象のバンドルPluginには plugin-sdk/bundled-channel-config-schema を使用
plugin-sdk/telegram-command-configTelegramコマンド設定ヘルパーコマンド名正規化、説明のトリミング、重複/競合検証
plugin-sdk/channel-policyグループ/DMポリシー解決resolveChannelGroupRequireMention
plugin-sdk/channel-lifecycle非推奨の互換性ファサードplugin-sdk/channel-outbound を使用
plugin-sdk/inbound-envelopeインバウンドエンベロープヘルパー共有ルート + エンベロープビルダーヘルパー
plugin-sdk/channel-inboundインバウンド受信ヘルパーコンテキスト構築、フォーマット、ルート、ランナー、準備済み返信ディスパッチ、ディスパッチ述語
plugin-sdk/messaging-targets非推奨のターゲット解析インポートパス汎用ターゲット解析ヘルパーには plugin-sdk/channel-targets、ルート比較には plugin-sdk/channel-route、プロバイダー固有のターゲット解決にはPlugin所有の messaging.targetResolver / messaging.resolveOutboundSessionRoute を使用
plugin-sdk/outbound-mediaアウトバウンドメディアヘルパー共有アウトバウンドメディア読み込み
plugin-sdk/outbound-send-deps非推奨の互換性ファサードplugin-sdk/channel-outbound を使用
plugin-sdk/channel-outboundアウトバウンドメッセージライフサイクルヘルパーメッセージアダプター、受信確認、永続送信ヘルパー、ライブプレビュー/ストリーミングヘルパー、返信オプション、ライフサイクルヘルパー、アウトバウンドID、ペイロード計画
plugin-sdk/channel-streaming非推奨の互換性ファサードplugin-sdk/channel-outbound を使用
plugin-sdk/outbound-runtime非推奨の互換性ファサードplugin-sdk/channel-outbound を使用
plugin-sdk/thread-bindings-runtimeスレッドバインディングヘルパースレッドバインディングのライフサイクルとアダプターヘルパー
plugin-sdk/agent-media-payloadレガシーメディアペイロードヘルパーレガシーフィールドレイアウト用のエージェントメディアペイロードビルダー
plugin-sdk/channel-runtime非推奨の互換性shimレガシーチャンネルランタイムユーティリティのみ
plugin-sdk/channel-send-result送信結果型返信結果型
plugin-sdk/runtime-store永続PluginストレージcreatePluginRuntimeStore
plugin-sdk/runtime広範なランタイムヘルパーランタイム/ロギング/バックアップ/Pluginインストールヘルパー
plugin-sdk/runtime-env範囲を絞ったランタイム環境ヘルパーロガー/ランタイム環境、タイムアウト、リトライ、バックオフヘルパー
plugin-sdk/plugin-runtime共有PluginランタイムヘルパーPluginコマンド/フック/http/インタラクティブヘルパー
plugin-sdk/hook-runtimeフックパイプラインヘルパー共有Webhook/内部フックパイプラインヘルパー
plugin-sdk/lazy-runtime遅延ランタイムヘルパーcreateLazyRuntimeModule, createLazyRuntimeMethod, createLazyRuntimeMethodBinder, createLazyRuntimeNamedExport, createLazyRuntimeSurface
plugin-sdk/process-runtimeプロセスヘルパー共有execヘルパー
plugin-sdk/cli-runtimeCLIランタイムヘルパーコマンドフォーマット、待機、バージョンヘルパー
plugin-sdk/gateway-runtimeGatewayヘルパーGatewayクライアント、イベントループ準備済み開始ヘルパー、通知されるLANホスト解決、チャンネルステータスパッチヘルパー
plugin-sdk/config-runtime非推奨の設定互換性shimconfig-contracts, plugin-config-runtime, runtime-config-snapshot, config-mutation を推奨
plugin-sdk/telegram-command-configTelegramコマンドヘルパーバンドルTelegram契約サーフェスが利用できない場合のフォールバック安定なTelegramコマンド検証ヘルパー
plugin-sdk/approval-runtime承認プロンプトヘルパーexec/Plugin承認ペイロード、承認機能/プロファイルヘルパー、ネイティブ承認ルーティング/ランタイムヘルパー、構造化承認表示パスフォーマット
plugin-sdk/approval-auth-runtime承認認証ヘルパー承認者解決、同一チャットアクション認証
plugin-sdk/approval-client-runtime承認クライアントヘルパーネイティブexec承認プロファイル/フィルターヘルパー
plugin-sdk/approval-delivery-runtime承認配信ヘルパーネイティブ承認機能/配信アダプター
plugin-sdk/approval-gateway-runtime承認Gatewayヘルパー共有承認Gateway解決ヘルパー
plugin-sdk/approval-handler-adapter-runtime承認アダプターヘルパーホットチャンネルエントリポイント向けの軽量ネイティブ承認アダプター読み込みヘルパー
plugin-sdk/approval-handler-runtime承認ハンドラーヘルパーより広範な承認ハンドラーランタイムヘルパー。十分な場合は、より狭いアダプター/Gateway境界を推奨
plugin-sdk/approval-native-runtime承認ターゲットヘルパーネイティブ承認ターゲット/アカウントバインディングヘルパー
plugin-sdk/approval-reply-runtime承認返信ヘルパーexec/Plugin承認返信ペイロードヘルパー
plugin-sdk/channel-runtime-contextチャンネルランタイムコンテキストヘルパー汎用チャンネルランタイムコンテキストの登録/get/watchヘルパー
plugin-sdk/security-runtimeセキュリティヘルパー共有信頼、DMゲート、ルート境界付きファイル/パスヘルパー、外部コンテンツ、シークレット収集ヘルパー
plugin-sdk/ssrf-policySSRFポリシーヘルパーホストallowlistとプライベートネットワークポリシーヘルパー
plugin-sdk/ssrf-runtimeSSRFランタイムヘルパーピン留めdispatcher、ガード付きfetch、SSRFポリシーヘルパー
plugin-sdk/system-event-runtimeシステムイベントヘルパーenqueueSystemEvent, peekSystemEventEntries
plugin-sdk/heartbeat-runtimeHeartbeatヘルパーHeartbeat起動、イベント、可視性ヘルパー
plugin-sdk/delivery-queue-runtime配信キューヘルパーdrainPendingDeliveries
plugin-sdk/channel-activity-runtimeチャンネルアクティビティヘルパーrecordChannelActivity
plugin-sdk/dedupe-runtime重複排除ヘルパーインメモリおよび永続バックエンド付き重複排除キャッシュ
plugin-sdk/file-access-runtimeファイルアクセスヘルパー安全なローカルファイル/メディアパスヘルパー
plugin-sdk/transport-ready-runtimeトランスポート準備状態ヘルパーwaitForTransportReady
plugin-sdk/exec-approvals-runtimeexec承認ポリシーヘルパーloadExecApprovals, resolveExecApprovalsFromFile, ExecApprovalsFile
plugin-sdk/collection-runtime境界付きキャッシュヘルパーpruneMapToMaxSize
plugin-sdk/diagnostic-runtime診断ゲートヘルパーisDiagnosticFlagEnabled, isDiagnosticsEnabled
plugin-sdk/error-runtimeエラーフォーマットヘルパーformatUncaughtError, isApprovalNotFoundError, エラーグラフヘルパー
plugin-sdk/fetch-runtimeラップされたfetch/プロキシヘルパーresolveFetch, プロキシヘルパー、EnvHttpProxyAgentオプションヘルパー
plugin-sdk/host-runtimeホスト正規化ヘルパーnormalizeHostname, normalizeScpRemoteHost
plugin-sdk/retry-runtimeリトライヘルパーRetryConfig, retryAsync, ポリシーランナー
plugin-sdk/allow-fromallowlistフォーマットと入力マッピングformatAllowFromLowercase, mapAllowlistResolutionInputs
plugin-sdk/command-authコマンドゲートとコマンドサーフェスヘルパーresolveControlCommandGate, 送信者認可ヘルパー、動的引数メニューフォーマットを含むコマンドレジストリヘルパー
plugin-sdk/command-statusコマンドステータス/ヘルプレンダラーbuildCommandsMessage, buildCommandsMessagePaginated, buildHelpMessage
plugin-sdk/secret-inputシークレット入力解析シークレット入力ヘルパー
plugin-sdk/webhook-ingressWebhookリクエストヘルパーWebhookターゲットユーティリティ
plugin-sdk/webhook-request-guardsWebhook本文ガードヘルパーリクエスト本文の読み取り/制限ヘルパー
plugin-sdk/reply-runtime共有返信ランタイムインバウンドディスパッチ、Heartbeat、返信プランナー、チャンク化
plugin-sdk/reply-dispatch-runtime範囲を絞った返信ディスパッチヘルパーfinalization、プロバイダーディスパッチ、会話ラベルヘルパー
plugin-sdk/reply-history返信履歴ヘルパーcreateChannelHistoryWindow; buildPendingHistoryContextFromMap, recordPendingHistoryEntry, clearHistoryEntriesIfEnabled などの非推奨mapヘルパー互換性エクスポート
plugin-sdk/reply-reference返信参照計画createReplyReferencePlanner
plugin-sdk/reply-chunking返信チャンクヘルパーテキスト/Markdownチャンク化ヘルパー
plugin-sdk/session-store-runtimeセッションストアヘルパーストアパス + updated-atヘルパー
plugin-sdk/state-paths状態パスヘルパー状態およびOAuthディレクトリヘルパー
plugin-sdk/routingルーティング/セッションキーヘルパーresolveAgentRoutebuildAgentSessionKeyresolveDefaultAgentBoundAccountId、セッションキー正規化ヘルパー
plugin-sdk/status-helpersチャンネルステータスヘルパーチャンネル/アカウントステータス概要ビルダー、ランタイム状態のデフォルト、課題メタデータヘルパー
plugin-sdk/target-resolver-runtimeターゲット解決ヘルパー共有ターゲット解決ヘルパー
plugin-sdk/string-normalization-runtime文字列正規化ヘルパースラッグ/文字列正規化ヘルパー
plugin-sdk/request-urlリクエスト URL ヘルパーリクエスト風入力から文字列 URL を抽出
plugin-sdk/run-command時間制限付きコマンドヘルパー正規化された stdout/stderr を持つ時間制限付きコマンドランナー
plugin-sdk/param-readersパラメーターリーダー共通ツール/CLI パラメーターリーダー
plugin-sdk/tool-payloadツールペイロード抽出ツール結果オブジェクトから正規化ペイロードを抽出
plugin-sdk/tool-sendツール送信抽出ツール引数から正規送信先フィールドを抽出
plugin-sdk/temp-path一時パスヘルパー共有一時ダウンロードパスヘルパー
plugin-sdk/logging-coreロギングヘルパーサブシステムロガーと秘匿化ヘルパー
plugin-sdk/markdown-table-runtimeMarkdown テーブルヘルパーMarkdown テーブルモードヘルパー
plugin-sdk/reply-payloadメッセージ返信タイプ返信ペイロードタイプ
plugin-sdk/provider-setup厳選されたローカル/セルフホストプロバイダーセットアップヘルパーセルフホストプロバイダーの検出/設定ヘルパー
plugin-sdk/self-hosted-provider-setupOpenAI 互換セルフホストプロバイダー専用セットアップヘルパー同じセルフホストプロバイダーの検出/設定ヘルパー
plugin-sdk/provider-auth-runtimeプロバイダーランタイム認証ヘルパーランタイム API キー解決ヘルパー
plugin-sdk/provider-auth-api-keyプロバイダー API キーセットアップヘルパーAPI キーオンボーディング/プロファイル書き込みヘルパー
plugin-sdk/provider-auth-resultプロバイダー認証結果ヘルパー標準 OAuth 認証結果ビルダー
plugin-sdk/provider-selection-runtimeプロバイダー選択ヘルパー設定済みまたは自動のプロバイダー選択と生プロバイダー設定のマージ
plugin-sdk/provider-env-varsプロバイダー環境変数ヘルパープロバイダー認証環境変数検索ヘルパー
plugin-sdk/provider-model-shared共有プロバイダーモデル/リプレイヘルパーProviderReplayFamilybuildProviderReplayFamilyHooksnormalizeModelCompat、共有リプレイポリシービルダー、プロバイダーエンドポイントヘルパー、モデル ID 正規化ヘルパー
plugin-sdk/provider-catalog-shared共有プロバイダーカタログヘルパーfindCatalogTemplatebuildSingleProviderApiKeyCatalogbuildManifestModelProviderConfigsupportsNativeStreamingUsageCompatapplyProviderNativeStreamingUsageCompat
plugin-sdk/provider-onboardプロバイダーオンボーディングパッチオンボーディング設定ヘルパー
plugin-sdk/provider-httpプロバイダー HTTP ヘルパー音声文字起こしマルチパートフォームヘルパーを含む、汎用プロバイダー HTTP/エンドポイント機能ヘルパー
plugin-sdk/provider-web-fetchプロバイダー web-fetch ヘルパーweb-fetch プロバイダー登録/キャッシュヘルパー
plugin-sdk/provider-web-search-config-contractプロバイダー Web 検索設定ヘルパープラグイン有効化配線を必要としないプロバイダー向けの狭い Web 検索設定/認証情報ヘルパー
plugin-sdk/provider-web-search-contractプロバイダー Web 検索コントラクトヘルパーcreateWebSearchProviderContractFieldsenablePluginInConfigresolveProviderWebSearchPluginConfig、スコープ付き認証情報 setter/getter などの狭い Web 検索設定/認証情報コントラクトヘルパー
plugin-sdk/provider-web-searchプロバイダー Web 検索ヘルパーWeb 検索プロバイダー登録/キャッシュ/ランタイムヘルパー
plugin-sdk/provider-toolsプロバイダーツール/スキーマ互換ヘルパーProviderToolCompatFamilybuildProviderToolCompatFamilyHooks、DeepSeek/Gemini/OpenAI スキーマクリーンアップ + 診断
plugin-sdk/provider-usageプロバイダー使用量ヘルパーfetchClaudeUsagefetchGeminiUsagefetchGithubCopilotUsage、その他のプロバイダー使用量ヘルパー
plugin-sdk/provider-streamプロバイダーストリームラッパーヘルパーProviderStreamFamilybuildProviderStreamFamilyHookscomposeProviderStreamWrappers、ストリームラッパータイプ、共有 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot ラッパーヘルパー
plugin-sdk/provider-transport-runtimeプロバイダートランスポートヘルパーガード付き fetch、ツール結果テキスト抽出、トランスポートメッセージ変換、書き込み可能トランスポートイベントストリームなどのネイティブプロバイダートランスポートヘルパー
plugin-sdk/keyed-async-queue順序付き非同期キューKeyedAsyncQueue
plugin-sdk/media-runtime共有メディアヘルパーメディア fetch/変換/保存ヘルパー、ffprobe ベースの動画寸法プローブ、メディアペイロードビルダー
plugin-sdk/media-generation-runtime共有メディア生成ヘルパー画像/動画/音楽生成向けの共有フェイルオーバーヘルパー、候補選択、欠落モデルメッセージング
plugin-sdk/media-understandingメディア理解ヘルパーメディア理解プロバイダータイプと、プロバイダー向け画像/音声ヘルパーエクスポート
plugin-sdk/text-runtime非推奨の広範なテキスト互換エクスポートstring-coerce-runtimetext-chunkingtext-utility-runtimelogging-core を使用
plugin-sdk/text-chunkingテキストチャンク化ヘルパー送信テキストチャンク化ヘルパー
plugin-sdk/speech音声ヘルパー音声プロバイダータイプと、プロバイダー向けディレクティブ、レジストリ、検証ヘルパー、OpenAI 互換 TTS ビルダー
plugin-sdk/speech-core共有音声コア音声プロバイダータイプ、レジストリ、ディレクティブ、正規化
plugin-sdk/realtime-transcriptionリアルタイム文字起こしヘルパープロバイダータイプ、レジストリヘルパー、共有 WebSocket セッションヘルパー
plugin-sdk/realtime-voiceリアルタイム音声ヘルパープロバイダータイプ、レジストリ/解決ヘルパー、ブリッジセッションヘルパー、共有エージェントトークバックキュー、アクティブ実行音声制御、トランスクリプト/イベント健全性、エコー抑制、相談質問マッチング、強制相談調整、ターンコンテキスト追跡、出力アクティビティ追跡、高速コンテキスト相談ヘルパー
plugin-sdk/image-generation画像生成ヘルパー画像生成プロバイダータイプと画像アセット/データ URL ヘルパー、OpenAI 互換画像プロバイダービルダー
plugin-sdk/image-generation-core共有画像生成コア画像生成タイプ、フェイルオーバー、認証、レジストリヘルパー
plugin-sdk/music-generation音楽生成ヘルパー音楽生成プロバイダー/リクエスト/結果タイプ
plugin-sdk/music-generation-core共有音楽生成コア音楽生成タイプ、フェイルオーバーヘルパー、プロバイダー検索、モデル参照解析
plugin-sdk/video-generation動画生成ヘルパー動画生成プロバイダー/リクエスト/結果タイプ
plugin-sdk/video-generation-core共有動画生成コア動画生成タイプ、フェイルオーバーヘルパー、プロバイダー検索、モデル参照解析
plugin-sdk/interactive-runtimeインタラクティブ返信ヘルパーインタラクティブ返信ペイロードの正規化/縮約
plugin-sdk/channel-config-primitivesチャンネル設定プリミティブ狭いチャンネル設定スキーマプリミティブ
plugin-sdk/channel-config-writesチャンネル設定書き込みヘルパーチャンネル設定書き込み認可ヘルパー
plugin-sdk/channel-plugin-common共有チャンネルプリリュード共有チャンネルプラグインプリリュードエクスポート
plugin-sdk/channel-statusチャンネルステータスヘルパー共有チャンネルステータススナップショット/概要ヘルパー
plugin-sdk/allowlist-config-edit許可リスト設定ヘルパー許可リスト設定編集/読み取りヘルパー
plugin-sdk/group-accessグループアクセスヘルパー共有グループアクセス判定ヘルパー
plugin-sdk/direct-dm, plugin-sdk/direct-dm-access非推奨の互換ファサードplugin-sdk/channel-inbound を使用
plugin-sdk/direct-dm-guard-policyダイレクト DM ガードヘルパー暗号化前の狭いガードポリシーヘルパー
plugin-sdk/extension-shared共有拡張ヘルパーパッシブチャンネル/ステータスとアンビエントプロキシヘルパープリミティブ
plugin-sdk/webhook-targetsWebhook ターゲットヘルパーWebhook ターゲットレジストリとルートインストールヘルパー
plugin-sdk/webhook-path非推奨の Webhook パスエイリアスplugin-sdk/webhook-ingress を使用
plugin-sdk/web-media共有 Web メディアヘルパーリモート/ローカルメディア読み込みヘルパー
plugin-sdk/zod非推奨の Zod 互換再エクスポートzod から zod を直接インポート
plugin-sdk/memory-coreバンドルされた memory-core ヘルパーメモリマネージャー/設定/ファイル/CLI ヘルパーサーフェス
plugin-sdk/memory-core-engine-runtimeメモリエンジンランタイムファサードメモリインデックス/検索ランタイムファサード
plugin-sdk/memory-core-host-embedding-registryメモリ埋め込みレジストリ軽量メモリ埋め込みプロバイダーレジストリヘルパー
plugin-sdk/memory-core-host-engine-foundationメモリホスト基盤エンジンメモリホスト基盤エンジンエクスポート
plugin-sdk/memory-core-host-engine-embeddingsメモリホスト埋め込みエンジンメモリ埋め込みコントラクト、レジストリアクセス、ローカルプロバイダー、汎用バッチ/リモートヘルパー。具体的なリモートプロバイダーは所有元プラグインに存在
plugin-sdk/memory-core-host-engine-qmdメモリホスト QMD エンジンメモリホスト QMD エンジンエクスポート
plugin-sdk/memory-core-host-engine-storageメモリホストストレージエンジンメモリホストストレージエンジンエクスポート
plugin-sdk/memory-core-host-multimodalメモリホストマルチモーダルヘルパーメモリホストマルチモーダルヘルパー
plugin-sdk/memory-core-host-queryメモリホストクエリヘルパーメモリホストクエリヘルパー
plugin-sdk/memory-core-host-secretメモリホストシークレットヘルパーメモリホストシークレットヘルパー
plugin-sdk/memory-core-host-events非推奨のメモリイベントエイリアスplugin-sdk/memory-host-events を使用
plugin-sdk/memory-core-host-statusメモリホストステータスヘルパーメモリホストステータスヘルパー
plugin-sdk/memory-core-host-runtime-cliメモリホスト CLI ランタイムメモリホスト CLI ランタイムヘルパー
plugin-sdk/memory-core-host-runtime-coreメモリホストコアランタイムメモリホストコアランタイムヘルパー
plugin-sdk/memory-core-host-runtime-filesメモリホストファイル/ランタイムヘルパーメモリホストファイル/ランタイムヘルパー
plugin-sdk/memory-host-coreメモリホストコアランタイムエイリアスベンダー中立のメモリホストコアランタイムヘルパーエイリアス
plugin-sdk/memory-host-eventsメモリホストイベントジャーナルエイリアスベンダー中立のメモリホストイベントジャーナルヘルパーエイリアス
plugin-sdk/memory-host-files非推奨のメモリファイル/ランタイムエイリアスplugin-sdk/memory-core-host-runtime-files を使用
plugin-sdk/memory-host-markdown管理対象 Markdown ヘルパーメモリ隣接プラグイン向けの共有管理対象 Markdown ヘルパー
plugin-sdk/memory-host-searchActive Memory 検索ファサード遅延 Active Memory 検索マネージャーランタイムファサード
plugin-sdk/memory-host-status非推奨のメモリホストステータスエイリアスplugin-sdk/memory-core-host-status を使用
plugin-sdk/testingテストユーティリティリポジトリローカルの非推奨互換バレル。plugin-sdk/plugin-test-runtimeplugin-sdk/channel-test-helpersplugin-sdk/channel-target-testingplugin-sdk/test-envplugin-sdk/test-fixtures などの焦点を絞ったリポジトリローカルのテストサブパスを使用
この表は共通の移行サブセットであり、完全な SDK サーフェスではありません。 コンパイラーのエントリーポイント一覧は scripts/lib/plugin-sdk-entrypoints.json にあります。 パッケージエクスポートは公開サブセットから生成されます。 予約済みのバンドル Plugin ヘルパーの継ぎ目は、まだ公開済みの @openclaw/discord パッケージを直接インポートしている外部 Plugin 向けに保持されている、非推奨の plugin-sdk/discord shim のような明示的に文書化された互換性ファサードを除き、公開 SDK のエクスポートマップから廃止されました。オーナー固有のヘルパーは、所有元の Plugin パッケージ内にあります。共有ホスト動作は、plugin-sdk/gateway-runtimeplugin-sdk/security-runtimeplugin-sdk/plugin-config-runtime などの汎用 SDK コントラクトを通じて移動します。 用途に合う最も狭いインポートを使用してください。エクスポートが見つからない場合は、src/plugin-sdk/ のソースを確認するか、どの汎用コントラクトがそれを所有すべきかをメンテナーに確認してください。

現在の非推奨

Plugin SDK、プロバイダーコントラクト、ランタイムサーフェス、マニフェスト全体にわたる、より狭い範囲の非推奨です。それぞれは現在も動作しますが、将来のメジャーリリースで削除されます。各項目は古い API を正規の置き換え先に対応付けています。
旧 (openclaw/plugin-sdk/command-auth): buildCommandsMessage, buildCommandsMessagePaginated, buildHelpMessage.新 (openclaw/plugin-sdk/command-status): 同じシグネチャ、同じエクスポートです。より狭いサブパスからインポートするだけです。command-auth は互換性スタブとしてそれらを再エクスポートします。
// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";
: openclaw/plugin-sdk/channel-inbound または openclaw/plugin-sdk/channel-mention-gating からの resolveMentionGating(params)resolveMentionGatingWithBypass(params): resolveInboundMentionDecision({ facts, policy })。2 つに分かれた呼び出し形状ではなく、1 つの判断オブジェクトです。Discord、iMessage、Matrix、MS Teams、QQBot、Signal、Telegram、WhatsApp、Zalo 全体で採用済みです。Slack 独自の app_mention イベントモデルはこのヘルパーを使用しません。
openclaw/plugin-sdk/channel-runtime は古いチャネル Plugin 向けの互換性 shim です。新しいコードからインポートしないでください。ランタイムオブジェクトの登録には openclaw/plugin-sdk/channel-runtime-context を使用してください。openclaw/plugin-sdk/channel-actionschannelActions* ヘルパーは、生の「actions」チャネルエクスポートとあわせて非推奨です。代わりに、意味的な presentation サーフェスを通じて機能を公開してください。チャネル Plugin は、受け入れる生のアクション名ではなく、何をレンダリングするか(カード、ボタン、セレクト)を宣言します。
: openclaw/plugin-sdk/provider-web-search からの tool() ファクトリー。: プロバイダー Plugin 上で createTool(...) を直接実装します。OpenClaw はツールラッパーを登録するために SDK ヘルパーを必要としなくなりました。
: 受信チャネルメッセージからフラットな平文プロンプトエンベロープを構築するための api.runtime.channel.reply.formatInboundEnvelope(...)(および受信メッセージオブジェクト上の channelEnvelope フィールド)。: BodyForAgent と構造化されたユーザーコンテキストブロック。チャネル Plugin は、ルーティングメタデータ(スレッド、トピック、返信先、リアクション)をプロンプト文字列に連結する代わりに、型付きフィールドとして添付します。formatAgentEnvelope(...) ヘルパーは合成されたアシスタント向けエンベロープでは引き続きサポートされますが、受信用の平文エンベロープは廃止予定です。影響範囲: inbound_claimmessage_received、および古いエンベロープテキストを後処理していた任意のカスタムチャネル Plugin。
: api.on("deactivate", handler): api.on("gateway_stop", handler)。同じシャットダウン cleanup コントラクトです。変更されるのはフック名だけです。
// Before
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// After
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});
deactivate は、2026-08-16 以降に削除されるまで、非推奨の互換性エイリアスとして引き続き配線されています。
: threadBindingReady または deliveryOrigin を返す api.on("subagent_spawning", handler): core に、チャネルセッションバインディングアダプターを通じて thread: true のサブエージェントバインディングを準備させます。起動後の観測にのみ api.on("subagent_spawned", handler) を使用してください。
// Before
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// After
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});
subagent_spawningPluginHookSubagentSpawningEventPluginHookSubagentSpawningResult、および SubagentLifecycleHookRunner.runSubagentSpawning(...) は、外部 Plugin が移行する間だけ非推奨の互換性サーフェスとして残り、2026-08-30 以降に削除されます。
4 つの探索型エイリアスは現在、カタログ時代の型に対する薄いラッパーです。
旧エイリアス新しい型
ProviderDiscoveryOrderProviderCatalogOrder
ProviderDiscoveryContextProviderCatalogContext
ProviderDiscoveryResultProviderCatalogResult
ProviderPluginDiscoveryProviderPluginCatalog
加えて、レガシーの ProviderCapabilities 静的バッグもあります。プロバイダー Plugin は、静的オブジェクトではなく、buildReplayPolicynormalizeToolSchemaswrapStreamFn などの明示的なプロバイダーフックを使用する必要があります。
ProviderThinkingPolicy 上の 3 つの別個のフック): isBinaryThinking(ctx)supportsXHighThinking(ctx)、および resolveDefaultThinkingLevel(ctx): 正規の id、任意の label、およびランク付けされたレベルリストを含む ProviderThinkingProfile を返す単一の resolveThinkingProfile(ctx)。OpenClaw は古い保存値をプロファイルランクに基づいて自動的にダウングレードします。コンテキストには、providermodelId、任意のマージ済み reasoning、および任意のマージ済みモデル compat facts が含まれます。プロバイダー Plugin はそれらのカタログ facts を使用して、設定されたリクエストコントラクトが対応している場合にのみモデル固有のプロファイルを公開できます。3 つではなく 1 つのフックを実装してください。レガシーフックは非推奨期間中も動作しますが、プロファイル結果とは合成されません。
: Plugin マニフェストでプロバイダーを宣言せずに外部 auth フックを実装すること。: Plugin マニフェストで contracts.externalAuthProviders を宣言し、かつ resolveExternalAuthProfiles(...) を実装します。
{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}
マニフェストフィールド: providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }: 同じ env-var lookup をマニフェスト上の setup.providers[].envVars に反映します。これにより、セットアップ/ステータスの env メタデータが 1 か所に統合され、env-var lookup に回答するだけのために Plugin ランタイムを起動する必要がなくなります。providerAuthEnvVars は、非推奨期間が終了するまで互換性アダプターを通じてサポートされます。
: 3 つの別個の呼び出し、api.registerMemoryPromptSection(...)api.registerMemoryFlushPlan(...)api.registerMemoryRuntime(...): memory-state API 上の 1 つの呼び出し、 registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })同じスロットで、登録呼び出しが 1 つになります。追加的なプロンプトおよびコーパスヘルパー(registerMemoryPromptSupplementregisterMemoryCorpusSupplement)には影響しません。
: api.registerMemoryEmbeddingProvider(...)contracts.memoryEmbeddingProviders: api.registerEmbeddingProvider(...)contracts.embeddingProviders汎用 embedding プロバイダーコントラクトは Memory 以外でも再利用可能であり、新しいプロバイダーでサポートされる経路です。既存プロバイダーが移行する間、Memory 固有の登録 API は非推奨の互換性として引き続き配線されています。Plugin 検査では、非バンドルでの使用が互換性負債として報告されます。
src/plugins/runtime/types.ts からまだエクスポートされている 2 つのレガシー型エイリアス:
SubagentReadSessionParamsSubagentGetSessionMessagesParams
SubagentReadSessionResultSubagentGetSessionMessagesResult
ランタイムメソッド readSession は、getSessionMessages を優先するため非推奨です。同じシグネチャで、古いメソッドは新しいメソッドへ呼び出しを通します。
: runtime.tasks.flow(単数)は live task-flow アクセサーを返していました。: runtime.tasks.managedFlows は、フローから子タスクを作成、更新、キャンセル、または実行する Plugin 向けに、管理対象の TaskFlow mutation ランタイムを保持します。Plugin が DTO ベースの読み取りのみを必要とする場合は、runtime.tasks.flows を使用してください。
// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
2026-07-26 以降に削除されます。
上記の 移行方法 で説明しています。完全性のためここにも含めます。削除された embedded-runner 専用の api.registerEmbeddedExtensionFactory(...) 経路は、contracts.agentToolResultMiddleware 内の明示的なランタイムリストを伴う api.registerAgentToolResultMiddleware(...) に置き換えられます。
openclaw/plugin-sdk から再エクスポートされる OpenClawSchemaType は現在、OpenClawConfig の 1 行エイリアスです。正規の名前を優先してください。
// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";
拡張レベルの非推奨化(extensions/ 配下のバンドルされたチャネル/プロバイダー Plugin 内)は、それぞれ自身の api.tsruntime-api.ts バレルで追跡されます。これらはサードパーティ Plugin の契約には影響せず、ここには記載されません。バンドルされた Plugin のローカルバレルを直接利用している場合は、アップグレード前にそのバレル内の非推奨コメントを読んでください。

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

リアルタイム音声、電話、ミーティング、ブラウザーの Talk コードは、openclaw/plugin-sdk/realtime-voice からエクスポートされる 1 つの Talk セッションコントローラーを共有します。このコントローラーは、共通の Talk イベントエンベロープ、アクティブなターン状態、キャプチャ状態、出力音声状態、最近のイベント履歴、古いターンの拒否を所有します。プロバイダー Plugin はベンダー固有のリアルタイムセッションを所有し、サーフェス Plugin はキャプチャ、再生、電話、ミーティング固有の挙動を所有します。 すべてのバンドル済みサーフェスは共有コントローラー上で動作します。ブラウザーリレー、管理ルームへのハンドオフ、音声通話リアルタイム、音声通話ストリーミング STT、Google Meet リアルタイム、ネイティブのプッシュツートークです。Gateway は hello-ok.features.events で 1 つのライブ Talk イベントチャネル talk.event を通知します。 低レベルアダプターまたはテストフィクスチャを実装する場合を除き、新しいコードで createTalkEventSequencer(...) を直接呼び出すべきではありません。共有コントローラーを使用することで、ターン ID なしでターンスコープのイベントが送信されることを防ぎ、古い turnEnd / turnCancel 呼び出しが新しいアクティブターンをクリアできないようにし、電話、ミーティング、ブラウザーリレー、管理ルームへのハンドオフ、ネイティブ 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 });
await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });
ブラウザー所有の WebRTC/プロバイダー WebSocket セッションは talk.client.create を使用します。ブラウザーがプロバイダーのネゴシエーションとメディアトランスポートを所有し、Gateway が認証情報、指示、ツールポリシーを所有するためです。talk.session.* は、gateway-relay リアルタイム、gateway-relay 文字起こし、管理ルームのネイティブ STT/TTS セッション向けの共通 Gateway 管理サーフェスです。 talk.provider / talk.providers の横にリアルタイムセレクターを配置するレガシー設定は、openclaw doctor --fix で修復する必要があります。ランタイム Talk は、speech/TTS プロバイダー設定をリアルタイムプロバイダー設定として再解釈しません。 サポートされる talk.session.create の組み合わせは意図的に小さく保たれています。
モードトランスポートブレイン所有者注記
realtimegateway-relayagent-consultGatewayGateway を通じてブリッジされる全二重プロバイダー音声。ツール呼び出しは agent-consult ツール経由でルーティングされます。
transcriptiongateway-relaynoneGatewayストリーミング STT のみ。呼び出し元は入力音声を送信し、文字起こしイベントを受信します。
stt-ttsmanaged-roomagent-consultネイティブ/クライアントルームクライアントがキャプチャ/再生を所有し、Gateway がターン状態を所有する、プッシュツートークおよびトランシーバー形式のルーム。
stt-ttsmanaged-roomdirect-toolsネイティブ/クライアントルームGateway ツールアクションを直接実行する、信頼済みファーストパーティサーフェス向けの管理者専用ルームモード。
古い talk.realtime.* / talk.transcription.* / talk.handoff.* ファミリー(すべて削除済み)から移行する読者向けのメソッド対応表:
talk.realtime.sessiontalk.client.create
talk.realtime.toolCalltalk.client.toolCall
talk.realtime.relayAudiotalk.session.appendAudio
talk.realtime.relayCanceltalk.session.cancelOutput または talk.session.cancelTurn
talk.realtime.relayToolResulttalk.session.submitToolResult
talk.realtime.relayStoptalk.session.close
talk.transcription.sessiontalk.session.create({ mode: "transcription" })
talk.transcription.relayAudiotalk.session.appendAudio
talk.transcription.relayCanceltalk.session.cancelTurn
talk.transcription.relayStoptalk.session.close
talk.handoff.createtalk.session.create({ transport: "managed-room" })
talk.handoff.jointalk.session.join
talk.handoff.revoketalk.session.close
統一された制御語彙も意図的に狭く保たれています。
メソッド適用対象契約
talk.session.appendAudiorealtime/gateway-relay, transcription/gateway-relay同じ Gateway 接続が所有するプロバイダーセッションに base64 PCM 音声チャンクを追加します。
talk.session.startTurnstt-tts/managed-room管理ルームのユーザーターンを開始します。
talk.session.endTurnstt-tts/managed-room古いターンの検証後にアクティブターンを終了します。
talk.session.cancelTurnすべての Gateway 所有セッションターンに対するアクティブなキャプチャ/プロバイダー/エージェント/TTS 作業をキャンセルします。
talk.session.cancelOutputrealtime/gateway-relay必ずしもユーザーターンを終了せずに、アシスタント音声出力を停止します。
talk.session.submitToolResultrealtime/gateway-relayリレーが送信したプロバイダーツール呼び出しを完了します。中間出力には options.willContinue を渡し、別のアシスタント応答なしで呼び出しを満たすには options.suppressResponse を渡します。
talk.session.steerエージェントに支えられた Talk セッションTalk セッションから解決されたアクティブな埋め込み実行へ、音声の statussteercancel、または followup 制御を送信します。
talk.session.closeすべての統一セッションリレーセッションを停止するか管理ルーム状態を取り消し、その後、統一セッション ID を忘れます。
これを機能させるために、core にプロバイダーやプラットフォームの特別扱いを導入しないでください。core は Talk セッションのセマンティクスを所有します。プロバイダー Plugin はベンダーセッションのセットアップを所有します。音声通話と Google Meet は電話/ミーティングアダプターを所有します。ブラウザーとネイティブアプリはデバイスのキャプチャ/再生 UX を所有します。

削除タイムライン

時期発生すること
現在非推奨サーフェスはランタイム警告を出します。
各互換レコードの removeAfter 日付その特定のサーフェスは削除対象になります。日付を過ぎると pnpm plugins:boundary-report --fail-on-eligible-compat が CI を失敗させます。
次のメジャーリリースまだ移行されていないサーフェスはすべて削除され、それらを使用している Plugin は失敗します。
すべての core Plugin はすでに移行済みです。外部 Plugin は次のメジャーリリース前に移行してください。Plugin が使用するサーフェスについて、どの互換レコードの期限が最も近いかを確認するには、pnpm plugins:boundary-report を実行します。

警告を一時的に抑制する

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
これは一時的な逃げ道であり、恒久的な解決策ではありません。

関連