Bu kılavuz, OpenClaw’a bir model sağlayıcısı (LLM) ekleyen bir sağlayıcı Plugin’i oluşturmayı adım adım anlatır. Sonunda model kataloğu, API anahtarı kimlik doğrulaması ve dinamik model çözümlemesi olan bir sağlayıcınız olacak.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Daha önce hiç OpenClaw Plugin’i oluşturmadıysanız, temel paket
yapısı ve manifest kurulumu için önce
Başlarken bölümünü okuyun.
İzlenecek Yol
Paket ve manifest
1. Adım: Paket ve manifest
providerAuthEnvVars bildirir. 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ı hook’ları var olmadan önce OpenClaw’ın sağlayıcı Plugin’inizi
acme-large gibi kısa model kimliklerinden otomatik yüklemesini sağlar.
Sağlayıcıyı ClawHub’da yayımlarsanız, package.json içindeki bu
openclaw.compat ve openclaw.build alanları zorunludur.Sağlayıcıyı kaydet
En küçük metin sağlayıcısı için bir
id, label, auth ve catalog
gerekir. catalog, sağlayıcıya ait çalışma zamanı/yapılandırma hook’udur;
canlı satıcı API’lerini çağırabilir ve models.providers girdileri döndürür.index.ts
registerModelCatalogProvider, liste/yardım/seçici UI’si için daha yeni
kontrol düzlemi katalog yüzeyidir. Bunu metin, görüntü oluşturma,
video oluşturma ve müzik oluşturma satırları için kullanın. Satıcı uç nokta
çağrılarını ve yanıt eşlemesini Plugin içinde tutun; paylaşılan satır şekli,
kaynak etiketleri ve yardım işlemesini OpenClaw sahiplenir.Bu, çalışan bir sağlayıcıdır. Kullanıcılar artık
openclaw onboard --acme-ai-api-key <key> çalıştırabilir ve model olarak
acme-ai/acme-large seçebilir.Üst sağlayıcı OpenClaw’dan farklı kontrol token’ları kullanıyorsa, akış
yolunu değiştirmek yerine küçük bir çift yönlü metin dönüşümü ekleyin:input, aktarım öncesinde son sistem istemini ve metin mesajı içeriğini
yeniden yazar. output, OpenClaw kendi kontrol işaretleyicilerini veya kanal
teslimini ayrıştırmadan önce asistan metin deltalarını ve son metni yeniden
yazar.Yalnızca API anahtarı kimlik doğrulamalı tek bir metin sağlayıcısı ve tek bir
katalog destekli çalışma zamanı kaydeden yerleşik sağlayıcılar için daha dar
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 gerçekleştirebilir.
buildStaticProvider yalnızca kimlik doğrulaması yapılandırılmadan önce
gösterilmesi güvenli olan çevrimdışı satırlar için kullanın; kimlik bilgileri
gerektirmemeli veya ağ istekleri yapmamalıdır. OpenClaw’ın models list --all
gösterimi şu anda statik katalogları yalnızca yerleşik sağlayıcı Plugin’leri
için, boş yapılandırma, boş ortam ve ajan/çalışma alanı yolları olmadan
çalıştırır.Kimlik doğrulama akışınızın onboarding sırasında models.providers.*,
alias’lar ve ajan varsayılan modelini de yamalaması gerekiyorsa,
openclaw/plugin-sdk/provider-onboard içindeki hazır ayar yardımcılarını
kullanın. En dar 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 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 yerel Moonshot/DashScope tarzı uç noktalar,
bir Plugin özel sağlayıcı kimliği kullanıyor olsa bile yine de dahil olur.Dinamik model çözümlemesi ekle
Sağlayıcınız rastgele model kimliklerini kabul ediyorsa (proxy veya router
gibi), Çözümleme bir ağ çağrısı gerektiriyorsa async ısınma için
resolveDynamicModel ekleyin:prepareDynamicModel kullanın - resolveDynamicModel tamamlandıktan sonra
yeniden çalışır.Çalışma zamanı hook'ları ekle (gerektiğinde)
Çoğu sağlayıcı yalnızca Bugün kullanılabilen yeniden oynatma aileleri:
Bugün kullanılabilir akış aileleri:
catalog + resolveDynamicModel gerektirir.
Sağlayıcınız ihtiyaç duydukça hook’ları kademeli olarak ekleyin.Paylaşılan yardımcı oluşturucular artık en yaygın yeniden oynatma/araç
uyumluluğu ailelerini kapsar; bu nedenle Plugin’lerin genellikle her hook’u
tek tek elle bağlaması gerekmez:| Aile | Neleri bağlar | Birlikte gelen örnekler |
|---|---|---|
openai-compatible | Araç çağrısı kimliği temizleme, assistant-first sıralama düzeltmeleri ve taşımanın ihtiyaç duyduğu yerlerde genel Gemini-turn doğrulaması dahil, OpenAI uyumlu taşımalar için paylaşılan OpenAI tarzı yeniden oynatma ilkesi | moonshot, ollama, xai, zai |
anthropic-by-model | modelId tarafından seçilen Claude-aware yeniden oynatma ilkesi; böylece Anthropic-message taşımaları, çözümlenen model gerçekten bir Claude kimliği olduğunda yalnızca Claude’a özgü thinking-block temizliği alır | amazon-bedrock, anthropic-vertex |
google-gemini | Yerel Gemini yeniden oynatma ilkesi, ayrıca bootstrap yeniden oynatma temizliği ve etiketli reasoning-output modu | google, google-gemini-cli |
passthrough-gemini | OpenAI uyumlu proxy taşımaları üzerinden çalışan Gemini modelleri için Gemini thought-signature temizliği; yerel Gemini yeniden oynatma doğrulamasını veya bootstrap yeniden yazımlarını etkinleştirmez | openrouter, kilocode, opencode, opencode-go |
hybrid-anthropic-openai | Anthropic-message ve OpenAI uyumlu model yüzeylerini tek bir plugin içinde karıştıran sağlayıcılar için hibrit ilke; isteğe bağlı yalnızca Claude thinking-block bırakma Anthropic tarafıyla sınırlı kalır | minimax |
| Aile | Neleri bağlar | Birlikte gelen örnekler |
|---|---|---|
google-thinking | Paylaşılan akış yolunda Gemini thinking yükü normalleştirmesi | google, google-gemini-cli |
kilocode-thinking | Paylaşılan proxy akış yolunda Kilo reasoning sarmalayıcısı; kilo/auto ve desteklenmeyen proxy reasoning kimlikleri enjekte edilen thinking’i atlar | kilocode |
moonshot-thinking | Yapılandırma + /think düzeyinden Moonshot ikili yerel thinking yükü eşleme | moonshot |
minimax-fast-mode | Paylaşılan akış yolunda MiniMax fast-mode model yeniden yazımı | minimax, minimax-portal |
openai-responses-defaults | Paylaşılan yerel OpenAI/Codex Responses sarmalayıcıları: attribution başlıkları, /fast/serviceTier, metin ayrıntı düzeyi, yerel Codex web araması, reasoning uyumluluk yükü şekillendirmesi ve Responses bağlam yönetimi | openai, openai-codex |
openrouter-thinking | Proxy rotaları için OpenRouter reasoning sarmalayıcısı; desteklenmeyen model/auto atlamaları merkezi olarak işlenir | openrouter |
tool-stream-default-on | Açıkça devre dışı bırakılmadıkça araç akışı isteyen Z.AI gibi sağlayıcılar için varsayılan olarak açık tool_stream sarmalayıcısı | zai |
Aile oluşturucularına güç veren SDK birleşim noktaları
Aile oluşturucularına güç veren SDK birleşim noktaları
Her aile oluşturucu, 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 bunlara başvurabilirsiniz:
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ı (createDeepSeekV4OpenAICompatibleThinkingWrapper), Anthropic Messages thinking prefill temizliği (createAnthropicThinkingPrefillPayloadWrapper) ve paylaşılan proxy/sağlayıcı sarmalayıcıları (createOpenRouterWrapper,createToolStreamWrapper,createMinimaxFastModeWrapper).openclaw/plugin-sdk/provider-tools-ProviderToolCompatFamily,buildProviderToolCompatFamilyHooks("gemini")ve alttaki Gemini şema yardımcıları (normalizeGeminiToolSchemas,inspectGeminiToolSchemas).
@openclaw/anthropic-provider, wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier ve daha düşük düzeyli Anthropic sarmalayıcı oluşturucularını kendi genel api.ts / contract-api.ts birleşim noktasında tutar, çünkü bunlar Claude OAuth beta işlemesini ve context1m geçitlemesini kodlar. xAI plugin’i de yerel xAI Responses şekillendirmesini kendi wrapStreamFn içinde tutar (/fast takma adları, varsayılan tool_stream, desteklenmeyen katı araç temizliği, xAI’ye özgü reasoning yükü kaldırma).Aynı paket kökü kalıbı @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şturucu ile onboarding/yapılandırma yardımcıları) için de temel oluşturur.- Token değişimi
- Özel başlıklar
- Yerel taşıma kimliği
- Kullanım ve faturalandırma
Her çıkarım çağrısından önce token değişimine ihtiyaç duyan sağlayıcılar için:
Kullanılabilir tüm sağlayıcı hook'ları
Kullanılabilir 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:
OpenClaw’ın artık çağırmadığı,
Çalışma zamanı fallback notları:
ProviderPlugin.capabilities ve suppressBuiltInModel gibi yalnızca uyumluluk amaçlı sağlayıcı alanları burada listelenmez.| # | Hook | Ne zaman kullanılır |
|---|---|---|
| 1 | catalog | Model kataloğu veya temel URL varsayılanları |
| 2 | applyConfigDefaults | Yapılandırma maddeleştirmesi sırasında sağlayıcıya ait global varsayılanlar |
| 3 | normalizeModelId | Aramadan önce eski/önizleme model kimliği takma adı temizliği |
| 4 | normalizeTransport | Genel model derlemesinden önce sağlayıcı ailesi api / baseUrl temizliği |
| 5 | normalizeConfig | models.providers.<id> yapılandırmasını normalleştir |
| 6 | applyNativeStreamingUsageCompat | Yapılandırma sağlayıcıları için yerel akış kullanımı 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 saklanan profil yer tutucularını env/yapılandırma kimlik doğrulamasının arkasına indir |
| 10 | resolveDynamicModel | Rastgele upstream 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ı |
| 13 | contributeResolvedModelCompat | Başka bir uyumlu taşımanın arkasındaki vendor modelleri için uyumluluk bayrakları |
| 14 | normalizeToolSchemas | Kayıttan önce sağlayıcıya ait araç şeması temizliği |
| 15 | inspectToolSchemas | Sağlayıcıya ait araç şeması tanılamaları |
| 16 | resolveReasoningOutputMode | Etiketli ve yerel reasoning-output sözleşmesi |
| 17 | prepareExtraParams | Varsayılan istek parametreleri |
| 18 | createStreamFn | Tamamen özel StreamFn taşıması |
| 19 | wrapStreamFn | Normal akış yolunda özel başlık/gövde sarmalayıcıları |
| 20 | resolveTransportTurnState | Yerel tur başına başlıklar/meta veriler |
| 21 | resolveWebSocketSessionPolicy | Yerel WS oturum başlıkları/cool-down |
| 22 | formatApiKey | Özel çalışma zamanı token şekli |
| 23 | refreshOAuth | Özel OAuth yenileme |
| 24 | buildAuthDoctorHint | Kimlik doğrulama onarım rehberliği |
| 25 | matchesContextOverflowError | Sağlayıcıya ait taşma algılama |
| 26 | classifyFailoverReason | Sağlayıcıya ait rate-limit/overload sınıflandırması |
| 27 | isCacheTtlEligible | Prompt cache TTL geçitlemesi |
| 28 | buildMissingAuthMessage | Özel eksik kimlik doğrulama ipucu |
| 29 | augmentModelCatalog | Sentetik ileri uyumluluk satırları |
| 30 | resolveThinkingProfile | Modele özgü /think seçenek kümesi |
| 31 | isBinaryThinking | İkili thinking açık/kapalı uyumluluğu |
| 32 | supportsXHighThinking | xhigh reasoning desteği uyumluluğu |
| 33 | resolveDefaultThinkingLevel | Varsayılan /think ilkesi uyumluluğu |
| 34 | isModernModelRef | Canlı/smoke model eşleştirme |
| 35 | prepareRuntimeAuth | Çıkarımdan önce token değişimi |
| 36 | resolveUsageAuth | Özel kullanım kimlik bilgisi ayrıştırma |
| 37 | fetchUsageSnapshot | Özel kullanım uç noktası |
| 38 | createEmbeddingProvider | Bellek/arama için sağlayıcıya ait embedding adaptörü |
| 39 | buildReplayPolicy | Özel transcript yeniden oynatma/compaction ilkesi |
| 40 | sanitizeReplayHistory | Genel temizlikten sonra sağlayıcıya özgü yeniden oynatma yeniden yazımları |
| 41 | validateReplayTurns | Gömülü runner’dan önce katı replay-turn doğrulaması |
| 42 | onModelSelected | Seçim sonrası geri çağırma (ör. telemetri) |
normalizeConfigönce eşleşen sağlayıcıyı, ardından yapılandırmayı gerçekten değiştiren biri çıkana kadar diğer hook destekli sağlayıcı plugin’lerini denetler. Hiçbir sağlayıcı hook’u desteklenen bir Google ailesi yapılandırma girdisini yeniden yazmazsa, birlikte gelen Google yapılandırma normalleştiricisi yine de uygulanır.resolveConfigApiKey, sunulduğunda sağlayıcı hook’unu kullanır. Birlikte gelenamazon-bedrockyolunda ayrıca burada yerleşik bir AWS env-marker çözümleyicisi vardır; Bedrock çalışma zamanı kimlik doğrulamasının kendisi hâlâ AWS SDK varsayılan zincirini kullansa da.resolveSystemPromptContribution, bir sağlayıcının bir model ailesi için önbellek farkındalıklı sistem prompt’u rehberliği enjekte etmesini sağlar. Davranış tek bir sağlayıcı/model ailesine ait olduğunda ve kararlı/dinamik önbellek ayrımını koruması gerektiğinde bunubefore_prompt_buildyerine tercih edin.
Ek yetenekler ekle (isteğe bağlı)
Adım 5: Ek yetenekler ekle
Bir sağlayıcı plugin’i, metin çıkarımıyla birlikte konuşma, gerçek zamanlı transkripsiyon, gerçek zamanlı ses, medya anlama, görüntü oluşturma, video oluşturma, web getirme ve web aramayı kaydedebilir. OpenClaw bunu hibrit-yetenek plugin’i olarak sınıflandırır - şirket plugin’leri için önerilen desen budur (tedarikçi başına bir plugin). Bkz. Dahili Bilgiler: Yetenek Sahipliği.Her yeteneği, mevcutapi.registerProvider(...) çağrınızın yanında register(api) içinde kaydedin. Yalnızca ihtiyacınız olan sekmeleri seçin:- Speech (TTS)
- Realtime transcription
- Realtime voice
- Media understanding
- Image and video generation
- Web fetch and search
assertOkOrThrowProviderError(...) kullanın; böylece
plugin’ler sınırlı hata-gövdesi okumalarını, JSON hata ayrıştırmayı ve
istek kimliği soneklerini paylaşır.Test
Adım 6: Test
src/provider.test.ts
ClawHub’a Yayınlama
Sağlayıcı plugin’leri, diğer tüm harici kod plugin’leriyle aynı şekilde yayınlanı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 anahtarı sağlayıcıları |
profile | simple sonrası | Kimlik doğrulama profilleriyle sınırlandırılmış sağlayıcılar |
paired | profile sonrası | Birden çok ilişkili girdiyi sentezle |
late | Son geçiş | Mevcut sağlayıcıları geçersiz kıl (çakışmada kazanır) |
Sonraki adımlar
- Kanal Plugin’leri - plugin’iniz ayrıca bir kanal da sağlıyorsa
- SDK Çalışma Zamanı -
api.runtimeyardımcıları (TTS, arama, alt ajan) - SDK Genel Bakış - tam alt yol içe aktarma başvurusu
- Plugin Dahili Bilgileri - hook ayrıntıları ve paketli örnekler