Autenticazione

OpenClaw supporta OAuth e le chiavi API per i provider di modelli. Per un host Gateway sempre attivo, una chiave API è l'opzione più prevedibile; anche i flussi di abbonamento/OAuth funzionano quando sono compatibili con il modello di account del provider.

• Flusso OAuth completo e struttura di archiviazione: /concepts/oauth
• Autenticazione basata su SecretRef (provider env/file/exec): Gestione dei segreti
• Codici di idoneità/motivazione delle credenziali utilizzati da models status --probe: Semantica delle credenziali di autenticazione

Configurazione consigliata: chiave API (qualsiasi provider)

1. Crea una chiave API nella console del provider.
2. Inseriscila nell'host Gateway (la macchina che esegue openclaw gateway):

export <PROVIDER>_API_KEY="..."openclaw models status

3. Se il Gateway viene eseguito tramite systemd/launchd, inserisci la chiave in ~/.openclaw/.env affinché il daemon possa leggerla:

cat >> ~/.openclaw/.env <<'EOF'&lt;PROVIDER&gt;_API_KEY=...EOF

4. Riavvia il processo Gateway (o il daemon), quindi verifica nuovamente:

openclaw models statusopenclaw doctor

Anche openclaw onboard può archiviare le chiavi API per l'uso da parte del daemon, se non vuoi gestire personalmente le variabili di ambiente. Consulta Variabili di ambiente per la precedenza completa del caricamento dell'ambiente (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic: riutilizzo della CLI Claude

L'autenticazione tramite token di configurazione Anthropic rimane un percorso supportato. È consentito anche il riutilizzo della CLI Claude (utilizzo in stile claude -p) per questa integrazione; quando sull'host è disponibile un accesso alla CLI Claude, questo è il percorso preferito per l'uso locale/desktop. Per gli host Gateway di lunga durata, una chiave API Anthropic rimane comunque la scelta più prevedibile, con un controllo esplicito della fatturazione lato server.

Configurazione dell'host per il riutilizzo della CLI Claude:

# Esegui sull'host Gatewayclaude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Sono necessari due passaggi: accedere ad Anthropic con Claude Code sull'host, quindi indicare a OpenClaw di instradare la selezione dei modelli Anthropic attraverso il backend locale claude-cli e di archiviare il profilo di autenticazione OpenClaw corrispondente.

Se claude non è presente in PATH, installa Claude Code oppure imposta agents.defaults.cliBackends.claude-cli.command sul percorso del file binario.

Immissione manuale del token

Funziona con qualsiasi provider; scrive nell'archivio di autenticazione SQLite del singolo agente e aggiorna la configurazione:

openclaw models auth paste-token --provider openrouter

OpenClaw legge i profili di autenticazione dal file openclaw-agent.sqlite di ciascun agente. I dettagli dell'endpoint (baseUrl, api, ID dei modelli, intestazioni, timeout) devono essere definiti in models.providers.<id> in openclaw.json o models.json, non nei profili di autenticazione.

Se un'installazione precedente contiene ancora auth-profiles.json, auth-state.json o una struttura piatta come { "openrouter": { "apiKey": "..." } }, esegui openclaw doctor --fix per importarla in SQLite; doctor conserva backup con data e ora accanto ai file JSON originali.

Le modalità di autenticazione esterne, come auth: "aws-sdk" di Bedrock, non sono credenziali. Per una modalità Bedrock denominata, imposta auth.profiles.<id>.mode: "aws-sdk" in openclaw.json: non scrivere type: "aws-sdk" nell'archivio dei profili di autenticazione. openclaw doctor --fix migra i marcatori AWS SDK precedenti dall'archivio delle credenziali ai metadati di configurazione.

Credenziali basate su SecretRef

• Le credenziali api_key possono utilizzare keyRef: { source, provider, id }
• Le credenziali token possono utilizzare tokenRef: { source, provider, id }
• I profili in modalità OAuth rifiutano le credenziali SecretRef: se auth.profiles.<id>.mode è "oauth", un keyRef/tokenRef basato su SecretRef per tale profilo viene rifiutato.

Verifica dello stato di autenticazione dei modelli

openclaw models statusopenclaw doctor

Verifica adatta all'automazione, con codice di uscita 1 in caso di credenziali scadute/mancanti e 2 in caso di credenziali prossime alla scadenza:

openclaw models status --check

Verifiche di autenticazione in tempo reale (aggiungi --probe-provider, --probe-profile, --probe-timeout, --probe-concurrency o --probe-max-tokens per restringere l'ambito):

openclaw models status --probe

Note:

• Le righe della verifica possono provenire dai profili di autenticazione, dalle credenziali di ambiente o da models.json.
• Se auth.order.<provider> omette un profilo archiviato, la verifica segnala excluded_by_auth_order per tale profilo anziché provarlo.
• Se l'autenticazione esiste ma OpenClaw non riesce a individuare un modello verificabile per quel provider, la verifica segnala status: no_model.
• 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 sullo stesso provider.

Script operativi facoltativi (systemd/Termux): Script di monitoraggio dell'autenticazione.

Rotazione delle chiavi API (Gateway)

Alcuni provider riprovano una richiesta con una chiave alternativa configurata quando una chiamata raggiunge un limite di frequenza del provider.

Ordine di priorità delle chiavi per provider:

1. OPENCLAW_LIVE_<PROVIDER>_KEY (singola sostituzione, fissa una chiave)
2. <PROVIDER>_API_KEYS (elenco separato da virgole/spazi/punti e virgola)
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_* (qualsiasi variabile di ambiente con questo prefisso)

I provider Google (google, google-vertex) utilizzano inoltre GOOGLE_API_KEY come ripiego. L'elenco combinato viene deduplicato prima dell'uso.

OpenClaw passa alla chiave successiva solo quando il messaggio di errore corrisponde a: rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted o too many requests. Gli altri errori non vengono riprovati con chiavi alternative. Se tutte le chiavi non funzionano, viene restituito l'errore finale dell'ultimo tentativo.

La rimozione dell'autenticazione salvata non revoca la chiave presso il provider: quando è necessaria l'invalidazione lato provider, ruotala o revocala nel pannello di controllo del provider.

Rimozione dell'autenticazione di un provider mentre il Gateway è in esecuzione

Quando rimuovi l'autenticazione di un provider tramite il piano di controllo del Gateway, OpenClaw elimina i profili di autenticazione salvati per quel provider e interrompe le esecuzioni attive di chat/agenti il cui provider del modello selezionato corrisponde a quello rimosso. Le esecuzioni interrotte emettono i normali eventi di annullamento/ciclo di vita con stopReason: "auth-revoked", consentendo ai client connessi di mostrare che l'esecuzione è stata arrestata perché le credenziali sono state rimosse.

Controllo della credenziale utilizzata

OpenAI e ID precedenti openai-codex

I profili con chiave API OpenAI e i profili OAuth ChatGPT/Codex utilizzano entrambi l'ID provider canonico openai. Per le nuove configurazioni, utilizza ID profilo openai:* e auth.order.openai.

Se trovi openai-codex in configurazioni precedenti, ID dei profili di autenticazione o auth.order.openai-codex, consideralo un input di migrazione precedente: non creare nuovi profili openai-codex. Esegui:

openclaw doctor --fixopenclaw models auth list --provider openai

Doctor riscrive gli ID profilo precedenti openai-codex:* e le voci auth.order.openai-codex nel percorso canonico openai. Per l'instradamento di modelli/runtime specifico di OpenAI, consulta OpenAI.

Durante l'accesso (CLI)

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

--profile-id mantiene separati più accessi OAuth allo stesso provider all'interno di un singolo agente.

--force elimina i profili di autenticazione salvati per quel provider nella directory dell'agente selezionato, quindi riesegue lo stesso flusso di autenticazione. Utilizzalo quando un profilo salvato è bloccato, scaduto o associato all'account errato. Non revoca le credenziali presso il provider.

openclaw models auth login --provider anthropic --force

Per sessione (comando di chat)

• /model <alias-or-id>@<profileId> fissa una credenziale specifica del provider per la sessione corrente (esempi di ID profilo: anthropic:default, anthropic:work).
• /model (o /model list) mostra un selettore compatto; /model status mostra la visualizzazione completa (candidati + profilo di autenticazione successivo, oltre ai dettagli dell'endpoint del provider, se configurati).

Se modifichi l'ordine di autenticazione o il profilo fissato per una chat già in esecuzione, invia /new o /reset per avviare una nuova sessione: le sessioni esistenti mantengono la selezione corrente di modello/profilo fino alla reimpostazione.

Per agente (sostituzione tramite CLI)

Le sostituzioni dell'ordine di autenticazione vengono archiviate nello stato di autenticazione SQLite dell'agente:

openclaw models auth order get --provider anthropicopenclaw models auth order set --provider anthropic anthropic:defaultopenclaw models auth order clear --provider anthropic

Utilizza --agent <id> per specificare un agente; omettelo per utilizzare l'agente predefinito configurato. openclaw models status --probe mostra i profili archiviati omessi come excluded_by_auth_order anziché ignorarli silenziosamente.

Risoluzione dei problemi

"Nessuna credenziale trovata"

Configura una chiave API Anthropic sull'host Gateway oppure configura il percorso del token di configurazione Anthropic, quindi verifica nuovamente:

openclaw models status

Token prossimo alla scadenza/scaduto

Esegui openclaw models status per vedere quale profilo è prossimo alla scadenza. Se un profilo token Anthropic è mancante o scaduto, aggiornalo tramite il token di configurazione oppure esegui la migrazione a una chiave API Anthropic.

Contenuti correlati

• Gestione dei segreti
• Accesso remoto
• Archiviazione dell'autenticazione