Skip to main content
OpenClaw’a bir model sağlayıcısı (LLM) eklemek için sağlayıcı Plugin’i oluşturun: model kataloğu, API anahtarıyla kimlik doğrulama ve dinamik model çözümleme.
OpenClaw Plugin’lerinde yeni misiniz? Paket yapısı ve manifest kurulumu için önce Başlarken bölümünü okuyun.
Sağlayıcı Plugin’leri, OpenClaw’ın normal çıkarım döngüsüne modeller ekler. Modelin iş parçacıklarını, Compaction’ı veya araç olaylarını yöneten yerel bir ajan daemon’ı üzerinden çalışması gerekiyorsa daemon protokolü ayrıntılarını çekirdeğe koymak yerine sağlayıcıyı bir ajan çalışma düzeneği ile eşleştirin.

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 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
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 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), resolveDynamicModel ekleyin:
Çözümleme bir ağ çağrısı gerektiriyorsa eşzamansız ısınma için 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 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 yeniden oynatma aileleri:Günümüzde kullanılabilen akış aileleri:
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(...) ve setQwenChatTemplateThinking(...) 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ı.
Gemini ailesi sağlayıcılarında akıl yürütme çıktısı modunu aktarımla uyumlu tutun. Doğrudan Google Gemini API sağlayıcıları, OpenClaw’ın <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.
Her çıkarım çağrısından önce token değişimi gerektiren sağlayıcılar için:
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-antigravity yapılandırma girdilerini normalleştiren, Google’ın kendi normalizeConfig kancası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ı ise auth: "aws-sdk" ile yapılandırıldığında AWS SDK varsayılan zincirini kullanmaya devam eder.
  • resolveThinkingProfile(ctx); seçilen provider, modelId, isteğe bağlı birleştirilmiş reasoning katalog ipucu ve isteğe bağlı birleştirilmiş model compat olguları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 genelindeki before_prompt_build kancası 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, mevcut api.registerProvider(...) çağrınızın yanında register(api) içinde kaydedin. Yalnızca ihtiyaç duyduğunuz sekmeleri seçin:
Sağlayıcı HTTP hataları için 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

İlgili