Tworzenie pluginów providerów
Ten przewodnik przeprowadza przez tworzenie pluginu providera, który dodaje provider modeli (LLM) do OpenClaw. Na końcu będziesz mieć providera z katalogiem modeli, uwierzytelnianiem kluczem API i dynamicznym rozpoznawaniem modeli.Jeśli nie tworzyłeś wcześniej żadnego pluginu OpenClaw, najpierw przeczytaj
Pierwsze kroki, aby poznać podstawową strukturę
pakietu i konfigurację manifestu.
Omówienie krok po kroku
Pakiet i manifest
providerAuthEnvVars, dzięki czemu OpenClaw może wykrywać
poświadczenia bez ładowania runtime twojego pluginu. Dodaj providerAuthAliases,
gdy wariant providera ma ponownie używać uwierzytelniania innego identyfikatora providera. modelSupport
jest opcjonalne i pozwala OpenClaw automatycznie ładować twój plugin providera na podstawie skróconych
identyfikatorów modeli takich jak acme-large, zanim hooki runtime będą dostępne. Jeśli publikujesz
providera w ClawHub, pola openclaw.compat i openclaw.build
są wymagane w package.json.Zarejestruj providera
Minimalny provider potrzebuje To jest działający provider. Użytkownicy mogą teraz
Jeśli twój przepływ uwierzytelniania musi także aktualizować
id, label, auth i catalog:index.ts
openclaw onboard --acme-ai-api-key <key> i wybrać
acme-ai/acme-large jako swój model.Jeśli provider nadrzędny używa innych tokenów sterujących niż OpenClaw, dodaj
małą dwukierunkową transformację tekstu zamiast zastępować ścieżkę strumieniowania:input przepisuje końcowy prompt systemowy i treść wiadomości tekstowej przed
transportem. output przepisuje delty tekstu asystenta i końcowy tekst, zanim
OpenClaw przetworzy własne znaczniki sterujące lub dostarczanie kanałowe.W przypadku dołączonych providerów, które rejestrują tylko jednego providera tekstowego z
uwierzytelnianiem kluczem API oraz pojedynczym runtime opartym na katalogu, preferuj węższy
helper defineSingleProviderPluginEntry(...):models.providers.*, aliasy oraz
domyślny model agenta podczas onboardingu, użyj helperów presetów z
openclaw/plugin-sdk/provider-onboard. Najwęższe helpery to
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...) i
createModelCatalogPresetAppliers(...).Gdy natywny endpoint providera obsługuje strumieniowane bloki użycia na
zwykłym transporcie openai-completions, preferuj współdzielone helpery katalogu z
openclaw/plugin-sdk/provider-catalog-shared zamiast wpisywać na sztywno sprawdzenia
identyfikatora providera. supportsNativeStreamingUsageCompat(...) i
applyProviderNativeStreamingUsageCompat(...) wykrywają obsługę na podstawie mapy możliwości endpointu,
dzięki czemu natywne endpointy w stylu Moonshot/DashScope nadal mogą się włączyć, nawet gdy plugin używa niestandardowego identyfikatora providera.Dodaj dynamiczne rozpoznawanie modeli
Jeśli twój provider akceptuje dowolne identyfikatory modeli (jak proxy lub router),
dodaj Jeśli rozpoznawanie wymaga wywołania sieciowego, użyj
resolveDynamicModel:prepareDynamicModel do
asynchronicznego przygotowania — po jego zakończeniu resolveDynamicModel zostanie uruchomione ponownie.Dodaj hooki runtime (w razie potrzeby)
Większość providerów potrzebuje tylko Dostępne obecnie rodziny replay:
Rzeczywiste dołączone przykłady:
Rzeczywiste dołączone przykłady:
catalog + resolveDynamicModel. Dodawaj hooki
stopniowo, w miarę jak wymaga tego twój provider.Współdzielone buildery helperów obejmują teraz najczęstsze rodziny zgodności replay/narzędzi,
więc pluginy zwykle nie muszą ręcznie podłączać każdego hooka osobno:| Rodzina | Co podłącza |
|---|---|
openai-compatible | Współdzielone zasady replay w stylu OpenAI dla transportów zgodnych z OpenAI, w tym sanityzację identyfikatorów wywołań narzędzi, poprawki kolejności assistant-first oraz ogólną walidację tur Gemini tam, gdzie wymaga tego transport |
anthropic-by-model | Zasady replay świadome Claude wybierane według modelId, dzięki czemu transporty wiadomości Anthropic otrzymują czyszczenie bloków thinking specyficzne dla Claude tylko wtedy, gdy rozpoznany model jest faktycznie identyfikatorem Claude |
google-gemini | Natywne zasady replay Gemini plus sanityzację replay bootstrap i tryb wyjścia rozumowania z tagami |
passthrough-gemini | Sanityzację podpisu thought Gemini dla modeli Gemini uruchamianych przez transporty proxy zgodne z OpenAI; nie włącza natywnej walidacji replay Gemini ani przepisów bootstrap |
hybrid-anthropic-openai | Zasady hybrydowe dla providerów, którzy łączą powierzchnie modeli wiadomości Anthropic i zgodnych z OpenAI w jednym pluginie; opcjonalne usuwanie bloków thinking tylko dla Claude pozostaje ograniczone do strony Anthropic |
googleigoogle-gemini-cli:google-geminiopenrouter,kilocode,opencodeiopencode-go:passthrough-geminiamazon-bedrockianthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot,ollama,xaiizai:openai-compatible
| Rodzina | Co podłącza |
|---|---|
google-thinking | Normalizację ładunku thinking Gemini na współdzielonej ścieżce strumieniowania |
kilocode-thinking | Opakowanie rozumowania Kilo na współdzielonej ścieżce strumienia proxy, z pomijaniem wstrzykiwanego thinking dla kilo/auto i nieobsługiwanych identyfikatorów rozumowania proxy |
moonshot-thinking | Mapowanie binarnego natywnego ładunku thinking Moonshot z konfiguracji + poziomu /think |
minimax-fast-mode | Przepisywanie modelu MiniMax fast-mode na współdzielonej ścieżce strumieniowania |
openai-responses-defaults | Współdzielone natywne opakowania OpenAI/Codex Responses: nagłówki atrybucji, /fast/serviceTier, szczegółowość tekstu, natywne wyszukiwanie w sieci Codex, kształtowanie ładunku zgodności rozumowania oraz zarządzanie kontekstem Responses |
openrouter-thinking | Opakowanie rozumowania OpenRouter dla ścieżek proxy, z centralnie obsługiwanym pomijaniem dla nieobsługiwanych modeli/auto |
tool-stream-default-on | Domyślnie włączone opakowanie tool_stream dla providerów takich jak Z.AI, którzy chcą strumieniowania narzędzi, o ile nie zostanie ono jawnie wyłączone |
googleigoogle-gemini-cli:google-thinkingkilocode:kilocode-thinkingmoonshot:moonshot-thinkingminimaximinimax-portal:minimax-fast-modeopenaiiopenai-codex:openai-responses-defaultsopenrouter:openrouter-thinkingzai:tool-stream-default-on
openclaw/plugin-sdk/provider-model-shared eksportuje również enum
rodziny replay oraz współdzielone helpery, na których te rodziny są zbudowane. Typowe eksporty publiczne
obejmują:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- współdzielone buildery replay, takie jak
buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...)ibuildHybridAnthropicOrOpenAIReplayPolicy(...) - helpery replay Gemini, takie jak
sanitizeGoogleGeminiReplayHistory(...)iresolveTaggedReasoningOutputMode() - helpery endpointów/modeli, takie jak
resolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...)inormalizeNativeXaiModelId(...)
openclaw/plugin-sdk/provider-stream udostępnia zarówno builder rodziny, jak i
publiczne helpery opakowujące, które te rodziny wykorzystują ponownie. Typowe eksporty publiczne
obejmują:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)- współdzielone opakowania OpenAI/Codex, takie jak
createOpenAIAttributionHeadersWrapper(...),createOpenAIFastModeWrapper(...),createOpenAIServiceTierWrapper(...),createOpenAIResponsesContextManagementWrapper(...)icreateCodexNativeWebSearchWrapper(...) - współdzielone opakowania proxy/providerów, takie jak
createOpenRouterWrapper(...),createToolStreamWrapper(...)icreateMinimaxFastModeWrapper(...)
@openclaw/anthropic-provider eksportuje
wrapAnthropicProviderStream, resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier oraz
niższopoziomowe buildery opakowań Anthropic ze swojej publicznej granicy api.ts /
contract-api.ts. Te helpery pozostają specyficzne dla Anthropic, ponieważ
kodują również obsługę wersji beta Claude OAuth i bramkowanie context1m.Inni dołączeni providerzy również zachowują opakowania specyficzne dla transportu lokalnie, gdy
zachowanie nie jest czysto współdzielone między rodzinami. Obecny przykład: plugin xAI
dołączony do repozytorium zachowuje natywne kształtowanie Responses xAI we własnym
wrapStreamFn, w tym przepisywanie aliasów /fast, domyślne tool_stream,
czyszczenie nieobsługiwanych ścisłych narzędzi oraz usuwanie ładunku
rozumowania specyficznego dla xAI.openclaw/plugin-sdk/provider-tools obecnie udostępnia jedną współdzieloną
rodzinę schematów narzędzi oraz współdzielone helpery schematu/zgodności:ProviderToolCompatFamilydokumentuje obecny zestaw współdzielonych rodzin.buildProviderToolCompatFamilyHooks("gemini")podłącza czyszczenie schematu Gemini + diagnostykę dla providerów, którzy potrzebują schematów narzędzi bezpiecznych dla Gemini.normalizeGeminiToolSchemas(...)iinspectGeminiToolSchemas(...)są bazowymi publicznymi helperami schematu Gemini.resolveXaiModelCompatPatch()zwraca dołączoną łatkę zgodności xAI:toolSchemaProfile: "xai", nieobsługiwane słowa kluczowe schematu, natywne wsparcieweb_searchoraz dekodowanie argumentów wywołań narzędzi z encji HTML.applyXaiModelCompat(model)stosuje tę samą łatkę zgodności xAI do rozpoznanego modelu, zanim trafi on do runnera.
normalizeResolvedModel oraz
contributeResolvedModelCompat, aby zachować te metadane zgodności po stronie
providera zamiast wpisywać reguły xAI na sztywno w rdzeniu.Ten sam wzorzec z katalogiem głównym pakietu wspiera również innych dołączonych providerów:@openclaw/openai-provider:api.tseksportuje buildery providerów, helpery modeli domyślnych oraz buildery providerów realtime@openclaw/openrouter-provider:api.tseksportuje builder providera oraz helpery onboarding/config
- Wymiana tokena
- Niestandardowe nagłówki
- Tożsamość natywnego transportu
- Zużycie i rozliczenia
Dla providerów, którzy potrzebują wymiany tokena przed każdym wywołaniem inferencji:
Wszystkie dostępne hooki providera
Wszystkie dostępne hooki providera
OpenClaw wywołuje hooki w tej kolejności. Większość providerów używa tylko 2–3:
Uwagi dotyczące fallbacku runtime:
| # | Hook | Kiedy używać |
|---|---|---|
| 1 | catalog | Katalog modeli lub domyślne wartości baseUrl |
| 2 | applyConfigDefaults | Globalne wartości domyślne należące do providera podczas materializacji konfiguracji |
| 3 | normalizeModelId | Czyszczenie aliasów starszych/podglądowych identyfikatorów modeli przed wyszukiwaniem |
| 4 | normalizeTransport | Czyszczenie api / baseUrl rodziny providera przed ogólnym składaniem modelu |
| 5 | normalizeConfig | Normalizacja konfiguracji models.providers.<id> |
| 6 | applyNativeStreamingUsageCompat | Przepisania zgodności natywnego strumieniowania użycia dla providerów konfiguracyjnych |
| 7 | resolveConfigApiKey | Rozpoznawanie uwierzytelniania markerów env należące do providera |
| 8 | resolveSyntheticAuth | Syntetyczne uwierzytelnianie lokalne/self-hosted lub oparte na konfiguracji |
| 9 | shouldDeferSyntheticProfileAuth | Obniżanie priorytetu syntetycznych placeholderów zapisanych profili względem uwierzytelniania env/config |
| 10 | resolveDynamicModel | Akceptowanie dowolnych identyfikatorów modeli upstream |
| 11 | prepareDynamicModel | Asynchroniczne pobranie metadanych przed rozpoznaniem |
| 12 | normalizeResolvedModel | Przepisania transportu przed runnerem |
-
normalizeConfignajpierw sprawdza dopasowanego providera, a następnie inne pluginy providerów obsługujące hooki, dopóki któryś faktycznie nie zmieni konfiguracji. Jeśli żaden hook providera nie przepisze obsługiwanego wpisu konfiguracji rodziny Google, nadal zostanie zastosowany dołączony normalizator konfiguracji Google. -
resolveConfigApiKeyużywa hooka providera, gdy jest on udostępniony. Dołączona ścieżkaamazon-bedrockma tu także wbudowany resolver markerów środowiska AWS, mimo że samo uwierzytelnianie runtime Bedrock nadal używa domyślnego łańcucha AWS SDK. | 13 |contributeResolvedModelCompat| Flagi zgodności dla modeli dostawcy działających za innym zgodnym transportem | | 14 |capabilities| Starszy statyczny zestaw możliwości; tylko dla zgodności | | 15 |normalizeToolSchemas| Czyszczenie schematów narzędzi należące do providera przed rejestracją | | 16 |inspectToolSchemas| Diagnostyka schematów narzędzi należąca do providera | | 17 |resolveReasoningOutputMode| Kontrakt wyjścia rozumowania: tagowane czy natywne | | 18 |prepareExtraParams| Domyślne parametry żądania | | 19 |createStreamFn| W pełni niestandardowy transport StreamFn | | 20 |wrapStreamFn| Opakowania niestandardowych nagłówków/treści na zwykłej ścieżce strumienia | | 21 |resolveTransportTurnState| Natywne nagłówki/metadane dla każdej tury | | 22 |resolveWebSocketSessionPolicy| Natywne nagłówki sesji WS / czas odnowienia | | 23 |formatApiKey| Niestandardowy kształt tokena runtime | | 24 |refreshOAuth| Niestandardowe odświeżanie OAuth | | 25 |buildAuthDoctorHint| Wskazówki naprawy uwierzytelniania | | 26 |matchesContextOverflowError| Wykrywanie przepełnienia należące do providera | | 27 |classifyFailoverReason| Klasyfikacja ograniczeń szybkości/przeciążenia należąca do providera | | 28 |isCacheTtlEligible| Bramka TTL pamięci podręcznej promptów | | 29 |buildMissingAuthMessage| Niestandardowa wskazówka o braku uwierzytelniania | | 30 |suppressBuiltInModel| Ukrywanie nieaktualnych wierszy upstream | | 31 |augmentModelCatalog| Syntetyczne wiersze zgodności z przyszłością | | 32 |isBinaryThinking| Binarne thinking włączone/wyłączone | | 33 |supportsXHighThinking| Obsługa rozumowaniaxhigh| | 34 |resolveDefaultThinkingLevel| Domyślne zasady/think| | 35 |isModernModelRef| Dopasowanie modeli live/smoke | | 36 |prepareRuntimeAuth| Wymiana tokena przed inferencją | | 37 |resolveUsageAuth| Niestandardowe parsowanie poświadczeń użycia | | 38 |fetchUsageSnapshot| Niestandardowy endpoint użycia | | 39 |createEmbeddingProvider| Adapter embeddingów należący do providera dla pamięci/wyszukiwania | | 40 |buildReplayPolicy| Niestandardowe zasady replay/kompaktacji transkryptu | | 41 |sanitizeReplayHistory| Przepisania replay specyficzne dla providera po ogólnym czyszczeniu | | 42 |validateReplayTurns| Ścisła walidacja tur replay przed osadzonym runnerem | | 43 |onModelSelected| Callback po wyborze modelu (np. telemetria) | Uwaga dotycząca dostrajania promptów:resolveSystemPromptContributionpozwala providerowi wstrzykiwać wskazówki do promptu systemowego świadome pamięci podręcznej dla danej rodziny modeli. Preferuj to zamiastbefore_prompt_build, gdy zachowanie należy do jednej rodziny providera/modelu i powinno zachować stabilny/dynamiczny podział pamięci podręcznej.
Dodaj dodatkowe możliwości (opcjonalnie)
Plugin providera może rejestrować mowę, transkrypcję realtime, głos realtime,
rozumienie multimediów, generowanie obrazów, generowanie wideo, pobieranie z sieci
i wyszukiwanie w sieci obok inferencji tekstu:OpenClaw klasyfikuje to jako plugin o możliwościach hybrydowych. Jest to
zalecany wzorzec dla pluginów firmowych (jeden plugin na dostawcę). Zobacz
Wnętrza: Własność możliwości.W przypadku generowania wideo preferuj pokazany powyżej kształt możliwości
uwzględniający tryby:
generate, imageToVideo i videoToVideo. Płaskie pola zbiorcze, takie
jak maxInputImages, maxInputVideos i maxDurationSeconds, nie
wystarczają, aby w przejrzysty sposób reklamować obsługę trybów transformacji lub wyłączonych trybów.Providery generowania muzyki powinny stosować ten sam wzorzec:
generate dla generowania wyłącznie na podstawie promptu i edit dla generowania
opartego na obrazie referencyjnym. Płaskie pola zbiorcze, takie jak maxInputImages,
supportsLyrics i supportsFormat, nie wystarczają do reklamowania obsługi
edycji; oczekiwanym kontraktem są jawne bloki generate / edit.Publikowanie do ClawHub
Pluginy providerów publikuje się tak samo jak każdy inny zewnętrzny plugin kodu:clawhub package publish.
Struktura plików
Dokumentacja referencyjna kolejności katalogu
catalog.order kontroluje, kiedy twój katalog jest scalany względem
wbudowanych providerów:
| Kolejność | Kiedy | Przypadek użycia |
|---|---|---|
simple | Pierwsze przejście | Zwykli providerzy z kluczem API |
profile | Po simple | Providery zależne od profili uwierzytelniania |
paired | Po profile | Syntetyzowanie wielu powiązanych wpisów |
late | Ostatnie przejście | Nadpisywanie istniejących providerów (wygrywa przy kolizji) |
Następne kroki
- Pluginy kanałów — jeśli twój plugin udostępnia także kanał
- SDK Runtime — helpery
api.runtime(TTS, search, subagent) - Przegląd SDK — pełna dokumentacja referencyjna importów subpath
- Wnętrza pluginów — szczegóły hooków i dołączone przykłady