Plugin SDK の概要

Plugin SDK は、Plugin とコアの間の型付きコントラクトです。このページは、 何を import するか と 何を登録できるか のリファレンスです。

import 規約

必ず特定のサブパスから import してください。

各サブパスは、小さく自己完結したモジュールです。これにより起動が速く保たれ、 循環依存の問題を防げます。channel 固有の entry/build helper には、 openclaw/plugin-sdk/channel-core を優先してください。より広い包括的な surface や、buildChannelConfigSchema などの共有 helper には openclaw/plugin-sdk/core を残してください。

channel config では、channel が所有する JSON Schema を openclaw.plugin.json#channelConfigs 経由で公開してください。 plugin-sdk/channel-config-schema サブパスは、共有 schema primitive と汎用 builder 用です。OpenClaw の bundled Plugin は、保持されている bundled-channel schema に plugin-sdk/bundled-channel-config-schema を使用します。非推奨の 互換 export は plugin-sdk/channel-config-schema-legacy に残っています。どちらの bundled schema サブパスも、新しい Plugin のためのパターンではありません。

サブパスリファレンス

Plugin SDK は、領域（Plugin entry、channel、provider、auth、runtime、 capability、memory、予約済み bundled-plugin helper）ごとにグループ化された、狭い サブパスのセットとして公開されます。グループ化されリンクされた完全なカタログは、 Plugin SDK サブパスを参照してください。

compiler entrypoint inventory は scripts/lib/plugin-sdk-entrypoints.json にあります。package export は、 scripts/lib/plugin-sdk-private-local-only-subpaths.json に一覧された repo-local test/internal サブパスを差し引いた後の public subset から生成されます。 public export 数を監査するには pnpm plugin-sdk:surface を実行してください。 十分に古く、bundled extension の本番コードで使用されていない非推奨の public サブパスは scripts/lib/plugin-sdk-deprecated-public-subpaths.json で追跡されます。 広範な非推奨 re-export barrel は scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json で追跡されます。

登録 API

register(api) callback は、次の method を持つ OpenClawPluginApi object を受け取ります。

capability 登録

api.registerEmbeddingProvider(...) で登録された embedding provider は、 Plugin manifest の contracts.embeddingProviders にも listed されている必要があります。 これは、再利用可能な vector generation のための汎用 embedding surface です。memory search は、この汎用 provider surface を利用できます。古い api.registerMemoryEmbeddingProvider(...) と contracts.memoryEmbeddingProviders seam は、既存の memory-specific provider が 移行している間の非推奨の互換性です。

runtime batchEmbed(...) をまだ公開している memory-specific provider は、その runtime が明示的に sourceWideBatchEmbed: true を設定していない限り、既存の per-file batching コントラクトに留まります。この opt-in により、memory host は、複数の dirty memory file と有効な source からの chunk を、host の batch limit まで 1 回の batchEmbed(...) call で送信できます。JSONL request file を upload する batch adapter は、request-count cap だけでなく upload-size cap の前でも provider job を分割する必要があります。 provider は、batch.chunks と同じ順序で、input chunk ごとに 1 つの embedding を返す必要があります。 provider が file-local batch を想定している場合、またはより大きな source-wide job 全体で input ordering を保持できない場合は、この flag を省略してください。

tool と command

固定 tool 名の単純な tool-only Plugin には defineToolPlugin を 使用してください。mixed Plugin または完全に dynamic な tool 登録には、 api.registerTool(...) を直接使用してください。

Plugin command は、agent が短い command-owned routing hint を必要とする場合に agentPromptGuidance を設定できます。その text は command 自体に関するものに留めてください。 provider または Plugin 固有の policy を core prompt builder に追加しないでください。

guidance entry は、すべての prompt surface に適用される legacy string、または structured entry にできます。

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

structured surfaces には、openclaw_main、codex_app_server、 cli_backend、acp_backend、または subagent を含められます。pi_main は openclaw_main の非推奨 alias のままです。意図的にすべての surface に guidance を適用する場合は、surfaces を省略してください。空の surfaces array は渡さないでください。 偶発的な scope loss が global prompt text にならないように reject されます。

native Codex app-server developer instruction は、他の prompt surface より厳格です。 codex_app_server に明示的に scope された guidance だけが、その高優先度 lane に昇格されます。 legacy string guidance と unscoped structured guidance は、互換性のために non-Codex prompt surface で引き続き利用できます。

infrastructure

workflow Plugin 向け host hook

host hook は、provider、channel、または tool を追加するだけでなく、host lifecycle に参加する必要がある Plugin のための SDK seam です。これらは汎用コントラクトです。 Plan Mode も使用できますが、approval workflow、workspace policy gate、background monitor、 setup ウィザード、UI companion Plugin も使用できます。

新しい Plugin コードにはグループ化された名前空間を使用します。

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

同等のフラットなメソッドは、既存の plugins 向けの非推奨の互換エイリアスとして引き続き利用できます。api.registerSessionExtension、api.enqueueNextTurnInjection、api.registerControlUiDescriptor、api.registerRuntimeLifecycle、api.registerAgentEventSubscription、api.emitAgentEvent、api.setRunContext、api.getRunContext、api.clearRunContext、api.registerSessionSchedulerJob、api.registerSessionAction、api.sendSessionAttachment、api.scheduleSessionTurn、または api.unscheduleSessionTurnsByTag を直接呼び出す新しい Plugin コードは追加しないでください。

scheduleSessionTurn(...) は、Gateway Cron スケジューラー上のセッションスコープの便利機能です。Cron はタイミングを所有し、ターンの実行時にバックグラウンドタスクレコードを作成します。Plugin SDK は対象セッション、Plugin 所有の命名、クリーンアップのみを制約します。作業自体に永続的な複数ステップの Task Flow 状態が必要な場合は、スケジュール済みターン内で api.runtime.tasks.managedFlows を使用してください。

これらのコントラクトは、権限を意図的に分割しています。

• 外部 plugins は、セッション拡張、UI 記述子、コマンド、ツールメタデータ、次ターン注入、通常のフックを所有できます。
• 信頼済みツールポリシーは通常の before_tool_call フックより前に実行され、ホストから信頼されます。バンドル済みポリシーが最初に実行されます。インストール済み Plugin ポリシーには明示的な有効化と contracts.trustedToolPolicies 内のローカル id が必要で、Plugin 読み込み順で次に実行されます。ポリシー id は登録元 Plugin にスコープされます。
• 予約済みコマンドの所有権はバンドル専用です。外部 plugins は独自のコマンド名またはエイリアスを使用してください。
• allowPromptInjection=false は、agent_turn_prepare、before_prompt_build、heartbeat_prompt_contribution、レガシー before_agent_start からのプロンプトフィールド、enqueueNextTurnInjection を含む、プロンプトを変更するフックを無効にします。

Plan 以外のコンシューマー例:

Gateway 検出登録

api.registerGatewayDiscoveryService(...) により、Plugin は mDNS/Bonjour などのローカル検出トランスポート上でアクティブな Gateway をアドバタイズできます。OpenClaw はローカル検出が有効な場合に Gateway 起動中にサービスを呼び出し、現在の Gateway ポートと非シークレットの TXT ヒントデータを渡し、Gateway シャットダウン中に返された stop ハンドラーを呼び出します。

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Gateway 検出 plugins は、アドバタイズされた TXT 値をシークレットや認証として扱ってはいけません。検出はルーティングヒントです。Gateway 認証と TLS ピンニングが引き続き信頼を所有します。

CLI 登録メタデータ

api.registerCli(registrar, opts?) は 2 種類のコマンドメタデータを受け付けます。

• commands: レジストラーが所有する明示的なコマンド名
• descriptors: CLI ヘルプ、ルーティング、遅延 Plugin CLI 登録に使用される解析時コマンド記述子
• parentPath: ["nodes"] など、ネストされたコマンドグループ用の任意の親コマンドパス

ペアリング済みノード機能には、api.registerNodeCliFeature(registrar, opts?) を推奨します。これは api.registerCli(..., { parentPath: ["nodes"] }) の小さなラッパーであり、openclaw nodes canvas のようなコマンドを明示的な Plugin 所有ノード機能にします。

Plugin コマンドを通常のルート CLI 経路で遅延読み込みのままにしたい場合は、そのレジストラーが公開するすべてのトップレベルコマンドルートをカバーする descriptors を提供してください。

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

ネストされたコマンドは、解決済みの親コマンドを program として受け取ります。

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

遅延ルート CLI 登録が不要な場合にのみ、commands を単独で使用してください。その積極的な互換経路は引き続きサポートされますが、解析時の遅延読み込み用に記述子ベースのプレースホルダーをインストールしません。

CLI バックエンド登録

api.registerCliBackend(...) により、Plugin は claude-cli や my-cli などのローカル AI CLI バックエンドのデフォルト設定を所有できます。

• バックエンドの id は、my-cli/gpt-5 のようなモデル参照でプロバイダープレフィックスになります。
• バックエンドの config は agents.defaults.cliBackends.<id> と同じ形を使います。
• ユーザー設定が引き続き優先されます。OpenClaw は CLI を実行する前に、 プラグインのデフォルトに agents.defaults.cliBackends.<id> をマージします。
• バックエンドがマージ後に互換性のための書き換えを必要とする場合 （たとえば古いフラグ形状の正規化）には、normalizeConfig を使います。
• OpenClaw の thinking レベルをネイティブの effort フラグへマッピングするなど、 CLI 方言に属するリクエスト単位の argv 書き換えには resolveExecutionArgs を使います。 このフックは ctx.executionMode を受け取ります。一時的な /btw 呼び出しに バックエンドネイティブの分離フラグを追加するには "side-question" を使います。 それらのフラグが、通常は常時有効の CLI でネイティブツールを確実に無効化する場合は、 sideQuestionToolMode: "disabled" も宣言します。

エンドツーエンドの作成ガイドについては、 CLI バックエンドプラグインを参照してください。

排他的スロット

非推奨のメモリ埋め込みアダプター

• registerMemoryCapability は推奨される排他的メモリプラグイン API です。
• registerMemoryCapability は publicArtifacts.listArtifacts(...) も公開できます。 これにより、コンパニオンプラグインは特定のメモリプラグインの非公開レイアウトへ 直接到達する代わりに、openclaw/plugin-sdk/memory-host-core を通じて エクスポートされたメモリアーティファクトを利用できます。
• registerMemoryPromptSection、registerMemoryFlushPlan、および registerMemoryRuntime は、レガシー互換の排他的メモリプラグイン API です。
• MemoryFlushPlan.model は、有効なフォールバックチェーンを継承せずに、 フラッシュターンを ollama/qwen3:8b のような正確な provider/model 参照へ固定できます。
• registerMemoryEmbeddingProvider は非推奨です。新しい埋め込みプロバイダーは api.registerEmbeddingProvider(...) と contracts.embeddingProviders を 使うべきです。
• 既存のメモリ固有プロバイダーは移行期間中も動作し続けますが、 プラグイン検査では、バンドルされていないプラグインに対する互換性負債として報告されます。

イベントとライフサイクル

例、一般的なフック名、ガードセマンティクスについては、 Plugin フックを参照してください。

フック判定セマンティクス

before_install はプラグインランタイムのライフサイクルフックであり、オペレーターのインストール ポリシー面ではありません。許可/ブロックの判定が CLI と Gateway バックのインストールまたは更新パスを カバーする必要がある場合は、security.installPolicy を使います。

• before_tool_call: { block: true } を返すと終端です。いずれかのハンドラーが設定すると、低優先度のハンドラーはスキップされます。
• before_tool_call: { block: false } を返すと、判定なし（block を省略した場合と同じ）として扱われ、上書きとしては扱われません。
• before_install: { block: true } を返すと終端です。いずれかのハンドラーが設定すると、低優先度のハンドラーはスキップされます。
• before_install: { block: false } を返すと、判定なし（block を省略した場合と同じ）として扱われ、上書きとしては扱われません。
• reply_dispatch: { handled: true, ... } を返すと終端です。いずれかのハンドラーがディスパッチを主張すると、低優先度のハンドラーとデフォルトのモデルディスパッチパスはスキップされます。
• message_sending: { cancel: true } を返すと終端です。いずれかのハンドラーが設定すると、低優先度のハンドラーはスキップされます。
• message_sending: { cancel: false } を返すと、判定なし（cancel を省略した場合と同じ）として扱われ、上書きとしては扱われません。
• message_received: 受信スレッド/トピックのルーティングが必要な場合は、型付きの threadId フィールドを使います。metadata はチャンネル固有の追加情報用に残します。
• message_sending: チャンネル固有の metadata へフォールバックする前に、型付きの replyToId / threadId ルーティングフィールドを使います。
• gateway_start: 内部の gateway:startup フックに依存する代わりに、Gateway が所有する起動状態には ctx.config、ctx.workspaceDir、および ctx.getCron?.() を使います。
• cron_changed: Gateway が所有する Cron ライフサイクルの変更を監視します。外部のウェイクスケジューラーを同期する場合は event.job?.state?.nextRunAtMs と ctx.getCron?.() を使い、期限チェックと実行の信頼できる情報源として OpenClaw を維持します。

API オブジェクトフィールド

内部モジュール規約

プラグイン内では、内部インポートにローカルのバレルファイルを使います。

my-plugin/  api.ts            # Public exports for external consumers  runtime-api.ts    # Internal-only runtime exports  index.ts          # Plugin entry point  setup-entry.ts    # Lightweight setup-only entry (optional)

Facade で読み込まれるバンドル済みプラグインの公開面（api.ts、runtime-api.ts、 index.ts、setup-entry.ts、および同様の公開エントリファイル）は、 OpenClaw がすでに実行中の場合、有効なランタイム設定スナップショットを優先します。 ランタイムスナップショットがまだ存在しない場合は、ディスク上の解決済み設定ファイルへ フォールバックします。パッケージ化されたバンドル済みプラグインの Facade は、 OpenClaw のプラグイン Facade ローダーを通じて読み込むべきです。 dist/extensions/... からの直接インポートは、パッケージ化インストールが プラグイン所有コードに対して使うマニフェストとランタイムサイドカーチェックを迂回します。

プロバイダープラグインは、ヘルパーが意図的にプロバイダー固有であり、まだ汎用 SDK サブパスに属さない場合、狭いプラグインローカルの契約バレルを公開できます。バンドル済みの例:

• Anthropic: Claude beta-header と service_tier ストリームヘルパー用の公開 api.ts / contract-api.ts 境界。
• @openclaw/openai-provider: api.ts はプロバイダービルダー、デフォルトモデルヘルパー、リアルタイムプロバイダービルダーをエクスポートします。
• @openclaw/openrouter-provider: api.ts はプロバイダービルダーに加えて、オンボーディング/設定ヘルパーをエクスポートします。

関連