Variabili d'ambiente

OpenClaw carica le variabili d'ambiente da più fonti. La regola è non sovrascrivere mai i valori esistenti. I file .env dell'area di lavoro sono una fonte con minore attendibilità: OpenClaw ignora le credenziali dei provider e i controlli runtime protetti dal .env dell'area di lavoro prima di applicare la precedenza.

Precedenza (dalla più alta alla più bassa)

1. Ambiente del processo (ciò che il processo Gateway ha già dalla shell/daemon padre).
2. .env nella directory di lavoro corrente (predefinito dotenv; non sovrascrive; le credenziali dei provider e i controlli runtime protetti vengono ignorati).
3. .env globale in ~/.openclaw/.env (ovvero $OPENCLAW_STATE_DIR/.env; consigliato per le chiavi API dei provider; non sovrascrive).
4. Blocco env della configurazione in ~/.openclaw/openclaw.json (applicato solo se mancante).
5. Importazione opzionale dalla shell di login (env.shellEnv.enabled o OPENCLAW_LOAD_SHELL_ENV=1), applicata solo per le chiavi previste mancanti.

Nelle nuove installazioni su Ubuntu che usano la directory di stato predefinita, OpenClaw tratta anche ~/.config/openclaw/gateway.env come fallback di compatibilità dopo il .env globale. Se entrambi i file esistono e non coincidono, OpenClaw mantiene ~/.openclaw/.env e stampa un avviso.

Se il file di configurazione manca del tutto, il passaggio 4 viene saltato; l'importazione dalla shell viene comunque eseguita se abilitata.

Credenziali dei provider e .env dell'area di lavoro

Non conservare le chiavi API dei provider solo in un .env dell'area di lavoro. OpenClaw ignora le variabili d'ambiente delle credenziali dei provider dai file .env dell'area di lavoro, incluse chiavi comuni come GEMINI_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, PERPLEXITY_API_KEY, BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY e FIRECRAWL_API_KEY.

Usa una di queste fonti attendibili per le credenziali dei provider:

• L'ambiente del processo Gateway, come una shell, un'unità launchd/systemd, un segreto del container o un segreto CI.
• Il file dotenv runtime globale in ~/.openclaw/.env o $OPENCLAW_STATE_DIR/.env.
• Il blocco env della configurazione in ~/.openclaw/openclaw.json.
• L'importazione opzionale dalla shell di login quando env.shellEnv.enabled o OPENCLAW_LOAD_SHELL_ENV=1 è abilitato.

Se in precedenza hai archiviato le chiavi dei provider solo in un .env dell'area di lavoro, spostale in una delle fonti attendibili indicate sopra. Il .env dell'area di lavoro può ancora fornire normali variabili di progetto che non siano credenziali, reindirizzamenti di endpoint, override host o controlli runtime OPENCLAW_*.

Vedi File .env dell'area di lavoro per la motivazione di sicurezza.

Blocco env della configurazione

Due modi equivalenti per impostare variabili d'ambiente inline (entrambi senza sovrascrittura):

{  env: {    OPENROUTER_API_KEY: "sk-or-...",    vars: {      GROQ_API_KEY: "gsk-...",    },  },}

Il blocco env della configurazione accetta solo valori stringa letterali. Non espande i valori file:...; per esempio, XAI_API_KEY: "file:secrets/xai-api-key.txt" viene passato ai provider come quella stringa esatta.

Per chiavi dei provider basate su file, usa una SecretRef sul campo credenziale che la supporta:

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

Vedi Gestione dei segreti e la superficie delle credenziali SecretRef per i campi supportati.

Importazione env dalla shell

env.shellEnv esegue la tua shell di login e importa solo le chiavi previste mancanti:

{  env: {    shellEnv: {      enabled: true,      timeoutMs: 15000,    },  },}

Variabili d'ambiente equivalenti:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Snapshot della shell exec

Sugli host Gateway non Windows, i comandi exec di bash e zsh usano per impostazione predefinita uno snapshot di avvio. Imposta OPENCLAW_EXEC_SHELL_SNAPSHOT=0 nell'ambiente del processo Gateway per disabilitare questo percorso. Anche i valori false, no e off lo disabilitano. I valori exec.env per singola chiamata non possono attivare o disattivare gli snapshot né reindirizzare la cache degli snapshot.

Variabili d'ambiente iniettate dal runtime

OpenClaw inietta anche marker di contesto nei processi figli generati:

• OPENCLAW_SHELL=exec: impostato per i comandi eseguiti tramite lo strumento exec.
• OPENCLAW_SHELL=acp: impostato per gli spawn dei processi backend runtime ACP (per esempio acpx).
• OPENCLAW_SHELL=acp-client: impostato per openclaw acp client quando genera il processo bridge ACP.
• OPENCLAW_SHELL=tui-local: impostato per i comandi shell ! della TUI locale.
• OPENCLAW_CLI=1: impostato per i processi figli generati dall'entry point della CLI.

Questi sono marker runtime (non configurazione utente richiesta). Possono essere usati nella logica shell/profilo per applicare regole specifiche del contesto.

Variabili d'ambiente UI

• OPENCLAW_THEME=light: forza la palette TUI chiara quando il terminale ha uno sfondo chiaro.
• OPENCLAW_THEME=dark: forza la palette TUI scura.
• COLORFGBG: se il terminale la esporta, OpenClaw usa il suggerimento sul colore di sfondo per scegliere automaticamente la palette TUI.

Sostituzione delle variabili d'ambiente nella configurazione

Puoi fare riferimento direttamente alle variabili d'ambiente nei valori stringa della configurazione usando la sintassi ${VAR_NAME}:

{  models: {    providers: {      "vercel-gateway": {        apiKey: "${VERCEL_GATEWAY_API_KEY}",      },    },  },}

Vedi Configurazione: sostituzione delle variabili d'ambiente per tutti i dettagli.

Riferimenti ai segreti rispetto a stringhe ${ENV}

OpenClaw supporta due pattern guidati dall'ambiente:

• Sostituzione di stringhe ${VAR} nei valori di configurazione.
• Oggetti SecretRef ({ source: "env", provider: "default", id: "VAR" }) per i campi che supportano riferimenti ai segreti.

Entrambi vengono risolti dall'ambiente del processo al momento dell'attivazione. I dettagli di SecretRef sono documentati in Gestione dei segreti. Il blocco env della configurazione stesso non risolve SecretRef o valori abbreviati file:....

Variabili d'ambiente relative ai percorsi

Logging

OPENCLAW_HOME

Quando impostato, OPENCLAW_HOME sostituisce la directory home di sistema ($HOME / os.homedir()) per i percorsi predefiniti interni di OpenClaw. Ciò include la directory di stato predefinita, il percorso di configurazione, le directory degli agenti, le credenziali, l'area di lavoro di onboarding dell'installer e il checkout dev predefinito usato da openclaw update --channel dev.

Precedenza: OPENCLAW_HOME > $HOME > USERPROFILE > fallback della home Termux PREFIX su Android > os.homedir()

Esempio (macOS LaunchDaemon):

<key>EnvironmentVariables</key><dict>  <key>OPENCLAW_HOME</key>  <string>/Users/user</string></dict>

OPENCLAW_HOME può anche essere impostato su un percorso con tilde (es. ~/svc), che viene espanso usando la stessa catena di fallback della home del sistema operativo prima dell'uso.

Le variabili di percorso esplicite come OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH e OPENCLAW_GIT_DIR hanno comunque precedenza. Le attività dell'account del sistema operativo, come il rilevamento dei file di avvio della shell, la configurazione del gestore pacchetti e l'espansione di ~ dell'host, possono comunque usare la vera home di sistema.

Utenti nvm: errori TLS di web_fetch

Se Node.js è stato installato tramite nvm (non tramite il gestore pacchetti di sistema), il fetch() integrato usa l'archivio CA incluso in nvm, che potrebbe non contenere CA radice moderne (ISRG Root X1/X2 per Let's Encrypt, DigiCert Global Root G2, ecc.). Questo fa fallire web_fetch con "fetch failed" sulla maggior parte dei siti HTTPS.

Su Linux, OpenClaw rileva automaticamente nvm e applica la correzione nell'ambiente di avvio effettivo:

• openclaw gateway install scrive NODE_EXTRA_CA_CERTS nell'ambiente del servizio systemd
• l'entrypoint CLI openclaw riesegue se stesso con NODE_EXTRA_CA_CERTS impostato prima dell'avvio di Node

Correzione manuale (per versioni precedenti o avvii diretti node ...):

Esporta la variabile prima di avviare OpenClaw:

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crtopenclaw gateway run

Non fare affidamento sulla sola scrittura in ~/.openclaw/.env per questa variabile; Node legge NODE_EXTRA_CA_CERTS all'avvio del processo.

Variabili d'ambiente legacy

OpenClaw legge solo le variabili d'ambiente OPENCLAW_*. I prefissi legacy CLAWDBOT_* e MOLTBOT_* delle versioni precedenti vengono ignorati silenziosamente.

Se alcune sono ancora impostate sul processo Gateway all'avvio, OpenClaw emette un singolo avviso di deprecazione Node (OPENCLAW_LEGACY_ENV_VARS) che elenca i prefissi rilevati e il conteggio totale. Rinomina ogni valore sostituendo il prefisso legacy con OPENCLAW_ (per esempio CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN); i vecchi nomi non hanno alcun effetto.

Correlati

• Configurazione del Gateway
• FAQ: variabili d'ambiente e caricamento .env
• Panoramica dei modelli