Plugin のセットアップと設定

Plugin のパッケージング（package.json メタデータ）、マニフェスト（openclaw.plugin.json）、セットアップエントリ、設定スキーマのリファレンスです。

パッケージメタデータ

package.json には、Plugin システムに Plugin が提供する機能を伝える openclaw フィールドが必要です：

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "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 のフィールド

openclaw.channel

openclaw.channel は、ランタイムの読み込み前にチャンネルを検出し、セットアップ画面に表示するための軽量なパッケージメタデータです。

例：

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure は次の項目をサポートします：

• configured：設定済み一覧やステータス形式の一覧画面にチャンネルを含める
• setup：対話型セットアップ／設定の選択画面にチャンネルを含める
• docs：ドキュメント／ナビゲーション画面でチャンネルを一般公開対象として扱う

openclaw.install

openclaw.install はマニフェストメタデータではなく、パッケージメタデータです。

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

完全読み込みの遅延

チャンネル Plugin は、次の設定で遅延読み込みを有効にできます：

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

有効にすると、設定済みチャンネルの場合でも、OpenClaw はリッスン開始前の起動フェーズでは setupEntry のみを読み込みます。完全なエントリは Gateway がリッスンを開始した後に読み込まれます。

セットアップ／完全エントリが Gateway RPC メソッドを登録する場合は、Plugin 固有のプレフィックスを使用してください。予約済みのコア管理名前空間（config.*、exec.approvals.*、wizard.*、update.*）は引き続きコアが所有し、常に operator.admin に正規化されます。

Plugin マニフェスト

すべてのネイティブプラグインは、パッケージルートに openclaw.plugin.json を含めて配布する必要があります。OpenClaw はこれを使用して、プラグインコードを実行せずに設定を検証します。

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

チャンネルプラグインでは channels を追加します（プロバイダープラグインでは providers を追加します）。

{  "id": "my-channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

設定を持たないプラグインでも、スキーマを含めて配布する必要があります。空のスキーマも有効です。

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

完全なスキーマリファレンスについては、プラグインマニフェストを参照してください。

ClawHub への公開

Skills とプラグインパッケージでは、それぞれ異なる ClawHub 公開コマンドを使用します。プラグインパッケージには、パッケージ専用のコマンドを使用してください。

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

セットアップエントリ

setup-entry.ts は、OpenClaw がセットアップ用の機能（オンボーディング、設定修復、無効化されたチャンネルの検査）のみを必要とするときに読み込む、index.ts の軽量な代替です。

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

これにより、セットアップフロー中に重いランタイムコード（暗号化ライブラリ、CLI 登録、バックグラウンドサービス）が読み込まれるのを防げます。

セットアップに安全なエクスポートをサイドカーモジュールに保持するバンドル済みワークスペースチャンネルでは、defineSetupPluginEntry(...) の代わりに openclaw/plugin-sdk/channel-entry-contract の defineBundledChannelSetupEntry(...) を使用できます。このバンドル済みコントラクトは、オプションの runtime エクスポートにも対応しているため、セットアップ時のランタイム接続を軽量かつ明示的に保てます。

限定的なセットアップヘルパーのインポート

頻繁に実行されるセットアップ専用パスでは、セットアップ機能の一部のみが必要な場合、広範な plugin-sdk/setup アンブレラよりも限定的なセットアップヘルパーの境界を優先してください。

moveSingleAccountChannelSectionToDefaultAccount(...) などの設定パッチヘルパーを含む、共有セットアップツール一式が必要な場合は、より広範な plugin-sdk/setup の境界を使用してください。

固定されたセットアップウィザード文言には createSetupTranslator(...) を使用してください。これは CLI ウィザードのロケール（OPENCLAW_LOCALE、次にシステムロケール変数）に従い、英語へフォールバックします。プラグイン固有のセットアップ文言はプラグイン所有のコードに保持し、共有カタログキーは共通のセットアップラベル、ステータステキスト、公式バンドルプラグインのセットアップ文言にのみ使用してください。

セットアップパッチアダプターは、インポート時にもホットパスで安全です。バンドル済みの単一アカウント昇格コントラクトサーフェスの検索は遅延実行されるため、plugin-sdk/setup-runtime をインポートしても、アダプターが実際に使用される前にバンドル済みコントラクトサーフェスの検出が先行して読み込まれることはありません。

チャンネル所有の単一アカウント昇格

チャンネルが単一アカウントのトップレベル設定から channels.<id>.accounts.* へアップグレードされる場合、デフォルトの共有動作では、昇格されたアカウントスコープの値が accounts.default に移動されます。

バンドル済みチャンネルでは、セットアップコントラクトサーフェスを通じて、この昇格を限定または上書きできます。

• singleAccountKeysToMove: 昇格されたアカウントへ移動する追加のトップレベルキー
• namedAccountPromotionKeys: 名前付きアカウントがすでに存在する場合、昇格されたアカウントへ移動するキーをこれらのみに限定します。共有ポリシー／配信キーはチャンネルルートに残ります
• resolveSingleAccountPromotionTarget(...): 昇格された値を受け取る既存アカウントを選択します

設定スキーマ

プラグイン設定は、マニフェスト内の JSON Schema に対して検証されます。ユーザーは次のようにプラグインを設定します。

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

プラグインは登録時に、この設定を api.pluginConfig として受け取ります。

チャンネル固有の設定には、代わりにチャンネル設定セクションを使用してください。

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

チャンネル設定スキーマの構築

buildChannelConfigSchema を使用して、Zod スキーマを、プラグイン所有の設定アーティファクトで使用される ChannelConfigSchema ラッパーへ変換します。

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

コントラクトをすでに JSON Schema または TypeBox で記述している場合は、OpenClaw がメタデータパスで Zod から JSON Schema への変換を省略できるよう、直接ヘルパーを使用してください。

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

サードパーティ製プラグインでも、コールドパスのコントラクトは引き続きプラグインマニフェストです。生成された JSON Schema を openclaw.plugin.json#channelConfigs に反映し、設定スキーマ、セットアップ、UI の各機能が、ランタイムコードを読み込まずに channels.<id> を検査できるようにしてください。

セットアップウィザード

チャンネルプラグインは、openclaw onboard 用の対話型セットアップウィザードを提供できます。ウィザードは ChannelPlugin 上の ChannelSetupWizard オブジェクトです。

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

ChannelSetupWizard は textInputs、dmPolicy、allowFrom、groupAccess、prepare、finalize などにも対応しています。完全なバンドル例については、Discord プラグインの src/setup-core.ts を参照してください。

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

公開とインストール

外部 Plugin: ClawHub に公開してから、インストールします。

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

リポジトリ内 Plugin: 同梱 Plugin のワークスペースツリー配下に配置します。ビルド時に自動検出されます。

同梱パッケージのメタデータは明示的に定義され、Gateway 起動時にビルド済み JavaScript から推論されることはありません。ランタイム依存関係は、それを所有する Plugin パッケージに含めます。パッケージ版 OpenClaw の起動処理が Plugin の依存関係を修復または複製することはありません。

関連項目

• Plugin の構築 — ステップ形式のはじめにガイド
• Plugin マニフェスト — 完全なマニフェストスキーマのリファレンス
• SDK エントリポイント — definePluginEntry と defineChannelPluginEntry