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",
  "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/[email protected]",
      "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": "Adds My Plugin capabilities to OpenClaw",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "webhookSecret": {
        "type": "string",
        "description": "Webhook verification secret"
      }
    }
  }
}

チャンネル Plugin では、kind と channels を追加します。

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

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

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

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

# ClawHub 公開

Plugin パッケージでは、パッケージ固有の ClawHub コマンドを使用します。

clawhub package publish your-org/your-plugin --dry-run
clawhub 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 境界を使用してください。

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

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

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

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

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

# 設定スキーマ

Plugin 設定は、マニフェスト内の JSON Schema に対して検証されます。ユーザーは次の方法で Plugin を設定します。

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

Plugin は登録中に、この設定を api.pluginConfig として受け取ります。

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

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

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

buildChannelConfigSchema を使用して、Zod スキーマを Plugin 所有の設定アーティファクトで使われる 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())),
  }),
);

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

# セットアップウィザード

チャネル Plugin は 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 型は、credentials、textInputs、dmPolicy、allowFrom、groupAccess、prepare、finalize などに対応しています。完全な例については、バンドル済み Plugin パッケージ（たとえば Discord Plugin の src/channel.setup.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 ワークスペースツリーの下に配置すると、ビルド時に自動的に検出されます。

ユーザーはインストールできます:

openclaw plugins install <package-name>

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

# 関連

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