Ana içeriğe atla

Plugin Kurulumu ve Yapılandırması

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

Paket meta verileri

package.json dosyanızın, Plugin sistemine Plugin’inizin ne sağladığını söyleyen bir openclaw alanına ihtiyacı vardır: Kanal Plugin’i:
{
  "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ı Plugin’i / ClawHub yayımlama taban çizgisi:
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"
    }
  }
}
Plugin’i ClawHub üzerinde harici olarak yayımlıyorsanız, bu compat ve build alanları zorunludur. Kanonik yayımlama parçacıkları docs/snippets/plugin-publish/ içinde bulunur.

openclaw alanları

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

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.
docsLabelstringKanal kimliğinden farklı olması gerektiğinde belge bağlantıları için kullanılan geçersiz kılma etiketi.
blurbstringKısa onboarding/katalog açıklaması.
ordernumberKanal kataloglarındaki sıralama düzeni.
aliasesstring[]Kanal seçimi için ek arama takma adları.
preferOverstring[]Bu kanalın önüne geçmesi gereken daha düşük öncelikli Plugin/kanal kimlikleri.
systemImagestringKanal UI katalogları için isteğe bağlı simge/system-image adı.
selectionDocsPrefixstringSeçim yüzeylerinde belge bağlantılarından önce gelen önek metin.
selectionDocsOmitLabelbooleanSeçim kopyasında etiketli bir belge bağlantısı yerine belge yolunu doğrudan gösterir.
selectionExtrasstring[]Seçim kopyasına eklenen ek kısa dizgiler.
markdownCapablebooleanGiden biçimlendirme kararları için kanalı markdown yetenekli olarak işaretler.
exposureobjectKurulum, yapılandırılmış listeler ve belge yüzeyleri için kanal görünürlük denetimleri.
quickstartAllowFrombooleanBu kanalı standart hızlı başlangıç allowFrom kurulum akışına dahil eder.
forceAccountBindingbooleanYalnızca bir hesap bulunsa bile açık hesap bağlamasını zorunlu kılar.
preferSessionLookupForAnnounceTargetbooleanBu kanal için duyuru hedefleri çözümlenirken oturum aramayı 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,
      "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ı belge/navigasyon yüzeylerinde herkese açık olarak işaretle
showConfigured ve showInSetup, eski takma adlar olarak hâlâ desteklenir. Tercihen exposure kullanın.

openclaw.install

openclaw.install, manifest meta verisi değil paket meta verisidir.
AlanTürAnlamı
npmSpecstringKurulum/güncelleme akışları için kanonik npm belirtimi.
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ş-Plugin yeniden kurulum akışlarının belirli eski yapılandırma hatalarından kurtulmasına izin verir.
minHostVersion ayarlanmışsa, hem kurulum hem de manifest-kayıt yükleme bunu zorunlu kılar. Eski ana makineler Plugin’i atlar; geçersiz sürüm dizgileri reddedilir. allowInvalidConfigRecovery, bozuk yapılandırmalar için genel bir atlatma değildir. Yalnızca dar paketlenmiş-Plugin kurtarma senaryoları içindir; böylece yeniden kurulum/kurulum, eksik bir paketlenmiş plugin yolu veya aynı Plugin için eski bir channels.<id> girdisi gibi bilinen yükseltme kalıntılarını onarabilir. Yapılandırma ilgisiz nedenlerle bozuksa, kurulum yine güvenli biçimde kapalı başarısız olur ve operatöre openclaw doctor --fix çalıştırmasını söyler.

Ertelenmiş tam yükleme

Kanal Plugin’leri ertelenmiş yüklemeye şu şekilde katılabilir:
{
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}
Etkinleştirildiğinde, OpenClaw önceden yapılandırılmış kanallar için bile ön-dinleme başlangıç 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 rotaları, gateway yöntemleri). Gerekli başlangıç yetenekleri tam girişe aitse, varsayılan davranışı koruyun.
Kurulum/tam girişiniz Gateway RPC yöntemleri kaydediyorsa, bunları Plugin’e özgü bir önek altında tutun. Ayrılmış çekirdek yönetici ad alanları (config.*, exec.approvals.*, wizard.*, update.*) çekirdeğe aittir ve her zaman operator.admin olarak çözülür.

Plugin manifest’i

Her yerel Plugin, paket kökünde bir openclaw.plugin.json dosyası taşımalıdır. OpenClaw bunu Plugin kodunu yürütmeden 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 taşımalıdır. Boş bir şema geçerlidir:
{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}
Tam şema başvurusu için bkz. Plugin Manifest’i.

ClawHub yayımlama

Plugin paketleri için pakete özel 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 takma adı skill’ler içindir. Plugin 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 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ı kodunun (kripto kütüphaneleri, CLI kayıtları, arka plan hizmetleri) yüklenmesini önler. Kurulum açısından güvenli dışa aktarmaları yan modüllerde tutan paketlenmiş çalışma alanı kanalları, defineSetupPluginEntry(...) yerine openclaw/plugin-sdk/channel-entry-contract içinden defineBundledChannelSetupEntry(...) kullanabilir. Bu paketlenmiş sözleşme ayrıca isteğe bağlı bir runtime dışa aktarımını da destekler; böylece kurulum zamanındaki çalışma zamanı bağlantısı hafif ve açık kalabilir. OpenClaw’ın tam giriş yerine setupEntry kullandığı durumlar:
  • Kanal devre dışıdır ama kurulum/onboarding yüzeylerine ihtiyaç vardır
  • Kanal etkin ama yapılandırılmamıştır
  • Ertelenmiş yükleme etkinleştirilmiştir (deferConfiguredChannelFullLoadUntilAfterListen)
setupEntry dosyasının kaydetmesi gerekenler:
  • Kanal Plugin nesnesi (defineSetupPluginEntry aracılığıyla)
  • Gateway dinlemesinden önce gereken tüm HTTP rotaları
  • Başlangıç sırasında gereken tüm Gateway yöntemleri
Bu başlangıç Gateway yöntemleri yine de config.* veya update.* gibi ayrılmış çekirdek yönetici ad alanlarından kaçınmalıdır. setupEntry dosyasının İÇERMEMESİ gerekenler:
  • CLI kayıtları
  • Arka plan hizmetleri
  • Ağır çalışma zamanı içe aktarmaları (kripto, SDK’lar)
  • Yalnızca başlangıçtan sonra gereken Gateway yöntemleri

Dar kurulum yardımcı içe aktarmaları

Sıcak yalnızca-kurulum yolları için, kurulum yüzeyinin yalnızca bir kısmına ihtiyacınız olduğunda daha geniş plugin-sdk/setup şemsiyesi yerine dar kurulum yardımcı katmanlarını tercih edin:
İçe aktarma yoluŞunun için kullanınTemel dışa aktarmalar
plugin-sdk/setup-runtimesetupEntry / ertelenmiş kanal başlangıcı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/kurma CLI/arşiv/belge yardımcılarıformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
Yapılandırma yaması yardımcıları moveSingleAccountChannelSectionToDefaultAccount(...) gibi öğeler dahil tam paylaşılan kurulum araç kutusunu istediğinizde daha geniş plugin-sdk/setup katmanını kullanın. Kurulum yaması 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 aktarımı, bağdaştırıcı gerçekten kullanılmadan önce paketlenmiş sözleşme-yüzeyi keşfini hevesli biçimde yüklemez.

Kanala ait 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 kapsamlı değerleri accounts.default içine taşımaktır. Paketlenmiş kanallar bu yükseltmeyi kurulum sözleşme yüzeyi üzerinden daraltabilir veya geçersiz kılabilir:
  • singleAccountKeysToMove: yükseltilen hesaba taşınması gereken ek üst düzey anahtarlar
  • namedAccountPromotionKeys: adlandırılmış hesaplar zaten varsa, 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çer
Matrix, mevcut paketlenmiş örnektir. Tam olarak bir adlandırılmış Matrix hesabı zaten varsa veya defaultAccount, Ops gibi mevcut kanonik olmayan bir anahtarı işaret ediyorsa, yükseltme yeni bir accounts.default girdisi oluşturmak yerine bu hesabı korur.

Yapılandırma şeması

Plugin yapılandırması, manifest’inizdeki JSON Şeması’na 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, 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ı 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 Plugin’leri 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ş Plugin paketlerine bakın (örneğin Discord Plugin’i src/channel.setup.ts). 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ırlar açısından değişen kanal kurulum durumu blokları için, her Plugin’de aynı status nesnesini elle kurmak yerine openclaw/plugin-sdk/setup içindeki createStandardChannelSetupStatus(...) kullanın. Yalnızca belirli bağlamlarda görünmesi gereken isteğe bağlı kurulum yüzeyleri için, openclaw/plugin-sdk/channel-setup içinden 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",
});
// { setupAdapter, setupWizard } döndürür
plugin-sdk/channel-setup ayrıca, bu isteğe bağlı kurulum yüzeyinin yalnızca bir yarısına ihtiyacınız olduğunda daha düşük seviyeli createOptionalChannelSetupAdapter(...) ve createOptionalChannelSetupWizard(...) oluşturucularını da dışa aktarır. Oluşturulan isteğe bağlı bağdaştırıcı/sihirbaz, gerçek yapılandırma yazımlarında güvenli biçimde kapalı başarısız olur. Bunlar validateInput, applyAccountConfig ve finalize genelinde aynı kurulum-gerekli mesajını yeniden kullanır ve docsPath ayarlıysa bir belge bağlantısı ekler. İkili dosya destekli kurulum UI’ları için, aynı ikili/durum yapıştırıcısını her kanala kopyalamak yerine paylaşılan devredilmiş yardımcıları tercih edin:
  • Yalnızca etiketler, ipuçları, puanlar ve ikili algılama açısından değişen durum blokları için createDetectedBinaryStatus(...)
  • Yol destekli metin girdileri için createCliPathTextInput(...)
  • setupEntry dosyasının daha ağır bir tam sihirbaza tembel biçimde iletmesi gerektiğinde createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) ve createDelegatedResolveConfigured(...)
  • setupEntry yalnızca bir textInputs[*].shouldPrompt kararını devretmek zorundaysa createDelegatedTextInputShouldPrompt(...)

Yayımlama ve kurma

Harici Plugin’ler: ClawHub veya npm üzerinde yayımlayın, sonra kurun:
openclaw plugins install @myorg/openclaw-my-plugin
OpenClaw önce ClawHub’ı dener ve otomatik olarak npm’e geri düşer. Ayrıca 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 belirtimini kullanın:
openclaw plugins install @myorg/openclaw-my-plugin
Repo 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 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). Plugin bağımlılık ağaçlarını saf JS/TS tutun ve postinstall derlemeleri gerektiren paketlerden kaçının.
Paketlenmiş ve OpenClaw’a ait Plugin’ler tek başlangıç onarım istisnasıdır: paketlenmiş bir kurulum, bunlardan birini Plugin yapılandırması, eski kanal yapılandırması veya paketlenmiş varsayılan-etkin manifest’i aracılığıyla etkin görürse, başlangıç bu Plugin’in eksik çalışma zamanı bağımlılıklarını içe aktarmadan önce kurar. Üçüncü taraf Plugin’ler başlangıç kurulumlarına güvenmemelidir; açık Plugin kurucusunu kullanmaya devam edin.

İlgili