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": "マイチャンネル",      "blurb": "チャンネルの短い説明。"    }  }}

{  "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 は、ランタイムを読み込む前にチャンネルを検出し、セットアップ画面に表示するための軽量なパッケージメタデータです。

チャンネル所有のセットアップフィールド

チャンネル Plugin では、defineChannelSetupContract(...) を使用してランタイムコード内にセットアップフィールドを一度だけ定義し、それに対応するシリアライズ可能な投影を openclaw.channel.setup.fields で公開する必要があります。ランタイム定義は Plugin ローカルの入力型を推論し、ガイド付きと非対話型の両方の値を解析し、チャンネル固有のキーがコア型に混入しないようにします。パッケージメタデータにより、openclaw channels add <channel-id> --help と openclaw channels add --channel <channel-id> --help は Plugin を読み込まずに、選択されたチャンネルのオプションだけを検出できます。

 export const setupContract = defineChannelSetupContract({  fields: {    endpoint: {      kind: "string",      cli: { flags: "--endpoint <url>", description: "サービスエンドポイント" },    },    transport: {      kind: "choice",      choices: ["native", "container"],      cli: { flags: "--transport <kind>", description: "トランスポート所有者" },    },  },  adapter: {    applyAccountConfig: ({ cfg, input }) => ({      ...cfg,      channels: { ...cfg.channels, example: input },    }),  },});

{  "openclaw": {    "channel": {      "id": "example",      "setup": {        "fields": [          {            "key": "endpoint",            "kind": "string",            "cli": { "flags": "--endpoint <url>", "description": "サービスエンドポイント" }          },          {            "key": "transport",            "kind": "choice",            "choices": ["native", "container"],            "cli": { "flags": "--transport <kind>", "description": "トランスポート所有者" }          }        ]      }    }  }}

サポートされるフィールド種別は、string、boolean、integer、string-list、choice です。認証情報には sensitive: true を使用してください。各フィールドキーは、長形式 CLI フラグの属性名をキャメルケースにしたものと一致する必要があります。否定形も含まれ、たとえば --api-token に対しては apiToken となります。真偽値フィールドでは、肯定形と --no-* 形式の両方が必要な場合、cli.negatedFlags を追加できます。channel、account、アカウント表示用の name は、引き続き共有制御エンベロープです。

リリース済みの setup/ChannelSetupInput アダプターは、既存の外部 Plugin で引き続き使用できます。新しい Plugin では setupContract を公開してください。両方が存在する場合、OpenClaw は常にこちらを優先します。

例：

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "マイチャンネル",      "selectionLabel": "マイチャンネル（セルフホスト）",      "detailLabel": "マイチャンネル Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook ベースのセルフホスト型チャット連携。",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "ガイド：",      "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 マニフェスト

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

{  "id": "my-plugin",  "name": "My Plugin",  "description": "OpenClaw に My Plugin の機能を追加します",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook 検証シークレット"      }    }  }}

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

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

設定のない Plugin でもスキーマを含める必要があります。空のスキーマも有効です。

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

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

ClawHub への公開

Skills と Plugin パッケージでは、ClawHub への公開コマンドが異なります。Plugin パッケージには、パッケージ固有のコマンドを使用してください。

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

セットアップエントリ

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

// 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(...) を使用してください。これは OPENCLAW_LOCALE、LC_ALL、LC_MESSAGES、LANG の順に、空白ではない最初の値を使用し、その後英語にフォールバックします。明示的な英語の上書きには OPENCLAW_LOCALE=en を設定してください。Plugin 固有のセットアップテキストは Plugin 所有のコードに保持し、共有カタログキーは共通のセットアップラベル、ステータステキスト、および公式のバンドル Plugin のセットアップ文言にのみ使用してください。

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

チャネル所有のセットアップ入力フィールド

ChannelSetupInput は、セットアップ呼び出し元とチャネル Plugin が共有する汎用エンベロープです。恒久的に型付けされるフィールドは name、token、tokenFile、 useEnv、allowFrom、defaultTo です。Plugin 所有の追加キーも ランタイム入力オブジェクトに含めることができますが、共有型では インデックスシグネチャを宣言しません。各 Plugin は、独自のセットアップフィールドを宣言して絞り込むか、 アダプター境界で Plugin 所有のスキーマを使用して検証する必要があります。

 type AcmeSetupInput = ChannelSetupInput & {  workspaceId?: string;  webhookUrl?: string;}; export const acmeSetupAdapter: ChannelSetupAdapter = {  applyAccountConfig: ({ cfg, input }) => {    const setupInput = input as AcmeSetupInput;    return {      ...cfg,      channels: {        ...cfg.channels,        acme: {          token: setupInput.token,          workspaceId: setupInput.workspaceId,          webhookUrl: setupInput.webhookUrl,        },      },    };  },};

以前はチャンネル固有のフィールドが ChannelSetupInput に直接宣言されていましたが、外部ソースとの互換性のため、一時的に型定義が維持されています。 これらは非推奨です。2026-07-22 に公開済みのツリー外 チャンネルプラグイン 426 件をレジストリで調査した結果、読み取り元のない 21 個のフィールドを削除し、既知の 読み取り元がある 22 個を維持しました。維持された各フィールドは、公開済みプラグインから読み取られなくなり次第削除されます。 バージョン境界は必要ありません。新規および同梱プラグインは、この 階層に依存してはなりません。所有するフィールドをローカルで宣言してください。

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

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

各チャンネルプラグインは、そのセットアップアダプターを通じて、この昇格を拡張または限定できます。

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

singleAccountKeysToMove が存在すると、昇格コントラクトが完全であることを示します。従来のキー昇格を無効にする場合でも、空の配列としてこのフィールドを宣言してください。このフィールドを省略したアダプターでは、すでに公開されているプラグイン向けに、読み取り元に裏付けられた宣言前昇格階層が維持されます。2026-07-22 のレジストリ調査では、公開済みの依存先がない 23 個のキーを削除し、6 個の共通キーとセットアップ専用の rooms キーを維持しました。維持された各キーは、公開済みの読み取り元が宣言へ移行し次第削除されます。バージョン境界は必要ありません。

doctor が軽量の同梱セットアップ成果物からこれらの宣言を読み込む必要がある場合は、プラグインパッケージのマニフェストで openclaw.setupFeatures.configPromotion: true を宣言してください。セットアップ専用のプラグインサーフェスと完全なチャンネルプラグインは、同じ宣言を公開する必要があります。

解決済みのプラグインを指定して moveSingleAccountChannelSectionToDefaultAccount(...) を呼び出す場合は、そのセットアップアダプターを setupSurface として渡してください。呼び出し元から渡されたセットアップサーフェスは、読み込み済みおよび同梱の検索結果より優先されるため、スコープ付きまたはセットアップ専用のプラグインをグローバル登録から独立させられます。

設定スキーマ

プラグイン設定は、マニフェスト内の 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 }

公開とインストール

外部プラグイン: ClawHub に公開してから、次のようにインストールします。

openclaw plugins install @myorg/openclaw-my-plugin

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

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

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

同梱パッケージのメタデータは明示的であり、Gateway の起動時にビルド済み JavaScript から推論されるものではありません。ランタイム依存関係は、それを所有するプラグインパッケージに属します。パッケージ化された OpenClaw の起動処理が、プラグインの依存関係を修復またはミラーリングすることはありません。

関連項目

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