Plugin kurulumu ve yapılandırması

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

Paket meta verileri

package.json dosyanızda, Plugin sistemine Plugin'inizin ne sağladığını bildiren bir openclaw alanı gerekir:

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

openclaw alanları

openclaw.channel

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

Ö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 et
• setup: kanalı etkileşimli kurulum/yapılandırma seçicilerine dahil et
• docs: kanalı dokümantasyon/gezinme yüzeylerinde herkese açık olarak işaretle

openclaw.install

openclaw.install paket meta verisidir, manifest meta verisi değildir.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/[email protected]",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Ertelenmiş tam yükleme

Kanal Plugin'leri şu şekilde ertelenmiş yüklemeye dahil olabilir:

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

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

Kurulum/tam girişiniz gateway RPC yöntemleri kaydediyorsa, bunları Plugin'e özgü bir önekte tutun. Ayrılmış çekirdek yönetici ad alanları (config.*, exec.approvals.*, wizard.*, update.*) çekirdeğe ait kalır ve her zaman operator.admin olarak çözümlenir.

Plugin manifesti

Her yerel Plugin, paket kökünde bir openclaw.plugin.json ile gelmelidir. OpenClaw bunu, Plugin kodunu çalıştırmadan yapılandırmayı doğrulamak için 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 Plugin'leri için kind ve channels ekleyin:

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

Yapılandırması olmayan Plugin'ler bile bir şema ile gelmelidir. Boş bir şema geçerlidir:

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

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

ClawHub yayımlama

Plugin paketleri için pakete özgü ClawHub komutunu kullanın:

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

Kurulum girişi

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

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

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

Kurulum için güvenli dışa aktarımları yan modüllerde tutan paketlenmiş çalışma alanı kanalları, defineSetupPluginEntry(...) yerine openclaw/plugin-sdk/channel-entry-contract içindeki defineBundledChannelSetupEntry(...) işlevini kullanabilir. Bu paketlenmiş sözleşme, kurulum zamanı çalışma zamanı bağlantısının hafif ve açık kalabilmesi için isteğe bağlı bir runtime dışa aktarımını da destekler.

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

Sıcak yalnızca kurulum yollarında, kurulum yüzeyinin yalnızca bir bölümüne ihtiyaç duyduğunuzda daha geniş plugin-sdk/setup şemsiyesi yerine dar kurulum yardımcısı bağlantılarını tercih edin:

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

Kurulum yama adaptörleri içe aktarımda sıcak yol için güvenli kalır. Paketlenmiş tek hesap yükseltme sözleşme yüzeyi araması tembeldir; bu yüzden plugin-sdk/setup-runtime içe aktarımı, adaptör gerçekten kullanılmadan önce paketlenmiş sözleşme yüzeyi keşfini istekli biçimde yüklemez.

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

Bir kanal, tek hesaplı üst düzey yapılandırmadan channels.<id>.accounts.* yapısına yükselttiğinde, varsayılan paylaşılan davranış yükseltilen hesap kapsamlı değerleri accounts.default içine taşımaktı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 mevcut olduğunda, yalnızca bu anahtarlar yükseltilen hesaba taşınır; paylaşılan ilke/teslimat anahtarları kanal kökünde kalır
• resolveSingleAccountPromotionTarget(...): yükseltilen değerleri hangi mevcut hesabın alacağını seçin

Yapılandırma şeması

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

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

Plugin'iniz bu yapılandırmayı kayıt sırasında 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ı Plugin'e ait yapılandırma yapıları tarafından kullanılan 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 Plugin'ler için soğuk yol sözleşmesi hâlâ Plugin manifestidir: oluşturulan JSON Schema'yı openclaw.plugin.json#channelConfigs içine yansıtın; böylece yapılandırma şeması, kurulum ve UI yüzeyleri çalışma zamanı kodunu yüklemeden channels.<id> öğesini inceleyebilir.

Kurulum sihirbazları

Kanal Plugin'leri openclaw onboard için etkileşimli kurulum sihirbazları sağlayabilir. Sihirbaz, ChannelPlugin üzerinde 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 türü credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize ve daha fazlasını destekler. Tam örnekler için paketlenmiş Plugin paketlerine bakın (örneğin Discord Plugin'i src/channel.setup.ts).

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

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

Kullanıcılar şunu kurabilir:

openclaw plugins install <package-name>

Birlikte paketlenen paket meta verileri açıktır; Gateway başlangıcında derlenmiş JavaScript'ten çıkarımsanmaz. Çalışma zamanı bağımlılıkları, onlara sahip olan Plugin paketinde bulunmalıdır; paketlenmiş OpenClaw başlangıcı Plugin bağımlılıklarını asla onarmaz veya yansıtmaz.

İlgili

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