Modele CLI

Odwołania do modeli wybierają dostawcę i model. Zwykle nie wybierają niskopoziomowego środowiska uruchomieniowego agenta. Na przykład openai/gpt-5.5 może działać przez zwykłą ścieżkę dostawcy OpenAI albo przez środowisko uruchomieniowe serwera aplikacji Codex, zależnie od agents.defaults.agentRuntime.id. W trybie środowiska uruchomieniowego Codex odwołanie openai/gpt-* nie oznacza rozliczania kluczem API; uwierzytelnianie może pochodzić z konta Codex albo z profilu uwierzytelniania openai-codex. Zobacz Środowiska uruchomieniowe agentów.

# Jak działa wybór modelu

OpenClaw wybiera modele w tej kolejności:

# Źródło wyboru i zachowanie awaryjne

To samo provider/model może oznaczać różne rzeczy zależnie od tego, skąd pochodzi:

• Skonfigurowane ustawienia domyślne (agents.defaults.model.primary i modele główne specyficzne dla agentów) są normalnym punktem startowym i używają agents.defaults.model.fallbacks.
• Automatyczne wybory awaryjne są tymczasowym stanem odzyskiwania. Są przechowywane z modelOverrideSource: "auto", aby kolejne tury mogły nadal używać łańcucha awaryjnego bez wcześniejszego sprawdzania znanego wadliwego modelu głównego.
• 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 widoczny błąd zamiast przechodzić do innego skonfigurowanego modelu.
• Cron --model / model w ładunku to model główny dla pojedynczego zadania. Nadal używa skonfigurowanych modeli awaryjnych, chyba że zadanie dostarcza jawne fallbacks w ładunku (użyj fallbacks: [] dla ścisłego uruchomienia Cron).
• Selektory domyślnego modelu i listy dozwolonych w CLI respektują models.mode: "replace", pokazując jawne models.providers.*.models zamiast ładować pełny wbudowany katalog.
• Selektor modelu w interfejsie Control UI pyta Gateway o jego skonfigurowany widok modeli: agents.defaults.models, jeśli jest obecne, w przeciwnym razie jawne models.providers.*.models plus dostawcy 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 główny na najsilniejszy dostępny dla Ciebie model najnowszej generacji.
• Używaj modeli awaryjnych do zadań wrażliwych na koszt/opóźnienia i rozmów o niższej stawce.
• Dla agentów z narzędziami lub niezaufanych danych wejściowych unikaj starszych/słabszych klas 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)
• 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 is not allowed” (i dlaczego odpowiedzi się zatrzymują)

Jeśli agents.defaults.models jest ustawione, staje się listą dozwolonych dla /model i 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 potem ponów to samo polecenie /model ... --runtime .... Dla natywnego wykonywania Codex wybrany model nadal jest openai/gpt-5.5; środowisko uruchomieniowe codex wybiera harness i osobno używa uwierzytelniania Codex.

Dla modeli lokalnych/GGUF zapisz pełne odwołanie z prefiksem dostawcy na liście dozwolonych, 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 lub nazwy wyświetlane nie wystarczą, gdy lista dozwolonych jest aktywna.

Przykładowa konfiguracja listy dozwolonych:

{
  agent: {
    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 ponownego uruchamiania:

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

Pełne zachowanie/konfiguracja polecenia: Polecenia z ukośnikiem.

# Polecenia CLI

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

openclaw models (bez podpolecenia) jest skrótem do models status.

# models list

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

--allboolean

Pełny katalog. Obejmuje statyczne wiersze katalogu dostarczane z pakietem i należące do providera jeszcze przed skonfigurowaniem uwierzytelniania, dzięki czemu widoki wyłącznie do odkrywania mogą pokazywać modele niedostępne do czasu dodania odpowiednich danych uwierzytelniających providera.

--localboolean

Tylko lokalni providerzy.

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

--plainboolean

Jeden model na wiersz.

--jsonboolean

Dane wyjściowe czytelne maszynowo.

# models status

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

Przykład (Claude CLI):

claude auth login
openclaw models status

# Skanowanie (darmowe modele OpenRouter)

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

--no-probeboolean

Pomiń sondowania na żywo (tylko metadane).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

Ustaw agents.defaults.model.primary na pierwszy wybór.

--set-imageboolean

Ustaw agents.defaults.imageModel.primary na pierwszy wybór obrazu.

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)
• Sondowania 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
• Sterowanie żądaniami/sondowaniem: --timeout, --concurrency

Gdy sondowania na żywo działają w TTY, możesz interaktywnie wybrać modele zapasowe. W trybie nieinteraktywnym przekaż --yes, aby zaakceptować wartości domyślne. Wyniki tylko z metadanymi mają charakter informacyjny; --set-default i --set-image wymagają sondowań na żywo, aby OpenClaw nie skonfigurował bezużytecznego modelu OpenRouter bez klucza.

# Rejestr modeli (models.json)

Niestandardowi providerzy w models.providers są zapisywani do models.json w katalogu agenta (domyślnie ~/.openclaw/agents/<agentId>/agent/models.json). Ten plik jest domyślnie scalany, chyba że models.mode jest ustawione na replace.

# Powiązane

• Środowiska wykonawcze agentów — PI, Codex i inne środowiska wykonawcze pętli agenta
• Dokumentacja konfiguracji — klucze konfiguracji modeli
• Generowanie obrazów — konfiguracja modelu obrazu
• Przełączanie awaryjne modeli — łańcuchy modeli zapasowych
• Providerzy modeli — routing providerów i uwierzytelnianie
• Generowanie muzyki — konfiguracja modelu muzyki
• Generowanie wideo — konfiguracja modelu wideo