Plugin のエントリーポイント

​

パッケージエントリ

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

• extensions と setupEntry はソースエントリであり、ワークスペースおよび git チェックアウトでの開発に使用されます。
• runtimeExtensions と runtimeSetupEntry は、インストール済み パッケージで推奨されます。これにより、npm パッケージは実行時の TypeScript コンパイルを省略できます。
• runtimeExtensions が存在する場合、配列の長さが extensions と 一致している必要があります（エントリは位置ごとに対応します）。runtimeSetupEntry には setupEntry が必要です。
• runtimeExtensions/runtimeSetupEntry アーティファクトが宣言されているにもかかわらず 存在しない場合、インストールまたは検出はパッケージングエラーで失敗します。OpenClaw は 暗黙にソースへフォールバックしません。以下のソースフォールバックは、 ランタイムエントリがまったく宣言されていない場合にのみ適用されます。
• インストール済みパッケージが TypeScript ソースエントリのみを宣言している場合、OpenClaw は 対応するビルド済みの dist/*.js（または .mjs/.cjs）ピアを探して使用します。 見つからない場合は TypeScript ソースへフォールバックします。
• すべてのエントリパスは、プラグインパッケージのディレクトリ内に収まる必要があります。ランタイム エントリや推論されたビルド済み JS ピアが存在しても、パッケージ外を指す extensions または setupEntry ソースパスが有効になるわけではありません。

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Stock Quotes",
  description: "Fetch stock quotes.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "API key." })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "Quote",
      description: "Fetch a quote.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Ticker symbol." }),
      }),
      outputSchema: Type.Object(
        {
          symbol: Type.String(),
          hasKey: Type.Boolean(),
        },
        { additionalProperties: false },
      ),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema は省略可能です。省略すると厳密な空オブジェクトスキーマが使用されます （生成されるマニフェストには引き続き configSchema が含まれます）。
• execute は通常の文字列または JSON シリアライズ可能な値を返します。ヘルパーは、 元の（文字列化されていない）戻り値を details に設定した テキストツール結果としてラップします。
• outputSchema は、Code Mode および Tool Search 向けに、その元の details 値を 必要に応じて記述します。カタログ呼び出しは、実行前に無効なスキーマを拒否し、 返却前に最終値を検証します。
• カスタムツール結果向けに、openclaw/plugin-sdk/tool-results は textResult と jsonResult をエクスポートします。
• ツール名は静的であるため、openclaw plugins build は 手作業で名前を重複記述せずに、宣言されたツールから contracts.tools を導出します。
• ランタイムの読み込みは引き続き厳密です。インストール済みプラグインには、 openclaw.plugin.json および package.json の openclaw.extensions が必要です。OpenClaw は、 不足しているマニフェストデータを推論するためにプラグインコードを実行することはありません。

​

definePluginEntry

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

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({/* ... */});
    api.registerTool({/* ... */});
  },
});

• id は、openclaw.plugin.json マニフェストと一致する必要があります。
• 外部セッションカタログでは、 openclaw/plugin-sdk/session-catalog と api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }) を使用します。 コアは sessions.catalog.* Gateway メソッドを所有します。プロバイダーは RPC を登録せずに、 ホスト、セッション、正規化されたトランスクリプトのプロジェクションを返します。 リストプロバイダーは、各ホストの処理が確定するたびに、省略可能な onHost(host) コールバックを 呼び出す必要があります。返されるホスト配列は、最終的な互換性スナップショットとして引き続き必須です。
• kind は非推奨です。代わりに、openclaw.plugin.json マニフェストの kind フィールドで排他的スロット（"memory" または "context-engine"）を宣言してください。ランタイムエントリの kind は、 古いプラグイン向けの互換性フォールバックとしてのみ残されています。
• configSchema は遅延評価のための関数にできます。OpenClaw は最初のアクセス時に スキーマを解決してメモ化するため、負荷の高いスキーマビルダーは一度だけ実行されます。
• nodeHostCommands ディスクリプターでは isAvailable({ config, env }) を定義できます。 false を返すと、そのコマンドと機能はヘッドレス Node の Gateway 宣言から省略されます。 OpenClaw は Node ローカルの起動設定に対してこれを評価します。コマンドハンドラーは、 呼び出された際にも引き続き利用可能性を検証する必要があります。

​

defineChannelPluginEntry

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

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

• setRuntime は、"cli-metadata" と "tool-discovery" を除くすべてのモードで実行されます。通常は createPluginRuntimeStore を介して、ここにランタイム参照を保存します。
• registerCliMetadata は、"cli-metadata"、"discovery"、 "full" で実行されます。チャネルが所有する CLI ディスクリプターの標準的な配置場所として使用すると、 ルートヘルプによるアクティベーションを防ぎ、検出スナップショットに静的コマンドメタデータを含め、 通常の CLI 登録とプラグインの完全読み込みとの互換性を維持できます。
• registerFull は、"full" と "tool-discovery" でのみ実行されます。 "tool-discovery" では、チャネル登録の_代わりに_実行されます。OpenClaw は registerChannel/setRuntime を完全にスキップし、registerFull のみを 呼び出します。そのため、スタンドアロンのツール検出または実行にチャネルが必要とするプロバイダーやツールの登録は、 通常のチャネル設定の背後ではなく、ここに配置する必要があります。
• 検出登録は非アクティベーション型ですが、インポートを行わないわけではありません。OpenClaw は、 スナップショットを構築するために、信頼済みのプラグインエントリとチャネルプラグインモジュールを評価する場合があります。 トップレベルのインポートに副作用を持たせず、ソケット、クライアント、ワーカー、サービスは "full" 専用のパス内に配置してください。
• definePluginEntry と同様に、configSchema は遅延ファクトリーにできます。OpenClaw は、 最初のアクセス時に解決されたスキーマをメモ化します。

• 遅延読み込みしつつルート CLI の解析ツリーから消えないようにする、プラグイン所有のルート CLI コマンドには api.registerCli(..., { descriptors: [...] }) を使用します。 ディスクリプター名は、先頭を英字または数字とし、英字、数字、ハイフン、 アンダースコアのみに一致する必要があります。OpenClaw はそれ以外の 形式を拒否し、ヘルプを表示する前に説明から端末制御シーケンスを 除去します。レジストラーが公開するすべてのトップレベルコマンドルートを網羅してください。 commands のみの場合は、引き続き先行読み込みされる互換性パスが使用されます。
• ペアリング済み Node の機能コマンドには api.registerNodeCliFeature(...) を使用し、 openclaw nodes の配下（ registerCli(registrar, { parentPath: ["nodes"], ... }) と同等）に配置されるようにします。
• その他のネストされたプラグインコマンドでは、parentPath を追加し、レジストラーに渡される program オブジェクトにコマンドを登録します。OpenClaw はプラグインを呼び出す前に、 これを親コマンドへ解決します。
• チャンネルプラグインでは、registerCliMetadata から CLI ディスクリプターを登録し、 registerFull はランタイム専用の処理に集中させます。
• registerFull で Gateway RPC メソッドも登録する場合は、 プラグイン固有のプレフィックス配下に置きます。予約済みのコア管理名前空間（config.*、 exec.approvals.*、wizard.*、update.*）は常に operator.admin に強制変換されます。

​

defineSetupPluginEntry

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* セットアップセーフなルート */
      },
    });
  },
});

​

登録モード

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  if (api.registrationMode === "tool-discovery") {
    // ケイパビリティ専用サーフェス（プロバイダー／ツール）を登録し、チャンネルは登録しません。
    return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // 重量なランタイム専用登録
  api.registerService(/* ... */);
}

api.registerService({
  id: "index-events",
  start(ctx) {
    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });
  },
});

​

プラグインの形態

​

関連項目

• SDK の概要 - 登録 API とサブパスのリファレンス
• ランタイムヘルパー - api.runtime と createPluginRuntimeStore
• セットアップと設定 - マニフェスト、セットアップエントリ、遅延読み込み
• チャンネルプラグイン - ChannelPlugin オブジェクトの構築
• プロバイダープラグイン - プロバイダーの登録とフック