Provider-Plugins erstellen
Diese Anleitung führt Sie durch das Erstellen eines Provider-Plugins, das OpenClaw einen Model-Provider (LLM) hinzufügt. Am Ende haben Sie einen Provider mit einem Model-Katalog, API-Key-Authentifizierung und dynamischer Model-Auflösung.Wenn Sie noch nie ein OpenClaw-Plugin erstellt haben, lesen Sie zuerst
Erste Schritte für die grundlegende Paketstruktur
und die Manifest-Einrichtung.
Schritt-für-Schritt-Anleitung
Paket und Manifest
providerAuthEnvVars, damit OpenClaw
Zugangsdaten erkennen kann, ohne Ihre Plugin-Runtime zu laden. modelSupport ist optional
und ermöglicht es OpenClaw, Ihr Provider-Plugin anhand kurzer Model-IDs
wie acme-large automatisch zu laden, bevor Runtime-Hooks vorhanden sind. 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 ein Das ist ein funktionierender Provider. Benutzer können jetzt
Wenn Ihr Authentifizierungsablauf außerdem
id, label, auth und catalog:index.ts
openclaw onboard --acme-ai-api-key <key> verwenden und
acme-ai/acme-large als ihr Model auswählen.Für gebündelte Provider, die nur einen Text-Provider mit API-Key-
Authentifizierung plus eine einzelne kataloggestützte Runtime registrieren, sollten Sie den enger gefassten
Helper defineSingleProviderPluginEntry(...) bevorzugen:models.providers.*, Aliase und
das Standard-Model des Agenten während des Onboarding patchen muss, verwenden Sie die Preset-Helper aus
openclaw/plugin-sdk/provider-onboard. Die am engsten gefassten Helper sind
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...) und
createModelCatalogPresetAppliers(...).Wenn der native Endpunkt eines Providers gestreamte Usage-Blöcke auf dem normalen
Transport openai-completions unterstützt, sollten Sie die gemeinsamen Katalog-Helper in
openclaw/plugin-sdk/provider-catalog-shared bevorzugen, statt Provider-ID-Prüfungen
fest zu codieren. supportsNativeStreamingUsageCompat(...) und
applyProviderNativeStreamingUsageCompat(...) erkennen die Unterstützung anhand der Endpunkt-Fähigkeitszuordnung,
sodass native Endpunkte im Stil von Moonshot/DashScope weiterhin opt-in können, auch wenn ein Plugin eine benutzerdefinierte Provider-ID verwendet.Dynamische Model-Auflösung hinzufügen
Wenn Ihr Provider beliebige Model-IDs akzeptiert, etwa ein Proxy oder Router,
fügen Sie Wenn für die Auflösung ein Netzwerkaufruf erforderlich ist, verwenden Sie
resolveDynamicModel hinzu:prepareDynamicModel für asynchrones
Aufwärmen — resolveDynamicModel wird erneut ausgeführt, nachdem es abgeschlossen ist.Runtime-Hooks hinzufügen (nach Bedarf)
Die meisten Provider benötigen nur Heute verfügbare Replay-Familien:
Reale gebündelte Beispiele:
Reale gebündelte Beispiele:
catalog + resolveDynamicModel. Fügen Sie Hooks
schrittweise hinzu, wenn Ihr Provider sie benötigt.Gemeinsame Helper-Builder decken jetzt die häufigsten Replay-/Tool-Kompatibilitäts-
Familien ab, sodass Plugins normalerweise nicht jeden Hook einzeln verdrahten müssen:| Family | Was sie verdrahtet |
|---|---|
openai-compatible | Gemeinsame Replay-Richtlinie im OpenAI-Stil für OpenAI-kompatible Transports, 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 Transports für Anthropic-Nachrichten nur dann Claude-spezifische Bereinigung von Thinking-Blöcken erhalten, wenn das aufgelöste Model tatsächlich eine Claude-ID ist |
google-gemini | Native Gemini-Replay-Richtlinie plus Bootstrap-Replay-Bereinigung und getaggter Modus für Reasoning-Ausgabe |
passthrough-gemini | Bereinigung der Gemini-Thought-Signature für Gemini-Models, die über OpenAI-kompatible Proxy-Transports laufen; aktiviert keine native Gemini-Replay-Validierung oder Bootstrap-Rewrites |
hybrid-anthropic-openai | Hybride Richtlinie für Provider, die Oberflächen für Anthropic-Nachrichten und OpenAI-kompatible Models in einem Plugin mischen; optionales Verwerfen von Thinking-Blöcken nur für Claude bleibt auf die Anthropic-Seite beschränkt |
googleundgoogle-gemini-cli:google-geminiopenrouter,kilocode,opencodeundopencode-go:passthrough-geminiamazon-bedrockundanthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot,ollama,xaiundzai:openai-compatible
| Family | Was sie verdrahtet |
|---|---|
google-thinking | Normalisierung der Gemini-Thinking-Payload 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 das injizierte Thinking überspringen |
moonshot-thinking | Zuordnung der nativen binären Thinking-Payload von Moonshot aus Konfiguration + /think-Level |
minimax-fast-mode | Umschreiben des MiniMax-Fast-Mode-Models auf dem gemeinsamen Stream-Pfad |
openai-responses-defaults | Gemeinsame native OpenAI/Codex-Responses-Wrapper: Attribution-Header, /fast/serviceTier, Text-Verbosity, native Codex-Websuche, Payload-Gestaltung für Reasoning-Kompatibilität und Kontextverwaltung für Responses |
openrouter-thinking | OpenRouter-Reasoning-Wrapper für Proxy-Routen, mit zentral behandeltem Überspringen nicht unterstützter Models/auto |
tool-stream-default-on | Standardmäßig aktivierter tool_stream-Wrapper für Provider wie Z.AI, die Tool-Streaming wünschen, sofern es nicht ausdrücklich 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 Enum der Replay-Familien
sowie die gemeinsamen Helper, aus denen diese Familien aufgebaut sind. Zu den üblichen öffentlichen
Exporten gehören:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- gemeinsame Replay-Builder wie
buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...)undbuildHybridAnthropicOrOpenAIReplayPolicy(...) - Gemini-Replay-Helper wie
sanitizeGoogleGeminiReplayHistory(...)undresolveTaggedReasoningOutputMode() - Endpunkt-/Model-Helper wie
resolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...)undnormalizeNativeXaiModelId(...)
openclaw/plugin-sdk/provider-stream stellt sowohl den Family-Builder als auch
die öffentlichen Wrapper-Helper bereit, die diese Familien wiederverwenden. Zu den üblichen öffentlichen Exporten
gehören: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
Anthropic-Wrapper-Builder auf niedrigerer Ebene aus seinem öffentlichen api.ts- /
contract-api.ts-Seam. Diese Helper bleiben Anthropic-spezifisch, weil
sie auch die Behandlung von Claude-OAuth-Betas und context1m-Gating kodieren.Andere gebündelte Provider behalten ebenfalls transportspezifische Wrapper lokal, wenn
sich das Verhalten nicht sauber über Familien hinweg teilen lässt. Aktuelles Beispiel: das
gebündelte xAI-Plugin behält natives xAI-Responses-Shaping in seinem eigenen
wrapStreamFn, einschließlich Umschreiben von /fast-Aliasen, standardmäßigem tool_stream,
Bereinigung nicht unterstützter Strict-Tool-Konfigurationen und Entfernen
xAI-spezifischer 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 Family-Inventar.buildProviderToolCompatFamilyHooks("gemini")verdrahtet Gemini-Schema- Bereinigung + Diagnose für Provider, die Gemini-sichere Tool-Schemas 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 Model an, bevor es den Runner erreicht.
normalizeResolvedModel plus
contributeResolvedModelCompat, damit diese Kompatibilitäts-Metadaten dem
Provider gehören, statt xAI-Regeln im Core fest zu codieren.Dasselbe Muster mit Paket-Root wird auch von anderen gebündelten Providern unterstützt:@openclaw/openai-provider:api.tsexportiert Provider-Builder, Helper für Default-Models und Realtime-Provider-Builder@openclaw/openrouter-provider:api.tsexportiert den Provider-Builder plus Onboarding-/Konfigurations-Helper
- Token-Austausch
- Benutzerdefinierte Header
- Native Transportidentität
- Usage 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 | Model-Katalog oder Base-URL-Standardeinstellungen |
| 2 | applyConfigDefaults | Provider-eigene globale Standardeinstellungen während der Materialisierung der Konfiguration |
| 3 | normalizeModelId | Bereinigung von Aliasen für Legacy-/Preview-Model-IDs vor dem Lookup |
| 4 | normalizeTransport | Bereinigung von Provider-Familien-api / baseUrl vor der generischen Model-Zusammenstellung |
| 5 | normalizeConfig | models.providers.<id>-Konfiguration normalisieren |
| 6 | applyNativeStreamingUsageCompat | Rewrites für native Streaming-Usage-Kompatibilität bei Konfigurations-Providern |
| 7 | resolveConfigApiKey | Provider-eigene Auflösung von Authentifizierung über Env-Marker |
| 8 | resolveSyntheticAuth | Synthetische Authentifizierung lokal/selbst gehostet oder konfigurationsgestützt |
| 9 | shouldDeferSyntheticProfileAuth | Synthetische gespeicherte Profil-Platzhalter hinter Env-/Konfigurations-Authentifizierung zurückstellen |
| 10 | resolveDynamicModel | Beliebige vorgelagerte Model-IDs akzeptieren |
| 11 | prepareDynamicModel | Asynchrones Abrufen von Metadaten vor der Auflösung |
| 12 | normalizeResolvedModel | Transport-Rewrites vor dem Runner |
-
normalizeConfigprüft zuerst den passenden Provider, dann 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-Normalizer angewendet. -
resolveConfigApiKeyverwendet den Provider-Hook, wenn er verfügbar ist. Der gebündelte Pfadamazon-bedrockhat hier außerdem einen eingebauten AWS-Env-Marker-Resolver, obwohl die Runtime-Authentifizierung von Bedrock selbst weiterhin die Standardkette des AWS SDK verwendet. | 13 |contributeResolvedModelCompat| Kompatibilitäts-Flags für Vendor-Models hinter einem anderen kompatiblen Transport | | 14 |capabilities| Legacy-Bag statischer Fähigkeiten; nur aus Kompatibilitätsgründen | | 15 |normalizeToolSchemas| Provider-eigene Bereinigung von Tool-Schemas vor der Registrierung | | 16 |inspectToolSchemas| Provider-eigene Diagnose für Tool-Schemas | | 17 |resolveReasoningOutputMode| Vertrag für getaggte vs. native Reasoning-Ausgabe | | 18 |prepareExtraParams| Standard-Request-Parameter | | 19 |createStreamFn| Vollständig benutzerdefinierter StreamFn-Transport | | 20 |wrapStreamFn| Wrapper für benutzerdefinierte Header/Body-Anpassungen auf dem normalen Stream-Pfad | | 21 |resolveTransportTurnState| Native Header/Metadaten pro Turn | | 22 |resolveWebSocketSessionPolicy| Native WS-Session-Header/Cool-down | | 23 |formatApiKey| Benutzerdefinierte Form des Runtime-Tokens | | 24 |refreshOAuth| Benutzerdefinierte OAuth-Aktualisierung | | 25 |buildAuthDoctorHint| Hinweise zur Reparatur der Authentifizierung | | 26 |matchesContextOverflowError| Provider-eigene Erkennung von Overflow | | 27 |classifyFailoverReason| Provider-eigene Klassifizierung von Rate-Limit/Überlastung | | 28 |isCacheTtlEligible| TTL-Gating für Prompt-Cache | | 29 |buildMissingAuthMessage| Benutzerdefinierter Hinweis bei fehlender Authentifizierung | | 30 |suppressBuiltInModel| Veraltete vorgelagerte Zeilen ausblenden | | 31 |augmentModelCatalog| Synthetische Zeilen für Vorwärtskompatibilität | | 32 |isBinaryThinking| Binäres Thinking an/aus | | 33 |supportsXHighThinking| Unterstützung fürxhigh-Reasoning | | 34 |resolveDefaultThinkingLevel| Standardrichtlinie für/think| | 35 |isModernModelRef| Abgleich von Live-/Smoke-Models | | 36 |prepareRuntimeAuth| Token-Austausch vor der Inferenz | | 37 |resolveUsageAuth| Benutzerdefiniertes Parsen von Usage-Zugangsdaten | | 38 |fetchUsageSnapshot| Benutzerdefinierter Usage-Endpunkt | | 39 |createEmbeddingProvider| Provider-eigener Embedding-Adapter für Memory/Search | | 40 |buildReplayPolicy| Benutzerdefinierte Richtlinie für Transcript-Replay/-Kompaktierung | | 41 |sanitizeReplayHistory| Provider-spezifische Replay-Rewrites nach der generischen Bereinigung | | 42 |validateReplayTurns| Strikte Validierung von Replay-Turns vor dem eingebetteten Runner | | 43 |onModelSelected| Callback nach der Auswahl (z. B. für Telemetrie) | Detaillierte Beschreibungen und Beispiele aus der Praxis finden Sie unter Internals: Provider Runtime Hooks.
Zusätzliche Fähigkeiten hinzufügen (optional)
Ein Provider-Plugin kann zusätzlich zu Textinferenz Sprache, Realtime-Transkription, Realtime-
Voice, Media Understanding, Bildgenerierung, Videogenerierung, Web Fetch
und Web Search registrieren:OpenClaw klassifiziert dies als Plugin mit hybriden Fähigkeiten. Das ist das
empfohlene Muster für Unternehmens-Plugins (ein Plugin pro Anbieter). Siehe
Internals: Capability Ownership.
Auf ClawHub veröffentlichen
Provider-Plugins werden genauso veröffentlicht wie jeder andere externe Code-Plugin:clawhub package publish verwenden.
Dateistruktur
Referenz für Katalogreihenfolge
catalog.order steuert, wann Ihr Katalog im Verhältnis zu eingebauten
Providern zusammengeführt wird:
| Order | 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 | Bestehende Provider überschreiben (gewinnt bei Kollisionen) |
Nächste Schritte
- Channel-Plugins — wenn Ihr Plugin auch einen Channel 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