Membangun Plugin Provider
Panduan ini memandu Anda membangun plugin provider yang menambahkan provider model (LLM) ke OpenClaw. Pada akhirnya Anda akan memiliki provider dengan katalog model, auth API key, dan resolusi model dinamis.Jika Anda belum pernah membangun plugin OpenClaw sebelumnya, baca
Memulai terlebih dahulu untuk struktur paket
dasar dan penyiapan manifes.
Panduan langkah demi langkah
Paket dan manifes
providerAuthEnvVars agar OpenClaw dapat mendeteksi
kredensial tanpa memuat runtime plugin Anda. Tambahkan providerAuthAliases
saat varian provider harus menggunakan kembali auth milik id provider lain. modelSupport
bersifat opsional dan memungkinkan OpenClaw memuat otomatis plugin provider Anda dari
id model singkat seperti acme-large sebelum hook runtime ada. Jika Anda menerbitkan provider
di ClawHub, field openclaw.compat dan openclaw.build tersebut
wajib ada di package.json.Daftarkan provider
Provider minimal memerlukan Itu adalah provider yang berfungsi. Pengguna sekarang dapat
Jika alur auth Anda juga perlu menambal
id, label, auth, dan catalog:index.ts
openclaw onboard --acme-ai-api-key <key> dan memilih
acme-ai/acme-large sebagai model mereka.Jika provider upstream menggunakan token control yang berbeda dari OpenClaw, tambahkan
transformasi teks dua arah kecil alih-alih mengganti jalur stream:input menulis ulang prompt sistem final dan konten pesan teks sebelum
transport. output menulis ulang delta teks asisten dan teks final sebelum
OpenClaw mengurai penanda control miliknya sendiri atau pengiriman channel.Untuk provider bawaan yang hanya mendaftarkan satu provider teks dengan API-key
auth plus satu runtime berbasis katalog, utamakan helper yang lebih sempit
defineSingleProviderPluginEntry(...):models.providers.*, alias, dan
model default agen selama onboarding, gunakan helper preset dari
openclaw/plugin-sdk/provider-onboard. Helper yang paling sempit adalah
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...), dan
createModelCatalogPresetAppliers(...).Saat endpoint native provider mendukung blok penggunaan streaming pada
transport openai-completions normal, utamakan helper katalog bersama di
openclaw/plugin-sdk/provider-catalog-shared alih-alih meng-hardcode pemeriksaan
provider-id. supportsNativeStreamingUsageCompat(...) dan
applyProviderNativeStreamingUsageCompat(...) mendeteksi dukungan dari peta kapabilitas endpoint,
sehingga endpoint native bergaya Moonshot/DashScope tetap ikut serta meskipun plugin
menggunakan id provider kustom.Tambahkan resolusi model dinamis
Jika provider Anda menerima id model arbitrer (seperti proxy atau router),
tambahkan Jika resolusi memerlukan panggilan jaringan, gunakan
resolveDynamicModel:prepareDynamicModel untuk
warm-up async — resolveDynamicModel dijalankan lagi setelah itu selesai.Tambahkan hook runtime (sesuai kebutuhan)
Sebagian besar provider hanya memerlukan Keluarga replay yang tersedia saat ini:
Contoh bawaan nyata:
Contoh bawaan nyata:
catalog + resolveDynamicModel. Tambahkan hook
secara bertahap sesuai kebutuhan provider Anda.Builder helper bersama kini mencakup keluarga replay/tool-compat yang paling umum,
sehingga plugin biasanya tidak perlu menghubungkan setiap hook satu per satu secara manual:| Family | Yang dihubungkan |
|---|---|
openai-compatible | Kebijakan replay bergaya OpenAI bersama untuk transport yang kompatibel dengan OpenAI, termasuk sanitasi tool-call-id, perbaikan urutan assistant-first, dan validasi giliran Gemini generik saat transport membutuhkannya |
anthropic-by-model | Kebijakan replay yang sadar Claude dipilih berdasarkan modelId, sehingga transport pesan Anthropic hanya mendapatkan pembersihan thinking-block khusus Claude saat model yang diresolusikan memang id Claude |
google-gemini | Kebijakan replay Gemini native plus sanitasi replay bootstrap dan mode keluaran reasoning bertag |
passthrough-gemini | Sanitasi thought-signature Gemini untuk model Gemini yang berjalan melalui transport proxy yang kompatibel dengan OpenAI; tidak mengaktifkan validasi replay Gemini native atau penulisan ulang bootstrap |
hybrid-anthropic-openai | Kebijakan hibrida untuk provider yang mencampur permukaan model pesan Anthropic dan yang kompatibel dengan OpenAI dalam satu plugin; penghapusan thinking-block khusus Claude yang opsional tetap dibatasi ke sisi Anthropic |
googledangoogle-gemini-cli:google-geminiopenrouter,kilocode,opencode, danopencode-go:passthrough-geminiamazon-bedrockdananthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot,ollama,xai, danzai:openai-compatible
| Family | Yang dihubungkan |
|---|---|
google-thinking | Normalisasi payload thinking Gemini pada jalur stream bersama |
kilocode-thinking | Wrapper reasoning Kilo pada jalur stream proxy bersama, dengan kilo/auto dan id reasoning proxy yang tidak didukung melewati thinking yang disuntikkan |
moonshot-thinking | Pemetaan payload native-thinking biner Moonshot dari konfigurasi + level /think |
minimax-fast-mode | Penulisan ulang model fast-mode MiniMax pada jalur stream bersama |
openai-responses-defaults | Wrapper Responses OpenAI/Codex native bersama: header atribusi, /fast/serviceTier, verbosity teks, web search Codex native, pembentukan payload reasoning-compat, dan manajemen konteks Responses |
openrouter-thinking | Wrapper reasoning OpenRouter untuk rute proxy, dengan lompatan unsupported-model/auto ditangani secara terpusat |
tool-stream-default-on | Wrapper tool_stream aktif-secara-default untuk provider seperti Z.AI yang menginginkan tool streaming kecuali dinonaktifkan secara eksplisit |
googledangoogle-gemini-cli:google-thinkingkilocode:kilocode-thinkingmoonshot:moonshot-thinkingminimaxdanminimax-portal:minimax-fast-modeopenaidanopenai-codex:openai-responses-defaultsopenrouter:openrouter-thinkingzai:tool-stream-default-on
openclaw/plugin-sdk/provider-model-shared juga mengekspor enum replay-family
serta helper bersama yang membangun family tersebut. Ekspor publik umum
meliputi:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- builder replay bersama seperti
buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...), danbuildHybridAnthropicOrOpenAIReplayPolicy(...) - helper replay Gemini seperti
sanitizeGoogleGeminiReplayHistory(...)danresolveTaggedReasoningOutputMode() - helper endpoint/model seperti
resolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...), dannormalizeNativeXaiModelId(...)
openclaw/plugin-sdk/provider-stream mengekspos builder family dan
helper wrapper publik yang digunakan ulang oleh family tersebut. Ekspor publik umum
meliputi:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)- wrapper OpenAI/Codex bersama seperti
createOpenAIAttributionHeadersWrapper(...),createOpenAIFastModeWrapper(...),createOpenAIServiceTierWrapper(...),createOpenAIResponsesContextManagementWrapper(...), dancreateCodexNativeWebSearchWrapper(...) - wrapper proxy/provider bersama seperti
createOpenRouterWrapper(...),createToolStreamWrapper(...), dancreateMinimaxFastModeWrapper(...)
@openclaw/anthropic-provider mengekspor
wrapAnthropicProviderStream, resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier, dan
builder wrapper Anthropic tingkat lebih rendah dari seam publik api.ts /
contract-api.ts miliknya. Helper tersebut tetap khusus Anthropic karena
juga mengodekan penanganan beta OAuth Claude dan gating context1m.Provider bawaan lain juga mempertahankan wrapper khusus transport tetap lokal saat
perilakunya tidak dapat dibagikan secara bersih lintas family. Contoh saat ini: plugin
xAI bawaan mempertahankan pembentukan Responses xAI native di
wrapStreamFn miliknya sendiri, termasuk penulisan ulang alias /fast, tool_stream
default, pembersihan strict-tool yang tidak didukung, dan penghapusan
payload reasoning khusus xAI.openclaw/plugin-sdk/provider-tools saat ini mengekspos satu family
skema alat bersama plus helper skema/compat bersama:ProviderToolCompatFamilymendokumentasikan inventaris family bersama saat ini.buildProviderToolCompatFamilyHooks("gemini")menghubungkan pembersihan skema Gemini + diagnostik untuk provider yang membutuhkan skema alat yang aman untuk Gemini.normalizeGeminiToolSchemas(...)daninspectGeminiToolSchemas(...)adalah helper skema Gemini publik yang mendasarinya.resolveXaiModelCompatPatch()mengembalikan patch compat xAI bawaan:toolSchemaProfile: "xai", keyword skema yang tidak didukung, dukungan nativeweb_search, dan decoding argumen tool-call entitas HTML.applyXaiModelCompat(model)menerapkan patch compat xAI yang sama ke model yang diresolusikan sebelum mencapai runner.
normalizeResolvedModel plus
contributeResolvedModelCompat agar metadata compat tersebut tetap dimiliki oleh
provider alih-alih meng-hardcode aturan xAI di core.Pola package-root yang sama juga mendasari provider bawaan lain:@openclaw/openai-provider:api.tsmengekspor builder provider, helper model default, dan builder provider realtime@openclaw/openrouter-provider:api.tsmengekspor builder provider plus helper onboarding/config
- Pertukaran token
- Header kustom
- Identitas transport native
- Penggunaan dan penagihan
Untuk provider yang memerlukan pertukaran token sebelum setiap panggilan inferensi:
Semua hook provider yang tersedia
Semua hook provider yang tersedia
OpenClaw memanggil hook dalam urutan ini. Sebagian besar provider hanya menggunakan 2-3:
Catatan fallback runtime:
| # | Hook | Kapan digunakan |
|---|---|---|
| 1 | catalog | Katalog model atau default base URL |
| 2 | applyConfigDefaults | Default global milik provider selama materialisasi konfigurasi |
| 3 | normalizeModelId | Pembersihan alias model-id lama/preview sebelum lookup |
| 4 | normalizeTransport | Pembersihan family provider api / baseUrl sebelum perakitan model generik |
| 5 | normalizeConfig | Menormalkan konfigurasi models.providers.<id> |
| 6 | applyNativeStreamingUsageCompat | Penulisan ulang compat native streaming-usage untuk provider konfigurasi |
| 7 | resolveConfigApiKey | Resolusi auth penanda env milik provider |
| 8 | resolveSyntheticAuth | Auth sintetis lokal/self-hosted atau berbasis konfigurasi |
| 9 | shouldDeferSyntheticProfileAuth | Menurunkan placeholder stored-profile sintetis di bawah auth env/config |
| 10 | resolveDynamicModel | Menerima id model upstream arbitrer |
| 11 | prepareDynamicModel | Pengambilan metadata async sebelum resolusi |
| 12 | normalizeResolvedModel | Penulisan ulang transport sebelum runner |
-
normalizeConfigmemeriksa provider yang cocok terlebih dahulu, lalu provider plugin lain yang mampu menggunakan hook sampai salah satunya benar-benar mengubah konfigurasi. Jika tidak ada hook provider yang menulis ulang entri konfigurasi family Google yang didukung, normalizer konfigurasi Google bawaan tetap diterapkan. -
resolveConfigApiKeymenggunakan hook provider saat diekspos. Jalur bawaanamazon-bedrockjuga memiliki resolver penanda env AWS bawaan di sini, meskipun auth runtime Bedrock sendiri masih menggunakan rantai default AWS SDK. | 13 |contributeResolvedModelCompat| Flag compat untuk model vendor di balik transport kompatibel lain | | 14 |capabilities| Bag kemampuan statis lama; hanya untuk kompatibilitas | | 15 |normalizeToolSchemas| Pembersihan skema alat milik provider sebelum pendaftaran | | 16 |inspectToolSchemas| Diagnostik skema alat milik provider | | 17 |resolveReasoningOutputMode| Kontrak keluaran reasoning bertag vs native | | 18 |prepareExtraParams| Parameter request default | | 19 |createStreamFn| Transport StreamFn kustom sepenuhnya | | 20 |wrapStreamFn| Wrapper header/body kustom pada jalur stream normal | | 21 |resolveTransportTurnState| Header/metadata native per giliran | | 22 |resolveWebSocketSessionPolicy| Header sesi WS native/cool-down | | 23 |formatApiKey| Bentuk token runtime kustom | | 24 |refreshOAuth| Refresh OAuth kustom | | 25 |buildAuthDoctorHint| Panduan perbaikan auth | | 26 |matchesContextOverflowError| Deteksi overflow milik provider | | 27 |classifyFailoverReason| Klasifikasi rate-limit/overload milik provider | | 28 |isCacheTtlEligible| Gating TTL cache prompt | | 29 |buildMissingAuthMessage| Petunjuk auth yang hilang kustom | | 30 |suppressBuiltInModel| Menyembunyikan baris upstream yang basi | | 31 |augmentModelCatalog| Baris sintetis forward-compat | | 32 |isBinaryThinking| Thinking biner aktif/nonaktif | | 33 |supportsXHighThinking| Dukungan reasoningxhigh| | 34 |resolveDefaultThinkingLevel| Kebijakan default/think| | 35 |isModernModelRef| Pencocokan model live/smoke | | 36 |prepareRuntimeAuth| Pertukaran token sebelum inferensi | | 37 |resolveUsageAuth| Penguraian kredensial penggunaan kustom | | 38 |fetchUsageSnapshot| Endpoint penggunaan kustom | | 39 |createEmbeddingProvider| Adaptor embedding milik provider untuk memori/pencarian | | 40 |buildReplayPolicy| Kebijakan replay/kompaksi transkrip kustom | | 41 |sanitizeReplayHistory| Penulisan ulang replay khusus provider setelah pembersihan generik | | 42 |validateReplayTurns| Validasi ketat replay-turn sebelum runner tertanam | | 43 |onModelSelected| Callback pasca-pemilihan (misalnya telemetri) | Catatan penyetelan prompt:resolveSystemPromptContributionmemungkinkan provider menyuntikkan panduan system-prompt yang sadar cache untuk family model. Utamakan ini daripadabefore_prompt_buildsaat perilaku tersebut milik satu family provider/model dan harus mempertahankan pemisahan cache stabil/dinamis.
Tambahkan kapabilitas tambahan (opsional)
Plugin provider dapat mendaftarkan speech, transkripsi realtime, voice realtime,
pemahaman media, pembuatan gambar, pembuatan video, web fetch,
dan web search di samping inferensi teks:OpenClaw mengklasifikasikan ini sebagai plugin hybrid-capability. Ini adalah
pola yang direkomendasikan untuk plugin perusahaan (satu plugin per vendor). Lihat
Internal: Kepemilikan Kapabilitas.Untuk pembuatan video, utamakan bentuk kapabilitas yang sadar mode seperti yang ditunjukkan di atas:
generate, imageToVideo, dan videoToVideo. Field agregat datar seperti
maxInputImages, maxInputVideos, dan maxDurationSeconds tidak
cukup untuk mengiklankan dukungan mode transformasi atau mode yang dinonaktifkan secara bersih.Provider pembuatan musik harus mengikuti pola yang sama:
generate untuk pembuatan berbasis prompt saja dan edit untuk pembuatan
berbasis gambar referensi. Field agregat datar seperti maxInputImages,
supportsLyrics, dan supportsFormat tidak cukup untuk mengiklankan dukungan edit;
blok generate / edit eksplisit adalah kontrak yang diharapkan.Terbitkan ke ClawHub
Plugin provider diterbitkan dengan cara yang sama seperti plugin kode eksternal lainnya:clawhub package publish.
Struktur file
Referensi urutan katalog
catalog.order mengontrol kapan katalog Anda digabungkan relatif terhadap
provider bawaan:
| Order | Kapan | Kasus penggunaan |
|---|---|---|
simple | Pass pertama | Provider API-key biasa |
profile | Setelah simple | Provider yang digating pada profil auth |
paired | Setelah profile | Menyintesis beberapa entri terkait |
late | Pass terakhir | Menimpa provider yang ada (menang saat tabrakan) |
Langkah berikutnya
- Plugin Channel — jika plugin Anda juga menyediakan channel
- SDK Runtime — helper
api.runtime(TTS, pencarian, subagen) - Ikhtisar SDK — referensi impor subpath lengkap
- Internal Plugin — detail hook dan contoh bawaan