CLI dei modelli

I riferimenti dei modelli scelgono un provider e un modello. Di solito non scelgono il runtime dell'agente di basso livello. Per esempio, openai/gpt-5.5 può essere eseguito tramite il normale percorso del provider OpenAI o tramite il runtime del server applicativo Codex, a seconda di agents.defaults.agentRuntime.id. In modalità runtime Codex, il riferimento openai/gpt-* non implica la fatturazione con chiave API; l'autenticazione può provenire da un account Codex o da un profilo di autenticazione openai-codex. Consulta Runtime degli agenti.

# 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 provenienza:

• Le impostazioni predefinite configurate (agents.defaults.model.primary e i modelli principali specifici dell'agente) sono il normale punto di partenza e usano agents.defaults.model.fallbacks.
• Le selezioni di fallback automatico sono uno stato di recupero temporaneo. Sono archiviate con modelOverrideSource: "auto" in modo che i turni successivi possano continuare a usare la catena di fallback senza sondare prima un modello principale noto come non funzionante.
• Le selezioni della sessione utente sono esatte. /model, il selettore di modello, session_status(model=...) e sessions.patch archiviano modelOverrideSource: "user"; se il provider/modello selezionato non è raggiungibile, OpenClaw fallisce in modo visibile invece di proseguire con un altro modello configurato.
• Cron --model / payload model è un modello principale per job. Usa comunque i fallback configurati, a meno che il job non fornisca fallbacks espliciti nel payload (usa fallbacks: [] per un'esecuzione cron rigorosa).
• I selettori del modello predefinito CLI e dell'allowlist rispettano models.mode: "replace" elencando i models.providers.*.models espliciti invece di caricare l'intero catalogo integrato.
• Il selettore di modelli della Control UI chiede al Gateway la vista dei modelli configurata: agents.defaults.models quando presente, altrimenti models.providers.*.models espliciti più i provider con autenticazione utilizzabile. Il catalogo integrato completo è riservato alle viste di esplorazione esplicite come models.list con view: "all" o openclaw models list --all.

# Policy rapida dei modelli

• Imposta come principale il modello di ultima generazione più potente a tua disposizione.
• Usa i fallback per attività sensibili a costo/latenza e chat a basso rischio.
• Per agenti con strumenti abilitati o input non attendibili, evita livelli di modello più vecchi/deboli.

# Onboarding (consigliato)

Se non vuoi modificare la configurazione a mano, 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 del provider)
• models.providers (provider personalizzati scritti in models.json)

# Modifiche sicure dell'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 fermano)

Se agents.defaults.models è impostato, diventa l'allowlist per /model e per le sovrascritture di sessione. Quando un utente seleziona un modello che non è in quell'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 una sovrascrittura del runtime come /model openai/gpt-5.5 --runtime codex, correggi prima l'allowlist, poi riprova lo stesso comando /model ... --runtime .... Per l'esecuzione Codex nativa, il modello selezionato è ancora openai/gpt-5.5; il runtime codex seleziona l'harness e usa separatamente l'autenticazione Codex.

Per i modelli locali/GGUF, archivia nell'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 di file locali semplici o i nomi visualizzati non bastano quando l'allowlist è attiva.

Esempio di configurazione dell'allowlist:

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

# Cambiare modelli in chat (/model)

Puoi cambiare modello per la sessione corrente senza riavviare:

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

Comportamento/configurazione completa dei comandi: Comandi slash.

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

# models list

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

--allboolean

Catalogo completo. Include le righe del catalogo statico in bundle di proprietà del provider prima che l'autenticazione sia configurata, così le viste di sola scoperta possono mostrare modelli non disponibili finché non aggiungi le credenziali del provider corrispondente.

--localboolean

Solo provider locali.

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

--plainboolean

Un modello per riga.

--jsonboolean

Output leggibile dalla macchina.

# models status

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

Esempio (Claude CLI):

claude auth login
openclaw models status

# Scansione (modelli gratuiti OpenRouter)

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

--no-probeboolean

Salta i probe live (solo metadati).

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

Imposta agents.defaults.model.primary sulla prima selezione.

--set-imageboolean

Imposta agents.defaults.imageModel.primary sulla prima selezione immagine.

I risultati della scansione sono classificati per:

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

Input:

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

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

# Registro dei modelli (models.json)

I provider personalizzati in models.providers vengono scritti in models.json sotto la directory dell'agente (predefinita ~/.openclaw/agents/<agentId>/agent/models.json). Questo file viene unito per impostazione predefinita, a meno che models.mode sia impostato su replace.

# Correlati

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