Variabili d'ambiente

OmeniaClaw legge le variabili d'ambiente da più fonti. La regola è non sovrascrivere mai i valori esistenti.

Precedenza (dalla più alta alla più bassa)

1. Ambiente del processo (ciò che il processo Gateway ha già dalla shell o dal daemon padre).
2. .env nella directory di lavoro corrente (valore predefinito di dotenv; non sovrascrive).
3. .env globale in ~/.OmeniaClaw/.env (ovvero $OmeniaClaw_STATE_DIR/.env; non sovrascrive).
4. Blocco env della configurazione in ~/.OmeniaClaw/OmeniaClaw.json (applicato solo se mancante).
5. Importazione login-shell opzionale (env.shellEnv.enabled o OmeniaClaw_LOAD_SHELL_ENV=1), applicata solo per le chiavi previste mancanti.

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

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

Blocco env della 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 env shell

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

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

Equivalenti come variabili d'ambiente:

• OmeniaClaw_LOAD_SHELL_ENV=1
• OmeniaClaw_SHELL_ENV_TIMEOUT_MS=15000

Variabili d'ambiente iniettate a runtime

OmeniaClaw inietta anche marcatori di contesto nei processi figlio avviati:

• OmeniaClaw_SHELL=exec: impostata per i comandi eseguiti tramite lo strumento exec.
• OmeniaClaw_SHELL=acp: impostata per gli avvii di processi backend runtime ACP (ad esempio acpx).
• OmeniaClaw_SHELL=acp-client: impostata per OmeniaClaw acp client quando avvia il processo bridge ACP.
• OmeniaClaw_SHELL=tui-local: impostata per i comandi shell ! della TUI locale.

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

Variabili d'ambiente dell'interfaccia utente

• OmeniaClaw_THEME=light: forza la palette TUI chiara quando il terminale ha uno sfondo chiaro.
• OmeniaClaw_THEME=dark: forza la palette TUI scura.
• COLORFGBG: se il terminale la esporta, OmeniaClaw usa l'indizio sul colore di sfondo per scegliere automaticamente la palette TUI.

Sostituzione di 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 di variabili d'ambiente per i dettagli completi.

Riferimenti ai segreti rispetto alle stringhe ${ENV}

OmeniaClaw supporta due pattern basati sull'ambiente:

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

Entrambi vengono risolti dall'ambiente del processo al momento dell'attivazione. I dettagli di SecretRef sono documentati in Gestione dei segreti.

Variabili d'ambiente relative ai percorsi

Logging

OmeniaClaw_HOME

Quando è impostata, OmeniaClaw_HOME sostituisce la directory home di sistema ($HOME / os.homedir()) per tutta la risoluzione dei percorsi interni. Questo abilita l'isolamento completo del filesystem per account di servizio headless.

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

Esempio (macOS LaunchDaemon):

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

OmeniaClaw_HOME può anche essere impostata su un percorso con tilde (ad esempio ~/svc), che viene espanso usando $HOME prima dell'uso.

utenti nvm: errori TLS di web_fetch

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

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

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

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

Esporta la variabile prima di avviare OmeniaClaw:

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

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

Variabili d'ambiente legacy

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

Se qualcuno di questi è ancora impostato sul processo Gateway all'avvio, OmeniaClaw emette un singolo avviso di deprecazione Node (OmeniaClaw_LEGACY_ENV_VARS) che elenca i prefissi rilevati e il conteggio totale. Rinomina ogni valore sostituendo il prefisso legacy con OmeniaClaw_ (ad esempio CLAWDBOT_GATEWAY_TOKEN → OmeniaClaw_GATEWAY_TOKEN); i vecchi nomi non hanno alcun effetto.

Correlati

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