Tworzenie wtyczek providerów
Ten przewodnik pokazuje, jak utworzyć wtyczkę providera, która dodaje providera modeli (LLM) do OpenClaw. Na końcu będziesz mieć providera z katalogiem modeli, uwierzytelnianiem kluczem API i dynamicznym rozwiązywaniem modeli.Jeśli wcześniej nie tworzyłeś żadnej wtyczki OpenClaw, najpierw przeczytaj
Pierwsze kroki, aby poznać podstawową strukturę
pakietu i konfigurację manifestu.
Przewodnik
Pakiet i manifest
providerAuthEnvVars, aby OpenClaw mógł wykrywać
poświadczenia bez ładowania runtime Twojej wtyczki. modelSupport jest opcjonalne
i pozwala OpenClaw automatycznie ładować Twoją wtyczkę providera na podstawie skróconych identyfikatorów modeli,
takich jak acme-large, zanim pojawią się hooki runtime. Jeśli publikujesz
providera w ClawHub, pola openclaw.compat i openclaw.build
są wymagane w package.json.Zarejestruj providera
Minimalny provider wymaga To jest działający provider. Użytkownicy mogą teraz wykonać
Jeśli Twój przepływ uwierzytelniania musi również 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.Dla 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 i
domyślny model agenta podczas onboardingu, użyj gotowych helperó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 w
zwykłym transporcie openai-completions, preferuj współdzielone helpery katalogu z
openclaw/plugin-sdk/provider-catalog-shared zamiast wpisywać na sztywno sprawdzenia identyfikatorów providerów.
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 jeśli wtyczka używa niestandardowego identyfikatora providera.Dodaj dynamiczne rozwiązywanie modeli
Jeśli Twój provider akceptuje dowolne identyfikatory modeli (jak proxy lub router),
dodaj Jeśli rozwiązywanie 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 przykłady dołączone do projektu:
Rzeczywiste przykłady dołączone do projektu:
catalog i resolveDynamicModel. Dodawaj hooki
stopniowo, zgodnie z potrzebami providera.Współdzielone konstruktory helperów obejmują teraz najczęstsze rodziny
zgodności replay/narzędzi, więc wtyczki zwykle nie muszą ręcznie podłączać każdego hooka osobno:| Family | Co podłączają |
|---|---|
openai-compatible | Współdzielona polityka replay w stylu OpenAI dla transportów zgodnych z OpenAI, w tym sanityzacja tool-call-id, poprawki kolejności assistant-first oraz ogólna walidacja tur Gemini tam, gdzie wymaga jej transport |
anthropic-by-model | Polityka replay uwzględniająca Claude, wybierana na podstawie modelId, dzięki czemu transporty komunikatów Anthropic dostają czyszczenie bloków myślenia specyficzne dla Claude tylko wtedy, gdy rozpoznany model jest rzeczywiście identyfikatorem Claude |
google-gemini | Natywna polityka replay Gemini wraz z sanityzacją bootstrap replay i oznaczonym trybem reasoning-output |
passthrough-gemini | Sanityzacja podpisu myśli Gemini dla modeli Gemini działających przez transporty proxy zgodne z OpenAI; nie włącza natywnej walidacji replay Gemini ani przepisania bootstrap |
hybrid-anthropic-openai | Hybrydowa polityka dla providerów, którzy łączą w jednej wtyczce powierzchnie modeli komunikatów Anthropic i zgodnych z OpenAI; opcjonalne odrzucanie bloków myślenia 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
| Family | Co podłączają |
|---|---|
google-thinking | Normalizacja ładunku myślenia Gemini na współdzielonej ścieżce strumienia |
kilocode-thinking | Wrapper rozumowania Kilo na współdzielonej ścieżce strumienia proxy, z pomijaniem wstrzykniętego myślenia dla kilo/auto i nieobsługiwanych identyfikatorów rozumowania proxy |
moonshot-thinking | Mapowanie binarnego natywnego ładunku myślenia Moonshot z konfiguracji i poziomu /think |
minimax-fast-mode | Przepisanie modelu MiniMax fast-mode na współdzielonej ścieżce strumienia |
openai-responses-defaults | Współdzielone natywne wrappery OpenAI/Codex Responses: nagłówki atrybucji, /fast/serviceTier, szczegółowość tekstu, natywne wyszukiwanie internetowe Codex, kształtowanie ładunku zgodności reasoning i zarządzanie kontekstem Responses |
openrouter-thinking | Wrapper rozumowania OpenRouter dla tras proxy, z centralnie obsługiwanym pomijaniem nieobsługiwanych modeli i auto |
tool-stream-default-on | Domyślnie włączony wrapper 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 także enum rodziny replay
oraz współdzielone helpery, z których te rodziny są budowane. Typowe publiczne eksporty
obejmują:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- współdzielone konstruktory replay, takie jak
buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...)ibuildHybridAnthropicOrOpenAIReplayPolicy(...) - helpery replay Gemini, takie jak
sanitizeGoogleGeminiReplayHistory(...)orazresolveTaggedReasoningOutputMode() - helpery endpointów/modeli, takie jak
resolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...)inormalizeNativeXaiModelId(...)
openclaw/plugin-sdk/provider-stream udostępnia zarówno konstruktor rodziny,
jak i publiczne helpery wrapperów, które te rodziny wykorzystują ponownie. Typowe publiczne eksporty
obejmują:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)- współdzielone wrappery OpenAI/Codex, takie jak
createOpenAIAttributionHeadersWrapper(...),createOpenAIFastModeWrapper(...),createOpenAIServiceTierWrapper(...),createOpenAIResponsesContextManagementWrapper(...)icreateCodexNativeWebSearchWrapper(...) - współdzielone wrappery proxy/providerów, takie jak
createOpenRouterWrapper(...),createToolStreamWrapper(...)icreateMinimaxFastModeWrapper(...)
@openclaw/anthropic-provider eksportuje
wrapAnthropicProviderStream, resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier oraz
niższopoziomowe konstruktory wrapperów Anthropic ze swojego publicznego interfejsu api.ts /
contract-api.ts. Te helpery pozostają specyficzne dla Anthropic, ponieważ
kodują także obsługę beta Claude OAuth i bramkowanie context1m.Inni dołączeni providerzy również przechowują lokalnie wrappery specyficzne dla transportu, gdy
zachowanie nie jest współdzielone w czysty sposób między rodzinami. Obecny przykład: dołączona
wtyczka xAI zachowuje natywne kształtowanie xAI Responses we własnym
wrapStreamFn, w tym przepisania 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 schematów/zgodności:ProviderToolCompatFamilydokumentuje aktualny zestaw współdzielonych rodzin.buildProviderToolCompatFamilyHooks("gemini")podłącza czyszczenie schematów Gemini i diagnostykę dla providerów, które potrzebują schematów narzędzi bezpiecznych dla Gemini.normalizeGeminiToolSchemas(...)iinspectGeminiToolSchemas(...)to bazowe publiczne helpery schematów 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ć własność tych metadanych zgodności po stronie
providera zamiast wpisywać reguły xAI na sztywno w core.Ten sam wzorzec katalogu głównego pakietu wspiera także innych dołączonych providerów:@openclaw/openai-provider:api.tseksportuje konstruktory providerów, helpery modeli domyślnych i konstruktory providerów realtime@openclaw/openrouter-provider:api.tseksportuje konstruktor providera oraz helpery onboardingu/konfiguracji
- Wymiana tokenów
- Niestandardowe nagłówki
- Tożsamość natywnego transportu
- Użycie i rozliczenia
Dla providerów, które wymagają wymiany tokena przed każdym wywołaniem inferencji:
Wszystkie dostępne hooki providerów
Wszystkie dostępne hooki providerów
OpenClaw wywołuje hooki w tej kolejności. Większość providerów używa tylko 2–3:
Uwagi dotyczące fallbacków runtime:
| # | Hook | Kiedy używać |
|---|---|---|
| 1 | catalog | Katalog modeli lub domyślne wartości baseUrl |
| 2 | applyConfigDefaults | Globalne wartości domyślne będące własnością providera podczas materializacji konfiguracji |
| 3 | normalizeModelId | Czyszczenie aliasów legacy/preview model-id przed wyszukaniem |
| 4 | normalizeTransport | Czyszczenie api / baseUrl rodziny providerów przed ogólnym złożeniem modelu |
| 5 | normalizeConfig | Normalizacja konfiguracji models.providers.<id> |
| 6 | applyNativeStreamingUsageCompat | Przepisania zgodności natywnego strumieniowania użycia dla providerów konfiguracyjnych |
| 7 | resolveConfigApiKey | Rozwiązywanie uwierzytelniania znaczników env będące własnością providera |
| 8 | resolveSyntheticAuth | Syntetyczne uwierzytelnianie lokalne/self-hosted lub oparte na konfiguracji |
| 9 | shouldDeferSyntheticProfileAuth | Obniżenie priorytetu syntetycznych placeholderów przechowywanych profili względem uwierzytelniania env/config |
| 10 | resolveDynamicModel | Akceptowanie dowolnych identyfikatorów modeli upstream |
| 11 | prepareDynamicModel | Asynchroniczne pobieranie metadanych przed rozpoznaniem |
| 12 | normalizeResolvedModel | Przepisania transportu przed runnerem |
-
normalizeConfignajpierw sprawdza dopasowanego providera, a następnie inne wtyczki providerów obsługujące hooki, dopóki któraś rzeczywiście nie zmieni konfiguracji. Jeśli żaden hook providera nie przepisze obsługiwanej konfiguracji rodziny Google, nadal zostanie zastosowany dołączony normalizator konfiguracji Google. -
resolveConfigApiKeyużywa hooka providera, jeśli jest udostępniony. Dołączona ścieżkaamazon-bedrockma tu także wbudowany resolver znaczników środowiskowych AWS, mimo że samo uwierzytelnianie runtime Bedrock nadal używa domyślnego łańcucha AWS SDK. | 13 |contributeResolvedModelCompat| Flagi zgodności dla modeli dostawcy za innym zgodnym transportem | | 14 |capabilities| Starszy statyczny zestaw możliwości; tylko zgodność | | 15 |normalizeToolSchemas| Czyszczenie schematów narzędzi będące własnością providera przed rejestracją | | 16 |inspectToolSchemas| Diagnostyka schematów narzędzi będąca własnością providera | | 17 |resolveReasoningOutputMode| Kontrakt tagged vs native dla reasoning-output | | 18 |prepareExtraParams| Domyślne parametry żądania | | 19 |createStreamFn| W pełni niestandardowy transport StreamFn | | 20 |wrapStreamFn| Wrappery niestandardowych nagłówków/body na zwykłej ścieżce strumienia | | 21 |resolveTransportTurnState| Natywne nagłówki/metadane dla pojedynczej tury | | 22 |resolveWebSocketSessionPolicy| Natywne nagłówki sesji WS / okres schładzania | | 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 będące własnością providera | | 27 |classifyFailoverReason| Klasyfikacja rate limit / przeciążenia będąca własnością providera | | 28 |isCacheTtlEligible| Bramka TTL pamięci podręcznej promptu | | 29 |buildMissingAuthMessage| Niestandardowa wskazówka dla brakującego uwierzytelniania | | 30 |suppressBuiltInModel| Ukrywanie nieaktualnych wierszy upstream | | 31 |augmentModelCatalog| Syntetyczne wiersze zgodności wprzód | | 32 |isBinaryThinking| Binarne thinking włączone/wyłączone | | 33 |supportsXHighThinking| Obsługa rozumowaniaxhigh| | 34 |resolveDefaultThinkingLevel| Domyślna polityka/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 będący własnością providera dla pamięci/wyszukiwania | | 40 |buildReplayPolicy| Niestandardowa polityka replay/kompaktowania transkrypcji | | 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 strojenia promptów:resolveSystemPromptContributionpozwala providerowi wstrzykiwać wskazówki system-prompt świadome cache dla rodziny modeli. Preferuj to zamiastbefore_prompt_build, gdy zachowanie należy do jednej rodziny provider/model i powinno zachować stabilny/dynamiczny podział cache.
Dodaj dodatkowe możliwości (opcjonalnie)
Wtyczka providera może rejestrować mowę, transkrypcję w czasie rzeczywistym, głos w czasie rzeczywistym,
rozumienie mediów, generowanie obrazów, generowanie wideo, pobieranie treści z internetu
i wyszukiwanie w internecie obok inferencji tekstowej:OpenClaw klasyfikuje to jako wtyczkę o hybrydowych możliwościach. Jest to
zalecany wzorzec dla wtyczek firmowych (jedna wtyczka na dostawcę). Zobacz
Elementy wewnętrzne: Własność możliwości.
Publikowanie w ClawHub
Wtyczki providerów publikuje się tak samo jak każdy inny zewnętrzny pakiet kodu:clawhub package publish.
Struktura plików
Dokumentacja catalog.order
catalog.order określa, kiedy Twój katalog jest scalany względem wbudowanych
providerów:
| Order | Kiedy | Przypadek użycia |
|---|---|---|
simple | Pierwsze przejście | Prości providerzy z kluczem API |
profile | Po simple | Providerzy zależni 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
- Wtyczki kanałów — jeśli Twoja wtyczka udostępnia także kanał
- SDK Runtime — helpery
api.runtime(TTS, wyszukiwanie, subagent) - Przegląd SDK — pełna dokumentacja importów subpath
- Elementy wewnętrzne wtyczek — szczegóły hooków i przykłady dołączone do projektu