Plugin SDK の移行

​

変更点

• 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 などの組み込みランナーイベントを 監視していた、組み込みランナー専用の削除済みフックです。代わりにエージェントの ツール結果ミドルウェアを使用してください（組み込みツール結果拡張機能を ミドルウェアへ移行するを参照）。

​

理由

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

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

​

互換性ポリシー

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

​

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

​

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

​

読み取り元の検証

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 アーティファクトから読み取られていない場合だけです。維持されるフィールドおよびキーのリストの横にあるコードコメント内の読み取り元名を、調査結果と同期させてください。

​

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

import { toInboundMediaFacts } from "openclaw/plugin-sdk/channel-inbound";

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

const ctx = finalizeInboundContext({ Body: caption, media });

​

移行方法

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

​

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

​

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

​

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

​

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

​

移行リファレンス

// 変更前
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 とリアルタイム音声の移行

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

​

削除タイムライン

​

警告を一時的に抑制する

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

​

関連項目

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