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 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 tampil untuk publik di permukaan docs/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 tertunda

Plugin channel dapat ikut serta dalam 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 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 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 channel, 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.

# Penerbitan ClawHub

Untuk paket Plugin, gunakan perintah ClawHub khusus paket:

clawhub package publish your-org/your-plugin --dry-run
clawhub 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 config, inspeksi channel yang dinonaktifkan).

// setup-entry.ts


export default defineSetupPluginEntry(myChannelPlugin);

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

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

# Import helper setup sempit

Untuk path panas yang hanya 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 lengkap, termasuk helper patch config seperti moveSingleAccountChannelSectionToDefaultAccount(...).

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

# Promosi akun tunggal milik channel

Saat channel meningkatkan config tingkat atas akun tunggal ke channels.<id>.accounts.*, perilaku bersama default adalah memindahkan nilai tercakup akun yang dipromosikan ke accounts.default.

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

• 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 config

Config Plugin divalidasi terhadap JSON Schema dalam manifest Anda. Pengguna mengonfigurasi Plugin melalui:

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

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

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

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

# Membuat skema config channel

Gunakan buildChannelConfigSchema untuk mengonversi skema Zod menjadi wrapper ChannelConfigSchema yang digunakan oleh artefak config 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 path metadata:

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

Untuk Plugin pihak ketiga, kontrak cold-path tetap merupakan manifest Plugin: cerminkan JSON Schema yang dihasilkan ke openclaw.plugin.json#channelConfigs agar skema config, 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 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 hasil build 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
• Manifest Plugin — referensi skema manifest lengkap
• Titik masuk SDK — definePluginEntry dan defineChannelPluginEntry