Plugin SDKの移行

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

何が変わるのか

• 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 専用バンドル拡張フック。

​

なぜ変更されたのか

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

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

​

Talk と realtime 音声の移行計画

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 パスを削除します。

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

​

互換性ポリシー

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

​

移行方法

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/

​

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

​

有効な非推奨

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

​

削除タイムライン

​

警告を一時的に抑制する

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 マニフェスト - マニフェストスキーマリファレンス