CLI modeli

Referencje modeli wybierają dostawcę i model. Zwykle nie wybierają niskopoziomowego środowiska uruchomieniowego agenta. Głównym wyjątkiem są referencje agentów OpenAI: openai/gpt-5.5 domyślnie działa przez środowisko uruchomieniowe serwera aplikacji Codex u oficjalnego dostawcy OpenAI. Referencje subskrypcyjne Copilot (github-copilot/*) mogą dodatkowo zostać włączone do zewnętrznego pluginu środowiska uruchomieniowego agenta GitHub Copilot — ta ścieżka pozostaje jawna (bez rezerwowego auto). Jawne nadpisania środowiska uruchomieniowego należą do zasad dostawcy/modelu, a nie do całego agenta ani sesji. W trybie środowiska uruchomieniowego Codex referencja openai/gpt-* nie implikuje rozliczania kluczem API; uwierzytelnianie może pochodzić z konta Codex albo profilu OAuth openai. Zobacz Środowiska uruchomieniowe agentów i Środowisko uruchomieniowe agenta GitHub Copilot.

Jak działa wybór modelu

OpenClaw wybiera modele w tej kolejności:

Źródło wyboru i zachowanie rezerwowe

Ten sam provider/model może oznaczać różne rzeczy w zależności od tego, skąd pochodzi:

• Skonfigurowane wartości domyślne (agents.defaults.model.primary oraz podstawowe modele specyficzne dla agentów) są normalnym punktem startowym i używają agents.defaults.model.fallbacks.
• Automatyczne wybory rezerwowe są tymczasowym stanem odzyskiwania. Są przechowywane z modelOverrideSource: "auto", aby kolejne tury mogły nadal używać łańcucha rezerwowego bez każdorazowego sprawdzania znanego jako wadliwy modelu podstawowego; OpenClaw okresowo ponownie sprawdza pierwotny model podstawowy, czyści automatyczny wybór po jego odzyskaniu i ogłasza przejścia na rezerwę/odzyskanie raz na zmianę stanu.
• Wybory sesji użytkownika są dokładne. /model, selektor modelu, session_status(model=...) i sessions.patch zapisują modelOverrideSource: "user"; jeśli wybrany dostawca/model jest nieosiągalny, OpenClaw zgłasza widoczną awarię zamiast przechodzić do innego skonfigurowanego modelu.
• Zmiana agents.defaults.model.primary nie przepisuje istniejących wyborów sesji. Jeśli status mówi This session is pinned to X; config primary Y will apply to new/unpinned sessions., wyczyść wybór bieżącej sesji przez /model default, aby znów dziedziczyła skonfigurowany model podstawowy.
• Cron --model / ładunek model jest modelem podstawowym dla zadania. Nadal używa skonfigurowanych rezerw, chyba że zadanie dostarcza jawne fallbacks w ładunku (użyj fallbacks: [] dla ścisłego uruchomienia Cron).
• Selektory domyślnego modelu CLI i listy dozwolonych respektują models.mode: "replace", wyświetlając jawne models.providers.*.models zamiast ładować pełny wbudowany katalog.
• Selektor modeli w Control UI pyta Gateway o skonfigurowany widok modeli: agents.defaults.models, gdy jest obecne, w tym wpisy całych dostawców provider/*, w przeciwnym razie jawne models.providers.*.models plus dostawców z użytecznym uwierzytelnianiem. Pełny wbudowany katalog jest zarezerwowany dla jawnych widoków przeglądania, takich jak models.list z view: "all" albo openclaw models list --all.

Szybka polityka modeli

• Ustaw model podstawowy na najsilniejszy dostępny dla Ciebie model najnowszej generacji.
• Używaj rezerw dla zadań wrażliwych na koszt/opóźnienia oraz rozmów o niższej wadze.
• W przypadku agentów z narzędziami lub niezaufanych danych wejściowych unikaj starszych/słabszych poziomów modeli.

Onboarding (zalecane)

Jeśli nie chcesz ręcznie edytować konfiguracji, uruchom onboarding:

openclaw onboard

Może skonfigurować model i uwierzytelnianie dla typowych dostawców, w tym subskrypcję OpenAI Code (Codex) (OAuth) i Anthropic (klucz API albo Claude CLI).

Klucze konfiguracji (przegląd)

• agents.defaults.model.primary i agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary i agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary i agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary i agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary i agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models (lista dozwolonych + aliasy + parametry dostawcy + dynamiczne wpisy dostawców provider/*)
• models.providers (niestandardowi dostawcy zapisani w models.json)

Bezpieczne edycje listy dozwolonych

Używaj zapisów addytywnych podczas ręcznego aktualizowania agents.defaults.models:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

„Model jest niedozwolony” (i dlaczego odpowiedzi się zatrzymują)

Jeśli agents.defaults.models jest ustawione, staje się listą dozwolonych dla /model oraz nadpisań sesji. Gdy użytkownik wybierze model, którego nie ma na tej liście dozwolonych, OpenClaw zwraca:

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Gdy odrzucone polecenie zawierało nadpisanie środowiska uruchomieniowego, takie jak /model openai/gpt-5.5 --runtime codex, najpierw napraw listę dozwolonych, a następnie ponów to samo polecenie /model ... --runtime .... W przypadku natywnego wykonywania Codex wybrany model nadal ma postać openai/gpt-5.5; środowisko uruchomieniowe codex wybiera uprząż i osobno używa uwierzytelniania Codex.

W przypadku modeli lokalnych/GGUF przechowuj na liście dozwolonych pełną referencję z prefiksem dostawcy, na przykład ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf albo dokładny dostawca/model pokazany przez openclaw models list --provider <provider>. Same lokalne nazwy plików albo nazwy wyświetlane nie wystarczą, gdy lista dozwolonych jest aktywna.

Jeśli chcesz ograniczyć dostawców bez ręcznego wypisywania każdego modelu, dodaj wpisy provider/* do agents.defaults.models:

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

Przy takiej polityce /model, /models i selektory modeli pokazują wykryty katalog tylko dla tych dostawców. Nowe modele od wybranych dostawców mogą pojawiać się bez edytowania listy dozwolonych. Dokładne wpisy provider/model można mieszać z wpisami provider/*, gdy potrzebujesz jednego konkretnego modelu od innego dostawcy.

Przykładowa konfiguracja listy dozwolonych:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-sonnet-4-6" },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },}

Przełączanie modeli na czacie (/model)

Możesz przełączać modele dla bieżącej sesji bez restartu:

/model/model list/model 3/model openai/gpt-5.4/model default/model status

Pełne zachowanie poleceń/konfiguracja: Polecenia ukośnikowe.

Polecenia CLI

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw models image-fallbacks add <provider/model>openclaw models image-fallbacks remove <provider/model>openclaw models image-fallbacks clear

openclaw models (bez podpolecenia) to skrót dla models status.

models list

Domyślnie pokazuje skonfigurowane/dostępne po uwierzytelnieniu modele. Przydatne flagi:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Filtruj według identyfikatora dostawcy, na przykład moonshot. Etykiety wyświetlane z interaktywnych selektorów nie są akceptowane.

models status

Pokazuje rozwiązany model główny, modele zapasowe, model obrazu oraz przegląd uwierzytelniania skonfigurowanych dostawców. Pokazuje także status wygaśnięcia OAuth dla profili znalezionych w magazynie uwierzytelniania (domyślnie ostrzega w ciągu 24 godzin). --plain wypisuje tylko rozwiązany model główny.

Przykład (Claude CLI):

claude auth loginopenclaw models status

Skanowanie (darmowe modele OpenRouter)

openclaw models scan sprawdza katalog darmowych modeli OpenRouter i opcjonalnie może sondować modele pod kątem obsługi narzędzi i obrazów.

Wyniki skanowania są klasyfikowane według:

1. Obsługi obrazów
2. Opóźnienia narzędzi
3. Rozmiaru kontekstu
4. Liczby parametrów

Dane wejściowe:

• Lista OpenRouter /models (filtr :free)
• Sondy na żywo wymagają klucza API OpenRouter z profili uwierzytelniania lub OPENROUTER_API_KEY (zobacz Zmienne środowiskowe)
• Opcjonalne filtry: --max-age-days, --min-params, --provider, --max-candidates
• Kontrole żądań/sond: --timeout, --concurrency

Gdy sondy na żywo działają w TUI, możesz interaktywnie wybrać modele zapasowe. W trybie nieinteraktywnym przekaż --yes, aby zaakceptować wartości domyślne. Wyniki wyłącznie metadanych mają charakter informacyjny; --set-default i --set-image wymagają sond na żywo, aby OpenClaw nie skonfigurował bezużytecznego modelu OpenRouter bez klucza.

Rejestr modeli (models.json)

Niestandardowi dostawcy w models.providers są zapisywani do models.json w katalogu agenta (domyślnie ~/.openclaw/agents/<agentId>/agent/models.json). Katalogi dostawców-pluginów są przechowywane jako wygenerowane fragmenty katalogu należące do pluginu w stanie pluginu agenta i ładowane automatycznie. Ten plik jest domyślnie scalany, chyba że models.mode jest ustawione na replace.

Powiązane

• Środowiska wykonawcze agentów — OpenClaw, Codex i inne środowiska wykonawcze pętli agentów
• Dokumentacja konfiguracji — klucze konfiguracji modeli
• Generowanie obrazów — konfiguracja modelu obrazów
• Przełączanie awaryjne modeli — łańcuchy zapasowe
• Dostawcy modeli — routing dostawców i uwierzytelnianie
• Generowanie muzyki — konfiguracja modelu muzyki
• Generowanie wideo — konfiguracja modelu wideo