CLI dei modelli

I riferimenti dei modelli scelgono un provider e un modello. Di solito non scelgono il runtime agente di basso livello. I riferimenti agente OpenAI sono l'eccezione principale: openai/gpt-5.5 viene eseguito tramite il runtime app-server Codex per impostazione predefinita sul provider OpenAI ufficiale. I riferimenti Copilot in abbonamento (github-copilot/*) possono inoltre essere configurati per usare il Plugin runtime agente GitHub Copilot esterno: quel percorso resta esplicito (nessun fallback auto). Gli override espliciti del runtime appartengono alla policy provider/modello, non all'intero agente o alla sessione. In modalità runtime Codex, il riferimento openai/gpt-* non implica fatturazione tramite chiave API; l'autenticazione può provenire da un account Codex o da un profilo OAuth openai. Vedi Runtime degli agenti e Runtime agente GitHub Copilot.

Come funziona la selezione del modello

OpenClaw seleziona i modelli in questo ordine:

Origine della selezione e comportamento di fallback

Lo stesso provider/model può significare cose diverse a seconda della sua origine:

• I valori predefiniti configurati (agents.defaults.model.primary e primari specifici dell'agente) sono il normale punto di partenza e usano agents.defaults.model.fallbacks.
• Le selezioni automatiche di fallback sono stato temporaneo di recupero. Sono archiviate con modelOverrideSource: "auto" così i turni successivi possono continuare a usare la catena di fallback senza sondare ogni volta un primario noto come non funzionante; OpenClaw sonda periodicamente di nuovo il primario originale, cancella la selezione automatica quando si ripristina e annuncia le transizioni di fallback/ripristino una volta per cambio di stato.
• Le selezioni della sessione utente sono esatte. /model, il selettore modelli, session_status(model=...) e sessions.patch memorizzano modelOverrideSource: "user"; se quel provider/modello selezionato non è raggiungibile, OpenClaw fallisce in modo visibile invece di passare a un altro modello configurato.
• La modifica di agents.defaults.model.primary non riscrive le selezioni di sessione esistenti. Se lo stato dice This session is pinned to X; config primary Y will apply to new/unpinned sessions., cancella la selezione della sessione corrente con /model default in modo che erediti di nuovo il primario configurato.
• Cron --model / payload model è un primario per job. Usa comunque i fallback configurati, a meno che il job non fornisca payload fallbacks espliciti (usa fallbacks: [] per un'esecuzione cron rigorosa).
• I selettori CLI per modello predefinito e allowlist rispettano models.mode: "replace" elencando i models.providers.*.models espliciti invece di caricare l'intero catalogo integrato.
• Il selettore modelli della UI di controllo chiede al Gateway la vista modelli configurata: agents.defaults.models quando presente, incluse voci provider/* a livello di provider, altrimenti models.providers.*.models espliciti più provider con autenticazione utilizzabile. L'intero catalogo integrato è riservato alle viste di esplorazione esplicite come models.list con view: "all" o openclaw models list --all.

Policy rapida sui modelli

• Imposta il primario sul modello di ultima generazione più potente disponibile per te.
• Usa i fallback per attività sensibili a costi/latenza e chat a rischio più basso.
• Per agenti con strumenti abilitati o input non attendibili, evita fasce di modelli più vecchie/deboli.

Onboarding (consigliato)

Se non vuoi modificare manualmente la configurazione, esegui l'onboarding:

openclaw onboard

Può configurare modello + autenticazione per provider comuni, inclusi OpenAI Code (Codex) subscription (OAuth) e Anthropic (chiave API o Claude CLI).

Chiavi di configurazione (panoramica)

• agents.defaults.model.primary e agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary e agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary e agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary e agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary e agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models (allowlist + alias + parametri provider + voci provider dinamiche provider/*)
• models.providers (provider personalizzati scritti in models.json)

Modifiche sicure alla allowlist

Usa scritture additive quando aggiorni agents.defaults.models a mano:

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

"Il modello non è consentito" (e perché le risposte si interrompono)

Se agents.defaults.models è impostato, diventa la allowlist per /model e per gli override di sessione. Quando un utente seleziona un modello che non è in quella allowlist, OpenClaw restituisce:

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

Quando il comando rifiutato includeva un override del runtime come /model openai/gpt-5.5 --runtime codex, correggi prima la allowlist, poi riprova lo stesso comando /model ... --runtime .... Per l'esecuzione nativa Codex, il modello selezionato resta openai/gpt-5.5; il runtime codex seleziona l'harness e usa l'autenticazione Codex separatamente.

Per i modelli locali/GGUF, memorizza nella allowlist il riferimento completo con prefisso provider, per esempio ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf o il provider/modello esatto mostrato da openclaw models list --provider <provider>. I nomi file locali semplici o i nomi visualizzati non sono sufficienti quando la allowlist è attiva.

Se vuoi limitare i provider senza elencare manualmente ogni modello, aggiungi voci provider/* a agents.defaults.models:

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

Con quella policy, /model, /models e i selettori modelli mostrano il catalogo rilevato solo per quei provider. I nuovi modelli dai provider selezionati possono comparire senza modificare la allowlist. Le voci provider/model esatte possono essere combinate con voci provider/* quando serve uno specifico modello da un altro provider.

Esempio di configurazione allowlist:

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

Cambiare modello in chat (/model)

Puoi cambiare modello per la sessione corrente senza riavviare:

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

Comportamento/configurazione completa dei comandi: Comandi slash.

Comandi 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 (senza sottocomando) è una scorciatoia per models status.

models list

Mostra per impostazione predefinita i modelli configurati/disponibili con l'autenticazione. Flag utili:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Filtra per ID provider, per esempio moonshot. Le etichette visualizzate dai selettori interattivi non sono accettate.

models status

Mostra il modello primario risolto, i fallback, il modello immagine e una panoramica dell'autenticazione dei provider configurati. Espone anche lo stato di scadenza OAuth per i profili trovati nell'archivio di autenticazione (per impostazione predefinita avvisa entro 24 ore). --plain stampa solo il modello primario risolto.

Esempio (CLI Claude):

claude auth loginopenclaw models status

Scansione (modelli gratuiti OpenRouter)

openclaw models scan ispeziona il catalogo dei modelli gratuiti di OpenRouter e può facoltativamente verificare i modelli per supporto a strumenti e immagini.

I risultati della scansione sono ordinati in base a:

1. Supporto immagini
2. Latenza strumenti
3. Dimensione del contesto
4. Numero di parametri

Input:

• Elenco /models di OpenRouter (filtro :free)
• I probe live richiedono una chiave API OpenRouter dai profili di autenticazione o OPENROUTER_API_KEY (vedi Variabili d'ambiente)
• Filtri facoltativi: --max-age-days, --min-params, --provider, --max-candidates
• Controlli richiesta/probe: --timeout, --concurrency

Quando i probe live vengono eseguiti in una TUI, puoi selezionare i fallback in modo interattivo. In modalità non interattiva, passa --yes per accettare i valori predefiniti. I risultati di soli metadati sono informativi; --set-default e --set-image richiedono probe live così OpenClaw non configura un modello OpenRouter inutilizzabile senza chiave.

Registro dei modelli (models.json)

I provider personalizzati in models.providers vengono scritti in models.json nella directory dell'agente (predefinita ~/.openclaw/agents/<agentId>/agent/models.json). I cataloghi dei provider-plugin sono memorizzati come shard di catalogo generati di proprietà del Plugin nello stato dei Plugin dell'agente e caricati automaticamente. Questo file viene unito per impostazione predefinita a meno che models.mode sia impostato su replace.

Correlati

• Runtime degli agenti — OpenClaw, Codex e altri runtime del loop agente
• Riferimento di configurazione — chiavi di configurazione dei modelli
• Generazione di immagini — configurazione del modello immagine
• Failover dei modelli — catene di fallback
• Provider di modelli — routing dei provider e autenticazione
• Generazione di musica — configurazione del modello musicale
• Generazione di video — configurazione del modello video