Plugin SDK の概要

​

インポート規則

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

​

サブパスリファレンス

​

登録 API

​

ケイパビリティの登録

​

ツールとコマンド

agentPromptGuidance: [
  "グローバルコマンドのヒント。",
  { text: "これは OpenClaw のメインプロンプトでのみ表示します。", surfaces: ["openclaw_main"] },
];

​

インフラストラクチャ

​

応答確認後の Webhook 処理

import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guards";

void runDetachedWebhookWork(() => processWebhookEvent(event)).catch((error) => {
  runtime.error?.(`Webhook のディスパッチに失敗しました: ${String(error)}`);
});

​

リクエスター単位の MCP 接続

api.registerMcpServerConnectionResolver({
  serverName: "user-email",
  resolve: async (ctx) => {
    // ctx.requesterSenderId はホストが信頼する値です。ここで送信者の識別情報を作り出してはいけません。
    const token = await lookupUserToken(ctx.requesterSenderId);
    if (!token) {
      return null; // 現在の実行ではこのサーバーを除外します
    }
    return {
      url: "https://mcp.example.com/email",
      headers: { Authorization: `Bearer ${token}` },
    };
  },
});

• リゾルバーコンテキストが保持するのは、信頼されたホスト識別情報だけです（requesterSenderId、 任意の agentAccountId / messageChannel）。将来、信頼されたフィールド（たとえば Cron／サブエージェントのユーザーコンテキスト）を追加的に加えられます。
• 1 つの Plugin が 1 つのサーバー名を所有します。別の Plugin から同じ serverName に対する重複した registerMcpServerConnectionResolver が登録されると、エラー診断とともに拒否されます（最初の登録が優先されます）。したがって、 接続の所有権が Plugin のロード順序に依存することはありません。
• ツール名は宣言されたサーバーの完全な集合から導出されるため、部分的な解決によって リクエスター間またはターン間で安全なサーバー名が変化することはありません。コアは、 リクエスターごとの異なるエンドポイントが同一のツールスキーマを提供するかどうかを検証しません。 リゾルバーはすべてのリクエスターを同一の論理サービスに接続する必要があります。そうしないと、 ツールスキーマ（およびプロンプトキャッシュの安定性）がリクエスターごとに分岐します。
• 信頼された requesterSenderId がない実行（Cron、サブエージェント、Heartbeat、パブリック Gateway）では、リクエスター単位のサーバーを実体化しません。共有の フォールバック接続はありません。
• resolve はサーバーごとに 10 秒を上限とします。タイムアウトまたは例外発生時は、 静的 MCP を失敗させることなく、その実行から該当サーバーを除外します。
• 解決済み接続は、リクエスターごとに最大でも 5 分ごとに再検証されます。 ローテーション時は新しい認証情報でトランスポートを再構築し、null の結果が返された場合は 接続を無効化します（キャッシュされたランタイムはセッション途中でも破棄されます）。したがって、無効化または ローテーションされた認証情報が最大 5 分間使用され続ける可能性があります。
• 解決済みの headers がログ記録または永続化されることはありません。コアは認証情報の ローテーションを検出するために、エフェメラルなメモリ内キー付きダイジェスト（プロセスローカル HMAC）だけを保持し、 解決済みのヘッダー／URL 認証情報値をログ／デバッグキャプチャの リダクションレジストリに登録します。
• リクエスター単位のサーバーは MCP App ビューを生成しません。ビューは リクエスター認証済みの実行より長く存続し、Gateway のビュー境界にはリクエスターの 識別情報がないため、これらのサーバーではアプリのプレビューをフェイルクローズのままにします。ツール結果には 影響しません。
• リゾルバーのない静的サーバーは、既存のセッション単位のライフサイクルを維持します。
• ハーネス配信ルール: リクエスター単位のサーバーがハーネスネイティブの MCP クライアント設定（Codex スレッド mcp_servers、CLI -c mcp_servers=…、またはその他の セッション共有 MCP プロジェクション）に入ることはありません。代わりに、ハーネスはそれらを実行単位の ツールとして配信します。
  • 組み込みランナー: セッション MCP ランタイム + バンドルツール（静的 + スコープ付き）。
  • Codex app-server: materializeRequesterScopedMcpToolsForHarnessRun を介した動的ツール（スコープ付きのみ。静的 サーバーは Codex のネイティブ MCP クライアントに残ります）。
• スコープ付きツールの 仕様 は、そのセッションで最初に正常に解決された後は セッションを通じて安定するため、共有スレッド型ハーネス（Codex）は 送信者が変わってもスレッドをローテーションしません。どのリクエスターも解決される前は、 スコープ付き仕様は公開されません。
• 共有スレッド型ハーネス上の未認証リクエスターにも、公開された スコープ付きツールは表示されます。そのいずれかを呼び出すと、そのリクエスターには 明確な未接続ツールエラーが返されます。OpenClaw が別のリクエスターの認証情報へ フォールバックすることはありません。

​

ワークフロー Plugin 用のホストフック

api.session.controls.registerControlUiDescriptor({
  surface: "tab",
  id: "logbook",
  label: "日誌",
  description: "画面のスナップショットから構築された、タイムライン形式の一日。",
  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 内のローカル ID が必要であり、その後 Plugin の読み込み順に実行されます。ポリシー ID は、登録した Plugin のスコープ内に限定されます。
• 予約済みコマンドの所有権はバンドル版に限定されます。外部 Plugin は独自の コマンド名またはエイリアスを使用する必要があります。
• allowPromptInjection=false は、 agent_turn_prepare、before_prompt_build、heartbeat_prompt_contribution、 および 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: "Matrix のアカウント、検証、デバイス、プロファイル状態を管理",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "ペアリングされた Node からキャンバスコンテンツをキャプチャまたはレンダリング",
        hasSubcommands: true,
      },
    ],
  },
);

​

CLI バックエンドの登録

• バックエンドの id は、my-cli/gpt-5 のようなモデル参照のプロバイダープレフィックスになります。
• バックエンドの config は正式なコマンドアダプターです。argv、環境、 パーサー、セッション、画像、信頼性に関する動作は Plugin コードに実装されます。
• ユーザーはモデル参照またはモデルスコープの agentRuntime.id を介してバックエンドを選択します。 openclaw.json はアダプターを書き換えません。
• 登録済みの静的フィールドにランタイム対応の 正規化処理が必要な場合は、normalizeConfig を使用します。
• OpenClaw の思考レベルをネイティブの effort フラグにマッピングするなど、CLI 方言に属するリクエストスコープの argv 書き換えには、resolveExecutionArgs を使用します。このフックは ctx.executionMode を受け取ります。一時的な /btw 呼び出しに バックエンドネイティブの分離フラグを追加するには、"side-question" を使用します。通常は常時有効な CLI で、それらのフラグによって ネイティブツールを確実に無効化できる場合は、sideQuestionToolMode: "disabled" も宣言します。
• バックエンドが所有する起動環境または一時的な 認証／設定ブリッジには、prepareExecution を使用します。その ctx.contextTokenBudget は実行用に選択された有効なトークン 上限であるため、ネイティブ Compaction バックエンドは、プロバイダー固有のコア分岐を設けずに 独自のしきい値を調整できます。また、バックエンドのステージングで同梱 MCP 設定を拡張する必要がある場合は、 コアで準備された ctx.env も受け取ります。
• 特定の実行ですべてのネイティブツールを無効化できるバックエンドは、 nativeToolMode: "selectable" を宣言できます。制限された呼び出しでは、正確な ctx.toolAvailability.native リストと正規の ctx.toolAvailability.openClaw 名が渡されます。 toolAvailabilityEnforcement: "execution-args" を宣言して最終的な新規／再開 argv で契約を適用するか、 "prepare-execution" を宣言してステージングされたポリシーで適用し、 toolAvailabilityEnforced: true を返します。OpenClaw は Cron toolsAllow などの ランタイム上限のためにネイティブツールを無効化し、宣言された適用パスが不完全な場合は フェイルクローズします。

​

排他的スロット

​

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

• registerMemoryCapability は排他的なメモリ Plugin API です。
• registerMemoryCapability は、ホスト管理のエクスポート用に publicArtifacts.listArtifacts(...) も公開できます。宣言されたアーティファクトを列挙するコンパニオン Plugin は、対象を絞った公開コンシューマー API が提供されるまで、維持されている openclaw/plugin-sdk/memory-host-core ファサードの listActiveMemoryPublicArtifacts(...) を引き続き使用します。別の Plugin の非公開レイアウトに直接アクセスしてはなりません。
• MemoryFlushPlan.model は、アクティブなフォールバック チェーンを継承せずに、フラッシュターンを ollama/qwen3:8b などの正確な provider/model 参照に固定できます。
• registerMemoryEmbeddingProvider は非推奨です。新しい埋め込みプロバイダーは、 api.registerEmbeddingProvider(...) と contracts.embeddingProviders を使用してください。
• 既存のメモリ固有プロバイダーは移行 期間中も引き続き動作しますが、Plugin の検査では、同梱されていない 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 がまだ読み込み中の場合があります。
• cron_reconciled: 起動後またはスケジューラーの再読み込み後に、完全な外部 Cron プロジェクションを再構築します。これには reason と、enabled: false を含む有効な enabled 状態が含まれ、ctx.getCron?.() は正確に調整されたスケジューラーを返します。永続的なプロジェクション処理には ctx.abortSignal を渡します。そのスケジューラーのスナップショットが置き換えられるか、Gateway が閉じると中止されます。
• cron_changed: Gateway が所有する Cron のライフサイクル変更を監視します。scheduled および removed イベントはコミット後の調整ヒントであり、順序付けされた差分ログではありません。スケジュールされたイベントの event.nextRunAtMs は、ジョブに次回の起動がない場合は存在しません。削除イベントには、削除されたジョブのスナップショットが引き続き含まれます。

​

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

​

内部モジュールの規約

my-plugin/
  api.ts            # 外部コンシューマー向けの公開エクスポート
  runtime-api.ts    # 内部専用のランタイムエクスポート
  index.ts          # Plugin のエントリポイント
  setup-entry.ts    # セットアップ専用の軽量エントリ（省略可能）

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

​

関連項目