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:
- Channel plugin
- Provider plugin / ClawHub baseline
Plugin’i ClawHub üzerinde harici olarak yayımlarsanız, bu
compat ve build alanları zorunludur. Kanonik 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 için 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 verileridir.
| Alan | Tür | Anlamı |
|---|---|---|
id | string | Kanonik 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 etiketi geçersiz kılar. |
blurb | string | Kısa ilk katılı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örüntüsü adı. |
selectionDocsPrefix | string | Seçim yüzeylerinde dokümantasyon bağlantılarından önceki önek metni. |
selectionDocsOmitLabel | boolean | Seçim kopyasında etiketli dokümantasyon bağlantısı yerine dokümantasyon yolunu doğrudan göster. |
selectionExtras | string[] | Seçim kopyasına eklenen ek kısa dizeler. |
markdownCapable | boolean | Giden biçimlendirme kararları için kanalı markdown yetenekli olarak işaretler. |
exposure | object | Kurulum, yapılandırılmış listeler ve dokümantasyon yüzeyleri için kanal görünürlük denetimleri. |
quickstartAllowFrom | boolean | Bu kanalı standart hızlı başlangıç allowFrom kurulum akışına dahil eder. |
forceAccountBinding | boolean | Yalnızca bir hesap mevcut 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 verileridir, manifest meta verisi değildir.
| Alan | Tür | Anlamı |
|---|---|---|
clawhubSpec | string | Kurulum/güncelleme ve ilk katılımda isteğe bağlı kurulum akışları için kanonik ClawHub belirtimi. |
npmSpec | string | Kurulum/güncelleme yedek akışları için kanonik npm belirtimi. |
localPath | string | Yerel geliştirme veya paketlenmiş kurulum yolu. |
defaultChoice | "clawhub" | "npm" | "local" | Birden fazla kaynak kullanılabilir olduğunda tercih edilen kurulum kaynağı. |
minHostVersion | string | >=x.y.z veya >=x.y.z-prerelease biçiminde desteklenen minimum OpenClaw sürümü. |
expectedIntegrity | string | Sabitlenmiş kurulumlar için genellikle sha512-... olan beklenen npm dist bütünlük dizesi. |
allowInvalidConfigRecovery | boolean | Paketlenmiş-Plugin yeniden kurulum akışlarının belirli eski-yapılandırma hatalarından kurtulmasını sağlar. |
requiredPlatformPackages | string[] | npm kurulumu sırasında doğrulanan, gerekli platforma özgü npm takma adları. |
Onboarding behavior
Onboarding behavior
Etkileşimli ilk katılım, isteğe bağlı kurulum yüzeyleri için
openclaw.install öğesini de 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 katılım bu seçeneği gösterebilir, ClawHub, npm veya yerel kurulum için sorabilir, Plugin’i kurabilir veya etkinleştirebilir ve ardından seçilen akışa devam edebilir. ClawHub ilk katılım seçenekleri clawhubSpec kullanır ve mevcut olduğunda tercih edilir; npm seçenekleri, kayıt defteri npmSpec ile 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 enforcement
minHostVersion enforcement
minHostVersion ayarlanmışsa, hem kurulum hem de paketlenmemiş manifest-kayıt defteri yüklemesi bunu zorunlu kılar. Daha eski host’lar harici Plugin’leri atlar; geçersiz sürüm dizeleri reddedilir. Paketlenmiş kaynak Plugin’lerin host checkout’u ile aynı sürümde olduğu varsayılır.Pinned npm installs
Pinned npm installs
Sabitlenmiş npm kurulumları için kesin sürümü
npmSpec içinde tutun ve beklenen artefakt bütünlüğünü ekleyin:allowInvalidConfigRecovery scope
allowInvalidConfigRecovery scope
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ı şekilde 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ülür.
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 skill yayımlama takma adı Skills içindir. Plugin paketleri her zaman
clawhub package publish kullanmalıdır.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.
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.
OpenClaw setupEntry öğesini tam girdi yerine ne zaman kullanır
OpenClaw setupEntry öğesini tam girdi yerine ne zaman kullanır
- Kanal devre dışıdır ancak kurulum/onboarding yüzeylerine ihtiyaç duyar.
- Kanal etkindir ancak yapılandırılmamıştır.
- Ertelenmiş yükleme etkindir (
deferConfiguredChannelFullLoadUntilAfterListen).
setupEntry ne kaydetmelidir
setupEntry ne kaydetmelidir
- Kanal Plugin nesnesi (
defineSetupPluginEntryaracılığıyla). - Gateway dinlemeye başlamadan önce gerekli olan HTTP rotaları.
- Başlatma sırasında gereken 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 hizmetleri.
- Ağır çalışma zamanı içe aktarımları (kripto, SDK’ler).
- Yalnızca başlatmadan sonra gereken Gateway yöntemleri.
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:
| İçe aktarma yolu | Ne için kullanılır | Ana dışa aktarımlar |
|---|---|---|
plugin-sdk/setup-runtime | setupEntry / ertelenmiş kanal başlatmasında kullanılabilir kalan kurulum zamanı çalışma zamanı yardımcıları | createSetupTranslator, 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üman yardımcıları | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
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’denchannels.<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 anahtarlarnamedAccountPromotionKeys: 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ırresolveSingleAccountPromotionTarget(...): yükseltilmiş 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.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:api.pluginConfig olarak alır.
Kanala özgü config için bunun yerine kanal config bölümünü kullanın:
Kanal config şemaları oluşturma
Bir Zod şemasını Plugin’e ait config artifact’leri 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 config ş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 üzerindeki 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 (örneğin Discord Plugin’i src/channel.setup.ts) bakın.
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 etiketler, puanlar 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 yazmak yerine openclaw/plugin-sdk/setup içindeki createStandardChannelSetupStatus(...) öğesini 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 öğesini kullanın:plugin-sdk/channel-setup ayrıca isteğe bağlı kurulum yüzeyinin yalnızca bir yarısına ihtiyaç duyduğunuzda daha düşük seviyeli createOptionalChannelSetupAdapter(...) ve createOptionalChannelSetupWizard(...) oluşturucularını da sunar.Oluşturulan isteğe bağlı bağdaştırıcı/sihirbaz gerçek config yazımlarında kapalı olarak 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üman 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/durum bağlantı kodunu her kanala kopyalamak yerine paylaşılan temsilci yardımcılarını 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 girişleri için
createCliPathTextInput(...) setupEntrydaha ağır tam sihirbaza tembel şekilde yönlendirme yapması gerektiğindecreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)vecreateDelegatedResolveConfigured(...)setupEntryyalnızca birtextInputs[*].shouldPromptkararını devretmesi gerektiğindecreateDelegatedTextInputShouldPrompt(...)
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ı yüklemelerde,
openclaw plugins install paketi ~/.openclaw/npm/projects altında Plugin başına ayrı bir projeye, yaşam döngüsü betikleri devre dışı bırakılmış şekilde yükler. Plugin bağımlılık ağaçlarını saf JS/TS tutun ve postinstall derlemeleri gerektiren paketlerden kaçının.Gateway başlangıcı Plugin bağımlılıklarını yüklemez. Bağımlılık yakınsamasından npm/git/ClawHub yükleme akışları sorumludur; yerel Plugin’lerin bağımlılıkları önceden yüklenmiş 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