Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Referensi untuk pengemasan Plugin (metadata package.json), manifes (openclaw.plugin.json), entri penyiapan, dan skema konfigurasi.
Mencari panduan langkah demi langkah? Panduan cara penggunaan membahas pengemasan dalam konteks: Plugin saluran dan Plugin penyedia.

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."
    }
  }
}
Jika Anda memublikasikan Plugin secara eksternal di ClawHub, kolom compat dan build tersebut wajib ada. Cuplikan publikasi kanonis berada di docs/snippets/plugin-publish/.

Kolom openclaw

extensions
string[]
Berkas titik masuk (relatif terhadap root paket).
setupEntry
string
Entri ringan khusus penyiapan (opsional).
channel
object
Metadata katalog saluran untuk penyiapan, pemilih, quickstart, dan permukaan status.
providers
string[]
ID penyedia yang didaftarkan oleh Plugin ini.
install
object
Petunjuk instalasi: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.
startup
object
Flag perilaku startup.

openclaw.channel

openclaw.channel adalah metadata paket ringan untuk penemuan saluran dan permukaan penyiapan sebelum runtime dimuat.
KolomTipeArtinya
idstringID saluran kanonis.
labelstringLabel saluran utama.
selectionLabelstringLabel pemilih/penyiapan saat harus berbeda dari label.
detailLabelstringLabel detail sekunder untuk katalog saluran dan permukaan status yang lebih kaya.
docsPathstringJalur dokumentasi untuk tautan penyiapan dan pemilihan.
docsLabelstringLabel pengganti yang digunakan untuk tautan dokumentasi saat harus berbeda dari ID saluran.
blurbstringDeskripsi singkat untuk onboarding/katalog.
ordernumberUrutan pengurutan dalam katalog saluran.
aliasesstring[]Alias pencarian tambahan untuk pemilihan saluran.
preferOverstring[]ID Plugin/saluran prioritas lebih rendah yang harus dikalahkan saluran ini.
systemImagestringNama ikon/system-image opsional untuk katalog UI saluran.
selectionDocsPrefixstringTeks awalan sebelum tautan dokumentasi di permukaan pemilihan.
selectionDocsOmitLabelbooleanTampilkan jalur dokumentasi secara langsung alih-alih tautan dokumentasi berlabel dalam salinan pemilihan.
selectionExtrasstring[]String pendek tambahan yang ditambahkan dalam salinan pemilihan.
markdownCapablebooleanMenandai saluran sebagai mendukung markdown untuk keputusan pemformatan keluar.
exposureobjectKontrol visibilitas saluran untuk penyiapan, daftar terkonfigurasi, dan permukaan dokumentasi.
quickstartAllowFrombooleanIkutkan saluran ini ke dalam alur penyiapan quickstart allowFrom standar.
forceAccountBindingbooleanWajibkan pengikatan akun eksplisit bahkan saat hanya ada satu akun.
preferSessionLookupForAnnounceTargetbooleanUtamakan pencarian sesi saat menyelesaikan target pengumuman untuk saluran ini.
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
showConfigured dan showInSetup tetap didukung sebagai alias lama. Utamakan exposure.

openclaw.install

openclaw.install adalah metadata paket, bukan metadata manifes.
KolomTipeArtinya
clawhubSpecstringSpesifikasi ClawHub kanonis untuk alur instal/perbarui dan instal saat diperlukan onboarding.
npmSpecstringSpesifikasi npm kanonis untuk alur fallback instal/perbarui.
localPathstringJalur pengembangan lokal atau instalasi bawaan.
defaultChoice"clawhub" | "npm" | "local"Sumber instalasi pilihan saat tersedia beberapa sumber.
minHostVersionstringVersi OpenClaw minimum yang didukung dalam bentuk >=x.y.z atau >=x.y.z-prerelease.
expectedIntegritystringString integritas dist npm yang diharapkan, biasanya sha512-..., untuk instalasi terpancang.
allowInvalidConfigRecoverybooleanMemungkinkan alur instal ulang Plugin bawaan memulihkan kegagalan konfigurasi usang tertentu.
Onboarding interaktif juga menggunakan openclaw.install untuk permukaan instal saat diperlukan. Jika Plugin Anda mengekspos pilihan auth penyedia atau metadata penyiapan/katalog saluran sebelum runtime dimuat, onboarding dapat menampilkan pilihan itu, meminta instalasi ClawHub, npm, atau lokal, menginstal atau mengaktifkan Plugin, lalu melanjutkan alur yang dipilih. Pilihan onboarding ClawHub menggunakan clawhubSpec dan diutamakan saat tersedia; pilihan npm memerlukan metadata katalog tepercaya dengan npmSpec registry; versi persis dan expectedIntegrity adalah pin npm opsional. Jika expectedIntegrity ada, alur instal/perbarui memberlakukannya untuk npm. Simpan metadata “apa yang ditampilkan” di openclaw.plugin.json dan metadata “cara menginstalnya” di package.json.
Jika minHostVersion disetel, pemuatan instalasi dan registry manifes non-bawaan sama-sama memberlakukannya. Host yang lebih lama melewati Plugin eksternal; string versi tidak valid ditolak. Plugin sumber bawaan diasumsikan diversi bersama dengan checkout host.
Untuk instalasi npm terpancang, simpan versi persis di npmSpec dan tambahkan integritas artefak yang diharapkan:
{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}
allowInvalidConfigRecovery bukan bypass umum untuk konfigurasi rusak. Ini hanya untuk pemulihan Plugin bawaan yang sempit, sehingga instal ulang/penyiapan dapat memperbaiki sisa peningkatan yang diketahui seperti jalur Plugin bawaan yang hilang atau entri channels.<id> usang untuk Plugin yang sama. Jika konfigurasi rusak karena alasan yang tidak terkait, instalasi tetap gagal tertutup dan memberi tahu operator untuk menjalankan openclaw doctor --fix.

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.
Aktifkan pemuatan tertunda hanya saat setupEntry Anda mendaftarkan semua yang dibutuhkan Gateway sebelum mulai listening (pendaftaran saluran, rute HTTP, metode Gateway). Jika entri penuh memiliki kapabilitas startup yang diperlukan, pertahankan perilaku default.
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-run
clawhub package publish your-org/your-plugin
Alias publish lama yang hanya untuk skill ditujukan untuk skills. Paket Plugin harus selalu menggunakan clawhub package publish.

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
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { myChannelPlugin } from "./src/channel.js";

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.
  • Channel dinonaktifkan tetapi memerlukan permukaan penyiapan/onboarding.
  • Channel diaktifkan tetapi belum dikonfigurasi.
  • Pemuatan tertunda diaktifkan (deferConfiguredChannelFullLoadUntilAfterListen).
  • Objek Plugin channel (melalui defineSetupPluginEntry).
  • Rute HTTP apa pun yang diperlukan sebelum gateway listen.
  • Metode Gateway apa pun yang diperlukan selama startup.
Metode Gateway startup tersebut tetap harus menghindari namespace admin inti yang dicadangkan seperti config.* atau update.*.
  • Registrasi CLI.
  • Layanan latar belakang.
  • Impor runtime berat (crypto, SDK).
  • Metode Gateway yang hanya diperlukan setelah startup.

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:
Jalur imporGunakan untukEkspor utama
plugin-sdk/setup-runtimehelper runtime saat penyiapan yang tetap tersedia di setupEntry / startup channel tertundacreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimealias kompatibilitas yang usang; gunakan plugin-sdk/setup-runtimecreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolshelper CLI/arsip/dokumen untuk penyiapan/instalasiformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
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
Matrix adalah contoh bawaan saat ini. Jika tepat satu akun Matrix bernama sudah ada, atau jika defaultAccount menunjuk ke kunci non-kanonis yang sudah ada seperti Ops, promosi mempertahankan akun tersebut alih-alih membuat entri accounts.default baru.

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:
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

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:
import { Type } from "typebox";
import { buildJsonChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

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:
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";

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.
Untuk prompt daftar izin DM yang hanya memerlukan alur standar note -> prompt -> parse -> merge -> patch, pilih helper penyiapan bersama dari openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...), dan createNestedChannelParsedAllowFromPrompt(...).
Untuk blok status penyiapan channel yang hanya berbeda pada label, skor, dan baris tambahan opsional, pilih createStandardChannelSetupStatus(...) dari openclaw/plugin-sdk/setup alih-alih membuat objek status yang sama secara manual di setiap Plugin.
Untuk permukaan penyiapan opsional yang hanya boleh muncul dalam konteks tertentu, gunakan createOptionalChannelSetupSurface dari openclaw/plugin-sdk/channel-setup:
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 }
plugin-sdk/channel-setup juga mengekspos builder tingkat lebih rendah createOptionalChannelSetupAdapter(...) dan createOptionalChannelSetupWizard(...) saat Anda hanya memerlukan salah satu bagian dari permukaan instal-opsional tersebut.Adapter/wizard opsional yang dihasilkan gagal secara tertutup pada penulisan konfigurasi nyata. Mereka menggunakan kembali satu pesan instalasi-diperlukan di validateInput, applyAccountConfig, dan finalize, serta menambahkan tautan dokumen saat docsPath diatur.
Untuk UI penyiapan berbasis biner, pilih helper delegasi bersama alih-alih menyalin glue biner/status yang sama ke setiap channel:
  • createDetectedBinaryStatus(...) untuk blok status yang hanya berbeda pada label, petunjuk, skor, dan deteksi biner
  • createCliPathTextInput(...) untuk input teks berbasis jalur
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...), dan createDelegatedResolveConfigured(...) saat setupEntry perlu meneruskan ke wizard penuh yang lebih berat secara lazy
  • createDelegatedTextInputShouldPrompt(...) saat setupEntry hanya perlu mendelegasikan keputusan textInputs[*].shouldPrompt

Menerbitkan dan menginstal

Plugin eksternal: terbitkan ke ClawHub, lalu instal:
openclaw plugins install @myorg/openclaw-my-plugin
Spesifikasi paket bare diinstal dari npm selama cutover peluncuran.
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>
Untuk instalasi yang bersumber dari npm, openclaw plugins install menginstal paket di bawah ~/.openclaw/npm dengan skrip lifecycle dinonaktifkan. Pertahankan pohon dependensi Plugin sebagai JS/TS murni dan hindari paket yang memerlukan build postinstall.
Startup Gateway tidak menginstal dependensi Plugin. Alur instalasi npm/git/ClawHub bertanggung jawab atas konvergensi dependensi; Plugin lokal harus sudah memiliki dependensinya terinstal.
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