L’autenticazione dei modelli in OpenClaw

La documentazione apre questa pagina con una nota sull’ambito che vale la pena ripetere: tratta l’autenticazione presso i provider di modelli, cioè chiavi API, OAuth, riutilizzo della CLI di Claude e token di configurazione di Anthropic, non il token o la password che protegge la connessione al Gateway. OpenClaw supporta OAuth e chiavi API per i provider, e la raccomandazione è chiara: per un host del Gateway sempre attivo una chiave API è l’opzione più prevedibile, mentre i flussi in abbonamento e OAuth funzionano quando corrispondono al tuo account presso il provider. Ecco la configurazione raccomandata, i percorsi Anthropic, dove risiedono le credenziali, come verificarle, la rotazione e come scegliere quale credenziale usa una sessione.

La configurazione raccomandata

• Crea una chiave nella console del provider, esportala sull’host del Gateway, cioè la macchina che esegue il Gateway, e verifica con il comando models status.
• Se il Gateway gira sotto systemd o launchd, metti la chiave nel file env della directory di stato così il demone può leggerla, riavvia e verifica di nuovo con models status e doctor; l’onboarding può salvare le chiavi per l’uso da parte del demone, se preferisci non gestire variabili.
• Il riutilizzo della CLI di Claude è un percorso approvato da Anthropic ed è quello preferito per l’uso locale o desktop quando sull’host esiste un accesso Claude: esegui l’accesso a Claude Code, poi indica a OpenClaw di instradare i modelli Anthropic attraverso il backend locale della CLI di Claude; OpenClaw non legge, non salva, non aggiorna e non inoltra mai i token di accesso nativi, il processo installato aggiorna da sé il proprio accesso, e il servizio deve trovare l’eseguibile nel proprio PATH.
• Il token di configurazione è l’altro percorso Anthropic: un token di lunga durata stampato da Claude Code su qualsiasi macchina e salvato sull’host tramite il comando auth login in modalità setup-token, che richiede un terminale interattivo.

Per un host del gateway sempre attivo, una chiave API è l’opzione più prevedibile; anche i flussi in abbonamento/OAuth funzionano quando corrispondono al modello di account del tuo provider.

Dove risiedono le credenziali

L’inserimento manuale del token funziona per qualsiasi provider e scrive nell’archivio di autenticazione SQLite per agente, da cui OpenClaw legge i profili di autenticazione; i dettagli degli endpoint come URL di base, tipi di API, ID dei modelli, header e timeout vanno nella configurazione del provider, non nei profili. Le installazioni più vecchie con file di autenticazione JSON vengono importate da doctor con backup contrassegnati da data e ora, i percorsi esterni come una modalità SDK di Bedrock sono metadati di configurazione e non credenziali, e le credenziali possono essere riferimenti a segreti per chiavi e token, tranne per i profili in modalità OAuth, che li rifiutano. Rimuovere un’autenticazione salvata non revoca la chiave presso il provider, e rimuovere l’autenticazione di un provider tramite il piano di controllo mentre il Gateway è in esecuzione interrompe le esecuzioni attive su quel provider con il motivo di arresto auth-revoked, così i client possono mostrare perché l’esecuzione si è fermata.

Verificare, ruotare, scegliere

• I comandi models status e doctor sono i controlli; per l’automazione, il flag check esce con codice uno quando una credenziale è scaduta o mancante e con codice due quando sta per scadere, e il flag probe esegue verifiche di autenticazione in tempo reale con flag di ambito, segnalando i profili esclusi dall’ordine di autenticazione, i provider con autenticazione ma senza un modello verificabile e i periodi di attesa per limiti di frequenza a livello di modello, che lasciano utilizzabili gli altri modelli dello stesso provider.
• Alcuni provider ritentano una richiesta bloccata dal limite di frequenza con un’altra chiave configurata, secondo una priorità fissa: una singola chiave di override attiva, un elenco delimitato di chiavi, la variabile della chiave semplice, poi qualsiasi variante con prefisso, e i provider Google ripiegano anche sulla chiave Google generica; la rotazione si attiva solo con errori di limite di frequenza, di quota e di troppe richieste, mentre le frasi di throttling specifiche dei provider alimentano invece la classificazione separata del failover.
• I profili OpenAI con chiave API e i profili OAuth di ChatGPT o Codex usano entrambi l’ID canonico di OpenAI, e doctor riscrive gli ID dei vecchi profili Codex e le voci dell’ordine di autenticazione. Più accessi per lo stesso provider restano separati tramite gli ID dei profili, un flag di forzatura elimina un profilo bloccato o dell’account sbagliato e riavvia il flusso, una sessione fissa una credenziale specifica con il comando model e un suffisso di profilo, e i comandi per agente dell’ordine di autenticazione leggono, impostano e cancellano la selezione automatica.

OpenClaw con Claude e OpenClaw con un abbonamento ChatGPT sono i due percorsi in abbonamento che questa pagina tiene distinti da una chiave API.

Quando non funziona

L’errore No credentials found significa che la chiave non si trova sull’host del Gateway oppure che il percorso del token di configurazione non è mai stato eseguito, e models status conferma la correzione; un token in scadenza o scaduto compare nello stesso stato e si rinnova tramite il token di configurazione o si sostituisce con una chiave API. I comandi di nuova sessione e di reset cancellano lo stato automatico di fallback e rotazione, ma conservano i profili fissati esplicitamente che sono ancora validi, e cambiare l’ordine di autenticazione cambia solo la selezione automatica. Il failover dei modelli in OpenClaw è il meccanismo che cambia modello o provider in caso di errori ripetuti, distinto dalla rotazione delle chiavi, mentre la guida ai segreti in OpenClaw descrive la sintassi usata dai riferimenti a chiavi e token.

Su Diali

Su Diali una chiave che porti tu va nel Vault e la configurazione che generiamo vi fa riferimento; senza chiave, l’assistente funziona con i crediti IA gestiti, e la dashboard mostra quale dei due è in uso. Può funzionare anche con un piano ChatGPT, SuperGrok o MiniMax che paghi già: la dashboard mostra un codice monouso, lo approvi sulla pagina del provider e l’assistente conserva da sé l’accesso, quindi Diali non detiene mai il token. Il setup token di Anthropic e l’accesso tramite Claude CLI sono disattivati su Diali, perché i termini di Anthropic non consentono a un servizio ospitato di funzionare con un abbonamento Claude; al loro posto funzionano una chiave API Anthropic o i crediti gestiti. OpenClaw ospitato su Diali è l’assistente, mentre la guida a modelli e provider di OpenClaw descrive i provider dietro le chiavi.

• Una chiave API sull’host per un Gateway sempre attivo.
• Profili di autenticazione in SQLite, endpoint nella configurazione.
• Rotazione per i limiti di frequenza; failover per tutto il resto.