Plugin kurulumu ve yapılandırması

Plugin paketleme (package.json meta verileri), manifestler (openclaw.plugin.json), kurulum girdileri ve yapılandırma şemaları için başvuru kaynağı.

Paket meta verileri

package.json dosyanızda, Plugin sistemine Plugininizin ne sunduğunu bildiren bir openclaw alanı bulunmalıdır:

{  "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"    }  }}

openclaw alanları

openclaw.channel

openclaw.channel, çalışma zamanı yüklenmeden önce kanal keşfi ve kurulum yüzeyleri için kullanılan düşük maliyetli paket meta verileridir.

Örnek:

{  "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 şunları destekler:

• configured: kanalı yapılandırılmış/durum tarzı listeleme yüzeylerine dahil eder
• setup: kanalı etkileşimli kurulum/yapılandırma seçicilerine dahil eder
• docs: kanalı dokümantasyon/gezinme yüzeylerinde herkese açık olarak işaretler

openclaw.install

openclaw.install, manifest meta verileri değil, paket meta verileridir.

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

Ertelenmiş tam yükleme

Kanal Pluginleri aşağıdaki ayarla ertelenmiş yüklemeyi etkinleştirebilir:

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

Etkinleştirildiğinde OpenClaw, ön dinleme başlatma aşamasında önceden yapılandırılmış kanallar için bile yalnızca setupEntry girdisini yükler. Tam giriş, Gateway dinlemeye başladıktan sonra yüklenir.

Kurulum/tam girişiniz Gateway RPC yöntemlerini kaydediyorsa bunları Plugine özgü bir ön ek altında tutun. Ayrılmış temel yönetici ad alanları (config.*, exec.approvals.*, wizard.*, update.*) temel sisteme ait kalır ve her zaman operator.admin olarak normalleştirilir.

Plugin manifesti

Her yerel plugin, paket kökünde bir openclaw.plugin.json dosyasıyla birlikte sunulmalıdır. OpenClaw, plugin kodunu çalıştırmadan yapılandırmayı doğrulamak için bunu kullanır.

{  "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"      }    }  }}

Kanal pluginleri için channels ekleyin (sağlayıcı pluginleri ise providers ekler):

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

Yapılandırması olmayan pluginler bile bir şemayla birlikte sunulmalıdır. Boş bir şema geçerlidir:

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

Tam şema başvurusu için Plugin bildirimi bölümüne bakın.

ClawHub'da yayımlama

Skills ve plugin paketleri ayrı ClawHub yayımlama komutları kullanır. Plugin paketleri için pakete özgü komutu kullanın:

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

Kurulum giriş noktası

setup-entry.ts, OpenClaw yalnızca kurulum yüzeylerine (ilk katılım, yapılandırma onarımı, devre dışı bırakılmış kanal incelemesi) ihtiyaç duyduğunda yüklediği, index.ts dosyasına göre daha hafif bir alternatiftir:

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

Bu, kurulum akışları sırasında ağır çalışma zamanı kodlarının (kriptografi kitaplıkları, CLI kayıtları, arka plan hizmetleri) yüklenmesini önler.

Kuruluma uygun dışa aktarımları yardımcı modüllerde tutan paketle birlikte sunulan çalışma alanı kanalları, defineSetupPluginEntry(...) yerine openclaw/plugin-sdk/channel-entry-contract içindeki defineBundledChannelSetupEntry(...) işlevini kullanabilir. Paketle birlikte sunulan bu sözleşme, kurulum zamanı çalışma bağlantılarının hafif ve açık kalabilmesi için isteğe bağlı bir runtime dışa aktarımını da destekler.

Dar kapsamlı kurulum yardımcısı içe aktarımları

Yalnızca kurulum için kullanılan yoğun yollarda, kurulum yüzeyinin yalnızca bir bölümüne ihtiyacınız olduğunda daha geniş plugin-sdk/setup şemsiyesi yerine dar kapsamlı kurulum yardımcısı bağlantılarını tercih edin:

moveSingleAccountChannelSectionToDefaultAccount(...) gibi yapılandırma yaması yardımcılarını da içeren paylaşılan kurulum araçlarının tamamını istediğinizde daha geniş plugin-sdk/setup bağlantısını kullanın.

Sabit kurulum sihirbazı metinleri için createSetupTranslator(...) kullanın. CLI sihirbazının yerel ayarını izler (OPENCLAW_LOCALE, ardından sistem yerel ayar değişkenleri) ve İngilizceye geri döner. Plugine özgü kurulum metinlerini Pluginin sahip olduğu kodda tutun; paylaşılan katalog anahtarlarını yalnızca ortak kurulum etiketleri, durum metinleri ve resmi paketlenmiş Plugin kurulum metinleri için kullanın.

Kurulum yama bağdaştırıcıları, içe aktarma sırasında yoğun yol açısından güvenli kalır. Paketlenmiş tek hesap yükseltme sözleşme yüzeyi araması tembeldir; bu nedenle plugin-sdk/setup-runtime içe aktarıldığında, bağdaştırıcı gerçekten kullanılmadan önce paketlenmiş sözleşme yüzeyi keşfi istekli olarak yüklenmez.

Kanalın sahip olduğu tek hesap yükseltme

Bir kanal, tek hesaplı üst düzey yapılandırmadan channels.<id>.accounts.* yapısına yükseltildiğinde, varsayılan paylaşılan davranış yükseltilen hesap kapsamındaki değerleri accounts.default içine taşır.

Paketlenmiş kanallar, kurulum sözleşme yüzeyleri aracılığıyla bu yükseltmeyi daraltabilir veya geçersiz kılabilir:

• singleAccountKeysToMove: yükseltilen hesaba taşınması gereken ek üst düzey anahtarlar
• namedAccountPromotionKeys: adlandırılmış hesaplar zaten mevcutsa yalnızca bu anahtarlar yükseltilen hesaba taşınır; paylaşılan ilke/teslim anahtarları kanal kökünde kalır
• resolveSingleAccountPromotionTarget(...): yükseltilen değerleri hangi mevcut hesabın alacağını seçer

Yapılandırma şeması

Plugin yapılandırması, manifestinizdeki JSON Schema'ya göre doğrulanır. Kullanıcılar Pluginleri şu şekilde yapılandırır:

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

Plugininiz, kayıt sırasında bu yapılandırmayı api.pluginConfig olarak alır.

Kanala özgü yapılandırma için bunun yerine kanal yapılandırma bölümünü kullanın:

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

Kanal yapılandırma şemaları oluşturma

Bir Zod şemasını, Pluginin sahip olduğu yapılandırma yapıtlarının kullandığı ChannelConfigSchema sarmalayıcısına dönüştürmek için buildChannelConfigSchema kullanın:

  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);

Sözleşmeyi zaten JSON Schema veya TypeBox olarak yazıyorsanız OpenClaw'ın meta veri yollarında Zod'dan JSON Schema'ya dönüştürmeyi atlayabilmesi için doğrudan yardımcıyı kullanın:

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

Üçüncü taraf Pluginler için soğuk yol sözleşmesi hâlâ Plugin manifestidir: yapılandırma şeması, kurulum ve kullanıcı arayüzü yüzeylerinin çalışma zamanı kodunu yüklemeden channels.<id> öğesini inceleyebilmesi için oluşturulan JSON Schema'yı openclaw.plugin.json#channelConfigs içine yansıtın.

Kurulum sihirbazları

Kanal Pluginleri, openclaw onboard için etkileşimli kurulum sihirbazları sağlayabilir. Sihirbaz, ChannelPlugin üzerindeki bir ChannelSetupWizard nesnesidir:

 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 ayrıca textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize ve daha fazlasını destekler. Tam bir paketlenmiş örnek için Discord Plugininin src/setup-core.ts dosyasına bakın.

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 }

Yayımlama ve yükleme

Harici Plugin'ler: ClawHub üzerinde yayımlayın, ardından yükleyin:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Depo içi Plugin'ler: paketle birlikte gelen Plugin çalışma alanı ağacının altına yerleştirin; derleme sırasında otomatik olarak keşfedilirler.

Paketle birlikte gelen paket meta verileri açıktır; Gateway başlatılırken derlenmiş JavaScript'ten çıkarılmaz. Çalışma zamanı bağımlılıkları, bunların sahibi olan Plugin paketinde bulunmalıdır; paketlenmiş OpenClaw başlatma işlemi Plugin bağımlılıklarını hiçbir zaman onarmaz veya yansıtmaz.

İlgili

• Plugin oluşturma — adım adım başlangıç kılavuzu
• Plugin bildirimi — tam bildirim şeması başvurusu
• SDK giriş noktaları — definePluginEntry ve defineChannelPluginEntry