Autenticazione

OpenClaw supporta OAuth e chiavi API per i provider di modelli. Per gli host Gateway always-on, le chiavi API sono in genere l'opzione più prevedibile. Sono supportati anche i flussi con abbonamento/OAuth quando corrispondono al modello di account del tuo provider.

Consulta /concepts/oauth per il flusso OAuth completo e il layout di archiviazione. Per l'autenticazione basata su SecretRef (provider env/file/exec), consulta Gestione dei segreti. Per le regole di idoneità delle credenziali/codici motivo usate da models status --probe, consulta Semantica delle credenziali di autenticazione.

Configurazione consigliata (chiave API, qualsiasi provider)

Se esegui un Gateway a lunga durata, inizia con una chiave API per il provider scelto. Per Anthropic in particolare, l'autenticazione con chiave API resta la configurazione server più prevedibile, ma OpenClaw supporta anche il riuso di un login locale della Claude CLI.

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

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

3. Se il Gateway viene eseguito sotto systemd/launchd, preferisci inserire la chiave in ~/.openclaw/.env così il daemon può leggerla:

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

Poi riavvia il daemon (o riavvia il processo Gateway) e ricontrolla:

openclaw models statusopenclaw doctor

Se preferisci non gestire personalmente le variabili d'ambiente, l'onboarding può salvare le chiavi API per l'uso da parte del daemon: openclaw onboard.

Consulta Guida per dettagli sull'ereditarietà dell'ambiente (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic: Claude CLI e compatibilità dei token

L'autenticazione setup-token di Anthropic è ancora disponibile in OpenClaw come percorso token supportato. Da allora lo staff Anthropic ci ha comunicato che l'uso della Claude CLI in stile OpenClaw è nuovamente consentito, quindi OpenClaw considera il riuso della Claude CLI e l'uso di claude -p approvati per questa integrazione, salvo pubblicazione di una nuova policy da parte di Anthropic. Quando il riuso della Claude CLI è disponibile sull'host, ora è il percorso preferito.

Per host Gateway a lunga durata, una chiave API Anthropic resta comunque la configurazione più prevedibile. Se vuoi riutilizzare un login Claude esistente sullo stesso host, usa il percorso Anthropic Claude CLI in onboarding/configure.

Configurazione host consigliata per il riuso della Claude CLI:

# Run on the gateway hostclaude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Questa è una configurazione in due passaggi:

1. Accedi con Claude Code stesso ad Anthropic sull'host Gateway.
2. Indica a OpenClaw di passare la selezione del modello Anthropic al backend locale claude-cli e di salvare il profilo di autenticazione OpenClaw corrispondente.

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

Inserimento manuale del token (qualsiasi provider; scrive lo store di autenticazione SQLite per agente + aggiorna la configurazione):

openclaw models auth paste-token --provider openrouter

Lo store dei profili di autenticazione conserva solo le credenziali. I file legacy auth-profiles.json usavano questa forma canonica:

{  "version": 1,  "profiles": {    "openrouter:default": {      "type": "api_key",      "provider": "openrouter",      "key": "OPENROUTER_API_KEY"    }  }}

OpenClaw ora legge i profili di autenticazione dal openclaw-agent.sqlite di ciascun agente. Se un'installazione più vecchia ha ancora auth-profiles.json, auth-state.json o un file di profilo di autenticazione piatto come { "openrouter": { "apiKey": "..." } }, esegui openclaw doctor --fix per importarlo in SQLite; doctor conserva backup con timestamp accanto ai file JSON originali. I dettagli degli endpoint come baseUrl, api, ID dei modelli, header e timeout appartengono a models.providers.<id> in openclaw.json o models.json, non nei profili di autenticazione.

Anche le route di autenticazione esterne come Bedrock auth: "aws-sdk" non sono credenziali. Se vuoi una route Bedrock con nome, inserisci auth.profiles.<id>.mode: "aws-sdk" in openclaw.json; non scrivere type: "aws-sdk" nello store dei profili di autenticazione. openclaw doctor --fix sposta i marker legacy AWS SDK dallo store delle credenziali ai metadati di configurazione.

I riferimenti ai profili di autenticazione sono supportati anche per credenziali statiche:

• le credenziali api_key possono usare keyRef: { source, provider, id }
• le credenziali token possono usare tokenRef: { source, provider, id }
• i profili in modalità OAuth non supportano credenziali SecretRef; se auth.profiles.<id>.mode è impostato su "oauth", l'input keyRef/tokenRef basato su SecretRef per quel profilo viene rifiutato.

Controllo adatto all'automazione (exit 1 quando scaduto/mancante, 2 quando in scadenza):

openclaw models status --check

Probe di autenticazione live:

openclaw models status --probe

Note:

• Le righe dei probe possono provenire da profili di autenticazione, credenziali env o models.json.
• Se auth.order.<provider> esplicito omette un profilo salvato, il probe segnala excluded_by_auth_order per quel profilo invece di provarlo.
• Se l'autenticazione esiste ma OpenClaw non riesce a risolvere un candidato modello verificabile per quel provider, il probe segnala status: no_model.
• I cooldown dei limiti di frequenza possono essere a livello di modello. Un profilo in cooldown per un modello può essere ancora utilizzabile per un modello sibling sullo stesso provider.

Gli script operativi opzionali (systemd/Termux) sono documentati qui: Script di monitoraggio dell'autenticazione

Nota su Anthropic

Il backend Anthropic claude-cli è di nuovo supportato.

• Lo staff Anthropic ci ha comunicato che questo percorso di integrazione OpenClaw è nuovamente consentito.
• OpenClaw quindi considera il riuso della Claude CLI e l'uso di claude -p approvati per le esecuzioni basate su Anthropic, salvo pubblicazione di una nuova policy da parte di Anthropic.
• Le chiavi API Anthropic restano la scelta più prevedibile per host Gateway a lunga durata e per il controllo esplicito della fatturazione lato server.

Controllo dello stato dell'autenticazione dei modelli

openclaw models statusopenclaw doctor

Comportamento di rotazione delle chiavi API (Gateway)

Alcuni provider supportano il nuovo tentativo di una richiesta con chiavi alternative quando una chiamata API raggiunge un limite di frequenza del provider.

• Ordine di priorità:
  • OPENCLAW_LIVE_<PROVIDER>_KEY (override singolo)
  • <PROVIDER>_API_KEYS
  • <PROVIDER>_API_KEY
  • <PROVIDER>_API_KEY_*
• I provider Google includono anche GOOGLE_API_KEY come fallback aggiuntivo.
• Lo stesso elenco di chiavi viene deduplicato prima dell'uso.
• OpenClaw riprova con la chiave successiva solo per errori di limite di frequenza (per esempio 429, rate_limit, quota, resource exhausted, Too many concurrent requests, ThrottlingException, concurrency limit reached o workers_ai ... quota limit exceeded).
• Gli errori non dovuti a limiti di frequenza non vengono riprovati con chiavi alternative.
• Se tutte le chiavi falliscono, viene restituito l'errore finale dell'ultimo tentativo.

Rimozione dell'autenticazione del provider mentre il Gateway è in esecuzione

Quando l'autenticazione del provider viene rimossa tramite il piano di controllo del Gateway, OpenClaw elimina i profili di autenticazione salvati per quel provider e interrompe le chat o le esecuzioni agente attive il cui provider del modello selezionato corrisponde al provider rimosso. Le esecuzioni interrotte emettono i normali eventi di annullamento chat e ciclo di vita con stopReason: "auth-revoked", così i client connessi possono mostrare che l'esecuzione è stata arrestata perché le credenziali sono state rimosse.

La rimozione dell'autenticazione salvata non revoca le chiavi presso il provider. Ruota o revoca la chiave nella dashboard del provider quando hai bisogno di invalidazione lato provider.

Controllare quale credenziale viene usata

OpenAI e ID legacy openai-codex

I profili con chiave API OpenAI e i profili OAuth ChatGPT/Codex usano entrambi l'ID provider canonico openai. La nuova configurazione dovrebbe usare ID profilo openai:* e auth.order.openai.

Se vedi openai-codex in una configurazione più vecchia, negli ID dei profili di autenticazione o in auth.order.openai-codex, trattalo come input di migrazione legacy. Non creare nuovi profili openai-codex. Esegui:

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

Doctor riscrive gli ID profilo legacy openai-codex:* e le voci auth.order.openai-codex nella route di autenticazione canonica openai. Per il routing di modelli/runtime specifico di OpenAI, consulta OpenAI.

Durante il login (CLI)

Usa openclaw models auth login --provider <id> --profile-id <profileId> per i provider che supportano profili di autenticazione con nome durante il login.

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

Questo è il modo più semplice per mantenere separati più login OAuth per lo stesso provider all'interno di un agente.

Usa --force quando un profilo provider salvato è bloccato, scaduto o collegato all'account sbagliato e il normale comando di login continua a riutilizzarlo. --force elimina i profili di autenticazione salvati per quel provider nella directory agente selezionata, poi esegue di nuovo lo stesso flusso di autenticazione del provider. Non revoca le credenziali presso il provider; ruotale o revocale nella dashboard del provider quando hai bisogno di invalidazione lato provider.

openclaw models auth login --provider anthropic --force

Per sessione (comando chat)

Usa /model <alias-or-id>@<profileId> per fissare una credenziale provider specifica per la sessione corrente (ID profilo di esempio: anthropic:default, anthropic:work).

Usa /model (o /model list) per un selettore compatto; usa /model status per la vista completa (candidati + prossimo profilo di autenticazione, più dettagli dell'endpoint del provider quando configurati).

Per agente (override CLI)

Imposta un override esplicito dell'ordine dei profili di autenticazione per un agente (salvato nello stato di autenticazione SQLite di quell'agente):

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

Usa --agent <id> per scegliere un agente specifico; omettilo per usare l'agente predefinito configurato. Quando esegui il debug di problemi di ordine, openclaw models status --probe mostra i profili salvati omessi come excluded_by_auth_order invece di saltarli silenziosamente. Quando esegui il debug di problemi di cooldown, ricorda che i cooldown dei limiti di frequenza possono essere legati a un ID modello invece che all'intero profilo provider.

Se cambi l'ordine di autenticazione o il pinning del profilo per una chat già in esecuzione, invia /new o /reset in quella chat per avviare una nuova sessione. Le sessioni esistenti possono mantenere la selezione attuale di modello/profilo fino al reset.

Risoluzione dei problemi

"No credentials found"

Se il profilo Anthropic manca, configura una chiave API Anthropic sull' host Gateway oppure configura il percorso setup-token Anthropic, poi ricontrolla:

openclaw models status

Token in scadenza/scaduto

Esegui openclaw models status per confermare quale profilo è in scadenza. Se un profilo token Anthropic manca o è scaduto, aggiorna quella configurazione tramite setup-token oppure migra a una chiave API Anthropic.

Correlati

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