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",  "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 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 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 verileridir, manifest meta verisi değildir.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "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, zaten yapılandırılmış kanallar için bile dinleme öncesi başlatma aşamasında 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ülür.

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

Config'i olmayan Plugin'ler bile bir şema göndermelidir. Boş bir şema geçerlidir:

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

Tam şema başvurusu için Plugin manifest 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 girdisi

setup-entry.ts dosyası, OpenClaw yalnızca kurulum yüzeylerine (onboarding, config onarımı, devre dışı kanal incelemesi) ihtiyaç duyduğunda 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 hizmetleri) yüklenmesini önler.

Kurulum açısından güvenli dışa aktarımları sidecar modüllerde tutan paketlenmiş çalışma alanı kanalları, defineSetupPluginEntry(...) yerine openclaw/plugin-sdk/channel-entry-contract içindeki defineBundledChannelSetupEntry(...) öğesini kullanabilir. Bu paketlenmiş sözleşme ayrıca isteğe bağlı bir runtime dışa aktarımını destekler; böylece kurulum zamanı çalışma zamanı kablolaması hafif ve açık kalabilir.

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

Sıcak yalnızca kurulum yolları için, kurulum yüzeyinin yalnızca bir kısmına ihtiyaç duyduğunuzda daha geniş plugin-sdk/setup şemsiyesi yerine dar kurulum yardımcı bağlantı noktalarını tercih edin:

moveSingleAccountChannelSectionToDefaultAccount(...) gibi config yama yardımcıları dahil tam paylaşılan kurulum araç kutusunu istediğinizde daha geniş plugin-sdk/setup bağlantı noktasını kullanın.

Sabit kurulum sihirbazı metni için createSetupTranslator(...) kullanın. CLI sihirbaz yerel ayarını (OPENCLAW_LOCALE, ardından sistem yerel ayar değişkenleri) izler ve İngilizceye geri döner. Plugin'e özgü kurulum metnini Plugin'e ait kodda tutun ve paylaşılan katalog anahtarlarını yalnızca yaygın kurulum etiketleri, durum metni ve resmi paketlenmiş Plugin kurulum metni için kullanın.

Kurulum yama bağdaştırıcıları içe aktarmada sıcak 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 aktarmak, bağdaştırıcı gerçekten kullanılmadan önce paketlenmiş sözleşme yüzeyi keşfini hevesle yüklemez.

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

Bir kanal tek hesaplı üst düzey config'den channels.<id>.accounts.* biçimine yükseltildiğinde, varsayılan paylaşılan davranış yükseltilmiş hesap kapsamlı değerleri accounts.default içine taşımaktır.

Paketlenmiş kanallar bu yükseltmeyi kurulum sözleşme yüzeyleri üzerinden daraltabilir veya geçersiz kılabilir:

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

Config şeması

Plugin config'i manifest'inizdeki JSON Schema'ya göre doğrulanır. Kullanıcılar Plugin'leri şu yolla yapılandırır:

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

Plugin'iniz bu config'i kayıt sırasında api.pluginConfig olarak alır.

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

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

Kanal config şemaları oluşturma

Bir Zod şemasını Plugin'e ait config artifact'leri 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 metadata yollarında Zod'dan JSON Schema'ya dönüşümü 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 manifest'idir: oluşturulan JSON Schema'yı openclaw.plugin.json#channelConfigs içine yansıtın; böylece config ş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 ü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 türü credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize ve daha fazlasını destekler. Tam örnekler için paketlenmiş Plugin paketlerine (örneğin Discord Plugin'i src/channel.setup.ts) 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: paketlenmiş Plugin çalışma alanı ağacının altına yerleştirin; derleme sırasında otomatik olarak keşfedilirler.

Kullanıcılar şunu yükleyebilir:

openclaw plugins install <package-name>

Paketlenmiş paket meta verileri açıktır; Gateway başlangıcında derlenmiş JavaScript'ten çıkarım yapılmaz. Çalışma zamanı bağımlılıkları, onlara sahip olan Plugin paketinde yer alır; paketlenmiş OpenClaw başlangıcı 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 manifesti — tam manifest şeması başvurusu
• SDK giriş noktaları — definePluginEntry ve defineChannelPluginEntry