OpenClaw Plugin’lerinde yeni misiniz? Paket yapısı ve manifest kurulumu için
önce Başlarken bölümünü okuyun.
Adım adım açıklama
1
Paket ve manifest
1. Adım: Paket ve manifest
setup.providers[].envVars, OpenClaw’ın Plugin çalışma zamanınızı yüklemeden
kimlik bilgilerini algılamasını sağlar. Bir sağlayıcı varyantının başka bir
sağlayıcı kimliğinin kimlik doğrulamasını yeniden kullanması gerektiğinde
providerAuthAliases ekleyin. modelSupport isteğe bağlıdır ve çalışma
zamanı kancaları mevcut olmadan önce OpenClaw’ın sağlayıcı Plugin’inizi
acme-large gibi kısaltılmış model kimliklerinden otomatik olarak
yüklemesini sağlar. package.json içindeki openclaw.compat
ve openclaw.build, ClawHub’da yayımlama için gereklidir
(openclaw.compat.pluginApi ve openclaw.build.openclawVersion gerekli iki alandır;
minGatewayVersion belirtilmediğinde openclaw.install.minHostVersion değerine geri döner).2
Sağlayıcıyı kaydetme
Asgari bir metin sağlayıcısı için Sağlayıcı API’si daha zengin meta veriler döndürdüğünde ve Plugin’in
satırları bizzat OpenClaw model tanımlarına dönüştürmesi gerektiğinde
id, label, auth ve catalog gerekir.
catalog, sağlayıcının sahip olduğu çalışma zamanı/yapılandırma kancasıdır;
canlı satıcı API’lerini çağırabilir ve models.providers girdileri döndürür.index.ts
registerModelCatalogProvider; text, voice,
image_generation, video_generation ve music_generation satırlarını
kapsayan liste/yardım/seçici kullanıcı arayüzü için daha yeni denetim düzlemi
katalog yüzeyidir. Satıcı uç noktası çağrılarını ve yanıt eşlemesini Plugin’de
tutun; paylaşılan satır şekli, kaynak etiketleri ve yardım oluşturma OpenClaw’a aittir.Bu, çalışan bir sağlayıcıdır. Kullanıcılar artık openclaw onboard --acme-ai-api-key <key>
komutunu çalıştırabilir ve model olarak acme-ai/acme-large seçebilir.Canlı model keşfi
Sağlayıcınız OpenAI uyumlu bir/models API’si sunuyorsa tek
sağlayıcılı yardımcıyı paylaşılan keşfe dahil edin:liveModelDiscovery: true, aşağıdaki davranışlara sahip genel bir Plugin SDK sözleşmesidir:Bearer kullanmayan veya standart dışı bir liste uç noktası için
true yerine seçenekleri iletin:endpointUrl değerini koşulsuz bir alternatif ana makine olarak kullanmayın.
Bunun requireBaseUrl denetimi, model listesi ana makinesi çıkarım ana makinesinden
farklı olan sağlayıcılar için kimlik bilgisi yalıtım sınırıdır.Sağlayıcı, ihtiyatlı OpenAI uyumlu yansıtma yerine özel model semantiğine
ihtiyaç duyuyorsa bu yansıtmayı Plugin’de tutun ve paylaşılan getirme yaşam
döngüsü için openclaw/plugin-sdk/provider-catalog-live-runtime kullanın. Yardımcı; sağlayıcı politikasını
OpenClaw çekirdeğine koymadan korumalı HTTP getirmeleri, sağlayıcı kimlik doğrulama
üst bilgileri, yapılandırılmış HTTP hataları, TTL önbelleğe alma ve statik geri
dönüş davranışı sağlar.Canlı API yalnızca sağlayıcının sahip olduğu statik katalog satırlarından
hangilerinin o anda kullanılabilir olduğunu bildiriyorsa buildLiveModelProviderConfig kullanın:index.ts
getCachedLiveProviderModelRows kullanın:index.ts
run kimlik doğrulama korumalı kalmalı ve kullanılabilir kimlik bilgisi
olmadığında null döndürmelidir. Kurulum, belgeler,
testler ve seçici yüzeylerinin canlı ağ erişimine bağlı olmaması için çevrimdışı bir
staticRun veya statik geri dönüş bulundurun. Model listesi güncelliğine
uygun bir TTL kullanın, istek sırasında dosya sistemi yoklamasından kaçının
ve yalnızca üst sistem yanıtı OpenAI uyumlu bir { data: [{ id, object }] }
biçiminde değilse sağlayıcıya özgü bir readRows / readModelId iletin.Üst sistem sağlayıcısı OpenClaw’dan farklı kontrol belirteçleri kullanıyorsa akış
yolunu değiştirmek yerine küçük, çift yönlü bir metin dönüşümü ekleyin:input, aktarımdan önce son sistem istemini ve metin mesajı içeriğini
yeniden yazar. output, OpenClaw kendi kontrol işaretleyicilerini ayrıştırmadan
veya kanal teslimatı gerçekleşmeden önce asistan metin deltalarını ve son metni yeniden yazar.Yalnızca API anahtarıyla kimlik doğrulanan tek bir metin sağlayıcısını ve
katalog destekli tek bir çalışma zamanını kaydeden paketlenmiş sağlayıcılar için
daha dar kapsamlı defineSingleProviderPluginEntry(...) yardımcısını tercih edin:buildProvider, OpenClaw gerçek sağlayıcı kimlik doğrulamasını çözümleyebildiğinde
kullanılan canlı katalog yoludur. Sağlayıcıya özgü keşif yapabilir. Kimlik
doğrulama yapılandırılmadan önce gösterilmesi güvenli olan çevrimdışı satırlar için
yalnızca buildStaticProvider kullanın; kimlik bilgisi gerektirmemeli veya ağ isteği
yapmamalıdır. OpenClaw’ın models list --all görünümü şu anda statik katalogları
yalnızca paketlenmiş sağlayıcı Plugin’leri için; boş yapılandırma, boş ortam ve
hiçbir ajan/çalışma alanı yolu olmadan çalıştırır.Kimlik doğrulama akışınızın ilk katılım sırasında ayrıca models.providers.*, takma
adları ve ajanın varsayılan modelini yamaması gerekiyorsa openclaw/plugin-sdk/provider-onboard
içindeki hazır ayar yardımcılarını kullanın. En dar kapsamlı yardımcılar
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...) ve
createModelCatalogPresetAppliers(...) şeklindedir.Bir sağlayıcının yerel uç noktası normal openai-completions aktarımında akışlı
kullanım bloklarını desteklediğinde sağlayıcı kimliği denetimlerini sabit kodlamak
yerine openclaw/plugin-sdk/provider-catalog-shared içindeki ortak katalog yardımcılarını tercih edin.
supportsNativeStreamingUsageCompat(...) ve applyProviderNativeStreamingUsageCompat(...), desteği uç nokta yetenek haritasından
algılar; böylece yerel Moonshot/DashScope tarzı uç noktalar, bir Plugin özel
sağlayıcı kimliği kullandığında bile özelliği etkinleştirebilir.Yukarıdaki canlı keşif örnekleri /models tarzı sağlayıcı API’lerini kapsar.
Bu keşfi kullanılabilir kimlik doğrulamayla korunan catalog.run içinde tutun
ve çevrimdışı katalog üretimi için staticRun öğesini ağdan bağımsız tutun.3
Dinamik model çözümleme ekleyin
Sağlayıcınız rastgele model kimliklerini kabul ediyorsa (bir proxy veya yönlendirici
gibi), Çözümleme bir ağ çağrısı gerektiriyorsa eşzamansız ısınma için
resolveDynamicModel ekleyin:prepareDynamicModel
kullanın; tamamlandıktan sonra resolveDynamicModel yeniden çalışır.4
Çalışma zamanı kancaları ekleyin (gerektiğinde)
Çoğu sağlayıcı yalnızca Günümüzde kullanılabilen yeniden oynatma aileleri:
catalog + resolveDynamicModel gerektirir.
Sağlayıcınız ihtiyaç duydukça kancaları aşamalı olarak ekleyin.Ortak yardımcı oluşturucular artık en yaygın yeniden oynatma/araç uyumluluğu
ailelerini kapsadığından Plugin’lerin genellikle her kancayı tek tek elle
bağlaması gerekmez:Günümüzde kullanılabilen akış aileleri:
Aile oluşturucularını destekleyen SDK bağlantı noktaları
Aile oluşturucularını destekleyen SDK bağlantı noktaları
Her aile oluşturucusu, aynı paketten dışa aktarılan daha düşük düzeyli genel yardımcılarla oluşturulur; bir sağlayıcının ortak kalıbın dışına çıkması gerektiğinde bunları kullanabilirsiniz:
openclaw/plugin-sdk/provider-model-shared-ProviderReplayFamily,buildProviderReplayFamilyHooks(...)ve ham yeniden oynatma oluşturucuları (buildOpenAICompatibleReplayPolicy,buildAnthropicReplayPolicyForModel,buildGoogleGeminiReplayPolicy,buildHybridAnthropicOrOpenAIReplayPolicy). Ayrıca Gemini yeniden oynatma yardımcılarını (sanitizeGoogleGeminiReplayHistory,resolveTaggedReasoningOutputMode) ve uç nokta/model yardımcılarını (resolveProviderEndpoint,normalizeProviderId,normalizeGooglePreviewModelId) dışa aktarır.openclaw/plugin-sdk/provider-stream-ProviderStreamFamily,buildProviderStreamFamilyHooks(...),composeProviderStreamWrappers(...); ayrıca paylaşılan OpenAI/Codex sarmalayıcıları (createOpenAIAttributionHeadersWrapper,createOpenAIFastModeWrapper,createOpenAIServiceTierWrapper,createOpenAIResponsesContextManagementWrapper,createCodexNativeWebSearchWrapper), DeepSeek V4 OpenAI uyumlu sarmalayıcısı (createDeepSeekV4OpenAICompatibleThinkingWrapper), Anthropic Messages düşünme ön dolgu temizliği (createAnthropicThinkingPrefillPayloadWrapper), düz metin araç çağrısı uyumluluğu (createPlainTextToolCallCompatWrapper) ve paylaşılan proxy/sağlayıcı sarmalayıcıları (createOpenRouterWrapper,createToolStreamWrapper,createMinimaxFastModeWrapper).openclaw/plugin-sdk/provider-stream-shared-createOpenAICompatibleCompletionsThinkingOffWrapper,createPayloadPatchStreamWrapper,createPlainTextToolCallCompatWrapper,normalizeOpenAICompatibleReasoningPayload(...)vesetQwenChatTemplateThinking(...)dâhil olmak üzere yoğun kullanılan sağlayıcı yolları için hafif yük ve olay sarmalayıcıları.openclaw/plugin-sdk/provider-tools-ProviderToolCompatFamily,buildProviderToolCompatFamilyHooks("deepseek" | "gemini" | "openai")ve temel sağlayıcı şeması yardımcıları.
<think> / <final> istem yönergeleri eklemeden yerel düşünce parçalarını
tüketebilmesi için native akıl yürütme çıktısını kullanmalıdır. Son bir
JSON/metin yanıtını ayrıştıran, yalnızca metin kullanan Gemini CLI tarzı arka uçlar,
paylaşılan google-gemini etiketli sözleşmeyi kullanmaya devam edebilir.Bazı akış yardımcıları bilerek sağlayıcıya özgü tutulur. @openclaw/anthropic-provider; Claude OAuth beta işlemesini ve context1m geçitlemesini kodladıkları için wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier ve daha düşük düzeyli Anthropic sarmalayıcı oluşturucularını kendi genel api.ts / contract-api.ts bağlantı noktasında tutar. xAI plugini de benzer biçimde yerel xAI Responses biçimlendirmesini kendi wrapStreamFn öğesinde tutar (/fast diğer adları, varsayılan tool_stream, desteklenmeyen katı araç temizliği, xAI’ye özgü akıl yürütme yükü kaldırma).Aynı paket kökü kalıbı ayrıca @openclaw/openai-provider (sağlayıcı oluşturucuları, varsayılan model yardımcıları, gerçek zamanlı sağlayıcı oluşturucuları) ve @openclaw/openrouter-provider (sağlayıcı oluşturucusu ile ilk katılım/yapılandırma yardımcıları) öğelerini destekler.- Token değişimi
- Özel üstbilgiler
- Yerel aktarım kimliği
- Kullanım ve faturalandırma
Her çıkarım çağrısından önce token değişimi gerektiren sağlayıcılar için:
Yaygın sağlayıcı kancaları
Yaygın sağlayıcı kancaları
OpenClaw, model/sağlayıcı pluginleri için kancaları yaklaşık olarak bu sırayla çağırır.
Çoğu sağlayıcı yalnızca 2-3 tanesini kullanır. Bu,
ProviderPlugin
sözleşmesinin tamamı değildir; eksiksiz ve güncel kanca listesi ile geri dönüş
notları için İç Yapı: Sağlayıcı Çalışma Zamanı
Kancaları bölümüne bakın.
ProviderPlugin.capabilities ve suppressBuiltInModel gibi OpenClaw’ın artık
çağırmadığı, yalnızca uyumluluk amaçlı sağlayıcı alanları burada listelenmez.Çalışma zamanı geri dönüş notları:
normalizeConfig, sağlayıcı kimliği başına bir sahip Plugin’i çözümler (önce paketlenmiş sağlayıcılar, ardından eşleşen çalışma zamanı Plugin’i) ve yalnızca bu kancayı çağırır; diğer sağlayıcılar arasında tarama yapılmaz.google/google-vertex/google-antigravityyapılandırma girdilerini normalleştiren, Google’ın kendinormalizeConfigkancasıdır; bu, ayrı bir çekirdek geri dönüşü değildir.resolveConfigApiKey, kullanıma sunulduğunda sağlayıcı kancasını kullanır. Amazon Bedrock, AWS ortam işareti çözümlemesini kendi sağlayıcı Plugin’inde tutar; çalışma zamanı kimlik doğrulaması iseauth: "aws-sdk"ile yapılandırıldığında AWS SDK varsayılan zincirini kullanmaya devam eder.resolveThinkingProfile(ctx); seçilenprovider,modelId, isteğe bağlı birleştirilmişreasoningkatalog ipucu ve isteğe bağlı birleştirilmiş modelcompatolgularını alır.compatöğesini yalnızca sağlayıcının düşünme kullanıcı arayüzünü/profilini seçmek için kullanın.resolveSystemPromptContribution, bir sağlayıcının model ailesi için önbellek duyarlı sistem istemi yönlendirmesi eklemesini sağlar. Davranış tek bir sağlayıcı/model ailesine aitse ve kararlı/dinamik önbellek ayrımını koruması gerekiyorsa eski, Plugin genelindekibefore_prompt_buildkancası yerine bunu tercih edin.
5
Ek yetenekler ekleyin (isteğe bağlı)
5. Adım: Ek yetenekler ekleyin
Bir sağlayıcı Plugin’i, metin çıkarımının yanı sıra gömme, konuşma, gerçek zamanlı transkripsiyon, gerçek zamanlı ses, medya anlama, görüntü oluşturma, video oluşturma, web’den getirme ve web araması kaydedebilir. OpenClaw bunu, şirket Plugin’leri için önerilen kalıp olan (tedarikçi başına bir Plugin) karma yetenekli Plugin olarak sınıflandırır. Bkz. Dahili Yapı: Yetenek Sahipliği.Her yeteneği, mevcutapi.registerProvider(...) çağrınızın yanında register(api)
içinde kaydedin. Yalnızca ihtiyaç duyduğunuz sekmeleri seçin:- Konuşma (TTS)
- Gerçek zamanlı transkripsiyon
- Gerçek zamanlı ses
- Medya anlama
- Gömmeler
- Görüntü ve video oluşturma
- Web getirme ve arama
assertOkOrThrowProviderError(...) kullanın; böylece
Plugin’ler sınırlandırılmış hata gövdesi okumalarını, JSON hata ayrıştırmasını ve
istek kimliği son eklerini paylaşır.6
Test
Adım 6: Test
src/provider.test.ts
ClawHub’da yayımlama
Sağlayıcı pluginleri, diğer tüm harici kod pluginleriyle aynı şekilde yayımlanır:clawhub skill publish <path>, bir plugin paketini değil bir skill
klasörünü yayımlamak için kullanılan farklı bir komuttur; burada kullanmayın.
Dosya yapısı
Katalog sırası referansı
catalog.order, kataloğunuzun yerleşik sağlayıcılara göre ne zaman
birleştirileceğini denetler:
Sonraki adımlar
- Kanal Pluginleri - plugininiz aynı zamanda bir kanal sağlıyorsa
- SDK Çalışma Zamanı -
api.runtimeyardımcıları (TTS, arama, alt ajan) - SDK Genel Bakışı - tam alt yol içe aktarma referansı
- Plugin İç Yapısı - kanca ayrıntıları ve paketlenmiş örnekler