Sağlayıcı Plugin’leri Oluşturma
Bu kılavuz, OpenClaw’a bir model sağlayıcı (LLM) ekleyen bir sağlayıcı plugin’ini adım adım oluşturmayı anlatır. Sonunda model kataloğu, API anahtarı kimlik doğrulaması ve dinamik model çözümlemesi olan bir sağlayıcınız olacak.Daha önce hiç OpenClaw plugin’i oluşturmadıysanız, önce temel paket
yapısı ve manifest kurulumu için Başlangıç belgesini okuyun.
Adım adım anlatım
Paket ve manifest
providerAuthEnvVars bildirir.
Bir sağlayıcı varyantı başka bir sağlayıcı kimliğinin kimlik doğrulamasını yeniden kullanacaksa providerAuthAliases ekleyin. modelSupport
isteğe bağlıdır ve çalışma zamanı kancaları henüz yokken OpenClaw’ın
acme-large gibi kısa model kimliklerinden sağlayıcı plugin’inizi otomatik yüklemesini sağlar. Sağlayıcıyı
ClawHub üzerinde yayımlarsanız package.json içindeki bu openclaw.compat ve openclaw.build
alanları zorunludur.Sağlayıcıyı kaydedin
En küçük bir sağlayıcı için Bu, çalışan bir sağlayıcıdır. Kullanıcılar artık
id, label, auth ve catalog gerekir:index.ts
openclaw onboard --acme-ai-api-key <key> komutunu çalıştırabilir ve
model olarak acme-ai/acme-large seçebilir.Üst akış sağlayıcısı OpenClaw’dan farklı kontrol belirteçleri kullanıyorsa, akış yolunu değiştirmek yerine
küçük bir çift yönlü metin dönüşümü ekleyin:input, taşımadan önce son sistem prompt’unu ve metin mesaj içeriğini yeniden yazar. output,
OpenClaw kendi kontrol işaretleyicilerini veya kanal teslimini ayrıştırmadan önce
assistant metin delta’larını ve son metni yeniden yazar.Yalnızca API anahtarı
kimlik doğrulamasına sahip tek bir metin sağlayıcısı ve katalog destekli tek bir çalışma zamanı kaydeden paketlenmiş sağlayıcılar için,
daha dar olan
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 çevrim dışı 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ş env ve agent/çalışma alanı yolları olmadan çalıştırır.Kimlik doğrulama akışınız onboarding sırasında ayrıca models.providers.*,
takma adlar ve agent varsayılan modelini yamalamayı gerektiriyorsa,
openclaw/plugin-sdk/provider-onboard içindeki hazır yardımcıları kullanın. En dar yardımcılar
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...) ve
createModelCatalogPresetAppliers(...) öğeleridir.Bir sağlayıcının yerel uç noktası normal
openai-completions taşıması üzerinde akışlı kullanım bloklarını destekliyorsa, sağlayıcı kimliği kontrollerini sabit kodlamak yerine
openclaw/plugin-sdk/provider-catalog-shared içindeki paylaşılan katalog yardımcılarını tercih edin.
supportsNativeStreamingUsageCompat(...) ve
applyProviderNativeStreamingUsageCompat(...), desteği
uç nokta yetenek eşleminden algılar; böylece yerel Moonshot/DashScope tarzı uç noktalar bir plugin özel bir sağlayıcı kimliği kullanıyor olsa bile
yine de katılabilir.Dinamik model çözümlemesi ekleyin
Sağlayıcınız rastgele model kimliklerini kabul ediyorsa (proxy veya router gibi),
Çözümleme ağ çağrısı gerektiriyorsa eşzamansız
ısınma için
resolveDynamicModel ekleyin:prepareDynamicModel kullanın — tamamlandıktan sonra resolveDynamicModel yeniden çalışır.Çalışma zamanı kancaları ekleyin (gerektiğinde)
Çoğu sağlayıcı için yalnızca Günümüzde kullanılabilen replay aileleri:
Gerçek paketlenmiş örnekler:
Gerçek paketlenmiş örnekler:
catalog + resolveDynamicModel gerekir. Kancaları,
sağlayıcınız gerektirdikçe aşamalı olarak ekleyin.Paylaşılan yardımcı oluşturucular artık en yaygın replay/tool-compat
ailelerini kapsar; bu yüzden plugin’lerin genelde her kancayı tek tek elle bağlamasına gerek kalmaz:| Aile | Bağladığı şey |
|---|---|
openai-compatible | OpenAI uyumlu taşıma katmanları için paylaşılan OpenAI tarzı replay ilkesi; buna araç çağrısı kimliği temizleme, assistant-first sıralama düzeltmeleri ve taşıma katmanının ihtiyaç duyduğu durumlarda genel Gemini-turn doğrulaması dahildir |
anthropic-by-model | modelId ile seçilen Claude farkında replay ilkesi; böylece Anthropic-message taşıma katmanları Claude’a özgü düşünme bloğu temizliğini yalnızca çözümlenen model gerçekten bir Claude kimliği olduğunda alır |
google-gemini | Yerel Gemini replay ilkesi ile bootstrap replay temizleme ve etiketli reasoning-output modu |
passthrough-gemini | OpenAI uyumlu proxy taşıma katmanları üzerinden çalışan Gemini modelleri için Gemini thought-signature temizleme; yerel Gemini replay doğrulamasını veya bootstrap yeniden yazımlarını etkinleştirmez |
hybrid-anthropic-openai | Tek plugin içinde Anthropic-message ve OpenAI uyumlu model yüzeylerini karıştıran sağlayıcılar için hibrit ilke; isteğe bağlı yalnızca Claude düşünme bloğu bırakma davranışı Anthropic tarafında kapsamlı kalır |
googlevegoogle-gemini-cli:google-geminiopenrouter,kilocode,opencodeveopencode-go:passthrough-geminiamazon-bedrockveanthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot,ollama,xaivezai:openai-compatible
| Aile | Bağladığı şey |
|---|---|
google-thinking | Paylaşılan akış yolunda Gemini düşünme payload normalizasyonu |
kilocode-thinking | Paylaşılan proxy akış yolunda Kilo reasoning sarmalayıcısı; kilo/auto ve desteklenmeyen proxy reasoning kimlikleri eklenmiş düşünmeyi atlar |
moonshot-thinking | Yapılandırma + /think düzeyinden Moonshot ikili yerel düşünme payload eşlemesi |
minimax-fast-mode | Paylaşılan akış yolunda MiniMax fast-mode model yeniden yazımı |
openai-responses-defaults | Paylaşılan yerel OpenAI/Codex Responses sarmalayıcıları: attribution header’ları, /fast/serviceTier, metin ayrıntı düzeyi, yerel Codex web search, reasoning-compat payload biçimlendirmesi ve Responses bağlam yönetimi |
openrouter-thinking | Proxy rotaları için OpenRouter reasoning sarmalayıcısı; desteklenmeyen model/auto atlamaları merkezi olarak işlenir |
tool-stream-default-on | Z.AI gibi açıkça devre dışı bırakılmadıkça araç akışı isteyen sağlayıcılar için varsayılan açık tool_stream sarmalayıcısı |
googlevegoogle-gemini-cli:google-thinkingkilocode:kilocode-thinkingmoonshot:moonshot-thinkingminimaxveminimax-portal:minimax-fast-modeopenaiveopenai-codex:openai-responses-defaultsopenrouter:openrouter-thinkingzai:tool-stream-default-on
openclaw/plugin-sdk/provider-model-shared, replay-family
enum’unu ve bu ailelerin oluşturulduğu paylaşılan yardımcıları da dışa aktarır. Yaygın herkese açık
dışa aktarımlar şunları içerir:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...)vebuildHybridAnthropicOrOpenAIReplayPolicy(...)gibi paylaşılan replay oluşturucularısanitizeGoogleGeminiReplayHistory(...)veresolveTaggedReasoningOutputMode()gibi Gemini replay yardımcılarıresolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...)venormalizeNativeXaiModelId(...)gibi uç nokta/model yardımcıları
openclaw/plugin-sdk/provider-stream, hem aile oluşturucuyu hem de
bu ailelerin yeniden kullandığı herkese açık sarmalayıcı yardımcılarını açığa çıkarır. Yaygın herkese açık dışa aktarımlar
şunları içerir:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)createOpenAIAttributionHeadersWrapper(...),createOpenAIFastModeWrapper(...),createOpenAIServiceTierWrapper(...),createOpenAIResponsesContextManagementWrapper(...)vecreateCodexNativeWebSearchWrapper(...)gibi paylaşılan OpenAI/Codex sarmalayıcılarıcreateOpenRouterWrapper(...),createToolStreamWrapper(...)vecreateMinimaxFastModeWrapper(...)gibi paylaşılan proxy/sağlayıcı sarmalayıcıları
@openclaw/anthropic-provider,
herkese açık api.ts /
contract-api.ts seam’i üzerinden wrapAnthropicProviderStream, resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier ve
daha alt seviye Anthropic sarmalayıcı oluşturucularını dışa aktarır. Bu yardımcılar
Anthropic’e özgü kalır; çünkü aynı zamanda Claude OAuth beta işleme ve
context1m geçitlemesini de kodlarlar.Diğer paketlenmiş sağlayıcılar da davranış aileler arasında temiz biçimde paylaşılmadığında
taşıma katmanına özgü sarmalayıcıları yerelde tutar. Güncel örnek: paketlenmiş xAI plugin’i,
wrapStreamFn içinde yerel xAI Responses biçimlendirmesini kendi içinde tutar; buna
/fast takma ad yeniden yazımları, varsayılan tool_stream,
desteklenmeyen strict-tool temizliği ve xAI’ye özgü reasoning-payload
kaldırımı dahildir.openclaw/plugin-sdk/provider-tools, şu anda bir paylaşılan
tool-schema ailesini ve paylaşılan şema/uyumluluk yardımcılarını açığa çıkarır:ProviderToolCompatFamily, bugün paylaşılan aile envanterini belgelendirir.buildProviderToolCompatFamilyHooks("gemini"), Gemini-safe araç şemalarına ihtiyaç duyan sağlayıcılar için Gemini şema temizliği + tanılamayı bağlar.normalizeGeminiToolSchemas(...)veinspectGeminiToolSchemas(...), alttaki herkese açık Gemini şema yardımcılarıdır.resolveXaiModelCompatPatch(), paketlenmiş xAI uyumluluk yamasını döndürür:toolSchemaProfile: "xai", desteklenmeyen şema anahtar sözcükleri, yerelweb_searchdesteği ve HTML entity araç çağrısı argüman çözümleme.applyXaiModelCompat(model), aynı xAI uyumluluk yamasını çözümlenmiş bir modele runner’a ulaşmadan önce uygular.
normalizeResolvedModel ile birlikte
contributeResolvedModelCompat kullanır.Aynı paket kökü deseni diğer paketlenmiş sağlayıcıları da destekler:@openclaw/openai-provider:api.ts, sağlayıcı oluşturucuları, varsayılan model yardımcılarını ve gerçek zamanlı sağlayıcı oluşturucularını dışa aktarır@openclaw/openrouter-provider:api.ts, sağlayıcı oluşturucuyu ve onboarding/yapılandırma yardımcılarını dışa aktarır
- Belirteç değişimi
- Özel header'lar
- Yerel taşıma kimliği
- Kullanım ve faturalama
Her çıkarım çağrısından önce belirteç değişimi gerektiren sağlayıcılar için:
Kullanılabilen tüm sağlayıcı kancaları
Kullanılabilen tüm sağlayıcı kancaları
OpenClaw kancaları şu sırayla çağırır. Çoğu sağlayıcı yalnızca 2-3 tanesini kullanır:
Çalışma zamanı geri dönüş notları:
| # | Kanca | Ne zaman kullanılır |
|---|---|---|
| 1 | catalog | Model kataloğu veya base URL varsayılanları |
| 2 | applyConfigDefaults | Yapılandırma somutlaştırması sırasında sağlayıcıya ait genel varsayılanlar |
| 3 | normalizeModelId | Aramadan önce eski/preview model kimliği takma adı temizliği |
| 4 | normalizeTransport | Genel model oluşturmasından önce sağlayıcı ailesi api / baseUrl temizliği |
| 5 | normalizeConfig | models.providers.<id> yapılandırmasını normalize et |
| 6 | applyNativeStreamingUsageCompat | Yapılandırma sağlayıcıları için yerel streaming-usage uyumluluk yeniden yazımları |
| 7 | resolveConfigApiKey | Sağlayıcıya ait env-marker kimlik doğrulama çözümlemesi |
| 8 | resolveSyntheticAuth | Yerel/self-hosted veya yapılandırma destekli sentetik kimlik doğrulama |
| 9 | shouldDeferSyntheticProfileAuth | Sentetik saklanmış profil yer tutucularını env/yapılandırma kimlik doğrulamasının arkasına al |
| 10 | resolveDynamicModel | Rastgele üst akış model kimliklerini kabul et |
| 11 | prepareDynamicModel | Çözümlemeden önce eşzamansız meta veri getirme |
| 12 | normalizeResolvedModel | Runner’dan önce taşıma yeniden yazımları |
-
normalizeConfig, önce eşleşen sağlayıcıyı, sonra diğer kanca yetenekli sağlayıcı plugin’lerini, gerçekten yapılandırmayı değiştirene kadar kontrol eder. Hiçbir sağlayıcı kancası desteklenen bir Google ailesi yapılandırma girdisini yeniden yazmazsa, paketlenmiş Google yapılandırma normalizer’ı yine de uygulanır. -
resolveConfigApiKey, açığa çıkarılmışsa sağlayıcı kancasını kullanır. Paketlenmişamazon-bedrockyolu ayrıca burada yerleşik bir AWS env-marker çözümleyicisine sahiptir; Bedrock çalışma zamanı kimlik doğrulaması yine de AWS SDK varsayılan zincirini kullanıyor olsa da. | 13 |contributeResolvedModelCompat| Başka bir uyumlu taşıma katmanı arkasındaki vendor modelleri için uyumluluk bayrakları | | 14 |capabilities| Eski statik yetenek torbası; yalnızca uyumluluk | | 15 |normalizeToolSchemas| Kayıttan önce sağlayıcıya ait tool-schema temizliği | | 16 |inspectToolSchemas| Sağlayıcıya ait tool-schema tanılaması | | 17 |resolveReasoningOutputMode| Etiketli ile yerel reasoning-output sözleşmesi | | 18 |prepareExtraParams| Varsayılan istek parametreleri | | 19 |createStreamFn| Tamamen özel StreamFn taşıma katmanı | | 20 |wrapStreamFn| Normal akış yolunda özel header/gövde sarmalayıcıları | | 21 |resolveTransportTurnState| Yerel tur başına header’lar/meta veriler | | 22 |resolveWebSocketSessionPolicy| Yerel WS oturum header’ları/bekleme süresi | | 23 |formatApiKey| Özel çalışma zamanı belirteç biçimi | | 24 |refreshOAuth| Özel OAuth yenileme | | 25 |buildAuthDoctorHint| Kimlik doğrulama onarım yönlendirmesi | | 26 |matchesContextOverflowError| Sağlayıcıya ait taşma algılama | | 27 |classifyFailoverReason| Sağlayıcıya ait hız sınırı/aşırı yük sınıflandırması | | 28 |isCacheTtlEligible| Prompt önbelleği TTL geçitlemesi | | 29 |buildMissingAuthMessage| Özel eksik kimlik doğrulama ipucu | | 30 |suppressBuiltInModel| Eski üst akış satırlarını gizle | | 31 |augmentModelCatalog| Sentetik ileri uyumluluk satırları | | 32 |resolveThinkingProfile| Modele özgü/thinkseçenek kümesi | | 33 |isBinaryThinking| İkili düşünme açık/kapalı uyumluluğu | | 34 |supportsXHighThinking|xhighreasoning desteği uyumluluğu | | 35 |resolveDefaultThinkingLevel| Varsayılan/thinkilkesi uyumluluğu | | 36 |isModernModelRef| Canlı/smoke model eşleştirme | | 37 |prepareRuntimeAuth| Çıkarımdan önce belirteç değişimi | | 38 |resolveUsageAuth| Özel kullanım kimlik bilgisi ayrıştırması | | 39 |fetchUsageSnapshot| Özel kullanım uç noktası | | 40 |createEmbeddingProvider| Bellek/arama için sağlayıcıya ait embedding bağdaştırıcısı | | 41 |buildReplayPolicy| Özel transcript replay/Compaction ilkesi | | 42 |sanitizeReplayHistory| Genel temizlemeden sonra sağlayıcıya özgü replay yeniden yazımları | | 43 |validateReplayTurns| Gömülü runner’dan önce strict replay-turn doğrulaması | | 44 |onModelSelected| Seçim sonrası geri çağırım (ör. telemetri) | Prompt ayarlama notu:resolveSystemPromptContribution, bir sağlayıcının bir model ailesi için önbellek farkında sistem prompt yönlendirmesi eklemesine izin verir. Davranış tek bir sağlayıcı/model ailesine aitse ve kararlı/dinamik önbellek ayrımını koruması gerekiyorsabefore_prompt_buildyerine bunu tercih edin.
Ek yetenekler ekleyin (isteğe bağlı)
Bir sağlayıcı plugin’i, metin çıkarımının yanında konuşma, gerçek zamanlı transkripsiyon, gerçek zamanlı
ses, medya anlama, görsel oluşturma, video oluşturma, web getirme
ve web arama kaydedebilir:OpenClaw bunu bir hybrid-capability plugin’i olarak sınıflandırır. Bu,
şirket plugin’leri için önerilen desendir (satıcı başına bir plugin). Bkz.
İç Yapılar: Yetenek Sahipliği.Video oluşturma için yukarıda gösterilen kip farkında yetenek biçimini tercih edin:
generate, imageToVideo ve videoToVideo. maxInputImages, maxInputVideos ve maxDurationSeconds gibi
düz toplu alanlar,
dönüştürme kipi desteğini veya devre dışı kipleri temiz biçimde duyurmak için
yeterli değildir.Müzik oluşturma sağlayıcıları da aynı deseni izlemelidir:
yalnızca prompt ile oluşturma için generate ve başvuru görseli tabanlı
oluşturma için edit. maxInputImages,
supportsLyrics ve supportsFormat gibi düz toplu alanlar düzenleme
desteğini duyurmak için yeterli değildir; açık generate / edit blokları
beklenen sözleşmedir.ClawHub’a yayımlama
Sağlayıcı plugin’leri, diğer tüm harici kod plugin’leriyle aynı şekilde yayımlanır:clawhub package publish kullanmalıdır.
Dosya yapısı
Katalog sırası başvurusu
catalog.order, kataloğunuzun yerleşik
sağlayıcılara göre ne zaman birleştirileceğini denetler:
| Sıra | Ne zaman | Kullanım durumu |
|---|---|---|
simple | İlk geçiş | Düz API anahtarlı sağlayıcılar |
profile | simple sonrası | Kimlik doğrulama profilleriyle geçitlenen sağlayıcılar |
paired | profile sonrası | Birden çok ilişkili girdiyi sentezleme |
late | Son geçiş | Mevcut sağlayıcıları geçersiz kılma (çakışmada kazanır) |
Sonraki adımlar
- Kanal Plugin’leri — plugin’iniz ayrıca bir kanal da sağlıyorsa
- SDK Runtime —
api.runtimeyardımcıları (TTS, arama, alt agent) - SDK Genel Bakışı — tam alt yol içe aktarma başvurusu
- Plugin İç Yapıları — kanca ayrıntıları ve paketlenmiş örnekler