Plugin の構築

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

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

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 の形態を選択する

クイックスタート

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

{"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"}}}

{"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}}

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() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Got: ${params.input}` }],          details,        };      },    });  },});

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

pnpm test extensions/my-plugin/pnpm check

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

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

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

ツールの登録

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

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

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

outputSchema は任意です。コードモードとツール検索で使用される 構造化された details 値を記述します。カタログ呼び出しは実行前に無効なスキーマを拒否し、 ツールフックの後に最終値を検証します。安定した JSON 結果を持たないツールでは省略してください。 完全な契約については、ツール Pluginを参照してください。

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

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

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

{  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 サブパスからインポートします。

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

カスタム 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 SDK の互換性フィールドには TypeScript の @deprecated アノテーションが付いており、 エディターでは移行に関する警告として表示されます。ビルド時にこれを強制するには、 @typescript-eslint/no-deprecated のような 型情報を利用するルールを有効にしてください。 Oxlint は型情報を利用しないため、これらのアノテーションを強制できません。

提出前チェックリスト

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: