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 tentang 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 saluran dan tampilan 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 tampilan daftar bergaya terkonfigurasi/status
• setup: sertakan saluran dalam pemilih penyiapan/konfigurasi interaktif
• docs: tandai saluran sebagai dapat dilihat publik dalam tampilan dokumentasi/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"    }  }}

Penundaan pemuatan penuh

Plugin saluran dapat memilih pemuatan tertunda dengan:

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

Jika diaktifkan, OpenClaw hanya memuat setupEntry selama fase mulai sebelum mendengarkan, bahkan untuk saluran yang sudah dikonfigurasi. Entri penuh dimuat setelah gateway mulai mendengarkan.

Jika entri penyiapan/penuh Anda mendaftarkan metode RPC gateway, pertahankan metode tersebut pada awalan khusus plugin. Namespace admin inti yang dicadangkan (config.*, exec.approvals.*, wizard.*, update.*) tetap dimiliki inti dan selalu dinormalisasi menjadi operator.admin.

Manifes plugin

Setiap plugin native harus menyertakan openclaw.plugin.json di root paket. OpenClaw menggunakannya 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 channels (dan plugin penyedia menambahkan providers):

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

Bahkan plugin tanpa konfigurasi harus menyertakan skema. Skema kosong tetap valid:

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

Lihat manifes plugin untuk referensi skema lengkap.

Publikasi ClawHub

Paket Skills dan plugin menggunakan perintah publikasi ClawHub yang terpisah. Untuk paket plugin, gunakan perintah khusus paket:

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

Entri penyiapan

setup-entry.ts adalah alternatif ringan untuk index.ts yang dimuat OpenClaw ketika hanya memerlukan permukaan penyiapan (orientasi awal, perbaikan konfigurasi, pemeriksaan saluran yang dinonaktifkan):

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

Hal ini menghindari pemuatan kode runtime yang berat (pustaka kriptografi, pendaftaran CLI, layanan latar belakang) selama alur penyiapan.

Saluran ruang kerja bawaan yang menyimpan ekspor aman-penyiapan dalam modul pendamping dapat menggunakan defineBundledChannelSetupEntry(...) dari openclaw/plugin-sdk/channel-entry-contract sebagai pengganti defineSetupPluginEntry(...). Kontrak bawaan tersebut juga mendukung ekspor opsional runtime agar pengkabelan runtime pada waktu penyiapan tetap ringan dan eksplisit.

Impor pembantu penyiapan terbatas

Untuk jalur aktif yang hanya digunakan dalam penyiapan, utamakan celah pembantu penyiapan yang terbatas daripada payung plugin-sdk/setup yang lebih luas jika Anda hanya memerlukan sebagian permukaan penyiapan:

Gunakan celah plugin-sdk/setup yang lebih luas jika Anda menginginkan kotak alat penyiapan bersama yang lengkap, termasuk pembantu tambalan konfigurasi seperti moveSingleAccountChannelSectionToDefaultAccount(...).

Gunakan createSetupTranslator(...) untuk teks tetap pada wizard penyiapan. Fungsi ini mengikuti lokal wizard CLI (OPENCLAW_LOCALE, kemudian variabel lokal sistem) dan kembali menggunakan bahasa Inggris jika lokal tersebut tidak tersedia. Pertahankan teks penyiapan khusus plugin dalam kode milik plugin dan gunakan kunci katalog bersama hanya untuk label penyiapan umum, teks status, dan teks penyiapan plugin resmi yang dibundel.

Adaptor patch penyiapan tetap aman untuk jalur panas saat diimpor. Pencarian permukaan kontrak promosi akun tunggal yang dibundel dilakukan secara malas, sehingga mengimpor plugin-sdk/setup-runtime tidak langsung memuat penemuan permukaan kontrak yang dibundel sebelum adaptor benar-benar digunakan.

Promosi akun tunggal milik kanal

Saat kanal ditingkatkan dari konfigurasi tingkat atas untuk satu akun ke channels.<id>.accounts.*, perilaku bersama bawaan memindahkan nilai dalam cakupan akun yang dipromosikan ke accounts.default.

Kanal yang dibundel dapat mempersempit atau mengganti promosi tersebut melalui permukaan kontrak penyiapannya:

• singleAccountKeysToMove: kunci tingkat atas tambahan yang harus dipindahkan ke akun yang dipromosikan
• namedAccountPromotionKeys: jika akun bernama sudah ada, hanya kunci ini yang dipindahkan ke akun yang dipromosikan; kunci kebijakan/pengiriman bersama tetap berada di akar kanal
• resolveSingleAccountPromotionTarget(...): memilih akun yang sudah ada untuk menerima nilai yang dipromosikan

Skema konfigurasi

Konfigurasi plugin divalidasi terhadap JSON Schema dalam manifes Anda. Pengguna mengonfigurasi plugin melalui:

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

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

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

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

Membuat skema konfigurasi kanal

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 menyusun kontrak sebagai JSON Schema atau TypeBox, gunakan pembantu 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 agar permukaan skema konfigurasi, penyiapan, dan UI dapat memeriksa channels.<id> tanpa memuat kode runtime.

Wizard penyiapan

Plugin kanal dapat menyediakan wizard penyiapan interaktif untuk openclaw onboard. Wizard tersebut merupakan 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),        };      },    },  ],};

ChannelSetupWizard juga mendukung textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, dan lainnya. Lihat src/setup-core.ts milik plugin Discord untuk contoh lengkap yang dibundel.

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 }

Memublikasikan dan menginstal

Plugin eksternal: publikasikan 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 repositori: tempatkan di bawah pohon ruang kerja Plugin bawaan; Plugin tersebut ditemukan secara otomatis selama proses build.

Metadata paket bawaan ditentukan secara eksplisit, bukan disimpulkan dari JavaScript hasil build saat Gateway dimulai. Dependensi runtime harus berada dalam paket Plugin yang memilikinya; saat dimulai, OpenClaw yang telah dipaketkan 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