Plugin paketleme (Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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:
- Kanal Plugin'i
- Sağlayıcı Plugin'i / ClawHub taban çizgisi
Plugin’i ClawHub üzerinde harici olarak yayımlarsanız, bu
compat ve build alanları zorunludur. Standart yayımlama parçacıkları docs/snippets/plugin-publish/ içinde bulunur.openclaw alanları
Giriş noktası dosyaları (paket köküne göreli).
Hafif, yalnızca kurulum amaçlı giriş (isteğe bağlı).
Kurulum, seçici, hızlı başlangıç ve durum yüzeyleri için kanal katalog meta verileri.
Bu Plugin tarafından kaydedilen sağlayıcı kimlikleri.
Kurulum ipuçları:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.Başlatma 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.
| Alan | Tür | Anlamı |
|---|---|---|
id | string | Standart kanal kimliği. |
label | string | Birincil kanal etiketi. |
selectionLabel | string | label değerinden farklı olması gerektiğinde seçici/kurulum etiketi. |
detailLabel | string | Daha zengin kanal katalogları ve durum yüzeyleri için ikincil ayrıntı etiketi. |
docsPath | string | Kurulum ve seçim bağlantıları için dokümantasyon yolu. |
docsLabel | string | Kanal kimliğinden farklı olması gerektiğinde dokümantasyon bağlantıları için kullanılan geçersiz kılma etiketi. |
blurb | string | Kısa ilk kullanım/katalog açıklaması. |
order | number | Kanal kataloglarındaki sıralama düzeni. |
aliases | string[] | Kanal seçimi için ek arama takma adları. |
preferOver | string[] | Bu kanalın önüne geçmesi gereken daha düşük öncelikli Plugin/kanal kimlikleri. |
systemImage | string | Kanal UI katalogları için isteğe bağlı simge/sistem görseli adı. |
selectionDocsPrefix | string | Seçim yüzeylerinde dokümantasyon bağlantılarından önceki önek metni. |
selectionDocsOmitLabel | boolean | Seçim metninde etiketli dokümantasyon bağlantısı yerine dokümantasyon yolunu doğrudan gösterir. |
selectionExtras | string[] | Seçim metnine eklenen ek kısa dizeler. |
markdownCapable | boolean | Giden biçimlendirme kararları için kanalı Markdown uyumlu olarak işaretler. |
exposure | object | Kurulum, yapılandırılmış listeler ve dokümantasyon yüzeyleri için kanal görünürlük kontrolleri. |
quickstartAllowFrom | boolean | Bu kanalı standart hızlı başlangıç allowFrom kurulum akışına dahil eder. |
forceAccountBinding | boolean | Yalnızca bir hesap olsa bile açık hesap bağlamayı zorunlu kılar. |
preferSessionLookupForAnnounceTarget | boolean | Bu kanal için duyuru hedeflerini çözerken oturum aramasını tercih eder. |
exposure şunları destekler:
configured: kanalı yapılandırılmış/durum tarzı listeleme yüzeylerine dahil etsetup: kanalı etkileşimli kurulum/yapılandırma seçicilerine dahil etdocs: kanalı dokümantasyon/gezinme yüzeylerinde herkese açık olarak işaretle
showConfigured ve showInSetup eski takma adlar olarak desteklenmeye devam eder. exposure tercih edin.openclaw.install
openclaw.install paket meta verisidir, manifest meta verisi değildir.
| Alan | Tür | Anlamı |
|---|---|---|
clawhubSpec | string | Kurulum/güncelleme ve ilk kullanımda isteğe bağlı kurulum akışları için standart ClawHub belirtimi. |
npmSpec | string | Kurulum/güncelleme yedek akışları için standart npm belirtimi. |
localPath | string | Yerel geliştirme veya paketlenmiş kurulum yolu. |
defaultChoice | "clawhub" | "npm" | "local" | Birden fazla kaynak mevcut olduğunda tercih edilen kurulum kaynağı. |
minHostVersion | string | >=x.y.z veya >=x.y.z-prerelease biçimindeki desteklenen minimum OpenClaw sürümü. |
expectedIntegrity | string | Sabitlenmiş kurulumlar için beklenen npm dağıtım bütünlük dizesi; genellikle sha512-.... |
allowInvalidConfigRecovery | boolean | Paketlenmiş Plugin yeniden kurulum akışlarının belirli eski yapılandırma hatalarından kurtulmasına izin verir. |
İlk kullanım davranışı
İlk kullanım davranışı
Etkileşimli ilk kullanım da isteğe bağlı kurulum yüzeyleri için
openclaw.install kullanır. Plugin’iniz çalışma zamanı yüklenmeden önce sağlayıcı kimlik doğrulama seçenekleri veya kanal kurulum/katalog meta verileri sunuyorsa, ilk kullanım bu seçeneği gösterebilir, ClawHub, npm veya yerel kurulum için istemde bulunabilir, Plugin’i kurabilir veya etkinleştirebilir ve ardından seçilen akışa devam edebilir. ClawHub ilk kullanım seçenekleri clawhubSpec kullanır ve mevcut olduğunda tercih edilir; npm seçenekleri, kayıt defteri npmSpec içeren güvenilir katalog meta verileri gerektirir; kesin sürümler ve expectedIntegrity isteğe bağlı npm sabitlemeleridir. expectedIntegrity mevcutsa, kurulum/güncelleme akışları bunu npm için zorunlu kılar. “Ne gösterilecek” meta verilerini openclaw.plugin.json içinde, “nasıl kurulacak” meta verilerini ise package.json içinde tutun.minHostVersion zorunlu kılma
minHostVersion zorunlu kılma
minHostVersion ayarlanmışsa, hem kurulum hem de paketlenmemiş manifest kayıt defteri yükleme bunu zorunlu kılar. Eski ana makineler harici Plugin’leri atlar; geçersiz sürüm dizeleri reddedilir. Paketlenmiş kaynak Plugin’lerin ana makine çalışma kopyasıyla aynı sürümde olduğu varsayılır.Sabitlenmiş npm kurulumları
Sabitlenmiş npm kurulumları
Sabitlenmiş npm kurulumları için kesin sürümü
npmSpec içinde tutun ve beklenen yapıt bütünlüğünü ekleyin:allowInvalidConfigRecovery kapsamı
allowInvalidConfigRecovery kapsamı
allowInvalidConfigRecovery, bozuk yapılandırmalar için genel bir baypas değildir. Yalnızca dar kapsamlı paketlenmiş Plugin kurtarması içindir; böylece yeniden kurulum/kurulum, eksik paketlenmiş Plugin yolu veya aynı Plugin için eski channels.<id> girdisi gibi bilinen yükseltme artıklarını onarabilir. Yapılandırma ilgisiz nedenlerle bozuksa, kurulum yine 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 şu şekilde ertelenmiş yüklemeye dahil olabilir: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 biropenclaw.plugin.json ile gelmelidir. OpenClaw bunu, Plugin kodunu çalıştırmadan yapılandırmayı doğrulamak için kullanır.
kind ve channels ekleyin:
ClawHub yayımlama
Plugin paketleri için pakete özgü ClawHub komutunu kullanın:Eski yalnızca beceri yayımlama takma adı beceriler içindir. Plugin paketleri her zaman
clawhub package publish kullanmalıdır.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.
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.
OpenClaw setupEntry'yi tam giriş yerine ne zaman kullanır
OpenClaw setupEntry'yi tam giriş yerine ne zaman kullanır
- Kanal devre dışıdır ama kurulum/ilk katılım yüzeylerine ihtiyaç duyar.
- Kanal etkindir ama yapılandırılmamıştır.
- Ertelenmiş yükleme etkindir (
deferConfiguredChannelFullLoadUntilAfterListen).
setupEntry ne kaydetmelidir
setupEntry ne kaydetmelidir
- Kanal Plugin nesnesi (
defineSetupPluginEntryaracılığıyla). - Gateway dinlemeden önce gereken tüm HTTP rotaları.
- Başlangıç sırasında gereken tüm Gateway yöntemleri.
config.* veya update.* gibi ayrılmış çekirdek yönetim ad alanlarından kaçınmalıdır.setupEntry neleri içermemelidir
setupEntry neleri içermemelidir
- CLI kayıtları.
- Arka plan servisleri.
- Ağır çalışma zamanı içe aktarımları (kripto, SDK’ler).
- Yalnızca başlangıçtan sonra gereken Gateway yöntemleri.
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:
| İçe aktarma yolu | Bunun için kullanın | Ana dışa aktarımlar |
|---|---|---|
plugin-sdk/setup-runtime | setupEntry / 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-runtime | kullanımdan kaldırılmış uyumluluk takma adı; plugin-sdk/setup-runtime kullanın | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | kurulum/yükleme CLI/arşiv/dokümantasyon yardımcıları | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
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ırmadanchannels.<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 anahtarlarnamedAccountPromotionKeys: 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ırresolveSingleAccountPromotionTarget(...): yükseltilen değerleri hangi mevcut hesabın alacağını seçin
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 o hesabı korur.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:api.pluginConfig olarak alır.
Kanala özgü yapılandırma için bunun yerine kanal yapılandırma bölümünü kullanın:
Kanal yapılandırma şemaları oluşturma
Bir Zod şemasını Plugin’e ait yapılandırma yapıları tarafından kullanılanChannelConfigSchema sarmalayıcısına dönüştürmek için buildChannelConfigSchema kullanın:
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’leriopenclaw onboard için etkileşimli kurulum sihirbazları sağlayabilir. Sihirbaz, ChannelPlugin üzerinde bir ChannelSetupWizard nesnesidir:
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).
Paylaşılan allowFrom istemleri
Paylaşılan allowFrom istemleri
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(...).Standart kanal kurulum durumu
Standart kanal kurulum durumu
Yalnızca etiketlere, puanlara ve isteğe bağlı ek satırlara göre değişen kanal kurulum durumu blokları için, her Plugin’de aynı
status nesnesini elle oluşturmak yerine openclaw/plugin-sdk/setup içindeki createStandardChannelSetupStatus(...) işlevini tercih edin.İsteğe bağlı kanal kurulum yüzeyi
İsteğe bağlı kanal kurulum yüzeyi
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:plugin-sdk/channel-setup, bu isteğe bağlı yükleme yüzeyinin yalnızca bir yarısına ihtiyaç duyduğunuzda daha düşük düzeyli createOptionalChannelSetupAdapter(...) ve createOptionalChannelSetupWizard(...) oluşturucularını da sunar.Oluşturulan isteğe bağlı adaptör/sihirbaz, gerçek yapılandırma yazımlarında kapalı başarısız olur. validateInput, applyAccountConfig ve finalize boyunca tek bir yükleme gerekli mesajını yeniden kullanırlar ve docsPath ayarlandığında bir dokümantasyon bağlantısı eklerler.İkili dosya destekli kurulum yardımcıları
İkili dosya destekli kurulum yardımcıları
İkili dosya destekli kurulum UI’ları için, aynı ikili dosya/durum bağlantısını her kanala kopyalamak yerine paylaşılan yetkilendirilmiş yardımcıları tercih edin:
- Yalnızca etiketlere, ipuçlarına, puanlara ve ikili dosya algılamasına göre değişen durum blokları için
createDetectedBinaryStatus(...) - Yol destekli metin girdileri için
createCliPathTextInput(...) setupEntrydaha ağır bir tam sihirbaza tembel olarak iletmek zorunda olduğundacreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)vecreateDelegatedResolveConfigured(...)setupEntryyalnızca birtextInputs[*].shouldPromptkararını yetkilendirmek zorunda olduğundacreateDelegatedTextInputShouldPrompt(...)
Yayımlama ve yükleme
Harici Plugin’ler: ClawHub üzerinde yayımlayın, ardından yükleyin:- npm
- Yalnızca ClawHub
- npm paket belirtimi
npm kaynaklı kurulumlarda,
openclaw plugins install paketi yaşam döngüsü betikleri devre dışı bırakılmış şekilde ~/.openclaw/npm altına kurar. Plugin bağımlılık ağaçlarını saf JS/TS olarak tutun ve postinstall derlemeleri gerektiren paketlerden kaçının.Gateway başlangıcı Plugin bağımlılıklarını kurmaz. npm/git/ClawHub kurulum akışları bağımlılık yakınsamasından sorumludur; yerel Plugin’lerin bağımlılıkları zaten kurulmuş olmalıdır.
İlgili
- Plugin oluşturma — adım adım başlangıç kılavuzu
- Plugin manifesti — tam manifest şeması başvurusu
- SDK giriş noktaları —
definePluginEntryvedefineChannelPluginEntry