CLI modeli

Odwołanie do modelu (provider/model) wybiera dostawcę i model, a nie niskopoziomowe środowisko uruchomieniowe agenta. Gdy zasady środowiska uruchomieniowego nie są ustawione lub mają wartość auto, należące do dostawcy OpenAI zasady trasowania mogą wybrać Codex wyłącznie dla dokładnej, oficjalnej trasy HTTPS Platform Responses lub ChatGPT Responses bez nadpisania żądania przez autora; sam prefiks openai/* nigdy nie wybiera Codex. Adaptery Completions, niestandardowe punkty końcowe oraz zachowanie żądania określone przez autora pozostają w OpenClaw. Oficjalne punkty końcowe HTTP przesyłające tekst jawny są odrzucane. Zobacz Niejawne środowisko uruchomieniowe agenta OpenAI.

Odwołania subskrypcji Copilot (github-copilot/*) można jawnie włączyć do zewnętrznego pluginu środowiska uruchomieniowego agenta GitHub Copilot, ale ta ścieżka zawsze jest jawna (nigdy nie wybiera jej auto). Nadpisania środowiska uruchomieniowego należy ustawiać w zasadach dostawcy/modelu, a nie dla całego agenta lub sesji. Wybór środowiska uruchomieniowego nie określa sposobu rozliczania: poświadczenia klucza API OpenAI oraz subskrypcji ChatGPT/Codex pozostają odrębne. Zobacz Środowiska uruchomieniowe agentów oraz Środowisko uruchomieniowe agenta GitHub Copilot.

Kolejność wyboru

Powiązane obszary konfiguracji modeli:

• agents.defaults.models to lista dozwolonych modeli i katalog modeli, z których może korzystać OpenClaw, wraz z aliasami. Wpisy provider/* pozwalają dopuścić wszystkie wykryte modele dostawcy bez wymieniania każdego z nich.
• agents.defaults.utilityModel to opcjonalny, tańszy model do krótkich zadań wewnętrznych, takich jak generowanie tytułów sesji panelu, tytułów wątków/tematów obsługiwanych kanałów oraz opisów postępu. Ustawienie agents.list[].utilityModel dla konkretnego agenta je nadpisuje. Gdy nie jest ustawione, OpenClaw używa zadeklarowanego przez podstawowego dostawcę domyślnego małego modelu, jeśli taki istnieje (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5), a w przeciwnym razie podstawowego modelu agenta; ustawienie pustego ciągu znaków wyłącza trasowanie zadań pomocniczych. Zadania pomocnicze są osobnymi wywołaniami modelu i mogą wysyłać ograniczoną zawartość zadania do wybranego dostawcy modelu.
• agents.defaults.imageModel jest używany tylko wtedy, gdy model podstawowy nie może przyjmować obrazów.
• agents.defaults.pdfModel jest używany przez narzędzie pdf. Jeśli nie jest ustawiony, narzędzie używa kolejno imageModel, a następnie ustalonego modelu sesji/modelu domyślnego.
• agents.defaults.imageGenerationModel, musicGenerationModel oraz videoGenerationModel obsługują współdzielone narzędzia generowania multimediów. Jeśli nie są ustawione, każde narzędzie ustala domyślnego dostawcę z dostępnym uwierzytelnianiem: najpierw bieżącego dostawcę domyślnego, a następnie pozostałych zarejestrowanych dostawców danej funkcji w kolejności identyfikatorów dostawców. Ustaw agents.defaults.mediaGenerationAutoProviderFallback: false, aby wyłączyć takie ustalanie między dostawcami, zachowując jawne modele rezerwowe.
• Ustawienie agents.list[].model dla konkretnego agenta (wraz z powiązaniami) nadpisuje agents.defaults.model — zobacz Trasowanie wielu agentów.

Pełna dokumentacja kluczy, wartości domyślnych i przykłady JSON5: Dokumentacja konfiguracji.

Źródło wyboru i rygor modeli rezerwowych

To samo ustawienie provider/model działa inaczej w zależności od źródła:

Pozostałe zasady wyboru:

• Zmiana agents.defaults.model.primary nie modyfikuje istniejących przypięć sesji. Jeśli stan wskazuje This session is pinned to X; config primary Y will apply to new/unpinned sessions., uruchom /model default, aby usunąć przypięcie.
• Selektory domyślnego modelu i listy dozwolonych modeli w CLI respektują models.mode: "replace", wyświetlając tylko models.providers.*.models zamiast pełnego wbudowanego katalogu.
• Selektor modelu w interfejsie Control UI pobiera z Gateway skonfigurowany widok modeli: agents.defaults.models, jeśli jest ustawione (w tym wpisy wieloznaczne provider/*), a w przeciwnym razie models.providers.*.models oraz dostawców z działającym uwierzytelnianiem. Pełny wbudowany katalog jest zarezerwowany dla jawnych widoków przeglądania (models.list z view: "all" lub openclaw models list --all).
• Interfejsy wykazu dostawców używają models.list z view: "provider-config", aby wyświetlać pochodzące ze źródła wiersze models.providers.*.models bez stosowania list dozwolonych modeli selektora.

Pełny opis mechanizmu: Przełączanie awaryjne modeli.

Szybkie zasady dotyczące modeli

• Jako model podstawowy ustaw najsilniejszy dostępny model najnowszej generacji.
• Używaj modeli rezerwowych do zadań wrażliwych na koszt lub opóźnienia oraz do mniej istotnych rozmów.
• W przypadku agentów korzystających z narzędzi lub niezaufanych danych wejściowych unikaj starszych lub słabszych klas modeli.

Konfiguracja początkowa

openclaw onboard

Konfiguruje model i uwierzytelnianie dla popularnych dostawców bez ręcznego edytowania konfiguracji, w tym OAuth subskrypcji OpenAI Codex oraz Anthropic (klucz API lub ponowne użycie Claude CLI).

Jeśli nie skonfigurowano modelu podstawowego, nowa konfiguracja klucza API OpenAI wybiera openai/gpt-5.6; sam identyfikator bezpośredniego API wskazuje klasę Sol. Nowa konfiguracja OAuth ChatGPT/Codex wybiera dokładne odwołanie katalogowe openai/gpt-5.6-sol. Ponowne uwierzytelnienie zachowuje istniejący jawnie ustawiony model podstawowy, w tym openai/gpt-5.5. Jeśli GPT-5.6 jest niedostępny dla konta, należy jawnie wybrać openai/gpt-5.5; OpenClaw nie obniża jego wersji automatycznie.

„Model jest niedozwolony” (i dlaczego odpowiedzi przestają się pojawiać)

Jeśli ustawiono agents.defaults.models, staje się ono listą dozwolonych modeli dla /model i nadpisań sesji. Wybranie modelu spoza tej listy zwraca następujący komunikat, zanim zostanie wygenerowana zwykła odpowiedź:

Model „provider/model” jest niedozwolony. Użyj /models, aby wyświetlić dostawców, lub /models <provider>, aby wyświetlić modele.Dodaj go za pomocą: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

Aby rozwiązać problem, dodaj model do agents.defaults.models, całkowicie usuń listę dozwolonych modeli (usuń klucz) lub wybierz model z /model list. Jeśli odrzucone polecenie zawierało nadpisanie środowiska uruchomieniowego, takie jak /model openai/gpt-5.5 --runtime codex, najpierw popraw listę dozwolonych modeli, a następnie ponów to samo polecenie /model ... --runtime ....

W przypadku modeli lokalnych/GGUF lista dozwolonych modeli musi zawierać pełne odwołanie z prefiksem dostawcy, na przykład ollama/gemma4:26b lub lmstudio/Gemma4-26b-a4-it-gguf — dokładny ciąg można sprawdzić za pomocą openclaw models list --provider <provider>. Same nazwy plików lub nazwy wyświetlane nie wystarczą po włączeniu listy dozwolonych modeli.

Aby ograniczyć dostawców bez wymieniania każdego modelu, użyj wpisów wieloznacznych provider/*:

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

/model, /models oraz selektory modeli wyświetlają wtedy wykryty katalog wyłącznie dla tych dostawców, a nowe modele mogą pojawiać się bez edytowania listy dozwolonych modeli. Połącz dokładne wpisy provider/model z wpisami provider/*, aby uwzględnić jeden konkretny model innego dostawcy.

Przykładowa lista dozwolonych modeli z aliasami:

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

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

/model na czacie

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

• /model i /model list wyświetlają kompaktowy numerowany selektor (rodzina modeli + dostępni dostawcy); /model <#> dokonuje z niego wyboru. W Discord otwiera to listy rozwijane dostawcy/modelu z krokiem Submit; w Telegram wybory w selektorze mają zakres sesji i nigdy nie nadpisują trwałej wartości domyślnej agenta w openclaw.json. /models add jest przestarzałe i zamiast rejestrować modele z czatu, zwraca komunikat.
• /model natychmiast utrwala nowy wybór sesji. Jeśli agent jest bezczynny, następne uruchomienie używa go od razu; jeśli uruchomienie jest już aktywne, przełączenie zostaje umieszczone w kolejce do następnego bezpiecznego punktu ponowienia (lub późniejszego, jeśli aktywność narzędzi albo generowanie odpowiedzi już się rozpoczęły).
• /model default usuwa wybór sesji, aby ponownie dziedziczyła skonfigurowany model podstawowy.
• Wybrane przez użytkownika odwołanie /model jest ściśle obowiązujące w tej sesji: jeśli stanie się nieosiągalne, odpowiedź zakończy się widocznym błędem zamiast niejawnie przechodzić przez agents.defaults.model.fallbacks. Skonfigurowane wartości domyślne i modele podstawowe zadań cron nadal korzystają z łańcuchów zastępczych.
• /model status to widok szczegółowy: kandydaci uwierzytelniania dla każdego dostawcy oraz — jeśli skonfigurowano — punkt końcowy dostawcy baseUrl i tryb api.
• Odwołania do modeli są analizowane przez podział przy pierwszym /; należy wpisać provider/model. Jeśli sam identyfikator modelu zawiera / (jak w OpenRouter), należy dodać prefiks dostawcy, np. /model openrouter/moonshotai/kimi-k2. Jeśli dostawca zostanie pominięty, OpenClaw próbuje kolejno: (1) dopasować alias, (2) znaleźć unikatowe dopasowanie skonfigurowanego dostawcy dla dokładnie tego identyfikatora modelu bez prefiksu, (3) użyć skonfigurowanego domyślnego dostawcy (przestarzały mechanizm zastępczy) — a jeśli ten dostawca nie udostępnia już skonfigurowanego modelu domyślnego, zamiast niego użyć pierwszej skonfigurowanej pary dostawca/model, aby nie ujawniać nieaktualnej wartości domyślnej po usuniętym dostawcy.
• Odwołania do modeli są normalizowane do małych liter; poza tym identyfikatory dostawców są rozróżniane dokładnie, dlatego należy użyć identyfikatora ogłaszanego przez plugin.

Pełne zachowanie poleceń i konfiguracja: Polecenia z ukośnikiem.

CLI

openclaw models statusopenclaw models listopenclaw models set <provider/model>openclaw models set-image <provider/model>openclaw models scanopenclaw models aliases list|add|removeopenclaw models fallbacks list|add|remove|clearopenclaw models image-fallbacks list|add|remove|clearopenclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

openclaw models bez podpolecenia jest skrótem do models status, które wyświetla również czas wygaśnięcia OAuth dla profili magazynu uwierzytelniania (domyślnie ostrzega w ciągu 24h przed wygaśnięciem). Pełne flagi, struktury JSON i podpolecenia profili uwierzytelniania: Dokumentacja CLI modeli.

Rejestr modeli (models.json)

Niestandardowi dostawcy skonfigurowani w models.providers są zapisywani do models.json w katalogu agenta (domyślnie ~/.openclaw/agents/<agentId>/agent/models.json). Katalogi pluginów dostawców są przechowywane osobno jako wygenerowane fragmenty katalogu należące do pluginów i wczytywane automatycznie. Domyślnie ten plik jest scalany z konfiguracją; ustaw models.mode: "replace", aby używać wyłącznie skonfigurowanych dostawców.

Utrwalanie znaczników opiera się na autorytatywnym źródle: za każdym razem, gdy OpenClaw ponownie generuje models.json — w tym w ścieżkach uruchamianych poleceniami, takich jak openclaw agent — zapisuje znaczniki z aktywnej migawki konfiguracji źródłowej (sprzed rozwiązania), a nie rozwiązane wartości sekretów środowiska wykonawczego.

Powiązane

• Środowiska uruchomieniowe agentów — OpenClaw, Codex i inne środowiska uruchomieniowe pętli agentów
• Dokumentacja konfiguracji — klucze konfiguracji modeli
• Generowanie obrazów — konfiguracja modelu obrazów
• Przełączanie awaryjne modeli — łańcuchy zastępcze
• Dostawcy modeli — routing dostawców i uwierzytelnianie
• Dokumentacja CLI modeli — pełna dokumentacja poleceń i flag
• Generowanie muzyki — konfiguracja modelu muzyki
• Generowanie wideo — konfiguracja modelu wideo