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.

​

インポート規約

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

​

サブパスリファレンス

​

登録 API

​

ケイパビリティ登録

​

ツールとコマンド

​

インフラストラクチャ

​

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

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

​

排他的スロット

​

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

• 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 に対して解決されます。

​

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

​

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

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

​

関連