Variabili d’ambiente

OpenClaw recupera le variabili d’ambiente da piu fonti. La regola e non sovrascrivere mai i valori esistenti.

Precedenza (dalla piu alta alla piu bassa)

Ambiente del processo (cio che il processo Gateway ha gia dalla shell/daemon genitore).
.env nella directory di lavoro corrente (default di dotenv; non sovrascrive).
.env globale in ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env; non sovrascrive).
Blocco env nella configurazione in ~/.openclaw/openclaw.json (applicato solo se mancante).
Importazione opzionale della shell di login (env.shellEnv.enabled o OPENCLAW_LOAD_SHELL_ENV=1), applicata solo per chiavi attese mancanti.

Se il file di configurazione e completamente assente, il passo 4 viene saltato; l’importazione della shell viene eseguita comunque se abilitata.

Blocco `env` nella configurazione

Due modi equivalenti per impostare variabili d’ambiente inline (entrambi non sovrascrivono):

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

Importazione dell’env della shell

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

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

Equivalenti come variabili d’ambiente:

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Variabili d’ambiente iniettate a runtime

OpenClaw inietta anche marcatori di contesto nei processi figli generati:

OPENCLAW_SHELL=exec: impostato per comandi eseguiti tramite lo strumento exec.
OPENCLAW_SHELL=acp: impostato per spawn di processi backend ACP (ad esempio acpx).
OPENCLAW_SHELL=acp-client: impostato per openclaw acp client quando genera il processo ponte ACP.
OPENCLAW_SHELL=tui-local: impostato per comandi shell locali ! del TUI.

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

Variabili d’ambiente dell’UI

OPENCLAW_THEME=light: forzare la palette chiara del TUI quando il terminale ha sfondo chiaro.
OPENCLAW_THEME=dark: forzare la palette scura del TUI.
COLORFGBG: se il terminale lo esporta, OpenClaw usa il suggerimento del colore di sfondo per selezionare automaticamente la palette TUI.

Sostituzione di variabili d’ambiente nella configurazione

Puoi referenziare variabili d’ambiente direttamente nei valori stringa della configurazione usando la sintassi ${VAR_NAME}:

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

Vedi Configurazione: Sostituzione variabili d’ambiente per i dettagli completi.

SecretRef vs stringhe `${ENV}`

OpenClaw supporta due pattern basati sulle variabili d’ambiente:

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

Entrambi si risolvono dall’env del processo al momento dell’attivazione. I dettagli di SecretRef sono documentati in Gestione dei Segreti.

Variabili d’ambiente relative ai percorsi

Variabile	Scopo
`OPENCLAW_HOME`	Sovrascrivere la directory home usata per tutta la risoluzione interna dei percorsi (`~/.openclaw/`, directory agenti, sessioni, credenziali). Utile quando OpenClaw viene eseguito come utente di servizio dedicato.
`OPENCLAW_STATE_DIR`	Sovrascrivere la directory di stato (default `~/.openclaw`).
`OPENCLAW_CONFIG_PATH`	Sovrascrivere il percorso del file di configurazione (default `~/.openclaw/openclaw.json`).

Logging

Variabile	Scopo
`OPENCLAW_LOG_LEVEL`	Sovrascrivere il livello di log per file e console (es. `debug`, `trace`). Ha precedenza su `logging.level` e `logging.consoleLevel` nella configurazione. I valori non validi vengono ignorati con un avviso.

`OPENCLAW_HOME`

Quando impostato, OPENCLAW_HOME sostituisce la directory home di sistema ($HOME / os.homedir()) per tutta la risoluzione interna dei percorsi. Questo permette l’isolamento completo del filesystem per account di servizio headless.

Precedenza: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

Esempio (macOS LaunchDaemon):

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

OPENCLAW_HOME puo anche essere impostato su un percorso con tilde (es. ~/svc), che viene espanso usando $HOME prima dell’uso.