Domande frequenti: modelli e autenticazione

Si imposta con:

agents.defaults.model.primary

I modelli sono riferimenti provider/model (esempio: openai/gpt-5.5, anthropic/claude-sonnet-4-6). Imposta sempre provider/model in modo esplicito. Se ometti il provider, OpenClaw tenta prima una corrispondenza con un alias, poi una corrispondenza univoca tra i provider configurati per quell'ID modello, quindi utilizza il provider predefinito configurato (percorso di compatibilità deprecato). Se quel provider non dispone più del modello predefinito configurato, OpenClaw utilizza il primo provider/modello configurato invece di un'impostazione predefinita obsoleta.

Usa il modello più potente e di ultima generazione offerto dal tuo insieme di provider, soprattutto per gli agenti che utilizzano strumenti o ricevono input non attendibili: i modelli meno potenti o eccessivamente quantizzati sono più vulnerabili alla prompt injection e a comportamenti non sicuri (consulta Sicurezza). Assegna i modelli più economici alle conversazioni ordinarie o a basso rischio in base al ruolo dell'agente.

Assegna i modelli per agente e usa sotto-agenti per parallelizzare le attività lunghe (ogni sotto-agente consuma i propri token). Consulta Modelli, Sotto-agenti, MiniMax e Modelli locali.

Modifica soltanto i campi del modello, evitando di sostituire l'intera configurazione.

• /model nella chat (per sessione; consulta Comandi slash)
• openclaw models set ... (aggiorna soltanto la configurazione del modello)
• openclaw configure --section model (interattivo)
• modifica direttamente agents.defaults.model in ~/.openclaw/openclaw.json

Per le modifiche tramite RPC, esamina prima con config.schema.lookup (percorso normalizzato, documentazione sintetica dello schema e riepiloghi degli elementi figli), quindi preferisci config.patch a config.apply con un oggetto parziale. Se hai sovrascritto la configurazione, ripristinala dal backup oppure esegui openclaw doctor per correggerla.

Documentazione: Modelli, Configurazione, Configurazione, Doctor.

Sì: Ollama è il percorso più semplice. Configurazione rapida:

1. Installa Ollama da https://ollama.com/download
2. Scarica un modello locale, ad esempio ollama pull gemma4
3. Per usare anche i modelli cloud, esegui ollama signin
4. Esegui openclaw onboard, scegli Ollama, quindi Local o Cloud + Local

Cloud + Local offre i modelli cloud insieme ai tuoi modelli Ollama locali; i modelli cloud come kimi-k2.5:cloud non richiedono alcun download locale. Per cambiare modello manualmente: openclaw models list, quindi openclaw models set ollama/<model>.

I modelli più piccoli o fortemente quantizzati sono più vulnerabili alla prompt injection. Usa modelli di grandi dimensioni per qualsiasi bot che abbia accesso agli strumenti; se usi comunque modelli piccoli, abilita il sandboxing ed elenchi rigorosi degli strumenti consentiti.

Documentazione: Ollama, Modelli locali, Provider di modelli, Sicurezza, Sandboxing.

Invia /model <name> come messaggio autonomo. Consulta Comandi slash per l'elenco completo dei comandi, incluso il selettore numerato (/model, /model list, /model 3), /model default per rimuovere una sostituzione specifica della sessione e /model status per i dettagli sull'endpoint e sulla modalità API.

Forza uno specifico profilo di autenticazione per sessione con @profile:

/model opus@anthropic:default/model opus@anthropic:work

Per rimuovere il vincolo a un profilo impostato con @profile, esegui nuovamente /model senza il suffisso (ad esempio /model anthropic/claude-opus-4-6) oppure scegli il valore predefinito da /model. Usa /model status per confermare il profilo di autenticazione attivo.

/model provider/model seleziona esattamente il percorso di quel provider. Ad esempio, qianfan/deepseek-v4-flash e deepseek/deepseek-v4-flash sono riferimenti diversi anche se l'ID modello coincide: OpenClaw non cambia silenziosamente provider in base alla corrispondenza del solo ID.

Un riferimento /model selezionato dall'utente applica regole rigorose per il fallback: se quel provider/modello diventa indisponibile, la risposta non riesce in modo visibile invece di utilizzare agents.defaults.model.fallbacks. Le catene di fallback configurate continuano ad applicarsi alle impostazioni predefinite configurate, ai modelli primari dei processi Cron e allo stato di fallback selezionato automaticamente. Quando un'esecuzione senza sostituzione specifica della sessione può utilizzare il fallback, OpenClaw tenta prima il provider/modello richiesto, poi i fallback configurati e infine il modello primario configurato; in questo modo gli ID modello semplici duplicati non ritornano direttamente al provider predefinito.

Consulta Modelli e Failover dei modelli.

Sì: la scelta del modello e quella del runtime sono separate:

• Agente di programmazione Codex nativo: imposta agents.defaults.model.primary su openai/gpt-5.5. Accedi con openclaw models auth login --provider openai per l'autenticazione tramite abbonamento ChatGPT/Codex.
• Attività dirette dell'API OpenAI esterne al ciclo dell'agente: configura OPENAI_API_KEY per immagini, embedding, sintesi vocale, comunicazioni in tempo reale e altre funzionalità dell'API OpenAI non relative agli agenti.
• Autenticazione dell'agente OpenAI tramite chiave API: /model openai/gpt-5.5 con un profilo di chiavi API openai ordinato.
• Sotto-agenti: assegna le attività di programmazione a un agente incentrato su Codex con il proprio modello openai/gpt-5.5.

Consulta Modelli e Comandi slash.

• Per sessione: invia /fast on mentre usi openai/gpt-5.5.
• Impostazione predefinita per modello: imposta agents.defaults.models["openai/gpt-5.5"].params.fastMode su true.
• Limite automatico: /fast auto o params.fastMode: "auto" esegue rapidamente le nuove chiamate al modello fino al limite, quindi esegue senza modalità rapida i successivi tentativi, fallback, chiamate con risultati degli strumenti o continuazioni. Il limite predefinito è 60 secondi; puoi sovrascriverlo con params.fastAutoOnSeconds sul modello.

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: "auto",            fastAutoOnSeconds: 30,          },        },      },    },  },}

La modalità rapida corrisponde a service_tier = "priority" nelle richieste native OpenAI Responses; i valori service_tier esistenti vengono mantenuti e la modalità rapida non modifica reasoning o text.verbosity. Le sostituzioni /fast della sessione hanno la precedenza sulle impostazioni predefinite della configurazione.

Consulta Ragionamento e modalità rapida e la sezione sulla modalità rapida nella configurazione avanzata della pagina del provider OpenAI.

Se agents.defaults.models è impostato, diventa l'elenco consentito per /model e per le sostituzioni specifiche della sessione. Selezionare un modello esterno a tale elenco restituisce quanto segue invece di una risposta normale:

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

Soluzione: aggiungi il modello esatto ad agents.defaults.models, aggiungi un carattere jolly del provider come "provider/*": {} per i cataloghi dinamici, rimuovi l'elenco consentito oppure scegli un modello da /model list. Se il comando includeva anche --runtime codex, aggiorna prima l'elenco consentito, quindi ripeti lo stesso comando /model provider/model --runtime codex.

Se usi una versione precedente di OpenClaw, esegui prima l'aggiornamento (oppure avvia dal sorgente main) e riavvia il Gateway: MiniMax-M3 potrebbe non essere ancora presente nel catalogo della versione installata. In caso contrario, il provider MiniMax non è configurato (non è stata trovata alcuna voce del provider né alcun profilo di autenticazione), quindi il modello non può essere risolto. Consulta la sezione sulla risoluzione dei problemi nella pagina del provider MiniMax per l'elenco completo delle verifiche, la tabella degli ID provider/modello e un esempio di blocco di configurazione.

Sì. Usa MiniMax come modello predefinito e cambia modello per sessione: i fallback servono per gli errori, non per le "attività difficili", quindi usa /model o un agente separato.

Opzione A: cambio per sessione

{  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "minimax" },        "openai/gpt-5.5": { alias: "gpt" },      },    },  },}

Quindi esegui /model gpt.

Opzione B: agenti separati — L'agente A usa MiniMax come impostazione predefinita, mentre l'agente B usa OpenAI; instrada in base all'agente oppure usa /agent per cambiare.

Documentazione: Modelli, Instradamento multi-agente, MiniMax, OpenAI.

Sì: sono abbreviazioni integrate, applicate soltanto quando il modello di destinazione esiste in agents.defaults.models:

Un tuo alias con lo stesso nome sostituisce quello integrato.

Gli alias si trovano in agents.defaults.models.<modelId>.alias:

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

A questo punto /model sonnet (oppure /<alias>, quando supportato) viene risolto nell'ID di quel modello.

OpenRouter (pagamento per token; molti modelli):

{  agents: {    defaults: {      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },    },  },  env: { OPENROUTER_API_KEY: "sk-or-..." },}

Z.AI (modelli GLM):

{  agents: {    defaults: {      model: { primary: "zai/glm-5.1" },      models: { "zai/glm-5.1": {} },    },  },  env: { ZAI_API_KEY: "..." },}

L'assenza della chiave di un provider per un provider/modello referenziato genera un errore di autenticazione in fase di esecuzione (ad esempio No API key found for provider "zai").

Nessuna chiave API trovata per il provider dopo l'aggiunta di un nuovo agente

Un nuovo agente dispone di un archivio di autenticazione vuoto: l'autenticazione è specifica per agente ed è archiviata in:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Correzione: esegui openclaw agents add <id> e configura l'autenticazione nella procedura guidata, oppure copia dall'archivio dell'agente principale solo i profili statici portabili api_key/token. Per OAuth, accedi dal nuovo agente quando necessita di un proprio account. Consulta Instradamento multi-agente per le regole complete sul riutilizzo di agentDir e sulla condivisione delle credenziali: non riutilizzare mai agentDir tra agenti.

Due fasi:

1. Rotazione dei profili di autenticazione all'interno dello stesso provider.
2. Fallback del modello al modello successivo in agents.defaults.model.fallbacks.

Ai profili che non funzionano vengono applicati periodi di attesa (backoff esponenziale), così OpenClaw continua a rispondere quando un provider applica limiti di frequenza o presenta problemi temporanei.

La categoria dei limiti di frequenza include più del semplice 429: Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted e i limiti periodici delle finestre di utilizzo (weekly/monthly limit reached) sono tutti considerati limiti di frequenza che giustificano il failover.

Le risposte relative alla fatturazione non sono sempre 402 e alcuni 402 rimangono nella categoria transitoria/dei limiti di frequenza anziché in quella della fatturazione. Un testo esplicito relativo alla fatturazione in un 401/403 può comunque essere instradato alla categoria della fatturazione; i criteri testuali specifici del provider (ad esempio Key limit exceeded di OpenRouter) restano limitati al rispettivo provider. Un 402 che sembra indicare una finestra di utilizzo ritentabile o un limite di spesa dell'organizzazione/area di lavoro (daily limit reached, resets tomorrow, organization spending limit exceeded) viene trattato come rate_limit, non come una disabilitazione prolungata per motivi di fatturazione.

Gli errori di superamento del contesto restano completamente esclusi dal percorso di fallback: firme come request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model o ollama error: context length exceeded vengono indirizzate alla Compaction e a un nuovo tentativo, anziché passare al modello di fallback successivo.

Il testo generico degli errori del server è interpretato in modo più restrittivo rispetto a "qualsiasi cosa contenga unknown/error". Le forme transitorie specifiche del provider che vengono considerate segnali di failover includono: il semplice An unknown error occurred di Anthropic, il semplice Provider returned error di OpenRouter, errori relativi al motivo di arresto come Unhandled stop reason: error, payload JSON api_error con testo transitorio del server (internal server error, unknown error, 520, upstream error, backend error) ed errori di provider occupato come ModelNotReadyException quando il contesto del provider corrisponde. Il testo generico di fallback interno come LLM request failed with an unknown error. viene gestito in modo prudente e, da solo, non attiva il fallback.

L'ID del profilo di autenticazione anthropic:default non contiene credenziali nell'archivio di autenticazione previsto.

Elenco di controllo per la correzione:

• Verifica dove si trovano i profili: percorso attuale: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json; percorso precedente: ~/.openclaw/agent/* (migrato da openclaw doctor).
• Verifica che il Gateway carichi la variabile di ambiente. ANTHROPIC_API_KEY impostata solo nella shell non raggiungerà un Gateway eseguito tramite systemd/launchd: inseriscila in ~/.openclaw/.env oppure abilita env.shellEnv.
• Verifica di modificare l'agente corretto: le configurazioni multi-agente contengono più file auth-profiles.json.
• Esegui openclaw models status per visualizzare i modelli configurati e lo stato dell'autenticazione del provider.

Per "No credentials found for profile anthropic" (senza suffisso e-mail):

L'esecuzione è vincolata a un profilo Anthropic che il Gateway non riesce a trovare.

• Usa la CLI di Claude: esegui openclaw models auth login --provider anthropic --method cli --set-default sull'host del Gateway.

• In alternativa, preferisci una chiave API: inserisci ANTHROPIC_API_KEY in ~/.openclaw/.env sull'host del Gateway, quindi rimuovi qualsiasi ordine vincolato che imponga il profilo mancante:

  openclaw models auth order clear --provider anthropic

• Modalità remota: i profili di autenticazione si trovano sulla macchina del Gateway, non sul portatile; verifica di eseguire lì i comandi.

Se la configurazione dei modelli include Google Gemini come fallback (oppure hai selezionato una forma abbreviata di Gemini), OpenClaw lo prova durante il fallback. Se non sono configurate credenziali Google, viene restituito No API key found for provider "google". Correzione: aggiungi l'autenticazione Google oppure rimuovi i modelli Google da agents.defaults.model.fallbacks/dagli alias.

Richiesta LLM rifiutata: firma di ragionamento obbligatoria (Google Antigravity)

Causa: la cronologia della sessione contiene blocchi di ragionamento privi di firma (spesso provenienti da uno stream interrotto o parziale); Google Antigravity richiede firme nei blocchi di ragionamento. OpenClaw rimuove i blocchi di ragionamento non firmati per Google Antigravity Claude; se il problema persiste, avvia una nuova sessione oppure imposta /thinking off per quell'agente.

Un record di credenziali denominato (OAuth o chiave API) associato a un provider, archiviato in:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Esamina i profili salvati senza mostrare i segreti: openclaw models auth list (facoltativamente --provider <id> o --json). Consulta CLI dei modelli.

Con prefisso del provider: anthropic:default (comune quando non esiste un'identità e-mail), anthropic:<email> per le identità OAuth oppure un ID personalizzato scelto dall'utente (ad esempio anthropic:work).

Sì. La configurazione auth.order.<provider> imposta l'ordine di rotazione per ogni provider (solo metadati, senza memorizzare segreti).

OpenClaw può ignorare un profilo durante un breve periodo di attesa (limiti di frequenza, timeout, errori di autenticazione) o durante uno stato disabilitato più lungo (fatturazione/crediti insufficienti). Verifica con openclaw models status --json e controlla auth.unusableProfiles. Regola il comportamento con auth.cooldowns.billingBackoffHours*. I periodi di attesa dovuti ai limiti di frequenza possono essere specifici per modello: un profilo in attesa per un modello può comunque servire un modello correlato dello stesso provider; le finestre di fatturazione/disabilitazione bloccano l'intero profilo.

Imposta un ordine alternativo per agente (memorizzato nel file auth-state.json dell'agente):

# Defaults to the configured default agent (omit --agent)openclaw models auth order get --provider anthropic # Lock rotation to a single profileopenclaw models auth order set --provider anthropic anthropic:default # Or set an explicit order (fallback within provider)openclaw models auth order set --provider anthropic anthropic:work anthropic:default # Clear override (fall back to config auth.order / round-robin)openclaw models auth order clear --provider anthropic # Target a specific agentopenclaw models auth order set --provider anthropic --agent main anthropic:default

Verifica cosa verrà effettivamente provato: openclaw models status --probe. Un profilo memorizzato omesso da un ordine esplicito viene segnalato come excluded_by_auth_order anziché essere provato senza indicazioni.

• Accesso OAuth / CLI utilizza spesso l'accesso in abbonamento quando il provider lo supporta. Per Anthropic, il backend CLI di Claude di OpenClaw utilizza claude -p di Claude Code, che Anthropic attualmente considera un utilizzo tramite Agent SDK/programmatico che attinge dai limiti di utilizzo dell'abbonamento. Consulta Anthropic per lo stato attuale della sospensione della fatturazione e i collegamenti alle fonti.
• Le chiavi API utilizzano la fatturazione per token.

La procedura guidata supporta la CLI di Anthropic Claude, OAuth di OpenAI Codex e le chiavi API.