Variables d’environnement

OpenClaw charge les variables d’environnement depuis plusieurs sources. La regle est de ne jamais ecraser les valeurs existantes.

Priorite (de la plus haute a la plus basse)

Environnement du processus (ce que le processus Gateway possede deja du shell/daemon parent).
.env dans le repertoire de travail courant (comportement par defaut de dotenv ; n’ecrase pas).
.env global dans ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env ; n’ecrase pas).
Bloc env dans la configuration dans ~/.openclaw/openclaw.json (applique uniquement si absent).
Importation optionnelle du shell de connexion (env.shellEnv.enabled ou OPENCLAW_LOAD_SHELL_ENV=1), appliquee uniquement pour les cles attendues manquantes.

Si le fichier de configuration est completement absent, l’etape 4 est ignoree ; l’importation du shell s’execute toujours si activee.

Bloc `env` dans la configuration

Deux moyens equivalents de definir des variables d’environnement en ligne (les deux ne surchargent pas) :

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

Importation de l’env du shell

env.shellEnv execute votre shell de connexion et importe uniquement les cles attendues manquantes :

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

Equivalents en variables d’environnement :

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Variables d’environnement injectees a l’execution

OpenClaw injecte egalement des marqueurs de contexte dans les processus enfants lances :

OPENCLAW_SHELL=exec : defini pour les commandes executees via l’outil exec.
OPENCLAW_SHELL=acp : defini pour les lancements de processus backend ACP (par exemple acpx).
OPENCLAW_SHELL=acp-client : defini pour openclaw acp client lorsqu’il lance le processus pont ACP.
OPENCLAW_SHELL=tui-local : defini pour les commandes shell locales ! du TUI.

Ce sont des marqueurs d’execution (pas de configuration utilisateur requise). Ils peuvent etre utilises dans la logique shell/profil pour appliquer des regles specifiques au contexte.

Variables d’environnement de l’UI

OPENCLAW_THEME=light : forcer la palette claire du TUI lorsque votre terminal a un fond clair.
OPENCLAW_THEME=dark : forcer la palette sombre du TUI.
COLORFGBG : si votre terminal l’exporte, OpenClaw utilise l’indice de couleur de fond pour choisir automatiquement la palette TUI.

Substitution de variables d’environnement dans la configuration

Vous pouvez referencer des variables d’environnement directement dans les valeurs de chaines de configuration en utilisant la syntaxe ${VAR_NAME} :

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

Voir Configuration : Substitution de variables d’environnement pour les details complets.

SecretRef vs chaines `${ENV}`

OpenClaw prend en charge deux modeles bases sur les variables d’environnement :

Substitution de chaines ${VAR} dans les valeurs de configuration.
Objets SecretRef ({ source: "env", provider: "default", id: "VAR" }) pour les champs qui prennent en charge les references de secrets.

Les deux se resolvent depuis l’environnement du processus au moment de l’activation. Les details de SecretRef sont documentes dans Gestion des Secrets.

Variables d’environnement liees aux chemins

Variable	Objectif
`OPENCLAW_HOME`	Remplacer le repertoire home utilise pour toute la resolution interne des chemins (`~/.openclaw/`, repertoires d’agents, sessions, identifiants). Utile lorsqu’OpenClaw est execute en tant qu’utilisateur de service dedie.
`OPENCLAW_STATE_DIR`	Remplacer le repertoire d’etat (par defaut `~/.openclaw`).
`OPENCLAW_CONFIG_PATH`	Remplacer le chemin du fichier de configuration (par defaut `~/.openclaw/openclaw.json`).

Journalisation

Variable	Objectif
`OPENCLAW_LOG_LEVEL`	Remplacer le niveau de journalisation pour fichier et console (ex. `debug`, `trace`). Prend le pas sur `logging.level` et `logging.consoleLevel` dans la configuration. Les valeurs invalides sont ignorees avec un avertissement.

`OPENCLAW_HOME`

Lorsqu’il est defini, OPENCLAW_HOME remplace le repertoire home du systeme ($HOME / os.homedir()) pour toute la resolution interne des chemins. Cela permet l’isolation complete du systeme de fichiers pour les comptes de service headless.

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

Exemple (macOS LaunchDaemon) :

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

OPENCLAW_HOME peut aussi etre defini sur un chemin avec tilde (ex. ~/svc), qui est expanse en utilisant $HOME avant utilisation.