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": "Kanal Saya",      "blurb": "Deskripsi singkat kanal."    }  }}

{  "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 kanal dan permukaan penyiapan sebelum runtime dimuat.

Contoh:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "Kanal Saya",      "selectionLabel": "Kanal Saya (dihosting sendiri)",      "detailLabel": "Bot Kanal Saya",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Integrasi obrolan yang dihosting sendiri dan berbasis Webhook.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Panduan:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure mendukung:

• configured: sertakan kanal dalam permukaan daftar bergaya konfigurasi/status
• setup: sertakan kanal dalam pemilih penyiapan/konfigurasi interaktif
• docs: tandai kanal sebagai ditujukan untuk publik dalam permukaan 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 kanal dapat memilih pemuatan tertunda dengan:

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

Jika diaktifkan, OpenClaw hanya memuat setupEntry selama fase awal sebelum mulai mendengarkan, bahkan untuk kanal yang sudah dikonfigurasi. Entri lengkap dimuat setelah Gateway mulai mendengarkan.

Jika entri penyiapan/lengkap Anda mendaftarkan metode RPC gateway, pertahankan metode tersebut pada prefiks 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": "Plugin Saya",  "description": "Menambahkan kapabilitas Plugin Saya ke OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Rahasia verifikasi Webhook"      }    }  }}

Untuk plugin kanal, 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 kanal yang dinonaktifkan):

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

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

Kanal ruang kerja yang dibundel dan mempertahankan ekspor yang aman untuk penyiapan dalam modul pendamping dapat menggunakan defineBundledChannelSetupEntry(...) dari openclaw/plugin-sdk/channel-entry-contract, alih-alih defineSetupPluginEntry(...). Kontrak yang dibundel tersebut juga mendukung ekspor opsional runtime agar pengawatan runtime saat penyiapan tetap ringan dan eksplisit.

Impor helper penyiapan yang sempit

Untuk jalur khusus penyiapan yang sering digunakan, pilih seam helper penyiapan yang sempit daripada payung plugin-sdk/setup yang lebih luas ketika Anda hanya memerlukan sebagian permukaan penyiapan:

Gunakan seam plugin-sdk/setup yang lebih luas ketika Anda menginginkan kotak alat penyiapan bersama secara lengkap, termasuk helper patch konfigurasi seperti moveSingleAccountChannelSectionToDefaultAccount(...).

Gunakan createSetupTranslator(...) untuk teks tetap wizard penyiapan. Ini menggunakan nilai tidak kosong pertama dari OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES, dan LANG, dalam urutan tersebut, lalu kembali ke bahasa Inggris. Atur OPENCLAW_LOCALE=en untuk penggantian bahasa Inggris yang eksplisit. Pertahankan teks penyiapan khusus plugin dalam kode milik plugin dan gunakan kunci katalog bersama hanya untuk label penyiapan umum, teks status, serta teks penyiapan plugin resmi yang dibundel.

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

Promosi akun tunggal milik kanal

Ketika kanal meningkatkan konfigurasi tingkat atas akun tunggal menjadi channels.<id>.accounts.*, perilaku bersama default memindahkan nilai 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: ketika akun bernama sudah ada, hanya kunci-kunci ini yang dipindahkan ke akun yang dipromosikan; kunci kebijakan/pengiriman bersama tetap berada di root 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 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 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 adalah objek ChannelSetupWizard pada ChannelPlugin:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Terhubung",    unconfiguredLabel: "Belum dikonfigurasi",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Token bot",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Gunakan MY_CHANNEL_BOT_TOKEN dari lingkungan?",      keepPrompt: "Pertahankan token saat ini?",      inputPrompt: "Masukkan token bot Anda:",      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: "Kanal Saya",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Mengembalikan { 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 build.

Metadata paket bawaan bersifat eksplisit, bukan disimpulkan dari JavaScript hasil build saat Gateway dimulai. Dependensi runtime harus berada dalam paket plugin yang memilikinya; proses awal 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