Variables d’environnement OpenClaw

Vous exportez ANTHROPIC_API_KEY dans votre shell, vous lancez openclaw, tout fonctionne. Puis vous installez la passerelle comme service systemd ou launchd, vous la redémarrez, et la même clé a disparu. Rien n’a été supprimé et rien n’est cassé : un service démarré par le système ne voit jamais le shell dans lequel vous avez tapé cet export. OpenClaw charge les variables d’environnement depuis cinq sources classées, et votre terminal n’en est qu’une.

Les cinq sources, de la précédence la plus haute à la plus basse

• Le niveau un est l’environnement du processus, ce que le processus de la passerelle a déjà hérité de son shell ou de son démon parent. Tout ce qui se trouve en dessous ne fait que combler les manques, et c’est pourquoi un environnement de service vide reste vide tant que vous ne l’alimentez pas autrement.
• Le niveau deux est un fichier .env dans le répertoire de travail courant, le comportement dotenv par défaut. Il n’écrase aucune valeur existante, et OpenClaw en retire les identifiants de fournisseur et les contrôles d’exécution protégés avant même d’appliquer la précédence.
• Le niveau trois est le .env global situé dans ~/.openclaw/.env, aussi accessible via $OPENCLAW_STATE_DIR/.env, et la documentation le recommande pour les clés API des fournisseurs. Lui non plus n’écrase rien, à une exception près : pour un service systemd installé par OpenClaw, il peut remplacer les valeurs de service qu’OpenClaw a enregistrées comme gérées, tandis que les valeurs de service appartenant à l’opérateur gardent la priorité.
• Le niveau quatre est le bloc env de ~/.openclaw/openclaw.json, appliqué seulement si la clé manque, et le niveau cinq est l’import facultatif depuis le shell de connexion, qui ne récupère que les clés attendues manquantes. Si le fichier de configuration n’existe pas du tout, le niveau quatre est ignoré et l’import du shell s’exécute quand même s’il est activé.

Les fichiers .env d’espace de travail sont une source moins fiable : OpenClaw ignore les identifiants de fournisseur et les contrôles d’exécution protégés du .env d’espace de travail avant d’appliquer la précédence.

Pourquoi une clé placée dans le .env du projet ne fait rien

Ce comportement est délibéré et l’ensemble bloqué est large. Il couvre toutes les variables d’authentification de fournisseur connues, dont 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 et FIRECRAWL_API_KEY. Il couvre aussi toute clé se terminant par _API_HOST, _BASE_URL, _ENDPOINT ou _HOMESERVER, ainsi que les espaces de noms OPENCLAW_*, CLAWHUB_*, ANTHROPIC_API_KEY_* et OPENAI_API_KEY_* en entier. Les variables de projet ordinaires se chargent toujours depuis un .env d’espace de travail ; les identifiants, les redirections de point de terminaison, les surcharges d’hôte et les contrôles d’exécution, non. Rien n’échoue bruyamment quand vous y mettez une clé, et c’est précisément ce qui rend le symptôme si difficile à reconnaître. Si vous conservez déjà des clés de fournisseur ou des valeurs de routage de point de terminaison uniquement dans un .env d’espace de travail, déplacez-les : les sources de confiance sont l’environnement du processus de la passerelle, le .env global, le bloc env de la configuration et l’import facultatif depuis le shell.

Trois façons de faire parvenir la clé au service

• Écrivez-la dans le .env global, ~/.openclaw/.env. Ce fichier est l’emplacement documenté pour les clés API des fournisseurs, il compte comme une source de confiance, et il se charge que le service ait hérité ou non de quelque chose de votre shell. C’est aussi le fichier à utiliser pour les variables de chemin, car OpenClaw retire tout l’espace de noms OPENCLAW_* d’un .env d’espace de travail non fiable.
• Mettez-la dans le bloc env de la configuration, sous env.vars, où les valeurs ne s’appliquent que si elles manquent. Ce bloc n’accepte que des chaînes littérales : une valeur comme file:secrets/xai-api-key.txt est transmise au fournisseur telle quelle, et aucun fichier n’est lu.
• Activez l’import depuis le shell de connexion avec env.shellEnv.enabled, ou avec OPENCLAW_LOAD_SHELL_ENV=1. OpenClaw exécute alors votre shell de connexion et n’importe que les clés attendues manquantes, avec un délai de 15000 ms par défaut, et pour Bash il utilise un shell de connexion interactif : gardez donc ces fichiers de démarrage silencieux et bornés.

Un diagnostic induit souvent en erreur ici. La commande openclaw models status indique si l’import du shell est activé, donc une ligne affichant Shell env: off vous dit qu’OpenClaw ne lira pas votre shell de connexion, pas que vos clés ont disparu. Pour les clés stockées dans un fichier, laissez le bloc env de côté et posez plutôt une référence de secret sur le champ d’identifiant, ce dont traite la gestion des secrets dans OpenClaw. Le bloc env est l’outil grossier, et le guide du fichier openclaw.json décrit la structure qui l’entoure.

Ce qu’un démarrage de service conserve, et ce qu’il retire

Sur les installations Ubuntu neuves qui utilisent le répertoire d’état par défaut, OpenClaw lit aussi ~/.config/openclaw/gateway.env, un repli de compatibilité consulté après le .env global ; si les deux fichiers divergent, OpenClaw conserve ~/.openclaw/.env et affiche un avertissement. Le démarrage systemd préserve les valeurs de processus gérées que la configuration référence encore, y compris la notation abrégée de référence de secret avec le signe dollar dans les fichiers $include, ainsi que les valeurs fournies par une ligne EnvironmentFile de l’opérateur. Les valeurs gérées absentes à la fois des fichiers dotenv de confiance et des références de configuration actuelles sont retirées de l’environnement du processus de la passerelle : supprimer une clé du .env global la retire donc vraiment du service en cours. Un dernier point utile : OpenClaw ne lit que les variables OPENCLAW_*, et les anciens préfixes CLAWDBOT_* et MOLTBOT_* sont ignorés en silence, avec un unique avertissement de dépréciation s’il en reste. Si le processus de la passerelle vous est nouveau, la passerelle expliquée explique ce qu’il est, et l’authentification des modèles couvre l’endroit où les identifiants de fournisseur doivent vivre.

Sur Diali

Diali héberge OpenClaw, ce qui règle toute cette échelle avant même le démarrage de votre assistant. Chaque client fait tourner son propre assistant sur son propre runtime, la configuration d’exécution est générée depuis le tableau de bord et remplacée à chaque version, et les clés de fournisseur se saisissent là plutôt que dans un fichier qu’il faut penser à modifier sur un serveur. L’état de travail vit sur un volume persistant, avec des instantanés quotidiens et une restauration en un clic grâce à l’option Sauvegardes (incluse avec Max). OpenClaw hébergé sur Diali détaille ce que comprend le runtime hébergé, et Tarifs Diali présente les formules.

• L’environnement du processus l’emporte, tout le reste ne fait que combler.
• Les clés de fournisseur vont dans ~/.openclaw/.env, jamais dans un .env d’espace de travail.
• Un service n’hérite de rien de votre shell tant que vous n’activez pas l’import.