Plugin SDKの概要

​

インポート規約

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

サブパスリファレンス

​

登録 API

​

ケイパビリティ登録

​

ツールとコマンド

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

​

インフラストラクチャ

​

ワークフロー Plugin 向けホストフック

api.session.controls.registerControlUiDescriptor({
  surface: "tab",
  id: "logbook",
  label: "Logbook",
  description: "Your day as a timeline, built from screen snapshots.",
  icon: "sun",
  group: "control",
  requiredScopes: ["operator.write"],
});

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

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

​

Gateway 検出登録

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() };
  },
});

​

CLI 登録メタデータ

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

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,
      },
    ],
  },
);

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 バックエンド登録

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

​

排他的スロット

​

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

• 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 を使用してください。
• 既存のメモリ固有プロバイダーは移行期間中も動作しますが、 プラグイン検査では、非バンドルプラグインに対する互換性負債として報告されます。

​

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

​

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

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

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

​

関連