English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

Autenticazione

OpenClaw supporta OAuth e le chiavi API per i provider di modelli. Per gli host Gateway sempre attivi, le chiavi API sono di solito l'opzione più prevedibile. I flussi con abbonamento/OAuth sono supportati anche quando corrispondono al modello di account del provider.

Consulta /concepts/oauth per il flusso OAuth completo e la struttura 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 di 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 riutilizzo di un accesso locale alla Claude CLI.

  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
  1. Se il Gateway viene eseguito tramite systemd/launchd, preferisci inserire la chiave in ~/.openclaw/.env in modo che il demone possa leggerla:
cat >> ~/.openclaw/.env <<'EOF'
&lt;PROVIDER&gt;_API_KEY=...
EOF

Poi riavvia il demone (o riavvia il processo Gateway) e verifica di nuovo:

openclaw models status
openclaw doctor

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

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

Anthropic: compatibilità con Claude CLI e token

L'autenticazione con setup-token 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 è di nuovo consentito, quindi OpenClaw tratta il riutilizzo della Claude CLI e l'uso di claude -p come approvati per questa integrazione, a meno che Anthropic non pubblichi una nuova policy. Quando il riutilizzo della Claude CLI è disponibile sull'host, ora è il percorso preferito.

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

Configurazione host consigliata per il riutilizzo della Claude CLI:

# Run on the gateway host
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

Questa configurazione avviene in due passaggi:

  1. Accedi ad Anthropic con Claude Code stesso sull'host Gateway.
  2. Indica a OpenClaw di passare la selezione dei modelli Anthropic al backend locale claude-cli e di archiviare 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 auth-profiles.json + aggiorna la configurazione):

openclaw models auth paste-token --provider openrouter

auth-profiles.json archivia solo le credenziali. La forma canonica è:

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

OpenClaw si aspetta la forma canonica version + profiles a runtime. Se un'installazione più vecchia ha ancora un file piatto come { "openrouter": { "apiKey": "..." } }, esegui openclaw doctor --fix per riscriverlo come profilo chiave API openrouter:default; doctor conserva una copia .legacy-flat.*.bak accanto all'originale. I dettagli degli endpoint come baseUrl, api, ID dei modelli, header e timeout vanno sotto models.providers.<id> in openclaw.json o models.json, non in auth-profiles.json.

Sono supportati anche i riferimenti ai profili di autenticazione per le 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 (uscita 1 quando scaduto/mancante, 2 quando in scadenza):

openclaw models status --check

Sonde di autenticazione live:

openclaw models status --probe

Note:

  • Le righe della sonda possono provenire da profili di autenticazione, credenziali d'ambiente o models.json.
  • Se auth.order.<provider> esplicito omette un profilo archiviato, la sonda segnala excluded_by_auth_order per quel profilo invece di provarlo.
  • Se l'autenticazione esiste ma OpenClaw non riesce a risolvere un candidato modello sondabile per quel provider, la sonda segnala status: no_model.
  • I cooldown per rate limit possono essere specifici del modello. Un profilo in cooldown per un modello può comunque essere utilizzabile per un modello affine 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 è di nuovo consentito.
  • OpenClaw quindi tratta il riutilizzo della Claude CLI e l'uso di claude -p come approvati per le esecuzioni basate su Anthropic, a meno che Anthropic non pubblichi una nuova policy.
  • Le chiavi API Anthropic restano la scelta più prevedibile per gli host Gateway di lunga durata e per il controllo esplicito della fatturazione lato server.

Controllare lo stato dell'autenticazione dei modelli

openclaw models status
openclaw doctor

Comportamento della rotazione delle chiavi API (Gateway)

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

  • Ordine di priorità:
    • OPENCLAW_LIVE_&lt;PROVIDER&gt;_KEY (override singolo)
    • &lt;PROVIDER&gt;_API_KEYS
    • &lt;PROVIDER&gt;_API_KEY
    • &lt;PROVIDER&gt;_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 rate limit (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 legati al rate limit non vengono riprovati con chiavi alternative.
  • Se tutte le chiavi falliscono, viene restituito l'errore finale dell'ultimo tentativo.

Controllare quale credenziale viene usata

Per sessione (comando chat)

Usa /model <alias-or-id>@<profileId> per fissare una credenziale specifica del provider 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ù i dettagli dell'endpoint del provider quando configurati).

Per agente (override CLI)

Imposta un override esplicito dell'ordine dei profili di autenticazione per un agente (archiviato in auth-state.json di quell'agente):

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

Usa --agent <id> per scegliere come destinazione 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 archiviati omessi come excluded_by_auth_order invece di saltarli silenziosamente. Quando esegui il debug di problemi di cooldown, ricorda che i cooldown per rate limit possono essere legati a un ID modello invece che all'intero profilo del provider.

Risoluzione dei problemi

"No credentials found"

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

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