Plugin SDK の概要

プラグイン SDK は、プラグインとコアの間の型付きコントラクトです。このページは、何をインポートするか、および何を登録できるかのリファレンスです。

インポート規約

常に特定のサブパスからインポートします。

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

チャネル設定では、チャネルが所有する JSON Schema を openclaw.plugin.json#channelConfigs を通じて公開します。plugin-sdk/channel-config-schema サブパスは、共有スキーマプリミティブと汎用ビルダー用です。OpenClaw のバンドルプラグインは、保持されているバンドルチャネルスキーマに plugin-sdk/bundled-channel-config-schema を使用します。非推奨の互換性エクスポートは plugin-sdk/channel-config-schema-legacy に残っています。どちらのバンドルスキーマサブパスも、新しいプラグインのパターンではありません。

サブパスリファレンス

プラグイン SDK は、領域別（プラグインエントリー、チャネル、プロバイダー、認証、ランタイム、ケイパビリティ、メモリ、予約済みのバンドルプラグインヘルパー）にグループ化された狭いサブパスの集合として公開されます。グループ化されリンクされた完全なカタログについては、Plugin SDK サブパス を参照してください。

コンパイラーエントリーポイントのインベントリは scripts/lib/plugin-sdk-entrypoints.json にあります。パッケージエクスポートは、scripts/lib/plugin-sdk-private-local-only-subpaths.json に列挙されたリポジトリローカルのテスト/内部サブパスを差し引いた後の公開サブセットから生成されます。公開エクスポート数を監査するには pnpm plugin-sdk:surface を実行してください。十分に古く、バンドル拡張機能の本番コードで未使用の非推奨公開サブパスは scripts/lib/plugin-sdk-deprecated-public-subpaths.json で追跡されます。広い非推奨の再エクスポートバレルは scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json で追跡されます。

登録 API

register(api) コールバックは、次のメソッドを持つ OpenClawPluginApi オブジェクトを受け取ります。

ケイパビリティ登録

ツールとコマンド

プラグインコマンドは、エージェントが短い、コマンド所有のルーティングヒントを必要とする場合に agentPromptGuidance を設定できます。そのテキストはコマンド自体についての内容に留めてください。プロバイダーまたはプラグイン固有のポリシーをコアプロンプトビルダーに追加しないでください。

インフラストラクチャ

ワークフロープラグイン向けホストフック

ホストフックは、プロバイダー、チャネル、ツールを追加するだけではなく、ホストライフサイクルに参加する必要があるプラグイン向けの SDK シームです。これらは汎用コントラクトです。Plan Mode で使用できますが、承認ワークフロー、ワークスペースポリシーゲート、バックグラウンドモニター、セットアップウィザード、UI コンパニオンプラグインでも使用できます。

新しいプラグインコードでは、グループ化された名前空間を使用してください。

• 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(...)

同等のフラットメソッドは、既存プラグイン向けの非推奨互換性エイリアスとして引き続き利用できます。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 を直接呼び出す新しいプラグインコードは追加しないでください。

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

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

• 外部 Plugin は、セッション拡張、UI 記述子、コマンド、ツールメタデータ、次ターン注入、通常のフックを所有できます。
• 信頼済みツールポリシーは通常の before_tool_call フックより前に実行され、ホストの安全ポリシーに関与するためバンドル専用です。
• 予約済みコマンドの所有権はバンドル専用です。外部 Plugin は独自のコマンド名またはエイリアスを使用してください。
• 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 検出 Plugin は、公開された TXT 値をシークレットや認証として扱ってはいけません。検出はルーティングのヒントです。Gateway 認証と TLS ピンニングが引き続き信頼を所有します。

CLI 登録メタデータ

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

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

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

Plugin コマンドを通常のルート CLI パスで遅延ロードされたままにしたい場合は、その registrar が公開するすべてのトップレベルコマンドルートをカバーする 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 は codex-cli などのローカル AI CLI バックエンドのデフォルト設定を所有できます。

• バックエンドの id は、codex-cli/gpt-5 のようなモデル参照のプロバイダープレフィックスになります。
• バックエンドの config は、agents.defaults.cliBackends.<id> と同じ形を使用します。
• ユーザー設定が引き続き優先されます。OpenClaw は CLI を実行する前に、agents.defaults.cliBackends.<id> を Plugin のデフォルトに重ねてマージします。
• バックエンドがマージ後に互換性のための書き換えを必要とする場合は、normalizeConfig を使用します。たとえば古いフラグ形状の正規化です。
• OpenClaw の思考レベルをネイティブな effort フラグにマッピングするなど、CLI 方言に属するリクエストスコープの argv 書き換えには、resolveExecutionArgs を使用します。

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

排他的スロット

メモリ埋め込みアダプター

• registerMemoryCapability は、推奨される排他的メモリ Plugin API です。
• registerMemoryCapability は publicArtifacts.listArtifacts(...) も公開できるため、コンパニオン Plugin は特定のメモリ Plugin のプライベートレイアウトに踏み込まずに、openclaw/plugin-sdk/memory-host-core を通じてエクスポート済みメモリアーティファクトを利用できます。
• registerMemoryPromptSection、registerMemoryFlushPlan、registerMemoryRuntime は、レガシー互換の排他的メモリ Plugin API です。
• MemoryFlushPlan.model は、アクティブなフォールバックチェーンを継承せずに、フラッシュターンを ollama/qwen3:8b のような正確な provider/model 参照に固定できます。
• registerMemoryEmbeddingProvider を使うと、アクティブなメモリ Plugin は、1 つ以上の埋め込みアダプター ID（たとえば openai、gemini、またはカスタムの Plugin 定義 ID）を登録できます。
• agents.defaults.memorySearch.provider や agents.defaults.memorySearch.fallback などのユーザー設定は、それらの登録済みアダプター ID に対して解決されます。

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

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

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

• 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 オブジェクトフィールド

内部モジュール規約

Plugin 内では、内部インポートにローカルのバレルファイルを使用します。

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)

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

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

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

関連