Plugin エントリポイント

​

パッケージエントリ

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

• extensions と setupEntry はソースエントリで、ワークスペースおよび git checkout 開発に使われます。
• runtimeExtensions と runtimeSetupEntry はインストール済み パッケージで優先されます。これにより npm パッケージは実行時の TypeScript コンパイルをスキップできます。
• runtimeExtensions が存在する場合は、配列の長さが extensions と一致している必要があります (エントリは位置でペアになります)。runtimeSetupEntry には setupEntry が必要です。
• runtimeExtensions/runtimeSetupEntry アーティファクトが宣言されているのに 存在しない場合、インストール/検出はパッケージングエラーで失敗します。OpenClaw は 暗黙にソースへフォールバックしません。ソースフォールバック (下記) は、ランタイムエントリがまったく宣言されていない場合にのみ適用されます。
• インストール済みパッケージが TypeScript ソースエントリのみを宣言している場合、OpenClaw は 対応するビルド済み dist/*.js (または .mjs/.cjs) ピアを探して使用します。 見つからない場合は TypeScript ソースへフォールバックします。
• すべてのエントリパスは Plugin パッケージディレクトリ内にとどまる必要があります。ランタイム エントリや推論されたビルド済み 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." }),
      }),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema は任意です。省略すると厳密な空オブジェクトスキーマが使われます (生成されたマニフェストには引き続き configSchema が含まれます)。
• execute はプレーン文字列または JSON シリアライズ可能な値を返します。ヘルパーは それをテキストツール結果としてラップし、details には元の (文字列化されていない) 戻り値を設定します。
• カスタムツール結果には、openclaw/plugin-sdk/tool-results が textResult と jsonResult をエクスポートしています。
• ツール名は静的なので、openclaw plugins build は手動で名前を重複させることなく、 宣言されたツールから contracts.tools を導出します。
• ランタイム読み込みは厳密なままです。インストール済み Plugin には引き続き openclaw.plugin.json と package.json の openclaw.extensions が必要です。OpenClaw は 不足しているマニフェストデータを推論するために Plugin コードを実行することはありません。

​

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 マニフェストと一致している必要があります。
• kind は非推奨です。代わりに openclaw.plugin.json マニフェストの kind フィールドで 排他的スロット ("memory" または "context-engine") を宣言してください。 ランタイムエントリの kind は、古い Plugin との互換性フォールバックとしてのみ残っています。
• configSchema は遅延評価のための関数にできます。OpenClaw は初回アクセス時にスキーマを解決して メモ化するため、コストの高いスキーマビルダーは一度だけ実行されます。

​

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 登録は完全な Plugin 読み込みと互換性を保ちます。
• registerFull は "full" と "tool-discovery" でのみ実行されます。 "tool-discovery" では、チャネル登録の_代わりに_実行されます。OpenClaw は registerChannel/setRuntime を完全にスキップし、registerFull のみを呼び出すため、 スタンドアロンのツール検出または実行にチャネルが必要とする Provider/ツール登録は、 通常のチャネルセットアップの背後ではなく、そこに置く必要があります。
• 検出登録は非アクティブ化ですが、インポート不要ではありません。OpenClaw は スナップショットを構築するために、信頼済み Plugin エントリとチャネル Plugin モジュールを評価することがあります。 トップレベルのインポートに副作用がないようにし、ソケット、 クライアント、ワーカー、サービスは "full" 専用パスの背後に置いてください。
• definePluginEntry と同様に、configSchema は遅延ファクトリにできます。OpenClaw は 初回アクセス時に解決済みスキーマをメモ化します。

• ルート CLI の解析木から消えないように遅延読み込みしたい、Plugin 所有のルート CLI コマンドには api.registerCli(..., { descriptors: [...] }) を使います。 ディスクリプタ名は文字、数字、ハイフン、アンダースコアに一致し、文字または数字で始まる必要があります。OpenClaw は他の 形状を拒否し、ヘルプ表示前に説明から端末制御シーケンスを取り除きます。 登録側が公開するすべてのトップレベルコマンドルートをカバーしてください。 commands だけの場合は eager な互換パスのままです。
• ペアノード機能コマンドには api.registerNodeCliFeature(...) を使い、 それらが openclaw nodes の下に配置されるようにします ( registerCli(registrar, { parentPath: ["nodes"], ... }) と同等です)。
• その他のネストされた Plugin コマンドには parentPath を追加し、登録側に渡された program オブジェクト上でコマンドを登録してください。OpenClaw は Plugin を呼び出す前に、 それを親コマンドへ解決します。
• チャネル Plugin では、registerCliMetadata から CLI ディスクリプタを登録し、 registerFull はランタイム専用の作業に集中させてください。
• registerFull が Gateway RPC メソッドも登録する場合は、Plugin 固有のプレフィックスに置いてください。 予約済みのコア管理名前空間 (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) => {
        /* setup-safe route */
      },
    });
  },
});

​

登録モード

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") {
    // Register capability-only surfaces (providers/tools), no channel.
    return;
  }

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

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

​

Plugin の形状

​

関連

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