Erstellen von Provider-Plugins
Diese Anleitung führt Sie Schritt für Schritt durch das Erstellen eines Provider-Plugins, das einen Modell-Provider (LLM) zu OpenClaw hinzufügt. Am Ende haben Sie einen Provider mit Modellkatalog, API-Key-Authentifizierung und dynamischer Modellauflösung.Wenn Sie noch nie zuvor ein OpenClaw-Plugin erstellt haben, lesen Sie zuerst
Getting Started für die grundlegende Paketstruktur
und das Manifest-Setup.
Anleitung
Paket und Manifest
providerAuthEnvVars, damit OpenClaw
Anmeldedaten erkennen kann, ohne die Laufzeit Ihres Plugins zu laden. Fügen Sie providerAuthAliases
hinzu, wenn eine Provider-Variante die Authentifizierung einer anderen Provider-ID wiederverwenden soll. modelSupport
ist optional und ermöglicht es OpenClaw, Ihr Provider-Plugin automatisch aus Kurzform-
Modell-IDs wie acme-large zu laden, bevor Runtime-Hooks existieren. Wenn Sie den
Provider auf ClawHub veröffentlichen, sind diese Felder openclaw.compat und openclaw.build
in package.json erforderlich.Den Provider registrieren
Ein minimaler Provider benötigt Das ist ein funktionierender Provider. Benutzer können jetzt
Wenn Ihr Auth-Flow außerdem
id, label, auth und catalog:index.ts
openclaw onboard --acme-ai-api-key <key> ausführen und
acme-ai/acme-large als Modell auswählen.Wenn der Upstream-Provider andere Steuertokens als OpenClaw verwendet, fügen Sie eine
kleine bidirektionale Texttransformation hinzu, statt den Stream-Pfad zu ersetzen:input schreibt den endgültigen System-Prompt und den Textnachrichteninhalt vor
dem Transport um. output schreibt Text-Deltas des Assistenten und den endgültigen Text um, bevor
OpenClaw seine eigenen Kontrollmarker oder die Kanalauslieferung verarbeitet.Für gebündelte Provider, die nur einen Text-Provider mit API-Key-
Authentifizierung plus eine einzelne kataloggestützte Runtime registrieren, verwenden Sie bevorzugt den enger gefassten
Helper defineSingleProviderPluginEntry(...):models.providers.*, Aliasse und
das Standard-Agentenmodell während des Onboardings patchen muss, verwenden Sie die Preset-Helper aus
openclaw/plugin-sdk/provider-onboard. Die engsten Helper sind
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...) und
createModelCatalogPresetAppliers(...).Wenn ein nativer Endpunkt eines Providers gestreamte Usage-Blöcke auf dem
normalen openai-completions-Transport unterstützt, verwenden Sie bevorzugt die gemeinsamen Katalog-Helper in
openclaw/plugin-sdk/provider-catalog-shared, statt Prüfungen auf Provider-IDs fest zu verdrahten.
supportsNativeStreamingUsageCompat(...) und
applyProviderNativeStreamingUsageCompat(...) erkennen die Unterstützung über die Endpoint-Fähigkeitszuordnung,
sodass native Moonshot-/DashScope-artige Endpunkte sich weiterhin aktivieren lassen, selbst wenn ein Plugin eine
benutzerdefinierte Provider-ID verwendet.Dynamische Modellauflösung hinzufügen
Wenn Ihr Provider beliebige Modell-IDs akzeptiert (wie ein Proxy oder Router),
fügen Sie Wenn die Auflösung einen Netzwerkaufruf erfordert, verwenden Sie
resolveDynamicModel hinzu:prepareDynamicModel für asynchrones
Warm-up — resolveDynamicModel wird erneut ausgeführt, nachdem dieses abgeschlossen ist.Runtime-Hooks hinzufügen (nach Bedarf)
Die meisten Provider benötigen nur Verfügbare Replay-Familien derzeit:
Echte gebündelte Beispiele:
Echte gebündelte Beispiele:
catalog + resolveDynamicModel. Fügen Sie Hooks
schrittweise hinzu, je nachdem, was Ihr Provider benötigt.Gemeinsam genutzte Helper-Builder decken jetzt die häufigsten Replay-/Tool-Kompatibilitäts-
Familien ab, sodass Plugins normalerweise nicht jeden Hook einzeln verdrahten müssen:| Familie | Was sie verdrahtet |
|---|---|
openai-compatible | Gemeinsame Replay-Richtlinie im OpenAI-Stil für OpenAI-kompatible Transporte, einschließlich Bereinigung von Tool-Call-IDs, Korrekturen für Assistant-First-Reihenfolge und generischer Gemini-Turn-Validierung, wo der Transport sie benötigt |
anthropic-by-model | Claude-spezifische Replay-Richtlinie, ausgewählt nach modelId, sodass Anthropic-Message-Transporte nur dann Claude-spezifische Thinking-Block-Bereinigung erhalten, wenn das aufgelöste Modell tatsächlich eine Claude-ID ist |
google-gemini | Native Gemini-Replay-Richtlinie plus Bootstrap-Replay-Bereinigung und markierter Reasoning-Output-Modus |
passthrough-gemini | Bereinigung von Gemini-Thought-Signaturen für Gemini-Modelle, die über OpenAI-kompatible Proxy-Transporte laufen; aktiviert keine native Gemini-Replay-Validierung oder Bootstrap-Umschreibungen |
hybrid-anthropic-openai | Hybride Richtlinie für Provider, die Anthropic-Message- und OpenAI-kompatible Modelloberflächen in einem Plugin mischen; optionales Entfernen von Claude-spezifischen Thinking-Blöcken bleibt auf die Anthropic-Seite begrenzt |
googleundgoogle-gemini-cli:google-geminiopenrouter,kilocode,opencodeundopencode-go:passthrough-geminiamazon-bedrockundanthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot,ollama,xaiundzai:openai-compatible
| Familie | Was sie verdrahtet |
|---|---|
google-thinking | Normalisierung von Gemini-Thinking-Payloads auf dem gemeinsamen Stream-Pfad |
kilocode-thinking | Kilo-Reasoning-Wrapper auf dem gemeinsamen Proxy-Stream-Pfad, wobei kilo/auto und nicht unterstützte Proxy-Reasoning-IDs injiziertes Thinking überspringen |
moonshot-thinking | Moonshot-Binärzuordnung nativer Thinking-Payloads aus Konfiguration + /think-Level |
minimax-fast-mode | Umschreibung von MiniMax-Fast-Mode-Modellen auf dem gemeinsamen Stream-Pfad |
openai-responses-defaults | Gemeinsame native OpenAI-/Codex-Responses-Wrapper: Attributions-Header, /fast/serviceTier, Text-Verbosity, native Codex-Websuche, Reasoning-Kompatibilitäts-Payload-Shaping und Responses-Kontextverwaltung |
openrouter-thinking | OpenRouter-Reasoning-Wrapper für Proxy-Routen, mit zentral behandeltem Überspringen für nicht unterstützte Modelle/auto |
tool-stream-default-on | Standardmäßig aktivierter tool_stream-Wrapper für Provider wie Z.AI, die Tool-Streaming möchten, sofern es nicht explizit deaktiviert wird |
googleundgoogle-gemini-cli:google-thinkingkilocode:kilocode-thinkingmoonshot:moonshot-thinkingminimaxundminimax-portal:minimax-fast-modeopenaiundopenai-codex:openai-responses-defaultsopenrouter:openrouter-thinkingzai:tool-stream-default-on
openclaw/plugin-sdk/provider-model-shared exportiert außerdem das Replay-Familien-
Enum sowie die gemeinsamen Helper, aus denen diese Familien aufgebaut sind. Häufige öffentliche
Exporte sind:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- gemeinsame Replay-Builder wie
buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...)undbuildHybridAnthropicOrOpenAIReplayPolicy(...) - Gemini-Replay-Helper wie
sanitizeGoogleGeminiReplayHistory(...)undresolveTaggedReasoningOutputMode() - Endpoint-/Modell-Helper wie
resolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...)undnormalizeNativeXaiModelId(...)
openclaw/plugin-sdk/provider-stream stellt sowohl den Familien-Builder als auch
die öffentlichen Wrapper-Helper bereit, die diese Familien wiederverwenden. Häufige öffentliche Exporte
sind:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)- gemeinsame OpenAI-/Codex-Wrapper wie
createOpenAIAttributionHeadersWrapper(...),createOpenAIFastModeWrapper(...),createOpenAIServiceTierWrapper(...),createOpenAIResponsesContextManagementWrapper(...)undcreateCodexNativeWebSearchWrapper(...) - gemeinsame Proxy-/Provider-Wrapper wie
createOpenRouterWrapper(...),createToolStreamWrapper(...)undcreateMinimaxFastModeWrapper(...)
@openclaw/anthropic-provider exportiert
wrapAnthropicProviderStream, resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier und die
niedrigeren Anthropic-Wrapper-Builder über sein öffentliches api.ts- /
contract-api.ts-Interface. Diese Helper bleiben Anthropic-spezifisch, weil
sie außerdem Claude-OAuth-Beta-Handling und context1m-Gating codieren.Andere gebündelte Provider behalten transportbezogene Wrapper ebenfalls lokal,
wenn das Verhalten sich nicht sauber familienübergreifend teilen lässt. Aktuelles Beispiel: das
gebündelte xAI-Plugin behält natives xAI-Responses-Shaping in seinem eigenen
wrapStreamFn, einschließlich Umschreibungen von /fast-Aliasen, standardmäßigem tool_stream,
Bereinigung nicht unterstützter Strict-Tool-Konfigurationen und Entfernung von xAI-spezifischen Reasoning-Payloads.openclaw/plugin-sdk/provider-tools stellt derzeit eine gemeinsame
Tool-Schema-Familie plus gemeinsame Schema-/Kompatibilitäts-Helper bereit:ProviderToolCompatFamilydokumentiert das heutige gemeinsame Familieninventar.buildProviderToolCompatFamilyHooks("gemini")verdrahtet die Bereinigung von Gemini-Schemata- Diagnosefunktionen für Provider, die Gemini-sichere Tool-Schemata benötigen.
normalizeGeminiToolSchemas(...)undinspectGeminiToolSchemas(...)sind die zugrunde liegenden öffentlichen Gemini-Schema-Helper.resolveXaiModelCompatPatch()gibt den gebündelten xAI-Kompatibilitäts-Patch zurück:toolSchemaProfile: "xai", nicht unterstützte Schema-Schlüsselwörter, nativeweb_search-Unterstützung und Dekodierung von Tool-Call-Argumenten mit HTML-Entities.applyXaiModelCompat(model)wendet denselben xAI-Kompatibilitäts-Patch auf ein aufgelöstes Modell an, bevor es den Runner erreicht.
normalizeResolvedModel plus
contributeResolvedModelCompat, damit diese Kompatibilitätsmetadaten dem
Provider gehören, statt xAI-Regeln im Core fest zu verdrahten.Dasselbe Paket-Root-Muster unterstützt auch andere gebündelte Provider:@openclaw/openai-provider:api.tsexportiert Provider-Builder, Helper für Standardmodelle und Realtime-Provider-Builder@openclaw/openrouter-provider:api.tsexportiert den Provider-Builder sowie Onboarding-/Konfigurations-Helper
- Token-Austausch
- Benutzerdefinierte Header
- Native Transportidentität
- Nutzung und Abrechnung
Für Provider, die vor jedem Inferenzaufruf einen Token-Austausch benötigen:
Alle verfügbaren Provider-Hooks
Alle verfügbaren Provider-Hooks
OpenClaw ruft Hooks in dieser Reihenfolge auf. Die meisten Provider verwenden nur 2-3:
Hinweise zu Runtime-Fallbacks:
| # | Hook | Wann verwenden |
|---|---|---|
| 1 | catalog | Modellkatalog oder Standardwerte für baseUrl |
| 2 | applyConfigDefaults | Provider-eigene globale Standardwerte während der Materialisierung der Konfiguration |
| 3 | normalizeModelId | Bereinigung von Legacy-/Preview-Modell-ID-Aliasen vor dem Lookup |
| 4 | normalizeTransport | Bereinigung von api / baseUrl für Provider-Familien vor der generischen Modellerstellung |
| 5 | normalizeConfig | models.providers.<id>-Konfiguration normalisieren |
| 6 | applyNativeStreamingUsageCompat | Native Streaming-Usage-Kompatibilitäts-Umschreibungen für Konfigurations-Provider |
| 7 | resolveConfigApiKey | Provider-eigene Auflösung von Env-Marker-Authentifizierung |
| 8 | resolveSyntheticAuth | Synthetische Authentifizierung für lokal/self-hosted oder konfigurationsgestützte Setups |
| 9 | shouldDeferSyntheticProfileAuth | Platzhalter für synthetische gespeicherte Profile hinter Env-/Konfigurations-Authentifizierung zurückstufen |
| 10 | resolveDynamicModel | Beliebige Upstream-Modell-IDs akzeptieren |
| 11 | prepareDynamicModel | Asynchroner Metadatenabruf vor der Auflösung |
| 12 | normalizeResolvedModel | Transport-Umschreibungen vor dem Runner |
-
normalizeConfigprüft zuerst den passenden Provider und danach andere Hook-fähige Provider-Plugins, bis eines die Konfiguration tatsächlich ändert. Wenn kein Provider-Hook einen unterstützten Google-Familien-Konfigurationseintrag umschreibt, wird weiterhin der gebündelte Google-Konfigurations-Normalisierer angewendet. -
resolveConfigApiKeyverwendet den Provider-Hook, wenn er verfügbar ist. Der gebündelteamazon-bedrock-Pfad hat hier außerdem einen eingebauten AWS-Env-Marker-Resolver, obwohl die Bedrock-Runtime-Authentifizierung selbst weiterhin die Standardkette des AWS SDK verwendet. | 13 |contributeResolvedModelCompat| Kompatibilitäts-Flags für Vendor-Modelle hinter einem anderen kompatiblen Transport | | 14 |capabilities| Legacy-statische Capabilities-Sammlung; nur aus Kompatibilitätsgründen | | 15 |normalizeToolSchemas| Provider-eigene Bereinigung von Tool-Schemata vor der Registrierung | | 16 |inspectToolSchemas| Provider-eigene Diagnose von Tool-Schemata | | 17 |resolveReasoningOutputMode| Vertrag für markierten vs. nativen Reasoning-Output | | 18 |prepareExtraParams| Standard-Request-Parameter | | 19 |createStreamFn| Vollständig benutzerdefinierter StreamFn-Transport | | 20 |wrapStreamFn| Benutzerdefinierte Header-/Body-Wrapper auf dem normalen Stream-Pfad | | 21 |resolveTransportTurnState| Native Header/Metadaten pro Turn | | 22 |resolveWebSocketSessionPolicy| Native WS-Sitzungs-Header/Cool-down | | 23 |formatApiKey| Benutzerdefinierte Runtime-Token-Form | | 24 |refreshOAuth| Benutzerdefiniertes OAuth-Refresh | | 25 |buildAuthDoctorHint| Hinweise zur Reparatur der Authentifizierung | | 26 |matchesContextOverflowError| Provider-eigene Erkennung von Context Overflow | | 27 |classifyFailoverReason| Provider-eigene Klassifizierung von Rate-Limit-/Überlastungsgründen | | 28 |isCacheTtlEligible| TTL-Gating für Prompt-Cache | | 29 |buildMissingAuthMessage| Benutzerdefinierter Hinweis bei fehlender Authentifizierung | | 30 |suppressBuiltInModel| Veraltete Upstream-Zeilen ausblenden | | 31 |augmentModelCatalog| Synthetische Forward-Compat-Zeilen | | 32 |isBinaryThinking| Binäres Thinking ein/aus | | 33 |supportsXHighThinking| Unterstützung fürxhigh-Reasoning | | 34 |resolveDefaultThinkingLevel| Standardrichtlinie für/think| | 35 |isModernModelRef| Abgleich für Live-/Smoke-Modelle | | 36 |prepareRuntimeAuth| Token-Austausch vor der Inferenz | | 37 |resolveUsageAuth| Benutzerdefiniertes Parsen von Nutzungsanmeldedaten | | 38 |fetchUsageSnapshot| Benutzerdefinierter Usage-Endpoint | | 39 |createEmbeddingProvider| Provider-eigener Embedding-Adapter für Memory/Suche | | 40 |buildReplayPolicy| Benutzerdefinierte Replay-/Verdichtungsrichtlinie für Transkripte | | 41 |sanitizeReplayHistory| Provider-spezifische Replay-Umschreibungen nach generischer Bereinigung | | 42 |validateReplayTurns| Strikte Validierung von Replay-Turns vor dem eingebetteten Runner | | 43 |onModelSelected| Callback nach Modellauswahl (z. B. Telemetrie) | Hinweis zur Prompt-Abstimmung:resolveSystemPromptContributionermöglicht es einem Provider, Cache-bewusste System-Prompt-Anweisungen für eine Modellfamilie einzuspeisen. Bevorzugen Sie dies gegenüberbefore_prompt_build, wenn das Verhalten zu einer Provider-/Modellfamilie gehört und die stabile/dynamische Cache-Aufteilung erhalten bleiben soll.
Zusätzliche Capabilities hinzufügen (optional)
Ein Provider-Plugin kann neben Textinferenz auch Speech, Realtime-Transkription, Realtime-
Voice, Media Understanding, Bilderzeugung, Videoerzeugung, Web Fetch
und Websuche registrieren:OpenClaw stuft dies als hybrid-capability-Plugin ein. Das ist das
empfohlene Muster für Unternehmens-Plugins (ein Plugin pro Anbieter). Siehe
Internals: Capability Ownership.Für Videoerzeugung bevorzugen Sie die oben gezeigte modusbewusste Capability-Form:
generate, imageToVideo und videoToVideo. Flache aggregierte Felder wie
maxInputImages, maxInputVideos und maxDurationSeconds reichen nicht aus,
um Unterstützung für Transformationsmodi oder deaktivierte Modi sauber auszuweisen.Provider für Musikerzeugung sollten demselben Muster folgen:
generate für rein promptbasierte Erzeugung und edit für referenzbildbasierte
Erzeugung. Flache aggregierte Felder wie maxInputImages,
supportsLyrics und supportsFormat reichen nicht aus, um edit-
Unterstützung auszuweisen; explizite generate- / edit-Blöcke sind der erwartete Vertrag.In ClawHub veröffentlichen
Provider-Plugins werden genauso veröffentlicht wie jedes andere externe Code-Plugin:clawhub package publish verwenden.
Dateistruktur
Referenz für die Katalogreihenfolge
catalog.order steuert, wann Ihr Katalog relativ zu integrierten
Providern zusammengeführt wird:
| Reihenfolge | Wann | Anwendungsfall |
|---|---|---|
simple | Erster Durchlauf | Einfache API-Key-Provider |
profile | Nach simple | Provider, die von Auth-Profilen abhängen |
paired | Nach profile | Mehrere zusammengehörige Einträge synthetisieren |
late | Letzter Durchlauf | Vorhandene Provider überschreiben (gewinnt bei Kollision) |
Nächste Schritte
- Channel Plugins — wenn Ihr Plugin auch einen Kanal bereitstellt
- SDK Runtime —
api.runtime-Helper (TTS, Suche, Subagent) - SDK Overview — vollständige Referenz für Subpath-Importe
- Plugin Internals — Hook-Details und gebündelte Beispiele