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 kaynağı.

Paket meta verileri

package.json dosyanız, plugin sistemine plugininizin ne sağladığını bildiren bir openclaw alanına ihtiyaç duyar:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "Kanalım",      "blurb": "Kanalın kısa açıklaması."    }  }}

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

Kanalın sahip olduğu kurulum alanları

Kanal pluginleri, kurulum alanlarını çalışma zamanı kodunda defineChannelSetupContract(...) ile bir kez tanımlamalı ve eşleşen serileştirilebilir izdüşümü openclaw.channel.setup.fields altında yayımlamalıdır. Çalışma zamanı tanımı, plugine özgü yerel girdi türünü çıkarır, hem yönlendirmeli hem de etkileşimsiz değerleri ayrıştırır ve kanala özgü anahtarları çekirdek türlerin dışında tutar. Paket meta verileri, openclaw channels add <channel-id> --help ve openclaw channels add --channel <channel-id> --help bileşenlerinin plugini yüklemeden yalnızca seçilen kanalın seçeneklerini keşfetmesini sağlar.

 export const setupContract = defineChannelSetupContract({  fields: {    endpoint: {      kind: "string",      cli: { flags: "--endpoint <url>", description: "Hizmet uç noktası" },    },    transport: {      kind: "choice",      choices: ["native", "container"],      cli: { flags: "--transport <kind>", description: "Aktarım sahibi" },    },  },  adapter: {    applyAccountConfig: ({ cfg, input }) => ({      ...cfg,      channels: { ...cfg.channels, example: input },    }),  },});

{  "openclaw": {    "channel": {      "id": "example",      "setup": {        "fields": [          {            "key": "endpoint",            "kind": "string",            "cli": { "flags": "--endpoint <url>", "description": "Hizmet uç noktası" }          },          {            "key": "transport",            "kind": "choice",            "choices": ["native", "container"],            "cli": { "flags": "--transport <kind>", "description": "Aktarım sahibi" }          }        ]      }    }  }}

Desteklenen alan türleri string, boolean, integer, string-list ve choice şeklindedir. Kimlik bilgileri için sensitive: true kullanın. Her alan anahtarı, olumsuz biçimler dâhil olmak üzere uzun CLI bayrağının camelCase biçimli öznitelik adına eşit olmalıdır; örneğin --api-token için apiToken. Hem olumlu hem de --no-* biçimleri gerektiğinde Boolean alanları cli.negatedFlags ekleyebilir. channel, account ve hesap görüntüleme name ortak denetim zarfı olarak kalır.

Yayımlanmış setup/ChannelSetupInput bağdaştırıcısı, mevcut harici pluginler için kullanılabilir olmaya devam eder. Yeni pluginler setupContract sunmalıdır; her ikisi de mevcut olduğunda OpenClaw her zaman bunu tercih eder.

Örnek:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "Kanalım",      "selectionLabel": "Kanalım (kendi sunucunuzda barındırılan)",      "detailLabel": "Kanalım Botu",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook tabanlı, kendi sunucunuzda barındırılan sohbet entegrasyonu.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Kılavuz:",      "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 dâhil eder
• setup: kanalı etkileşimli kurulum/yapılandırma seçicilerine dâhil eder
• docs: kanalı doküman/gezinme yüzeylerinde herkese açık olarak işaretler

openclaw.install

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

{  "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, aşağıdaki yapılandırmayla ertelenmiş yüklemeyi seçebilir:

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

Etkinleştirildiğinde OpenClaw, ön dinleme başlangıç aşamasında önceden 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öntemlerini kaydediyorsa bunları Plugin'e özgü bir ön ek altında tutun. Ayrılmış temel yönetici ad alanları (config.*, exec.approvals.*, wizard.*, update.*) temel bileşenin mülkiyetinde kalır ve her zaman operator.admin olarak normalleştirilir.

Plugin bildirimi

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

{  "id": "my-plugin",  "name": "My Plugin",  "description": "OpenClaw'a My Plugin yetenekleri ekler",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook doğrulama gizli anahtarı"      }    }  }}

Kanal Plugin'leri için channels ekleyin (sağlayıcı Plugin'leri de providers ekler):

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

Yapılandırması olmayan Plugin'ler bile bir şema sunmalıdır. Boş bir şema geçerlidir:

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

Şema başvurusunun tamamı 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şi

setup-entry.ts, OpenClaw'ın 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 için hafif bir alternatiftir:

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

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

Kurulum için güvenli dışa aktarımları yardımcı modüllerde tutan, çalışma alanıyla birlikte paketlenmiş kanallar, defineSetupPluginEntry(...) yerine openclaw/plugin-sdk/channel-entry-contract kaynağındaki defineBundledChannelSetupEntry(...) öğesini kullanabilir. Paketle birlikte gelen bu sözleşme, kurulum zamanı çalışma ortamı 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 amaçlı sıcak yollar için, kurulum yüzeyinin yalnızca bir kısmına ihtiyacınız olduğunda daha geniş kapsamlı plugin-sdk/setup çatı öğesi 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şımlı kurulum araç kutusunun tamamını istediğinizde daha geniş kapsamlı plugin-sdk/setup bağlantısını kullanın.

Sabit kurulum sihirbazı metni için createSetupTranslator(...) kullanın. Sırasıyla OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES ve LANG içindeki ilk boş olmayan değeri kullanır, ardından İngilizceye geri döner. Açık bir İngilizce geçersiz kılma değeri için OPENCLAW_LOCALE=en ayarlayın. Plugin'e özgü kurulum metnini Plugin'e ait kodda tutun ve paylaşımlı katalog anahtarlarını yalnızca ortak kurulum etiketleri, durum metni ve resmi paketle birlikte gelen Plugin kurulum metni için kullanın.

Kurulum yaması bağdaştırıcıları içe aktarma sırasında sıcak yol açısından güvenli kalır. Paketle birlikte gelen tek hesap yükseltme sözleşme yüzeyi araması tembel yürütülür; bu nedenle plugin-sdk/setup-runtime öğesini içe aktarmak, bağdaştırıcı gerçekten kullanılmadan önce paketle birlikte gelen sözleşme yüzeyi keşfini istekli biçimde yüklemez.

Kanalın sahip olduğu kurulum giriş alanları

ChannelSetupInput, kurulum çağıranları ve kanal Plugin'leri tarafından paylaşılan genel bir zarftır. Kalıcı olarak türü belirtilmiş alanları name, token, tokenFile, useEnv, allowFrom ve defaultTo öğeleridir. Plugin'e ait ek anahtarlar çalışma zamanı giriş nesnesinde yine bulunabilir, ancak paylaşılan tür bir dizin imzası bildirmez. Her Plugin kendi kurulum alanlarını bildirmeli ve daraltmalı veya bağdaştırıcı sınırında Plugin'e ait bir şemayla doğrulamalıdır:

 type AcmeSetupInput = ChannelSetupInput & {  workspaceId?: string;  webhookUrl?: string;}; export const acmeSetupAdapter: ChannelSetupAdapter = {  applyAccountConfig: ({ cfg, input }) => {    const setupInput = input as AcmeSetupInput;    return {      ...cfg,      channels: {        ...cfg.channels,        acme: {          token: setupInput.token,          workspaceId: setupInput.workspaceId,          webhookUrl: setupInput.webhookUrl,        },      },    };  },};

Daha önce doğrudan ChannelSetupInput üzerinde bildirilen kanala özgü alanlar, harici kaynak uyumluluğu için geçici olarak türlendirilmiş durumda kalır. Bunlar kullanımdan kaldırılmıştır. Ağaç dışı yayımlanmış 426 kanal Plugin'ini kapsayan 2026-07-22 tarihli kayıt defteri taraması, okuyucusu olmayan 21 alanı kaldırdı ve bilinen okuyucuları olan 22 alanı korudu. Korunan her alan, yayımlanmış hiçbir Plugin artık onu okumadığı anda silinir; sürüm sınırı gerekmez. Yeni ve paketle birlikte gelen Plugin'ler bu katmana dayanmamalıdır; sahip oldukları alanları yerel olarak bildirmelidir.

Kanalın sahip olduğu tek hesaplı yapılandırmanın yükseltilmesi

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.

Her kanal Plugin'i, kurulum bağdaştırıcısı aracılığıyla bu yükseltmeyi genişletebilir veya daraltabilir:

• 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 politika/teslimat anahtarları kanal kökünde kalır
• resolveSingleAccountPromotionTarget(...): yükseltilen değerleri hangi mevcut hesabın alacağını seçer

singleAccountKeysToMove alanının bulunması, yükseltme sözleşmesinin tamamlandığını belirtir. Eski anahtar yükseltmesini devre dışı bırakmak için alanı boş bir dizi olsa bile bildirin. Alanı atlayan bağdaştırıcılar, önceden yayımlanmış Plugin'ler için okuyucu destekli bildirim öncesi yükseltme katmanını korur. 2026-07-22 tarihli kayıt defteri taraması, yayımlanmış bağımlısı olmayan 23 anahtarı kaldırdı ve altı ortak anahtar ile yalnızca kurulumda kullanılan rooms anahtarını korudu. Korunan her anahtar, yayımlanmış okuyucuları bildirimlere geçirildiği anda silinir; sürüm sınırı gerekmez.

Doctor'ın bu bildirimleri hafif, paketle birlikte gelen kurulum yapısından yüklemesi gerektiğinde Plugin paket bildiriminde openclaw.setupFeatures.configPromotion: true bildirin. Yalnızca kuruluma yönelik Plugin yüzeyi ile tam kanal Plugin'i aynı bildirimleri sunmalıdır.

Önceden çözümlenmiş bir Plugin ile moveSingleAccountChannelSectionToDefaultAccount(...) çağrılırken kurulum bağdaştırıcısını setupSurface olarak iletin. Çağıranın sağladığı kurulum yüzeyleri, yüklenen ve paketle birlikte gelen aramalara göre önceliklidir; böylece kapsamlı veya yalnızca kuruluma yönelik Plugin'ler genel kayıttan bağımsız kalır.

Yapılandırma şeması

Plugin yapılandırması, bildirim dosyanızdaki 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 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ırması 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'in sahip olduğu yapılandırma yapılarında 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 biçiminde 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 yine Plugin bildirimidir: 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 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; textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize ve daha fazlasını da destekler. Paketle birlikte gelen tam bir örnek için Discord Plugin'inin src/setup-core.ts öğesine 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çıkça belirtilir; Gateway başlangıcında derlenmiş JavaScript'ten çıkarılmaz. Çalışma zamanı bağımlılıkları, bunların sahibi olan Plugin paketine aittir; 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 bildirimi — tam bildirim şeması başvurusu
• SDK giriş noktaları — definePluginEntry ve defineChannelPluginEntry