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 bidang 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",  "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"    }  }}

Bidang openclaw

openclaw.channel

openclaw.channel adalah metadata paket ringan untuk penemuan channel 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: menyertakan channel dalam permukaan daftar bergaya terkonfigurasi/status
• setup: menyertakan channel dalam pemilih penyiapan/konfigurasi interaktif
• docs: menandai channel sebagai menghadap publik dalam permukaan docs/navigasi

openclaw.install

openclaw.install adalah metadata paket, bukan metadata manifes.

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

Pemuatan penuh yang ditunda

Plugin channel 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 pra-listen, bahkan untuk channel yang sudah dikonfigurasi. Entri penuh dimuat setelah gateway mulai listen.

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 channel, tambahkan kind dan channels:

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

Bahkan plugin tanpa konfigurasi pun harus mengirimkan skema. Skema kosong valid:

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

Lihat manifes Plugin untuk referensi skema lengkap.

Penerbitan 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 setup

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

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

Ini menghindari pemuatan kode runtime berat (pustaka kriptografi, registrasi CLI, layanan latar belakang) selama alur setup.

Channel workspace bawaan yang menyimpan ekspor aman-setup 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 setup dapat tetap ringan dan eksplisit.

Impor helper setup sempit

Untuk jalur panas yang hanya untuk setup, pilih seam helper setup yang sempit daripada payung plugin-sdk/setup yang lebih luas saat Anda hanya membutuhkan sebagian permukaan setup:

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

Gunakan createSetupTranslator(...) untuk salinan wizard setup tetap. Ini mengikuti locale wizard CLI (OPENCLAW_LOCALE, lalu variabel locale sistem) dan melakukan fallback ke bahasa Inggris. Simpan teks setup khusus plugin dalam kode milik plugin dan gunakan kunci katalog bersama hanya untuk label setup umum, teks status, dan salinan setup plugin bawaan resmi.

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

Promosi akun tunggal milik channel

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

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

• singleAccountKeysToMove: kunci tingkat atas tambahan yang harus dipindahkan ke akun yang dipromosikan
• namedAccountPromotionKeys: saat akun bernama sudah ada, hanya kunci-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 manifes 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 wrapper 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 manifes plugin: cerminkan JSON Schema yang dihasilkan ke openclaw.plugin.json#channelConfigs sehingga skema konfigurasi, setup, dan permukaan UI dapat menginspeksi channels.<id> tanpa memuat kode runtime.

Wizard setup

Plugin channel dapat menyediakan wizard setup 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 bundel dan plugin tersebut akan otomatis ditemukan selama build.

Pengguna dapat menginstal:

openclaw plugins install <package-name>

Metadata paket bundel bersifat eksplisit, tidak disimpulkan dari JavaScript yang sudah dibangun saat startup Gateway. Dependensi runtime berada di 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