Penyiapan dan konfigurasi Plugin

Referensi untuk pengemasan Plugin (metadata package.json), manifes (openclaw.plugin.json), entri penyiapan, dan skema konfigurasi.

Metadata paket

package.json Anda memerlukan kolom openclaw yang memberi tahu sistem Plugin apa yang disediakan Plugin Anda:

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

Kolom openclaw

openclaw.channel

openclaw.channel adalah metadata paket ringan untuk penemuan saluran dan permukaan penyiapan sebelum runtime dimuat.

Contoh:

{  "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 mendukung:

• configured: sertakan saluran dalam permukaan daftar bergaya terkonfigurasi/status
• setup: sertakan saluran dalam pemilih penyiapan/konfigurasi interaktif
• docs: tandai saluran sebagai menghadap publik dalam permukaan dokumentasi/navigasi

openclaw.install

openclaw.install adalah metadata paket, bukan metadata manifes.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/[email protected]",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Pemuatan penuh yang ditangguhkan

Plugin saluran dapat memilih pemuatan tertunda dengan:

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

Saat diaktifkan, OpenClaw hanya memuat setupEntry selama fase startup sebelum listen, bahkan untuk saluran yang sudah dikonfigurasi. Entri penuh dimuat setelah Gateway mulai listening.

Jika entri penyiapan/penuh Anda mendaftarkan metode RPC Gateway, pertahankan pada prefiks khusus Plugin. Namespace admin inti yang dicadangkan (config.*, exec.approvals.*, wizard.*, update.*) tetap dimiliki inti dan selalu diselesaikan ke operator.admin.

Manifes Plugin

Setiap Plugin native harus menyertakan openclaw.plugin.json di root paket. OpenClaw menggunakan ini untuk memvalidasi konfigurasi tanpa mengeksekusi kode 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"      }    }  }}

Untuk Plugin saluran, tambahkan kind dan channels:

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

Bahkan Plugin tanpa konfigurasi harus menyertakan skema. Skema kosong valid:

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

Lihat Manifes Plugin untuk referensi skema lengkap.

Publikasi ClawHub

Untuk paket Plugin, gunakan perintah ClawHub khusus paket:

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

Entri penyiapan

File setup-entry.ts adalah alternatif ringan untuk index.ts yang dimuat OpenClaw saat hanya memerlukan permukaan penyiapan (onboarding, perbaikan konfigurasi, inspeksi channel yang dinonaktifkan).

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

Ini menghindari pemuatan kode runtime yang berat (pustaka crypto, registrasi CLI, layanan latar belakang) selama alur penyiapan.

Channel workspace bawaan yang menyimpan ekspor aman-penyiapan di modul sidecar dapat menggunakan defineBundledChannelSetupEntry(...) dari openclaw/plugin-sdk/channel-entry-contract alih-alih defineSetupPluginEntry(...). Kontrak bawaan itu juga mendukung ekspor runtime opsional sehingga wiring runtime saat penyiapan dapat tetap ringan dan eksplisit.

Impor helper penyiapan yang sempit

Untuk jalur panas khusus penyiapan, pilih seam helper penyiapan yang sempit daripada umbrella plugin-sdk/setup yang lebih luas saat Anda hanya memerlukan sebagian permukaan penyiapan:

Gunakan seam plugin-sdk/setup yang lebih luas saat Anda menginginkan seluruh toolbox penyiapan bersama, termasuk helper patch konfigurasi seperti moveSingleAccountChannelSectionToDefaultAccount(...).

Adapter patch penyiapan tetap aman untuk jalur panas saat diimpor. Lookup permukaan kontrak promosi akun tunggal bawaannya bersifat lazy, sehingga mengimpor plugin-sdk/setup-runtime tidak langsung memuat discovery permukaan kontrak bawaan sebelum adapter benar-benar digunakan.

Promosi akun tunggal milik channel

Saat sebuah channel ditingkatkan dari konfigurasi tingkat atas akun tunggal ke channels.<id>.accounts.*, perilaku bersama default adalah memindahkan nilai berskala akun yang dipromosikan ke accounts.default.

Channel bawaan dapat mempersempit atau menimpa promosi tersebut melalui permukaan kontrak penyiapannya:

• singleAccountKeysToMove: kunci tingkat atas tambahan yang harus dipindahkan ke akun yang dipromosikan
• namedAccountPromotionKeys: saat akun bernama sudah ada, hanya kunci ini yang dipindahkan ke akun yang dipromosikan; kunci kebijakan/pengiriman bersama tetap berada di root channel
• resolveSingleAccountPromotionTarget(...): pilih akun yang sudah ada yang menerima nilai yang dipromosikan

Skema konfigurasi

Konfigurasi Plugin divalidasi terhadap JSON Schema di manifest Anda. Pengguna mengonfigurasi Plugin melalui:

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

Plugin Anda menerima konfigurasi ini sebagai api.pluginConfig selama registrasi.

Untuk konfigurasi khusus channel, gunakan bagian konfigurasi channel sebagai gantinya:

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

Membuat skema konfigurasi channel

Gunakan buildChannelConfigSchema untuk mengonversi skema Zod menjadi pembungkus ChannelConfigSchema yang digunakan oleh artefak konfigurasi milik Plugin:

  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);

Jika Anda sudah menulis kontrak sebagai JSON Schema atau TypeBox, gunakan helper langsung agar OpenClaw dapat melewati konversi Zod-ke-JSON-Schema pada jalur metadata:

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

Untuk Plugin pihak ketiga, kontrak jalur dingin tetap berupa manifest Plugin: cerminkan JSON Schema yang dihasilkan ke openclaw.plugin.json#channelConfigs sehingga skema konfigurasi, penyiapan, dan permukaan UI dapat menginspeksi channels.<id> tanpa memuat kode runtime.

Wizard penyiapan

Plugin channel dapat menyediakan wizard penyiapan interaktif untuk openclaw onboard. Wizard adalah objek ChannelSetupWizard pada ChannelPlugin:

 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),        };      },    },  ],};

Tipe ChannelSetupWizard mendukung credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, dan lainnya. Lihat paket Plugin bawaan (misalnya Plugin Discord src/channel.setup.ts) untuk contoh lengkap.

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 }

Menerbitkan dan menginstal

Plugin eksternal: terbitkan ke ClawHub, lalu instal:

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Plugin dalam repo: tempatkan di bawah pohon workspace Plugin bawaan dan Plugin tersebut akan ditemukan secara otomatis selama build.

Pengguna dapat menginstal:

openclaw plugins install <package-name>

Metadata paket bawaan bersifat eksplisit, bukan disimpulkan dari JavaScript yang telah dibangun saat startup Gateway. Dependensi runtime berada dalam paket Plugin yang memilikinya; startup OpenClaw terpaket tidak pernah memperbaiki atau mencerminkan dependensi Plugin.

Terkait

• Membangun Plugin — panduan memulai langkah demi langkah
• Manifes Plugin — referensi skema manifes lengkap
• Titik masuk SDK — definePluginEntry dan defineChannelPluginEntry