Ana içeriğe atla

Eklenti Kurulumu ve Yapılandırması

Eklenti paketleme (package.json meta verileri), manifestler (openclaw.plugin.json), kurulum girişleri ve yapılandırma şemaları için başvuru.
Adım adım bir kılavuz mu arıyorsunuz? Nasıl yapılır kılavuzları, paketlemeyi bağlam içinde ele alır: Kanal Eklentileri ve Sağlayıcı Eklentileri.

Paket meta verileri

package.json dosyanızda, eklenti sistemine eklentinizin ne sağladığını bildiren bir openclaw alanı bulunmalıdır: Kanal eklentisi:
{
  "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."
    }
  }
}
Sağlayıcı eklentisi / ClawHub yayın temel yapısı:
openclaw-clawhub-package.json
{
  "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"
    }
  }
}
Eklentiyi dışarıda ClawHub üzerinde yayımlıyorsanız, bu compat ve build alanları zorunludur. Kanonik yayın kod parçaları docs/snippets/plugin-publish/ içinde bulunur.

openclaw alanları

AlanTürAçıklama
extensionsstring[]Giriş noktası dosyaları (paket köküne göre)
setupEntrystringHafif, yalnızca kurulum için giriş (isteğe bağlı)
channelobjectKurulum, seçici, hızlı başlangıç ve durum yüzeyleri için kanal katalog meta verileri
providersstring[]Bu eklenti tarafından kaydedilen sağlayıcı kimlikleri
installobjectKurulum ipuçları: npmSpec, localPath, defaultChoice, minHostVersion, allowInvalidConfigRecovery
startupobjectBaşlatma davranışı işaretleri

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.
AlanTürAnlamı
idstringKanonik kanal kimliği.
labelstringBirincil kanal etiketi.
selectionLabelstringlabel değerinden farklı olması gerektiğinde seçici/kurulum etiketi.
detailLabelstringDaha zengin kanal katalogları ve durum yüzeyleri için ikincil ayrıntı etiketi.
docsPathstringKurulum ve seçim bağlantıları için belge yolu.
docsLabelstringBelge bağlantılarında kanal kimliğinden farklı olması gereken etiket.
blurbstringKısa onboarding/katalog açıklaması.
ordernumberKanal kataloglarında sıralama düzeni.
aliasesstring[]Kanal seçimi için ek arama diğer adları.
preferOverstring[]Bu kanalın önüne geçmesi gereken daha düşük öncelikli eklenti/kanal kimlikleri.
systemImagestringKanal kullanıcı arayüzü katalogları için isteğe bağlı simge/sistem görüntüsü adı.
selectionDocsPrefixstringSeçim yüzeylerinde belge bağlantılarından önce gelen önek metin.
selectionDocsOmitLabelbooleanSeçim metninde etiketli belge bağlantısı yerine belge yolunu doğrudan gösterir.
selectionExtrasstring[]Seçim metnine eklenen ilave kısa dizeler.
markdownCapablebooleanGiden biçimlendirme kararları için kanalı markdown destekli olarak işaretler.
showConfiguredbooleanYapılandırılmış kanal listeleme yüzeylerinin bu kanalı gösterip göstermeyeceğini kontrol eder.
quickstartAllowFrombooleanBu kanalı standart hızlı başlangıç allowFrom kurulum akışına dahil eder.
forceAccountBindingbooleanYalnızca bir hesap olsa bile açık hesap bağlamasını zorunlu kılar.
preferSessionLookupForAnnounceTargetbooleanBu kanal için duyuru hedefleri çözülürken oturum aramasını tercih eder.
Ö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,
      "quickstartAllowFrom": true
    }
  }
}

openclaw.install

openclaw.install, manifest meta verisi değil paket meta verisidir.
AlanTürAnlamı
npmSpecstringKurulum/güncelleme akışları için kanonik npm tanımı.
localPathstringYerel geliştirme veya paketlenmiş kurulum yolu.
defaultChoice"npm" | "local"Her ikisi de mevcut olduğunda tercih edilen kurulum kaynağı.
minHostVersionstring>=x.y.z biçiminde desteklenen en düşük OpenClaw sürümü.
allowInvalidConfigRecoverybooleanPaketlenmiş eklenti yeniden kurulum akışlarının belirli eski yapılandırma hatalarını onarmasına izin verir.
minHostVersion ayarlanmışsa, hem kurulum hem de manifest kayıt defteri yüklemesi bunu uygular. Daha eski host’lar eklentiyi atlar; geçersiz sürüm dizeleri reddedilir. allowInvalidConfigRecovery, bozuk yapılandırmalar için genel amaçlı bir atlama değildir. Yalnızca dar kapsamlı paketlenmiş eklenti kurtarma içindir; böylece yeniden kurulum/kurulum, eksik paketlenmiş eklenti yolu veya aynı eklenti için eski channels.<id> girdisi gibi bilinen yükseltme kalıntılarını onarabilir. Yapılandırma alakasız nedenlerle bozuksa, kurulum yine hata durumunda kapalı kalır ve operatöre openclaw doctor --fix çalıştırmasını söyler.

Ertelenmiş tam yükleme

Kanal eklentileri şu şekilde ertelenmiş yüklemeyi seçebilir:
{
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}
Etkinleştirildiğinde OpenClaw, önceden 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.
Ertelenmiş yüklemeyi yalnızca setupEntry dosyanız gateway’in dinlemeye başlamasından önce ihtiyaç duyduğu her şeyi kaydediyorsa etkinleştirin (kanal kaydı, HTTP yolları, gateway yöntemleri). Tam giriş gerekli başlatma yeteneklerinin sahibiyse varsayılan davranışı koruyun.
Kurulum/tam girişiniz gateway RPC yöntemleri kaydediyorsa, bunları eklentiye özgü bir önekte tutun. Ayrılmış çekirdek yönetici ad alanları (config.*, exec.approvals.*, wizard.*, update.*) çekirdeğin sahipliğinde kalır ve her zaman operator.admin olarak çözülür.

Eklenti manifesti

Her yerel eklenti, paket kökünde bir openclaw.plugin.json dosyası göndermelidir. OpenClaw bunu eklenti 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 eklentileri için kind ve channels ekleyin:
{
  "id": "my-channel",
  "kind": "channel",
  "channels": ["my-channel"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}
Yapılandırması olmayan eklentiler bile bir şema göndermelidir. Boş şema geçerlidir:
{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}
Tam şema başvurusu için Eklenti Manifesti bölümüne bakın.

ClawHub yayımlama

Eklenti paketleri için pakete özgü ClawHub komutunu kullanın:
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
Eski yalnızca-skill yayımlama diğer adı skill’ler içindir. Eklenti paketleri her zaman clawhub package publish kullanmalıdır.

Kurulum girişi

setup-entry.ts dosyası, OpenClaw’ın yalnızca kurulum yüzeylerine ihtiyaç duyduğunda yüklediği index.ts dosyasına göre hafif bir alternatiftir (onboarding, yapılandırma onarımı, devre dışı kanal incelemesi).
// setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { myChannelPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(myChannelPlugin);
Bu, kurulum akışları sırasında ağır çalışma zamanı kodlarının (kripto kitaplıkları, CLI kayıtları, arka plan hizmetleri) yüklenmesini önler. OpenClaw’ın tam giriş yerine setupEntry kullandığı durumlar:
  • Kanal devre dışıdır ama kurulum/onboarding yüzeylerine ihtiyaç vardır
  • Kanal etkindir ama yapılandırılmamıştır
  • Ertelenmiş yükleme etkindir (deferConfiguredChannelFullLoadUntilAfterListen)
setupEntry dosyasının kaydetmesi gerekenler:
  • Kanal eklentisi nesnesi (defineSetupPluginEntry aracılığıyla)
  • Gateway dinlemesinden önce gerekli tüm HTTP yolları
  • Başlatma sırasında gerekli tüm gateway yöntemleri
Bu başlatma gateway yöntemleri yine de config.* veya update.* gibi ayrılmış çekirdek yönetici ad alanlarından kaçınmalıdır. setupEntry içinde OLMAMASI gerekenler:
  • CLI kayıtları
  • Arka plan hizmetleri
  • Ağır çalışma zamanı içe aktarımları (kripto, SDK’ler)
  • Yalnızca başlatmadan sonra gerekli gateway yöntemleri

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

Sadece kurulum yapılan sıcak yollar için, kurulum yüzeyinin yalnızca bir bölümüne ihtiyaç duyduğunuzda daha geniş plugin-sdk/setup şemsiyesi yerine dar kurulum yardımcı yüzeylerini tercih edin:
İçe aktarma yoluKullanım amacıTemel dışa aktarımlar
plugin-sdk/setup-runtimesetupEntry / ertelenmiş kanal başlatmasında kullanılabilir kalan kurulum zamanı çalışma zamanı yardımcılarıcreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimeortam farkındalıklı hesap kurulum bağdaştırıcılarıcreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolskurulum/yükleme CLI/arşiv/belge yardımcılarıformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
moveSingleAccountChannelSectionToDefaultAccount(...) gibi yapılandırma-yaması yardımcılarını da içeren tam paylaşılan kurulum araç kutusunu istediğinizde daha geniş plugin-sdk/setup yüzeyini kullanın. Kurulum yama bağdaştırıcıları içe aktarma açısından sıcak yol güvenliğini korur. 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 hevesli biçimde yüklemez.

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

Bir kanal, tek hesaplı üst düzey yapılandırmadan channels.<id>.accounts.* yapısına yükseldiğinde, varsayılan paylaşılan davranış yükseltilen hesap kapsamlı değerleri accounts.default içine taşımaktır. Paketlenmiş kanallar, kurulum sözleşmesi yüzeyleri üzerinden 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
Mevcut paketlenmiş örnek Matrix’tir. Tam olarak bir adlandırılmış Matrix hesabı zaten varsa veya defaultAccount, Ops gibi kanonik olmayan mevcut bir anahtarı işaret ediyorsa, yükseltme yeni bir accounts.default girdisi oluşturmak yerine o hesabı korur.

Yapılandırma şeması

Eklenti yapılandırması, manifestinizdeki JSON Schema’ya göre doğrulanır. Kullanıcılar eklentileri şu yollarla yapılandırır:
{
  plugins: {
    entries: {
      "my-plugin": {
        config: {
          webhookSecret: "abc123",
        },
      },
    },
  },
}
Eklentiniz 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ı OpenClaw’ın doğruladığı ChannelConfigSchema sarmalayıcısına dönüştürmek için openclaw/plugin-sdk/core içinden buildChannelConfigSchema kullanın:
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/core";

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

Kurulum sihirbazları

Kanal eklentileri, openclaw onboard için etkileşimli kurulum sihirbazları sağlayabilir. Sihirbaz, ChannelPlugin üzerindeki bir ChannelSetupWizard nesnesidir:
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),
        };
      },
    },
  ],
};
ChannelSetupWizard türü credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize ve daha fazlasını destekler. Tam örnekler için paketlenmiş eklenti paketlerine (örneğin Discord eklentisinin src/channel.setup.ts dosyasına) bakın. Yalnızca standart note -> prompt -> parse -> merge -> patch akışına ihtiyaç duyan DM izin listesi istemleri için, openclaw/plugin-sdk/setup içindeki paylaşılan kurulum yardımcılarını tercih edin: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) ve createNestedChannelParsedAllowFromPrompt(...). Yalnızca etiketler, puanlar ve isteğe bağlı ek satırlara göre değişen kanal kurulum durum blokları için, her eklentide aynı status nesnesini elle yazmak yerine openclaw/plugin-sdk/setup içindeki createStandardChannelSetupStatus(...) yardımcısını tercih edin. Yalnızca belirli bağlamlarda görünmesi gereken isteğe bağlı kurulum yüzeyleri için, openclaw/plugin-sdk/channel-setup içindeki createOptionalChannelSetupSurface kullanı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 }
plugin-sdk/channel-setup, yalnızca bu isteğe bağlı kurulum yüzeyinin yarısına ihtiyaç duyduğunuzda daha düşük seviyeli createOptionalChannelSetupAdapter(...) ve createOptionalChannelSetupWizard(...) oluşturucularını da açığa çıkarır. Oluşturulan isteğe bağlı bağdaştırıcı/sihirbaz, gerçek yapılandırma yazımlarında hata durumunda kapalı kalır. Bunlar validateInput, applyAccountConfig ve finalize boyunca tek bir kurulum-gerekli iletisini yeniden kullanır ve docsPath ayarlanmışsa bir belge bağlantısı ekler. İkili dosya destekli kurulum arayüzleri için, aynı ikili/durum yapıştırıcısını her kanala kopyalamak yerine paylaşılan delege yardımcılarını tercih edin:
  • Yalnızca etiketler, ipuçları, puanlar ve ikili dosya algılamasına göre değişen durum blokları için createDetectedBinaryStatus(...)
  • Yol destekli metin girdileri için createCliPathTextInput(...)
  • setupEntry yalnızca daha ağır bir tam sihirbaza tembel biçimde iletmek zorundaysa createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) ve createDelegatedResolveConfigured(...)
  • setupEntry yalnızca bir textInputs[*].shouldPrompt kararını devretmek zorundaysa createDelegatedTextInputShouldPrompt(...)

Yayımlama ve kurulum

Harici eklentiler: ClawHub veya npm üzerinde yayımlayın, ardından kurun:
openclaw plugins install @myorg/openclaw-my-plugin
OpenClaw önce ClawHub’ı dener ve ardından otomatik olarak npm’ye geri döner. İsterseniz ClawHub’ı açıkça zorlayabilirsiniz:
openclaw plugins install clawhub:@myorg/openclaw-my-plugin   # yalnızca ClawHub
Buna karşılık gelen bir npm: geçersiz kılması yoktur. ClawHub geri dönüşünden sonra npm yolunu istediğinizde normal npm paket tanımını kullanın:
openclaw plugins install @myorg/openclaw-my-plugin
Depo içi eklentiler: paketlenmiş eklenti ç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>
npm kaynaklı kurulumlar için openclaw plugins install, npm install --ignore-scripts çalıştırır (yaşam döngüsü betikleri yoktur). Eklenti bağımlılık ağaçlarını saf JS/TS olarak tutun ve postinstall derlemeleri gerektiren paketlerden kaçının.

İlgili