Variables d’environnement

OpenClaw charge les variables d’environnement depuis plusieurs sources. La règle est de ne jamais remplacer les valeurs existantes. Les fichiers .env de l’espace de travail constituent une source moins fiable : OpenClaw ignore les identifiants des fournisseurs et les contrôles d’exécution protégés provenant du fichier .env de l’espace de travail avant d’appliquer l’ordre de priorité.

Ordre de priorité (du plus élevé au plus faible)

1. Environnement du processus (ce que le processus Gateway reçoit déjà du shell ou du démon parent).
2. .env dans le répertoire de travail actuel (comportement par défaut de dotenv ; ne remplace rien ; les identifiants des fournisseurs et les contrôles d’exécution protégés sont ignorés).
3. Fichier .env global situé dans ~/.openclaw/.env (également appelé $OPENCLAW_STATE_DIR/.env ; recommandé pour les clés d’API des fournisseurs ; ne remplace rien).
4. Bloc env de la configuration dans ~/.openclaw/openclaw.json (appliqué uniquement si la valeur est absente).
5. Importation facultative depuis le shell de connexion (env.shellEnv.enabled ou OPENCLAW_LOAD_SHELL_ENV=1), appliquée uniquement aux clés attendues qui sont absentes.

Sur les nouvelles installations Ubuntu utilisant le répertoire d’état par défaut, OpenClaw traite également ~/.config/openclaw/gateway.env comme solution de repli de compatibilité après le fichier .env global. Si les deux fichiers existent et contiennent des valeurs différentes, OpenClaw conserve celles de ~/.openclaw/.env et affiche un avertissement.

Si le fichier de configuration est entièrement absent, l’étape 4 est ignorée ; l’importation depuis le shell s’exécute néanmoins si elle est activée.

Identifiants des fournisseurs et fichier .env de l’espace de travail

Ne conservez pas les clés d’API des fournisseurs uniquement dans un fichier .env d’espace de travail. OpenClaw bloque dans les fichiers .env d’espace de travail un vaste ensemble de clés d’identification de fournisseurs et de redirection de points de terminaison, notamment toutes les variables d’environnement d’authentification de fournisseurs connues (par exemple 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, FIRECRAWL_API_KEY), ainsi que toute clé se terminant par _API_HOST, _BASE_URL ou _HOMESERVER, et l’intégralité des espaces de noms OPENCLAW_*, CLAWHUB_*, ANTHROPIC_API_KEY_* et OPENAI_API_KEY_*.

Utilisez plutôt l’une des sources fiables suivantes pour les identifiants des fournisseurs :

• L’environnement du processus Gateway, par exemple un shell, une unité launchd/systemd, un secret de conteneur ou un secret de CI.
• Le fichier dotenv global d’exécution situé dans ~/.openclaw/.env ou $OPENCLAW_STATE_DIR/.env.
• Le bloc env de la configuration dans ~/.openclaw/openclaw.json.
• L’importation facultative depuis le shell de connexion lorsque env.shellEnv.enabled ou OPENCLAW_LOAD_SHELL_ENV=1 est activé.

Si vous stockiez auparavant les clés des fournisseurs uniquement dans un fichier .env d’espace de travail, déplacez-les vers l’une des sources fiables ci-dessus. Le fichier .env de l’espace de travail peut toujours fournir des variables de projet ordinaires qui ne sont ni des identifiants, ni des redirections de points de terminaison, ni des substitutions d’hôtes, ni des contrôles d’exécution OPENCLAW_*.

Consultez Fichiers .env de l’espace de travail pour connaître les raisons de sécurité.

Bloc env de la configuration

Deux méthodes équivalentes permettent de définir des variables d’environnement intégrées à la configuration (aucune ne remplace les valeurs existantes) :

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

Le bloc env de la configuration accepte uniquement des chaînes littérales. Il ne développe pas les valeurs file:... ; par exemple, XAI_API_KEY: "file:secrets/xai-api-key.txt" est transmis aux fournisseurs sous cette forme exacte.

Pour les clés de fournisseurs stockées dans des fichiers, utilisez une SecretRef dans le champ d’identification qui la prend en charge :

{  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" },      },    },  },}

Consultez Gestion des secrets et la portée des champs d’identification SecretRef pour connaître les champs pris en charge.

Importation de l’environnement du shell

env.shellEnv exécute votre shell de connexion et importe uniquement les clés attendues absentes :

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

Variables d’environnement équivalentes :

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000 (valeur par défaut : 15000)

Instantanés du shell d’exécution

Sur les hôtes Gateway autres que Windows, les commandes exec de bash et zsh utilisent par défaut un instantané de démarrage. Définissez OPENCLAW_EXEC_SHELL_SNAPSHOT=0 dans l’environnement du processus Gateway pour désactiver ce mécanisme. Les valeurs false, no et off le désactivent également. Les valeurs exec.env propres à chaque appel ne peuvent ni activer ou désactiver les instantanés, ni rediriger leur cache.

Variables d’environnement injectées à l’exécution

OpenClaw injecte également des marqueurs de contexte dans les processus enfants lancés :

• OPENCLAW_SHELL=exec : défini pour les commandes exécutées au moyen de l’outil exec.
• OPENCLAW_SHELL=acp-client : défini pour openclaw acp client lorsqu’il lance le processus de pont ACP.
• OPENCLAW_SHELL=tui-local : défini pour les commandes shell locales ! de la TUI.
• OPENCLAW_CLI=1 : défini pour les processus enfants lancés par le point d’entrée de la CLI.

Il s’agit de marqueurs d’exécution (et non d’une configuration utilisateur requise). Ils peuvent être utilisés dans la logique du shell ou du profil afin d’appliquer des règles propres au contexte.

Variables d’environnement de l’interface utilisateur

• OPENCLAW_THEME=light : force la palette claire de la TUI lorsque l’arrière-plan de votre terminal est clair.
• OPENCLAW_THEME=dark : force la palette sombre de la TUI.
• COLORFGBG : si votre terminal l’exporte, OpenClaw utilise l’indication de couleur d’arrière-plan pour sélectionner automatiquement la palette de la TUI.

Substitution des variables d’environnement dans la configuration

Vous pouvez référencer directement des variables d’environnement dans les chaînes de la configuration à l’aide de la syntaxe ${VAR_NAME} :

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

Consultez Configuration : substitution des variables d’environnement pour obtenir tous les détails.

Références de secrets et chaînes ${ENV}

OpenClaw prend en charge deux modèles reposant sur l’environnement :

• La substitution de chaînes ${VAR} dans les valeurs de configuration.
• Les objets SecretRef ({ source: "env", provider: "default", id: "VAR" }) pour les champs prenant en charge les références de secrets.

Les deux sont résolus depuis l’environnement du processus au moment de l’activation. Les détails relatifs à SecretRef sont documentés dans Gestion des secrets. Le bloc env de la configuration ne résout lui-même ni les SecretRef ni les valeurs abrégées file:....

Variables d’environnement liées aux chemins

Journalisation

OPENCLAW_HOME

Lorsqu’elle est définie, OPENCLAW_HOME remplace le répertoire personnel du système ($HOME / os.homedir()) utilisé par défaut pour les chemins internes d’OpenClaw. Cela comprend le répertoire d’état par défaut, le chemin de configuration, les répertoires des agents, les identifiants, l’espace de travail de configuration initiale de l’installateur et l’extraction de développement par défaut utilisée par openclaw update --channel dev.

Ordre de priorité : OPENCLAW_HOME > $HOME > USERPROFILE > répertoire personnel de repli du PREFIX de Termux sous Android > os.homedir()

Exemple (LaunchDaemon macOS) :

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

OPENCLAW_HOME peut également être défini sur un chemin contenant un tilde (par exemple ~/svc), qui est développé avant utilisation à l’aide de la même chaîne de repli du répertoire personnel du système d’exploitation.

Les variables de chemin explicites telles que OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH et OPENCLAW_GIT_DIR restent prioritaires. Les tâches liées au compte du système d’exploitation, comme la détection des fichiers de démarrage du shell, la configuration du gestionnaire de paquets et le développement de ~ par l’hôte, peuvent continuer à utiliser le véritable répertoire personnel du système.

Utilisateurs de nvm : échecs TLS de web_fetch

Si Node.js a été installé avec nvm (et non avec le gestionnaire de paquets du système), la fonction fetch() intégrée utilise le magasin d’autorités de certification fourni avec nvm, auquel certaines autorités racines modernes peuvent manquer (ISRG Root X1/X2 pour Let's Encrypt, DigiCert Global Root G2, etc.). Cela entraîne l’échec de web_fetch avec "fetch failed" sur la plupart des sites HTTPS.

Sous Linux, OpenClaw détecte automatiquement nvm et applique la correction dans l’environnement de démarrage réel :

• openclaw gateway install écrit NODE_EXTRA_CA_CERTS dans l’environnement du service systemd
• le point d’entrée de la CLI openclaw se réexécute avec NODE_EXTRA_CA_CERTS défini avant le démarrage de Node

Correction manuelle (pour les anciennes versions ou les lancements directs avec node ...) :

Exportez la variable avant de démarrer OpenClaw :

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

Ne vous contentez pas d’écrire cette variable uniquement dans ~/.openclaw/.env ; Node lit NODE_EXTRA_CA_CERTS au démarrage du processus.

Anciennes variables d’environnement

OpenClaw lit uniquement les variables d’environnement OPENCLAW_*. Les anciens préfixes CLAWDBOT_* et MOLTBOT_* des versions précédentes sont silencieusement ignorés.

Si certaines de ces variables sont encore définies dans le processus Gateway au démarrage, OpenClaw émet un unique avertissement d’obsolescence Node (OPENCLAW_LEGACY_ENV_VARS) indiquant les préfixes détectés et leur nombre total. Renommez chaque valeur en remplaçant l’ancien préfixe par OPENCLAW_ (par exemple CLAWDBOT_GATEWAY_TOKEN par OPENCLAW_GATEWAY_TOKEN) ; les anciens noms n’ont aucun effet.

Voir aussi

• Configuration du Gateway
• FAQ : variables d’environnement et chargement des fichiers .env
• Vue d’ensemble des modèles