Variables d’environnement

Chaque substitution de variable d’environnement d’opérateur utilise une grammaire unique en miroir du schéma. La fin d’une variable d’environnement ZEROCLAW_* est le chemin de propriété en notation pointée que zeroclaw config set accepte, où chaque __ (double trait de soulignement) sépare les segments du chemin et chaque _ simple est soit un connecteur snake-case à l’intérieur d’un nom de champ (api_key → api-key dans set_prop), soit un caractère littéral dans une clé d’alias.

ZEROCLAW_<dotted_path_with_double_underscores>=<value>

Exemples

# Injecter un identifiant d'alias de famille typée
ZEROCLAW_providers__models__anthropic__home__api_key=sk-ant-...

# Définir un modèle sur un alias OpenRouter non par défaut (un alias avec un trait de soulignement est acceptable)
ZEROCLAW_providers__models__openrouter__prod_v2__model=anthropic/claude-sonnet-4-6
ZEROCLAW_providers__models__openrouter__prod_v2__api_key=sk-or-...

# Activer/désactiver et configurer un canal
ZEROCLAW_channels__matrix__home__enabled=true
ZEROCLAW_channels__matrix__home__homeserver=https://matrix.example.org

# Remplacer les paramètres d'exécution de la passerelle
ZEROCLAW_gateway__request_timeout_secs=120
ZEROCLAW_gateway__long_running_request_timeout_secs=900

# Pointer la passerelle vers un tableau de bord web généré (chemin absolu ; pas de ~ / $HOME)
ZEROCLAW_gateway__web_dist_dir=/srv/zeroclaw/web/dist

# Injecter des secrets de signature de webhook
ZEROCLAW_channels__whatsapp__home__app_secret=...
ZEROCLAW_channels__linq__home__signing_secret=...
ZEROCLAW_channels__nextcloud_talk__home__webhook_secret=...

# Injecter la connexion au backend mémoire Qdrant
ZEROCLAW_storage__qdrant__home__url=https://qdrant.example.com
ZEROCLAW_storage__qdrant__home__collection=zeroclaw
ZEROCLAW_storage__qdrant__home__api_key=...

Le mappage entre le nom de la variable d’environnement et le chemin TOML est mécanique :

Les segments <alias> ci-dessus (home, prod_v2) sont choisis par l’opérateur, remplacez-les par les noms réellement utilisés dans votre configuration.

Bootstrap (suite en majuscules)

Ces variables d’environnement déterminent où se trouvent le fichier de configuration et les données d’instance, avant qu’une quelconque Config n’existe. Elles conservent leur forme en MAJUSCULES afin que la règle de casse les distingue de la surface miroir du schéma. Elles sont résolues dans l’ordre ZEROCLAW_CONFIG_DIR > ZEROCLAW_DATA_DIR > ZEROCLAW_WORKSPACE (obsolète) :

ZEROCLAW_CONFIG_DIR=/etc/zeroclaw         # emplacement du fichier de configuration (prioritaire)
ZEROCLAW_DATA_DIR=/srv/zeroclaw           # répertoire de données de l'instance (canonique)
ZEROCLAW_WORKSPACE=/srv/zeroclaw          # OBSOLÈTE — alias pour ZEROCLAW_DATA_DIR

L’emplacement du tableau de bord web de la passerelle est configuré via la forme standard de schéma miroir ZEROCLAW_gateway__web_dist_dir, consultez Web dashboard (web_dist_dir) pour la référence complète du paramètre.

Limite de persistance

Les valeurs appliquées via les variables d’environnement ZEROCLAW_* sont chargées dans la Config en mémoire au moment du chargement et ne sont jamais persistées sur le disque. zeroclaw config save rétablit les chemins surchargés par l’environnement à leurs valeurs sur disque ou par défaut avant le chiffrement. Une ligne de journal WARN est émise chaque fois qu’un chemin de type secret (par exemple une clé API) est surchargé par l’environnement, afin que les journaux d’audit rendent l’injection visible.

Grammaire des alias

Les alias (les segments <alias> dans les exemples ci-dessus, home, prod_v2, mymatrixalias, etc.) suivent les règles suivantes :

1. Lettres ASCII minuscules, chiffres et traits de soulignement simples.
2. Doit commencer ET se terminer par une lettre ou un chiffre (pas de trait de soulignement en début ou en fin).
3. Aucune sous-chaîne __ (réservée comme séparateur de chemin dans la grammaire des variables d’environnement).
4. Pas de trait d’union (illégal dans les identifiants de variables d’environnement).
5. Aucune majuscule (entrerait en conflit avec les noms de bootstrap).
6. 1–63 caractères.

prod_v2 est un jeton d’alias unique ; home__api_key est analysé comme deux segments (alias home, champ api_key). Les configurations avec des alias non conformes produisent une erreur au moment du chargement nommant l’alias fautif.

Erreurs

Les noms ZEROCLAW_<lowercase_*> non résolus (fautes de frappe, chemins ne correspondant à aucune propriété du schéma) interrompent le démarrage avec une erreur grave indiquant la variable d’environnement fautive. Les noms de variables d’environnement sans le préfixe ZEROCLAW_ ne sont pas lus par cette couche de surcharge.

Visibilité

L’état de remplacement est affiché partout où la configuration est rendue, avec un indicateur 💉 marquant les champs remplacés par l’environnement :

1. zeroclaw config list : la légende 💉 env-overridden 🔒 secret est affichée une seule fois en haut ; les lignes des champs remplacés par des variables d’environnement sont préfixées par 💉.
2. Éditeur de configuration Web : chaque ListEntry porte un booléen is_env_overridden. Les lignes de champs surchargés par l’environnement affichent le badge 💉 et un avertissement persistant « Les modifications effectuées ici n’auront aucun effet, surchargées par ZEROCLAW_… » afin que les opérateurs voient la surcharge sans avoir à tenter une modification.
3. Intégration CLI/TUI : prompt_field ignore les champs remplacés par des variables d’environnement et affiche une note 💉 de trois lignes (le nom de la variable d’environnement, le chemin TOML et un avis d’omission) qui s’efface lors de la navigation suivant/précédent. Les opérateurs ne sont pas invités à saisir une valeur qu’ils ont déjà injectée.
4. Dérive de rechargement : GET /api/config/drift, GET /api/config/list et le bandeau de rechargement excluent les chemins écrasés par les variables d’environnement du calcul de la dérive. Étant donné que ces valeurs résident uniquement en mémoire et ne sont jamais écrites sur le disque, elles seraient autrement détectées comme une dérive permanente qu’aucune modification de fichier de configuration ne pourrait réconcilier. En les excluant, la sortie de dérive se limite aux différences qu’un opérateur peut effectivement résoudre en modifiant la configuration stockée.
5. Programmatique : Config::prop_is_env_overridden(path) -> bool est une recherche O(1) dans un HashSet. Point d’ancrage ici pour toute couche de rendu personnalisée.

Dérivation des noms de variables d’environnement à partir de votre configuration

Trois étapes mécaniques pour dériver un nom de variable d’environnement à partir de n’importe quelle clé TOML :

1. Préfixez le chemin avec ZEROCLAW_. Le chemin de configuration en notation pointée est la source de vérité, trouvez le champ via zeroclaw config schema.
2. Remplacez . par __ (double trait de soulignement, le séparateur de chemin).
3. Le nom du champ reste tel quel (snake_case). Les alias restent tels quels. Rien d’autre n’est transformé.

Par exemple, [providers.models.anthropic.home] api_key = "sk-..." se trouve au chemin pointé providers.models.anthropic.home.api_key. Appliquez les trois règles et la variable d’environnement devient ZEROCLAW_providers__models__anthropic__home__api_key=sk-.... Le même mappage mécanique s’applique à n’importe quel champ dans n’importe quelle section.

Variables d’environnement par défaut de l’écosystème de pontage

La grammaire schema-mirror est la manière canonique d’injecter des valeurs, mais ANTHROPIC_API_KEY / OPENROUTER_API_KEY / QDRANT_URL / etc. restent des noms courants dans les fichiers .env et les configurations CI. Des expansions shell sur une seule ligne font pointer un nom schema-mirror vers la valeur par défaut de l’écosystème :

# POSIX (bash, zsh, sh) — à insérer dans ~/.bashrc / ~/.zshrc / .env / Dockerfile
export ZEROCLAW_providers__models__anthropic__home__api_key=$ANTHROPIC_API_KEY
export ZEROCLAW_providers__models__openai__home__api_key=$OPENAI_API_KEY
export ZEROCLAW_providers__models__openrouter__home__api_key="$OPENROUTER_API_KEY"
export ZEROCLAW_providers__models__nearai__tee__api_key="$NEARAI_API_KEY"
export ZEROCLAW_providers__models__zerorouter__gateway__api_key="$ZEROROUTER_API_KEY"
export ZEROCLAW_storage__qdrant__home__url="$QDRANT_URL"
export ZEROCLAW_storage__qdrant__home__api_key="$QDRANT_API_KEY"
export ZEROCLAW_gateway__request_timeout_secs="$GATEWAY_TIMEOUT_SECS"

# PowerShell — drop into $PROFILE
$env:ZEROCLAW_providers__models__anthropic__home__api_key = $env:ANTHROPIC_API_KEY
$env:ZEROCLAW_providers__models__openai__home__api_key = $env:OPENAI_API_KEY
$env:ZEROCLAW_providers__models__nearai__tee__api_key = $env:NEARAI_API_KEY
$env:ZEROCLAW_storage__qdrant__home__url = $env:QDRANT_URL

Remplacez home par le nom de votre alias pour correspondre à votre configuration. Pour plusieurs alias sur la même famille, répétez la ligne avec chaque alias.

Ces lignes constituent des passerelles shell vers la configuration typée, et non une règle générale selon laquelle les constructeurs lisent les variables d’environnement natives du fournisseur. Le code d’exécution doit recevoir la valeur résolue depuis Config, sauf si la famille d’intégration documente explicitement une passerelle d’environnement native.

Champs OAuth et chemin de la CLI

Quelques champs sont définis comme des champs de schéma, accessibles via le mapping standard :

1. Flux de rafraîchissement OAuth MiniMax : [providers.models.minimax.<alias>] oauth_refresh_token = "..." (avec oauth_client_id optionnel) ; la sélection de la région se fait via l’énumération typée endpoint (cn / intl). Le runtime échange le jeton de rafraîchissement contre un jeton d’accès de courte durée au moment de la construction du fournisseur.
2. Flux de rafraîchissement OAuth Qwen : [providers.models.qwen.<alias>] oauth_refresh_token = "..." (avec oauth_client_id et oauth_resource_url optionnels).
3. Gemini OAuth : [providers.models.gemini.<alias>] oauth_client_id et oauth_client_secret ; le paramètre optionnel oauth_project fixe un ID de projet GCP Code Assist.
4. Paramètres de processus KiloCLI / Gemini CLI / Grok Build CLI : [providers.models.kilocli.<alias>] binary_path, [providers.models.gemini_cli.<alias>] binary_path et les champs de [providers.models.grok_cli.<alias>] : binary_path, working_directory absolu obligatoire, extra_args facultatif et max_acp_stdout_bytes. Les alias Grok Build peuvent également répertorier des noms de variables d’environnement dans env_passthrough (identifiants des outils et passerelle d’authentification XAI_API_KEY facultative) ; les valeurs sont résolues uniquement au lancement du processus enfant et ne sont pas stockées dans la configuration. Par défaut, l’authentification utilise le cache de connexion de la CLI. Le nom exact XAI_API_KEY est la passerelle native documentée pour l’authentification par clé API lorsqu’il est explicitement répertorié ; les autres noms XAI_* et tous les noms GROK_* sont rejetés.
5. Clés de transcription / TTS : [transcription].api_key, [providers.tts.openai.<alias>].api_key, [providers.tts.elevenlabs.<alias>].api_key, [providers.tts.google.<alias>].api_key.
6. Notion / WhatsApp : [notion].api_key, [channels.whatsapp.<alias>].ws_url (remplacement WebSocket pour test/proxy).