OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Plugin の構築

Plugin を使用すると、コアを変更せずに OpenClaw を拡張できます。Plugin は、メッセージング チャネル、モデルプロバイダー、ローカル CLI バックエンド、エージェントツール、フック、メディアプロバイダー、 または Plugin が所有する別の機能を追加できます。

外部 Plugin を OpenClaw リポジトリに追加する必要はありません。パッケージを ClawHub に公開すると、ユーザーは次のコマンドでインストールできます。

bash
openclaw plugins install clawhub:<package-name>

ローンチ移行期間中は、プレフィックスなしのパッケージ指定も引き続き npm からインストールされます。ClawHub で解決する場合は clawhub: プレフィックスを使用してください。

要件

  • Node 22.22.3+、Node 24.15+、または Node 25.9+、および npm または pnpm。
  • TypeScript ESM モジュール。
  • リポジトリ内のバンドル Plugin を開発する場合は、リポジトリをクローンして pnpm install を実行します。 OpenClaw は extensions/* ワークスペースパッケージから バンドル Plugin を検出するため、ソースチェックアウトでの Plugin 開発では pnpm のみを使用できます。

Plugin の形式を選択する

チャネル Plugin

OpenClaw をメッセージングプラットフォームに接続します。
プロバイダー Plugin

モデル、メディア、検索、取得、音声、またはリアルタイムのプロバイダーを追加します。
CLI バックエンド Plugin

OpenClaw のモデルフォールバックを介してローカル AI CLI を実行します。
ツール Plugin

エージェントツールを登録します。

クイックスタート

必須のエージェントツールを 1 つ登録して、最小限のツール Plugin を構築します。これは 実用的な Plugin の最小構成であり、パッケージ、マニフェスト、エントリポイント、 およびローカルでの検証を網羅します。

  • パッケージメタデータを作成する

    package.json
    {"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"openclaw": {"extensions": ["./index.ts"],"compat": {"pluginApi": ">=2026.3.24-beta.2","minGatewayVersion": "2026.3.24-beta.2"},"build": {"openclawVersion": "2026.3.24-beta.2","pluginSdkVersion": "2026.3.24-beta.2"}}}
    openclaw.plugin.json
    {"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

    公開する外部 Plugin のランタイムエントリは、ビルド済み JavaScript ファイルを参照する必要があります。エントリポイントの完全な契約については、SDK エントリポイントを 参照してください。

    設定がない場合でも、すべての Plugin にマニフェストが必要です。OpenClaw が すべての Plugin ランタイムを先行して読み込まずに所有関係を検出できるように、 ランタイムツールを contracts.tools に記載する必要があります。activation.onStartup は 意図を持って設定してください。この例では Gateway の起動時に読み込みます。

    ホストが信頼する Plugin サーフェスもマニフェストによって制限され、インストール済み Plugin では明示的な宣言が必要です。api.registerAgentToolResultMiddleware(...) では 各対象ランタイムを contracts.agentToolResultMiddleware に記載する必要があり、 api.registerTrustedToolPolicy(...) では各ポリシー ID を contracts.trustedToolPolicies に記載する必要があります。これらの宣言により、インストール時の 検査とランタイム登録の整合性が保たれます。

    すべてのマニフェストフィールドについては、Plugin マニフェストを参照してください。

  • ツールを登録する

    index.ts
    import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

    チャネル以外の Plugin には definePluginEntry を使用します。チャネル Plugin では、代わりに openclaw/plugin-sdk/core の defineChannelPluginEntry を使用します。

  • ランタイムをテストする

    インストール済みまたは外部の Plugin では、読み込まれたランタイムを検査します。

    bash
    openclaw plugins inspect my-plugin --runtime --json

    Plugin が CLI コマンドを登録する場合は、そのコマンドも実行して出力を確認します。 例：openclaw demo-plugin ping。

    このリポジトリ内のバンドル Plugin については、OpenClaw が extensions/* ワークスペースからソースチェックアウトの Plugin パッケージを検出します。最も対象に近い テストを実行します。

    bash
    pnpm test extensions/my-plugin/pnpm check

  • パッケージのインストールをテストする

    パッケージとして公開可能な Plugin を公開する前に、ユーザーが利用するものと同じインストール形式を テストします。まずビルドステップを追加し、openclaw.extensions などのランタイムエントリが ./dist/index.js のようなビルド済み JavaScript を参照するようにして、 npm pack にその dist/ 出力が含まれることを確認します。TypeScript ソースエントリは、 ソースチェックアウトとローカル開発パスでのみ使用します。

    次に Plugin をパックし、npm-pack: を使用して tarball をインストールします。

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: は OpenClaw が管理する Plugin ごとの npm プロジェクトを使用するため、 ソースチェックアウトのテストでは見落とす可能性があるランタイム依存関係の誤りを検出できます。これにより パッケージと依存関係の構成は検証されますが、カタログに紐付いた公式の信頼性は検証されません。 ランタイムインポートは dependencies または optionalDependencies に含める必要があります。 devDependencies のみに残された依存関係は、管理対象の ランタイムプロジェクトにはインストールされません。

    公式または特権的な Plugin の動作に対する最終検証として、未加工のアーカイブやパスによるインストールを 使用しないでください。未加工のソースはローカルでのデバッグには役立ちますが、 npm または ClawHub によるインストールと同じ依存関係のパスを検証するものではありません。 Plugin が信頼された公式 Plugin のステータスに依存する場合は、カタログに基づく公式インストール、 または公式の信頼性を記録する公開済みパッケージのパスを使用して、2 つ目の検証を追加してください。 インストールルートと依存関係の所有権の詳細については、 Plugin の依存関係解決を参照してください。

  • 公開する

    公開前にパッケージを検証します。

    bash
    clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

    ClawHub パッケージの正規スニペットは docs/snippets/plugin-publish/ にあります。

  • インストールする

    公開したパッケージを ClawHub 経由でインストールします。

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • ツールの登録

    ツールは必須またはオプションにできます。必須ツールは、Plugin が有効な場合に 常に使用できます。オプションツールでは、OpenClaw が所有元の Plugin ランタイムを 読み込む前に、ユーザーによる明示的なオプトインが必要です。

    ツールファクトリは、deliveryContext、利用可能な場合はアクティブなプラットフォーム会話の nativeChannelId、および requesterSenderId を含む、信頼されたランタイムコンテキストを受け取ります。

    typescript
    register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

    api.registerTool(...) で登録するすべてのツールは、Plugin マニフェストでも 宣言する必要があります。

    json
    {  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

    ユーザーは tools.allow でオプトインします。

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

    オプションツールは、ツールをモデルに公開するかどうかを制御します。モデルがツールを選択した後、 アクションを実行する前にツールまたはフックが承認を求める必要がある場合は、 Plugin 権限リクエストを使用してください。

    副作用、一般的でないバイナリ、またはデフォルトで公開すべきでない機能には、 オプションツールを使用します。ツール名はコアツール名と競合してはなりません。 競合するものはスキップされ、Plugin 診断に報告されます。不正な登録も同様に スキップされ報告されます。具体的には、空でない name がない場合、 execute が関数でない場合、またはツール記述子に parameters オブジェクトがない場合です。

    ツールファクトリは、ランタイムから提供されるコンテキストオブジェクトを受け取ります。現在の ターンでアクティブなモデルに応じてログ記録、表示、または動作を調整する必要があるツールでは、 ctx.activeModel を使用してください。これには provider、modelId、 および modelRef が含まれる場合があります。これは情報提供用のランタイムメタデータとして扱い、 ローカルオペレーター、インストール済み Plugin コード、または変更された OpenClaw ランタイムに対する セキュリティ境界として扱わないでください。機密性の高いローカルツールでは、引き続き Plugin または オペレーターによる明示的なオプトインを必須とし、アクティブモデルのメタデータがない場合や 適切でない場合はフェイルクローズにする必要があります。

    マニフェストは所有権と検出方法を宣言しますが、実行時には引き続き登録済みの 実際のツール実装が呼び出されます。ツールが明示的に許可リストへ追加されるまで OpenClaw がその Plugin ランタイムを読み込まずに済むように、 toolMetadata.<tool>.optional: true と api.registerTool(..., { optional: true }) の整合性を保ってください。

    インポート規則

    目的別の SDK サブパスからインポートします。

    typescript

    非推奨のルートバレルからインポートしないでください。

    typescript

    Plugin パッケージ内では、内部インポートに api.ts や runtime-api.ts などのローカルバレルファイルを使用します。SDK パス経由で 自分の Plugin をインポートしないでください。プロバイダー固有のヘルパーは、 その境界が真に汎用的でない限り、プロバイダーパッケージ内に保持してください。

    カスタム Gateway RPC メソッドは高度なエントリポイントです。Plugin 固有の プレフィックスを使用してください。config.*、exec.approvals.*、 operator.admin.*、wizard.*、update.* などのコア管理名前空間は予約済みであり、 operator.admin に解決されます。 openclaw/plugin-sdk/gateway-method-runtime ブリッジは、contracts.gatewayMethodDispatch: ["authenticated-request"] を宣言する Plugin HTTP ルート用に予約されています。

    完全なインポートマップについては、Plugin SDK の概要を参照してください。

    提出前チェックリスト

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json に正しい openclaw メタデータがある OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json マニフェストが存在し、有効である OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s エントリポイントが defineChannelPluginEntry または definePluginEntry を使用している OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s すべてのインポートが目的別の plugin-sdk/<subpath> パスを使用している OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page