Dobór modelu, własne klucze API i zapasowy dostawca w OpenClaw

Gdzie w OpenClaw w ogóle ustawia się model

Model wybierasz kluczem agents.defaults.model.primary, w formacie provider/model. Zamiast obiektu można podać sam string — silnik zrozumie skrót. Katalog dostępnych referencji podglądasz komendą openclaw models list, a openclaw models list --all pokazuje wszystko, co dostawcy zgłaszają. Ustawienie domyślnego to openclaw models set <model-or-alias>.

Sesja czatu ma własny nadpis i to bywa źródłem nieporozumień. Komenda /model przypina model do bieżącej rozmowy, /model list pokazuje wybór, /model status stan, a /model default zdejmuje przypięcie. Przypięcie zostaje, dopóki go nie zdejmiesz. Ktoś testuje flagowy model w poniedziałek, zapomina o tym do piątku i dziwi się rachunkowi.

Jeśli w firmie ma być twardo ustalone, czego agent użyć nie może, służy do tego agents.defaults.modelPolicy.allow. Przyjmuje dokładne referencje albo wzorce w rodzaju provider/*, a odpowiednik per agent to agents.entries.*.modelPolicy.allow. Bez tej listy każdy, kto ma dostęp do czatu, może przełączyć agenta na dowolną pozycję z katalogu — łącznie z najdroższą.

Stan uwierzytelnienia i to, który endpoint faktycznie odpowiada, pokazuje openclaw models status. Flaga --probe robi żywe sprawdzenie, --check zwraca kod wyjścia 1 przy brakujących lub wygasłych poświadczeniach i kod 2 przy wygasających. Ten drugi kod jest wart zapamiętania: daje się wpiąć w monitoring i dowiedzieć się o wygasającym kluczu przed weekendem, a nie w jego trakcie.

openclaw models list
openclaw models set <model-or-alias>
openclaw models status --probe --check

Cztery role modeli obok prymarnego

Poza modelem prymarnym są cztery role: utility, image, pdf i media (ten ostatni rozbity na image, music i video). agents.defaults.utilityModel obsługuje zadania wewnętrzne po niższym koszcie. agents.defaults.imageModel wchodzi wtedy, gdy prymarny nie przyjmuje obrazów. agents.defaults.pdfModel obsługuje narzędzie pdf, a agents.defaults.mediaModels.{image,music,video} generowanie mediów.

utilityModel domyślnie schodzi na mały model dostawcy — dla OpenAI jest to gpt-5.6-luna, dla Anthropic claude-haiku-4-5. Zostaw to tak, jak jest. Najczęstszy sposób na ciche potrojenie rachunku wygląda tak, że ktoś wpisuje w to pole model flagowy, „żeby agent był mądrzejszy”, i od tej pory każda operacja pomocnicza kosztuje kilka razy więcej niż powinna.

Przy kilku agentach ręczne pilnowanie tych pól przestaje działać. Wtedy przydają się aliasy: openclaw models aliases add <alias> <model-or-alias>, openclaw models aliases list, openclaw models aliases remove <alias>. Trzymasz w configu nazwę własną, a przesiadkę robisz w jednym miejscu zamiast w siedmiu.

Nadpisy per agent siedzą w agents.entries.*.model oraz agents.entries.*.utilityModel. To wygodne w układzie, w którym jeden agent obsługuje klientów, a drugi tylko przekłada powiadomienia z jednego kanału do drugiego. Drugi nie potrzebuje flagowego modelu i nie ma powodu, żeby go dostał.

openclaw models aliases add glowny <provider/model>
openclaw models aliases list --json

BYOK: gdzie wpiąć klucz i w jakiej kolejności OpenClaw go szuka

BYOK znaczy tyle, że tokeny rozliczasz bezpośrednio u dostawcy modelu, na własnej umowie i własnym rachunku. Klucz ma leżeć na hoście gatewaya, czyli na maszynie, na której faktycznie działa openclaw gateway. Dokumentacja podaje dwa miejsca: zmienne środowiskowe procesu albo plik ~/.openclaw/.env. Dla zawsze włączonego hosta to podejście jest opisane jako zalecane.

Kolejność szukania kluczy jest ustalona i przydaje się dokładnie wtedy, gdy „klucz jest, a nie działa”. OpenClaw sprawdza po kolei OPENCLAW_LIVE_<PROVIDER>_KEY, potem <PROVIDER>_API_KEYS (wartości rozdzielane przecinkiem, spacją lub średnikiem), potem <PROVIDER>_API_KEY, a na końcu <PROVIDER>_API_KEY_* z dowolnym sufiksem. Jeden szczegół zmienia sposób myślenia o rotacji: klucze przełączają się wyłącznie przy błędach limitu. Inna awaria nie spowoduje ponowienia z drugim kluczem.

Klucz można też wkleić przez CLI, bez dotykania plików. openclaw models auth paste-api-key --provider <id> wsadza go do profilu, openclaw models auth list --provider <id> pokazuje, co jest zapisane. Anthropic ma dwie dodatkowe drogi: openclaw models auth setup-token --provider <id> oraz przejęcie logowania z Claude CLI przez openclaw models auth login --provider anthropic --method cli --set-default. Przy kilku kontach u jednego dostawcy rozdzielasz je flagą --profile-id, a w czacie wybierasz przez /model <id>@<profileId>.

Dostawcę spoza katalogu — własny endpoint albo bramkę zgodną z API OpenAI — konfigurujesz w models.providers.<id>.apiKey oraz models.providers.<id>.baseUrl. Klucz models.mode decyduje, czy Twoje wpisy dokładają się do katalogu hostowanego (merge), czy go zastępują (replace).

I rzecz, którą dokumentacja bezpieczeństwa mówi wprost, a którą i tak wszyscy łamią: poświadczenia dostawcy nie mają prawa leżeć w pliku .env w workspace agenta. Workspace bywa w repozytorium git, jest czytany przez narzędzia agenta i wędruje razem z projektem. Klucz należy do środowiska procesu gatewaya, globalnego dotenv albo configu.

# ~/.openclaw/.env — na hoście gatewaya
OPENAI_API_KEY=...

openclaw models auth paste-api-key --provider <id>
openclaw models auth list --provider <id> --json

Zapasowy dostawca ratuje agenta tylko przy części awarii

Awaria dostawcy nie musi zatrzymywać agenta, ale obsługa idzie w dwóch etapach. OpenClaw najpierw rotuje profile uwierzytelniania w obrębie tego samego dostawcy, a dopiero potem schodzi na kolejny model z listy zapasowej. Listę ustawiasz w agents.defaults.model.fallbacks albo komendami openclaw models fallbacks add, remove, list i clear. Obrazy mają własny łańcuch: openclaw models image-fallbacks.

Przełączenie uruchamiają błędy uwierzytelniania, limity, przeciążenie po stronie dostawcy, timeouty oraz wyłączenia z powodu rozliczeń. Nie uruchamia go przepełnienie kontekstu ani jawne przerwanie zadania. To rozróżnienie oszczędza godziny zgadywania. Jeśli agent wywala się na zbyt długim prompcie, żaden fallback go nie uratuje, bo drugi model dostanie dokładnie ten sam za duży prompt.

Cooldown po limicie rośnie schodkowo: 30 sekund po pierwszym błędzie, minuta po drugim, potem pięć minut. Błędy rozliczeniowe działają inaczej — kończą się dłuższym wyłączeniem profilu, nie krótką pauzą. Profil jest przypinany do sesji, żeby cache dostawcy pozostał ciepły, i rotuje dopiero przy limicie, cooldownie albo wyłączeniu. Kolejność profili ustawisz przez openclaw models auth order set --provider <id> <profileIds...>.

Skąd wziął się wybór modelu, decyduje o tym, czy fallback w ogóle zadziała. Konfiguracyjne wartości domyślne korzystają z łańcucha zapasowego. Prymarne modele agenta są traktowane sztywno, chyba że same mają zdefiniowane fallbacki. Wybór użytkownika przez /model albo przez picker jest dokładny i nie przełączy się po cichu przy awarii. Zadania cron biorą skonfigurowane fallbacki, o ile samo zadanie nie ma własnych.

Przełączenie działa w obrębie jednej tury. Runner utrwala tylko notatkę o użyciu fallbacku, a wybór modelu w sesji się nie zmienia. Agent nie „przeprowadzi się” trwale na tańszy model dlatego, że dostawca miał godzinę słabości.

openclaw models fallbacks add <model-or-alias>
openclaw models fallbacks list --plain
openclaw models auth order set --provider <id> <profileIds...>

Rachunek robi kontekst, nie cena modelu

Że rachunek robi wejście, a nie cena modelu, ustaliliśmy w lekcji czwartej. Tutaj interesuje nas, którymi komendami to zobaczysz i w którym kluczu ustawisz cennik.

Jedna liczba na kotwicę. Model po 3 USD za milion tokenów wejścia i 15 USD za milion wyjścia, 320 tur dziennie, średnio 12 000 tokenów wejścia na turę i 400 tokenów odpowiedzi — razem 403,20 USD miesięcznie, z czego 345,60 USD to samo wejście, czyli 86 procent. Zejście ze średnich 12 000 tokenów wejścia do 7 000 daje 259,20 USD przy tym samym modelu i tej samej liczbie rozmów.

Zużycie sprawdzasz w czacie i z CLI. /status pokazuje model sesji, wykorzystanie kontekstu i tokeny ostatniej odpowiedzi. /usage tokens daje szczegóły tury razem z cache, /usage full rozbicie kosztów, /usage cost samo podsumowanie, /usage off wyłącza wyświetlanie. /context list i /context detail pokazują, ile tokenów zjada każdy plik, każde narzędzie i każdy skill. openclaw status --usage dokłada okna limitów u dostawcy jako procent pozostały.

Kwoty w złotówkach albo dolarach pojawią się dopiero wtedy, gdy podasz cennik. Ustawia się go w models.providers.<provider>.models[].cost, w USD za milion tokenów, osobno dla wejścia, wyjścia, odczytów z cache i zapisów do cache. Bez tego zobaczysz tokeny i nic więcej. Zbiorcze zestawienie po dostawcach, modelach i zakresach dat daje Control UI w sekcji Usage.

/status
/usage tokens
/context detail
openclaw status --usage

Cache promptu to najtańszy ruch, jaki możesz zrobić

Cache promptu pozwala dostawcy ponownie użyć niezmienionego początku promptu — instrukcji systemowych, definicji narzędzi, stabilnego kontekstu — zamiast liczyć go od nowa przy każdej turze. Główna gałka to cacheRetention z trzema wartościami: „none”, „short” (domyślne u dostawcy, zwykle 5 minut) i „long” (wydłużony TTL). Ustawiasz ją globalnie w agents.defaults.params.cacheRetention, per model w agents.defaults.models["provider/model"].params.cacheRetention albo per agent w agents.entries.*.params.cacheRetention.

Wsparcie różni się między dostawcami. Anthropic — bezpośrednio, przez Vertex AI i Bedrock — wystawia jawnie cache_read_input_tokens i cache_creation_input_tokens, a „long” prosi o godzinny TTL tam, gdzie endpoint na to pozwala. OpenAI robi to automatycznie na nowszych modelach, używa prompt_cache_key do stabilnego routingu i przy długiej retencji ustawia prompt_cache_retention na „24h”. Gemini zarządza cache automatycznie w rodzinach gemini-2.5* i gemini-3*. Przez OpenRouter cache wchodzi na trasach Anthropic i DeepSeek.

OpenClaw pilnuje, żeby sam sobie nie zniszczyć cache. Prompt systemowy jest dzielony na część stabilną i zmienną, pliki kontekstu projektu z workspace idą przed metadanymi generowanymi co turę, a katalog narzędzi jest sortowany deterministycznie. Dzięki temu zwykły ruch w sesji nie unieważnia stabilnego prefiksu.

Wzorzec, który działa przy mieszanym ruchu, jest prosty: długa retencja na agentach głównych, cache wyłączony na agentach powiadomieniowych, które odzywają się rzadko i krótko. Do tego contextPruning.mode ustawiony na „cache-ttl”, żeby przycinać historię po okresie bezczynności i nie płacić za odtwarzanie cache, z którego nikt już nie skorzysta.

{
  agents: {
    defaults: {
      params: { cacheRetention: "long" }
    }
  }
}

Co jeszcze wydaje Twoje pieniądze, kiedy nie patrzysz

Odpowiedzi modelu to główne, ale nie jedyne źródło rachunku. Dokumentacja wymienia osobno: streszczanie i transkrypcję audio, obrazów oraz wideo przez API dostawcy, narzędzia image_generate i video_generate, embeddingi pamięci przy zdalnych adapterach (OpenAI, Gemini, Voyage, Mistral), wyszukiwanie w sieci, pobieranie stron przez Firecrawl, tryb głosowy oparty na ElevenLabs oraz skille wołające zewnętrzne API.

Wyszukiwarki mają tu ciekawy podział. Brave, Exa, Firecrawl, Gemini i Tavily kosztują, a DuckDuckGo i SearXNG są darmowe. Jeśli agent researchuje dużo i płytko, sama zmiana providera wyszukiwania potrafi zdjąć z rachunku więcej niż przesiadka modelu. Osobna pozycja: openclaw status --usage odpytuje endpointy limitów u dostawcy, więc odpalanie tego w pętli co minutę też nie jest darmowe.

Klucze do tego wszystkiego siedzą w kilku miejscach naraz i to jest najczęstszy powód, dla którego audyt kosztów się nie domyka. Sprawdź plik auth-profiles.json, zmienne środowiskowe (na przykład OPENAI_API_KEY albo BRAVE_API_KEY), ścieżki models.providers.*.apiKey, plugins.entries.*.config, memory.search.* oraz skills.entries.<name>.apiKey. Dopóki nie przejdziesz przez całą tę listę, „nie wiem, skąd ten rachunek” jest uzasadnione.

Praktyczna kolejność przy cięciu kosztów wygląda tak: najpierw /context detail, żeby zobaczyć, co zajmuje prompt, potem /compact na długich rozmowach, potem przycięcie rozdmuchanych wyjść z narzędzi, potem agents.defaults.imageMaxDimensionPx przy pracy ze zrzutami ekranu, i dopiero na końcu zmiana modelu. Opisy skilli też idą do promptu, więc rozwlekły opis kosztuje przy każdej turze.

Przesiadka na inny model bez psucia produkcji

Zacznij od odświeżenia katalogu, bo połowa „nieistniejących modeli” to nieaktualna lista. Robi to openclaw models refresh. Zachowaniem katalogu sterują models.catalogRefresh.enabled (domyślnie włączone) i models.catalogRefresh.url, jeśli chcesz wskazać własne lustro po HTTPS.

Nowy model testuj w sesji, nie w configu. Przypnij go przez /model, przepuść przez niego swoje prawdziwe zapytania, sprawdź /usage tokens i dopiero potem ustaw globalnie przez openclaw models set. Przy okazji odpal openclaw models status --probe, żeby potwierdzić, że poświadczenia dla nowego dostawcy faktycznie działają, a nie tylko wyglądają na skonfigurowane.

Zanim wypuścisz zmianę dalej, dopisz nowy model do modelPolicy.allow i sprawdź, czy stary został na liście fallbacków. Częsty błąd polega na przełączeniu prymarnego modelu i zostawieniu w fallbackach modelu, którego już nikt nie autoryzuje — łańcuch zapasowy wtedy istnieje tylko na papierze.

Po przesiadce policz koszt jeszcze raz, bo profil kosztowy się zmienia. Inny dostawca to inne stawki za odczyt z cache, inne okno kontekstu i inna długość odpowiedzi przy tym samym prompcie. Jeśli hostujesz agenta sam, cała ta robota jest po Twojej stronie; w wariancie chmurowym, na przykład w ClawLabs, część providerów działa w abonamencie, a Anthropic, OpenAI i Google wymagają wklejenia własnego klucza. Sam mechanizm BYOK jest ten sam.

openclaw models refresh
/model list
openclaw models status --probe
openclaw models set <model-or-alias>