Building Provider Plugins
Bu rehber, OpenClaw’a bir model sağlayıcısı (LLM) ekleyen bir sağlayıcı plugin’i oluşturmayı adım adım açıklar. Rehberin sonunda model kataloğu, API anahtarı kimlik doğrulaması ve dinamik model çözümlemesi olan bir sağlayıcıya sahip olacaksınız.Daha önce hiç OpenClaw plugin’i oluşturmadıysanız, temel paket
yapısı ve manifest kurulumu için önce
Getting Started sayfasını okuyun.
Adım adım rehber
Paket ve manifest
providerAuthEnvVars değerini bildirir; böylece OpenClaw,
plugin çalışma zamanınızı yüklemeden kimlik bilgilerini algılayabilir. modelSupport
isteğe bağlıdır ve çalışma zamanı hook’ları mevcut olmadan önce OpenClaw’ın
acme-large gibi kısa model kimliklerinden sağlayıcı plugin’inizi otomatik yüklemesine izin verir.
Sağlayıcıyı ClawHub üzerinde yayımlıyorsanız,
bu openclaw.compat ve openclaw.build alanları
package.json içinde zorunludur.Sağlayıcıyı kaydedin
Minimal bir sağlayıcı için Bu, çalışan bir sağlayıcıdır. Kullanıcılar artık
Kimlik doğrulama akışınızın onboarding sırasında
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.Yalnızca API anahtarı kimlik doğrulaması ve tek bir katalog destekli çalışma zamanı
kaydeden paketlenmiş sağlayıcılar için daha dar kapsamlı
defineSingleProviderPluginEntry(...) yardımcısını tercih edin:models.providers.*,
takma adları ve agent varsayılan modelini de düzeltmesi gerekiyorsa,
openclaw/plugin-sdk/provider-onboard içindeki hazır yardımcıları kullanın.
En dar kapsamlı yardımcılar şunlardır:
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...) ve
createModelCatalogPresetAppliers(...).Bir sağlayıcının yerel uç noktası normal openai-completions aktarımı ü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 haritasından algılar; böylece eklenti özel bir sağlayıcı kimliği
kullandığında bile yerel Moonshot/DashScope tarzı uç noktalar katılım sağlayabilir.Dinamik model çözümlemesi ekleyin
Sağlayıcınız keyfi model kimliklerini kabul ediyorsa (proxy veya router gibi),
Çözümleme bir ağ çağrısı gerektiriyorsa, async ön ısınma için
resolveDynamicModel ekleyin:prepareDynamicModel kullanın — tamamlandıktan sonra resolveDynamicModel
yeniden çalışır.Çalışma zamanı hook'ları ekleyin (gerektiğinde)
Çoğu sağlayıcı yalnızca Günümüzde mevcut replay aileleri:
Gerçek paketlenmiş örnekler:
Gerçek paketlenmiş örnekler:
catalog + resolveDynamicModel gerektirir. Hook’ları
sağlayıcınızın ihtiyacına göre kademeli olarak ekleyin.Paylaşılan yardımcı oluşturucular artık en yaygın replay/tool-compat
ailelerini kapsıyor, bu nedenle plugin’lerin genellikle her hook’u tek tek
elle bağlaması gerekmez:| Aile | Bağladığı şey |
|---|---|
openai-compatible | OpenAI uyumlu aktarımlar için, tool-call-id temizleme, assistant-first sıralama düzeltmeleri ve aktarımın gerektirdiği durumlarda genel Gemini dönüş doğrulaması dahil paylaşılan OpenAI tarzı replay ilkesi |
anthropic-by-model | modelId ile seçilen Claude farkındalıklı replay ilkesi; böylece Anthropic-message aktarımları, yalnızca çözümlenen model gerçekten bir Claude kimliği olduğunda Claude’a özgü thinking-block temizliğini alır |
google-gemini | Yerel Gemini replay ilkesi ile bootstrap replay temizliği ve etiketli reasoning-output modu |
passthrough-gemini | OpenAI uyumlu proxy aktarımları üzerinden çalışan Gemini modelleri için Gemini thought-signature temizliği; yerel Gemini replay doğrulamasını veya bootstrap yeniden yazımlarını etkinleştirmez |
hybrid-anthropic-openai | Tek bir 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 thinking-block bırakma işlemi Anthropic tarafında sınırlı 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 yükü normalizasyonu |
kilocode-thinking | Paylaşılan proxy akış yolunda Kilo reasoning sarmalayıcısı; kilo/auto ve desteklenmeyen proxy reasoning kimlikleri eklenen düşünmeyi atlar |
moonshot-thinking | Yapılandırma + /think düzeyinden Moonshot ikili native-thinking yükü 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 üst bilgileri, /fast/serviceTier, metin ayrıntı düzeyi, yerel Codex web araması, reasoning-compat yük şekillendirme ve Responses bağlam yönetimi |
openrouter-thinking | Proxy yolları 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 tool streaming isteyen sağlayıcılar için varsayılan olarak 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 üzerine kurulduğu paylaşılan yardımcıları da dışa aktarır.
Yaygın genel dışa aktarmalar ş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şturucusunu
hem de bu ailelerin yeniden kullandığı genel sarmalayıcı yardımcıları açığa çıkarır.
Yaygın genel dışa aktarmalar ş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,
genel api.ts /
contract-api.ts ayrım yüzeyi üzerinden wrapAnthropicProviderStream,
resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier ve
daha düşük seviyeli Anthropic sarmalayıcı oluşturucularını dışa aktarır.
Bu yardımcılar Anthropic’e özgü kalır çünkü Claude OAuth beta işleme ve
context1m kapılama mantığını da içerir.Davranış aileler arasında temiz şekilde paylaşılmadığında diğer paketlenmiş
sağlayıcılar da aktarım odaklı sarmalayıcıları yerel tutar. Güncel örnek:
paketlenmiş xAI plugin’i yerel xAI Responses şekillendirmeyi kendi
wrapStreamFn 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ırma dahildir.openclaw/plugin-sdk/provider-tools şu anda bir paylaşılan
tool-schema ailesi ile paylaşılan schema/compat yardımcılarını açığa çıkarır:ProviderToolCompatFamily, bugün paylaşılan aile envanterini belgelendirir.buildProviderToolCompatFamilyHooks("gemini"), Gemini-güvenli araç şemalarına ihtiyaç duyan sağlayıcılar için Gemini şema temizliği + tanılamaları bağlar.normalizeGeminiToolSchemas(...)veinspectGeminiToolSchemas(...)temelindeki genel 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 varlık biçimindeki tool-call argümanlarının çözülmesi.applyXaiModelCompat(model), aynı xAI uyumluluk yamasını runner’a ulaşmadan önce çözümlenen modele uygular.
normalizeResolvedModel ile contributeResolvedModelCompat kullanır.Aynı paket kökü deseni diğer paketlenmiş sağlayıcıların da temelini oluşturur:@openclaw/openai-provider:api.ts, sağlayıcı oluşturucularını, 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şturucusunu ve onboarding/yapılandırma yardımcılarını dışa aktarır
- Token exchange
- Özel üst bilgiler
- 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:
Mevcut tüm sağlayıcı hook'ları
Mevcut tüm sağlayıcı hook'ları
OpenClaw hook’ları bu sırayla çağırır. Çoğu sağlayıcı yalnızca 2-3 tanesini kullanır:
Çalışma zamanı geri dönüş notları:
| # | Hook | Kullanım zamanı |
|---|---|---|
| 1 | catalog | Model kataloğu veya base URL varsayılanları |
| 2 | applyConfigDefaults | Yapılandırma somutlaştırması sırasında sağlayıcı sahipliğinde genel varsayılanlar |
| 3 | normalizeModelId | Aramadan önce eski/önizleme model kimliği takma adlarını temizleme |
| 4 | normalizeTransport | Genel model derlemesinden önce sağlayıcı ailesi api / baseUrl temizliği |
| 5 | normalizeConfig | models.providers.<id> yapılandırmasını normalize etme |
| 6 | applyNativeStreamingUsageCompat | Yapılandırma sağlayıcıları için yerel akış kullanımı uyumluluk yeniden yazımları |
| 7 | resolveConfigApiKey | Sağlayıcı sahipliğinde env-marker kimlik doğrulama çözümlemesi |
| 8 | resolveSyntheticAuth | Yerel/self-hosted veya config destekli sentetik kimlik doğrulama |
| 9 | shouldDeferSyntheticProfileAuth | Sentetik depolanmış profil yer tutucularını env/config kimlik doğrulamasının gerisine alma |
| 10 | resolveDynamicModel | Keyfi upstream model kimliklerini kabul etme |
| 11 | prepareDynamicModel | Çözümlemeden önce async meta veri getirme |
| 12 | normalizeResolvedModel | Runner’dan önce aktarım yeniden yazımları |
normalizeConfigönce eşleşen sağlayıcıyı, sonra diğer hook yetenekli sağlayıcı plugin’lerini yalnızca gerçekten yapılandırmayı değiştiren biri olana kadar kontrol eder. Hiçbir sağlayıcı hook’u desteklenen Google ailesi yapılandırma girdisini yeniden yazmazsa, paketlenmiş Google yapılandırma normalleştiricisi yine de uygulanır.resolveConfigApiKey, açıksa sağlayıcı hook’unu kullanır. Paketlenmişamazon-bedrockyolu ayrıca burada yerleşik bir AWS env-marker çözümleyicisine sahiptir; Bedrock çalışma zamanı kimlik doğrulamasının kendisi hâlâ AWS SDK varsayılan zincirini kullansa da. | 13 |contributeResolvedModelCompat| Başka bir uyumlu aktarım arkasındaki üretici modelleri için uyumluluk işaretleri | | 14 |capabilities| Eski statik yetenek çantası; yalnızca uyumluluk | | 15 |normalizeToolSchemas| Kayıttan önce sağlayıcı sahipliğinde araç şeması temizliği | | 16 |inspectToolSchemas| Sağlayıcı sahipliğinde araç şeması tanılamaları | | 17 |resolveReasoningOutputMode| Etiketli ve yerel reasoning-output sözleşmesi | | 18 |prepareExtraParams| Varsayılan istek parametreleri | | 19 |createStreamFn| Tamamen özel StreamFn aktarımı | | 20 |wrapStreamFn| Normal akış yolunda özel üst bilgi/gövde sarmalayıcıları | | 21 |resolveTransportTurnState| Yerel dönüş başına üst bilgi/meta veri | | 22 |resolveWebSocketSessionPolicy| Yerel WS oturum üst bilgileri/bekleme süresi | | 23 |formatApiKey| Özel çalışma zamanı token biçimi | | 24 |refreshOAuth| Özel OAuth yenilemesi | | 25 |buildAuthDoctorHint| Kimlik doğrulama onarım yönlendirmesi | | 26 |matchesContextOverflowError| Sağlayıcı sahipliğinde taşma algılama | | 27 |classifyFailoverReason| Sağlayıcı sahipliğinde hız sınırı/aşırı yük sınıflandırması | | 28 |isCacheTtlEligible| Prompt cache TTL kapılama | | 29 |buildMissingAuthMessage| Özel eksik kimlik doğrulama ipucu | | 30 |suppressBuiltInModel| Eskimiş upstream satırlarını gizleme | | 31 |augmentModelCatalog| Sentetik ileri uyumluluk satırları | | 32 |isBinaryThinking| İkili thinking açık/kapalı | | 33 |supportsXHighThinking|xhighreasoning desteği | | 34 |resolveDefaultThinkingLevel| Varsayılan/thinkilkesi | | 35 |isModernModelRef| Canlı/smoke model eşleştirme | | 36 |prepareRuntimeAuth| Çıkarımdan önce token değişimi | | 37 |resolveUsageAuth| Özel kullanım kimlik bilgisi çözümleme | | 38 |fetchUsageSnapshot| Özel kullanım uç noktası | | 39 |createEmbeddingProvider| Bellek/arama için sağlayıcı sahipliğinde embedding bağdaştırıcısı | | 40 |buildReplayPolicy| Özel transkript replay/sıkıştırma ilkesi | | 41 |sanitizeReplayHistory| Genel temizlemeden sonra sağlayıcıya özgü replay yeniden yazımları | | 42 |validateReplayTurns| Gömülü runner’dan önce sıkı replay-turn doğrulaması | | 43 |onModelSelected| Seçim sonrası geri çağrı (ör. telemetri) |
resolveSystemPromptContribution, bir sağlayıcının model ailesi için cache farkındalıklı system-prompt yönlendirmesi eklemesine olanak tanır. Davranış bir sağlayıcı/model ailesine aitse ve kararlı/dinamik cache ayrımını koruması gerekiyorsa, bunubefore_prompt_buildyerine 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 (üretici başına bir plugin). Bkz.
Internals: Capability Ownership.
ClawHub’a yayımlayın
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 kontrol eder:
| 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 profillerine bağlı 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
- Channel Plugins — plugin’iniz ayrıca bir kanal da sağlıyorsa
- SDK Runtime —
api.runtimeyardımcıları (TTS, arama, alt agent) - SDK Overview — tam alt yol içe aktarma başvurusu
- Plugin Internals — hook ayrıntıları ve paketlenmiş örnekler