Tutoriel 08 — Analyse approfondie du système de configuration : stocker les clés API en toute sécurité

Objectif : comprendre l'architecture de configuration à trois niveaux d'OpenClaw, maîtriser les trois modes du Secret Provider pour des clés à la fois sécurisées et flexibles.

Ce que vous apprendrez

La structure des fichiers de configuration d'OpenClaw et l'ordre de lecture
Les trois façons d'écrire une clé API : chaîne / référence à une variable d'environnement / commande externe
La conception sécurisée du système Secret Provider
Comment s'intégrer avec 1Password, Vault et autres gestionnaires de secrets

I. Où se trouve le fichier de configuration

La configuration d'OpenClaw est stockée dans ~/.openclaw/openclaw.json (ou .yaml) et est lue automatiquement au démarrage de la passerelle.

# Afficher la configuration actuelle
openclaw config show
 
# Définir un champ via la ligne de commande
openclaw config set gateway.mode local

Structure globale :

{
  "gateway": { ... },        // Mode de la passerelle
  "agents": { ... },         // Comportement par défaut des agents IA
  "models": { ... },         // Liste des fournisseurs de modèles
  "channels": { ... },       // Canaux de messagerie (Telegram, Discord, etc.)
  "env": { ... },            // Variables d'environnement injectées à l'exécution
  "secrets": { ... },        // Configuration du Secret Provider (avancé)
  "hooks": { ... }           // Hooks de cycle de vie
}

II. Les trois façons d'écrire une clé API

Méthode A : Chaîne littérale (pour les tests rapides)

La plus simple, mais déconseillée en production ou en environnement partagé, car la clé est stockée en clair dans le fichier de configuration.

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "sk-proj-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Méthode B : Référence à une variable d'environnement (recommandée au quotidien)

Utilisez le paramètre substitution ${NOM_VARIABLE} pour référencer des variables d'environnement système — aucune clé réelle n'est stockée dans le fichier de configuration.

Étape 1 : exportez dans le shell ou ajoutez dans ~/.profile :

export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxx"
export MINIMAX_API_KEY="eyJhbGci..."

Étape 2 : référencez avec le paramètre substitution dans la configuration :

{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      },
      "minimax": {
        "apiKey": "${MINIMAX_API_KEY}"
      }
    }
  }
}

Syntaxe alternative plus explicite :

{
  "apiKey": { "source": "env", "provider": "default", "id": "OPENAI_API_KEY" }
}

Fonctionnement : au démarrage, OpenClaw détecte le motif ${NOM_VARIABLE}, lit la valeur correspondante depuis process.env, résout uniquement en mémoire sans écriture sur le disque.

Méthode C : Secret Provider (pour équipes / déploiements serveur)

La méthode la plus sécurisée et la plus flexible, adaptée pour :

Les serveurs où vous ne souhaitez pas configurer de variables d'environnement
Les équipes utilisant une passerelle partagée avec gestion centralisée des secrets
L'intégration avec 1Password CLI, HashiCorp Vault, etc.

Le Secret Provider dispose de trois sources :

source: "file" — Lecture depuis un fichier

Adapté pour stocker les secrets dans un fichier avec des permissions strictes (OpenClaw vérifie les permissions — les fichiers accessibles en écriture par le groupe sont refusés) :

{
  "secrets": {
    "providers": {
      "my-keys": {
        "source": "file",
        "path": "~/.openclaw/secrets.json",
        "mode": "json"
      }
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": { "source": "file", "provider": "my-keys", "id": "/openai/apiKey" }
      }
    }
  }
}

Le fichier ~/.openclaw/secrets.json correspondant :

{
  "openai": { "apiKey": "sk-proj-xxxxxxxx" },
  "minimax": { "apiKey": "eyJhbGci..." }
}

Exigence de sécurité : le fichier doit appartenir à l'utilisateur courant avec des permissions ne dépassant pas 600 (chmod 600 ~/.openclaw/secrets.json).

source: "exec" — Appel d'un programme externe

Pour s'intégrer avec 1Password CLI, Vault, le trousseau système :

{
  "secrets": {
    "providers": {
      "op-vault": {
        "source": "exec",
        "command": "/usr/local/bin/op-resolver",
        "timeoutMs": 5000
      }
    }
  },
  "models": {
    "providers": {
      "openai": {
        "apiKey": { "source": "exec", "provider": "op-vault", "id": "openai/api-key" }
      }
    }
  }
}

Le programme externe reçoit la requête via stdin et renvoie le résultat via stdout, selon le protocole :

# stdin reçoit (JSON) :
{ "protocolVersion": 1, "provider": "op-vault", "ids": ["openai/api-key"] }

# stdout renvoie (JSON) :
{ "protocolVersion": 1, "values": { "openai/api-key": "sk-proj-xxx" } }

III. Exemple d'intégration 1Password

Si vous stockez vos clés API dans 1Password, voici un script resolver simple :

#!/usr/bin/env bash
# ~/.openclaw/op-resolver.sh
# Définir les permissions : chmod 700 ~/.openclaw/op-resolver.sh
 
set -euo pipefail
INPUT=$(cat)
ID=$(echo "$INPUT" | jq -r '.ids[0]')
 
# Lecture depuis 1Password
VALUE=$(op read "op://Private/$ID" 2>/dev/null)
 
echo "{\"protocolVersion\":1,\"values\":{\"$ID\":\"$VALUE\"}}"

Puis configurez :

{
  "secrets": {
    "providers": {
      "1password": {
        "source": "exec",
        "command": "/Users/votre-nom/.openclaw/op-resolver.sh",
        "timeoutMs": 8000
      }
    }
  }
}

Attention : command doit être un chemin absolu, et le fichier ne doit pas être modifiable par d'autres utilisateurs.

IV. Le bloc `env` dans la configuration

En plus du Secret Provider, le bloc env offre un moyen simple de déclarer des variables d'environnement d'exécution directement dans le fichier de configuration :

{
  "env": {
    "vars": {
      "HTTP_PROXY": "http://127.0.0.1:7890",
      "OPENAI_BASE_URL": "https://api.openai.com"
    }
  }
}

Règles :

Seules les valeurs de env.vars dans le fichier de configuration sont injectées — les variables système existantes portant le même nom ne sont pas écrasées
Les noms de variables sensibles (PATH, LD_PRELOAD, etc.) sont automatiquement bloqués et ne peuvent pas être injectés de cette façon

V. Masquage automatique des champs sensibles

OpenClaw utilise le registre Zod sensitive pour marquer tous les champs secrets. Quand des informations de configuration sont exposées au tableau de bord ou dans les logs, ces champs sont automatiquement remplacés par [REDACTED] :

# Dans les logs ou les réponses API :
{ "apiKey": "[REDACTED]" }

# La valeur réelle en mémoire n'apparaît jamais dans les logs

VI. Exemple de configuration complète (multi-modèles + secrets sécurisés)

{
  "gateway": { "mode": "local" },
 
  "secrets": {
    "providers": {
      "env-keys": { "source": "env" }
    },
    "defaults": { "env": "env-keys" }
  },
 
  "agents": {
    "defaults": {
      "model": { "primary": "openai/gpt-4o" }
    }
  },
 
  "models": {
    "mode": "merge",
    "providers": {
      "openai": {
        "apiKey": "${OPENAI_API_KEY}",
        "models": [
          { "id": "gpt-4o", "name": "GPT-4o" }
        ]
      },
      "minimax": {
        "baseUrl": "https://api.minimax.io/anthropic",
        "apiKey": "${MINIMAX_API_KEY}",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "MiniMax-M2.1",
            "name": "MiniMax M2.1",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
 
  "channels": {
    "telegram": {
      "token": "${TELEGRAM_BOT_TOKEN}"
    }
  }
}

Variables d'environnement correspondantes (à ajouter dans ~/.profile ou .env) :

export OPENAI_API_KEY="sk-proj-..."
export MINIMAX_API_KEY="eyJhbGci..."
export TELEGRAM_BOT_TOKEN="8543054163:AAH..."

VII. Questions fréquentes

Pourquoi mes modifications de configuration ne sont-elles pas prises en compte ?

La passerelle doit être redémarrée pour relire la configuration (exception : les Skills SKILL.md) :

openclaw gateway restart

Comment vérifier que la clé est correctement lue ?

openclaw models list
# Si les modèles du fournisseur apparaissent, l'apiKey a été résolu correctement

Si la liste est vide, lancez openclaw config show pour voir si la configuration est correctement analysée et vérifiez que les variables d'environnement ${NOM_VARIABLE} correspondantes sont bien exportées.

Comment résoudre une erreur de permission sur source "file" ?

chmod 600 ~/.openclaw/secrets.json
# Vérifiez que le fichier appartient à l'utilisateur courant
ls -la ~/.openclaw/secrets.json

OpenClaw exige que les fichiers de secrets aient des permissions ne dépassant pas 600 et appartiennent à l'utilisateur courant (un fichier appartenant à root mais lisible par l'utilisateur d'exécution est refusé).

Que faire si le script de la source "exec" expire ?

Augmentez timeoutMs (maximum 120 000 ms). La cause la plus fréquente est que la commande externe nécessite une authentification — par exemple, 1Password CLI doit d'abord exécuter op signin. Il est recommandé d'ajouter une logique de reconnexion automatique dans le script, ou de mettre en cache le token de session dans un fichier.

Quelle différence entre le fichier `.env` et le bloc `env` de `openclaw.json` ?

Le fichier .env définit des variables d'environnement système, actives pour tous les processus. Le bloc env.vars de openclaw.json n'agit que dans le processus passerelle d'OpenClaw, sans affecter les autres programmes. Les deux prennent en charge ${NOM_VARIABLE} dans les champs comme apiKey. Il est recommandé d'utiliser .env pour les données sensibles et env.vars pour les configurations non sensibles propres à OpenClaw (comme les adresses proxy).

Peut-on avoir plusieurs fichiers de configuration en même temps ?

OpenClaw supporte la fusion de configurations ("mode": "merge"), mais le chemin du fichier principal est fixé à ~/.openclaw/openclaw.json. Vous pouvez utiliser le champ import dans openclaw.json pour inclure d'autres fragments de configuration et organiser la configuration de façon modulaire.

Prochaines étapes

Tutoriel 05 — Configurer plusieurs fournisseurs de modèles avec basculement automatique
Tutoriel 03 — Ajouter des Skills personnalisés à l'IA