OpenClaw configuration : guide complet

Introduction

La recherche « openclaw configuration » mène aujourd’hui à ~/.openclaw/openclaw.json, un fichier JSON5 lu et validé par le Gateway. Elle est utile pour choisir les modèles, organiser les agents, connecter les canaux, limiter les skills et durcir l’exécution. Ce guide remplace les anciens exemples openclaw.yaml, Pydantic et providers Python, qui ne correspondent pas au produit. Si l’onboarding et les valeurs par défaut couvrent votre besoin, évitez une configuration trop large : une approche plus simple réduit les erreurs. Vous apprendrez à modifier un champ, vérifier le schéma effectif, tester le rechargement et préserver une frontière de sécurité cohérente.

Résumé rapide

1. Le fichier actif par défaut est ~/.openclaw/openclaw.json.
2. Préférez openclaw configure ou openclaw config set aux gros copier-coller.
3. Les modèles utilisent des références provider/model.
4. Skills, tools et sandbox sont des contrôles distincts.
5. Validez avec openclaw doctor et relisez l’état effectif.

Le modèle de configuration du Gateway

OpenClaw accepte JSON5, donc les commentaires et virgules finales sont possibles. Le fichier est optionnel : des valeurs sûres permettent de démarrer sans tout déclarer. Les réglages d’infrastructure vivent à la racine, tandis que le comportement commun des agents se place sous agents.defaults et les exceptions sous agents.entries.

La Control UI génère ses formulaires depuis le schéma vivant. La CLI expose aussi openclaw config schema, openclaw config get, set et unset. Ces surfaces sont préférables à un exemple exhaustif, car le schéma évolue avec les plugins et les canaux installés. Une clé inconnue peut empêcher le Gateway de démarrer ; openclaw doctor indique alors le chemin fautif.

La procédure d’installation OpenClaw doit être terminée avant ce guide. Conservez l’écoute loopback et le pairing par défaut tant que vous n’avez pas défini votre modèle de confiance.

Configurer modèles, agents et sécurité

Lire avant d’écrire

openclaw config get agents.defaults.workspace
openclaw config schema

La première commande révèle une valeur ciblée ; la seconde affiche le schéma canonique. Pour un parcours guidé, utilisez openclaw configure.

Configuration minimale

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
    },
  },
  gateway: {
    mode: "local",
    bind: "loopback",
  },
}

Les noms de modèles ne sont pas une recommandation universelle : choisissez une référence réellement accessible dans votre installation et contrôlez-la via la CLI ou la Control UI.

Modifier un champ

openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config get agents.defaults.heartbeat.every

Utilisez openclaw config unset <chemin> pour retirer une valeur. Après une écriture, relisez exactement le chemin ; ne vous contentez pas du code retour.

Déclarer plusieurs agents

{
  agents: {
    entries: {
      main: { default: true, workspace: "~/.openclaw/workspace" },
      support: { workspace: "~/.openclaw/workspace-support", skills: ["support-runbook"] },
    },
  },
}

Les workspaces et états doivent rester distincts. Créez de préférence l’agent avec openclaw agents add, puis utilisez la configuration pour ajuster les paramètres. Le guide des agents OpenClaw explique les bindings.

Restreindre les skills

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    entries: {
      support: { skills: ["support-runbook"] },
      locked: { skills: [] },
    },
  },
}

Une liste par agent remplace la valeur par défaut ; elle ne fusionne pas automatiquement. Cette visibilité n’est pas une autorisation shell. Configurez aussi tools, le sandbox et les credentials.

Protéger les secrets

OpenClaw lit l’environnement du processus, un .env du répertoire courant et ~/.openclaw/.env comme fallback. La substitution ${NOM_VARIABLE} fonctionne dans les chaînes configurées. Préférez les SecretRef sur les champs compatibles. Ne placez jamais une clé réelle dans openclaw.json, un skill ou la mémoire.

Sessions et canaux

Les politiques de messages directs, groupes et mentions sont propres à chaque canal. Commencez avec le pairing, une allowlist et les mentions obligatoires en groupe. Pour plusieurs utilisateurs, choisissez une portée de session qui évite de mélanger les conversations. Testez avec deux expéditeurs distincts avant la production.

Sandbox et tools

Le workspace n’est pas un sandbox. Activez l’isolation pour les agents exposés, limitez les tools de fichiers, runtime et automation, puis testez une action refusée. L’autorisation d’un plugin ne doit pas élargir implicitement toutes les policies.

Validation et rechargement

Le Gateway surveille le fichier et applique de nombreux changements à chaud. Une configuration invalide est rejetée et l’état accepté reste actif. Après modification :

openclaw doctor
openclaw gateway status
openclaw security audit --deep

Redémarrez le Gateway lorsque le changement de plugin ou la documentation du champ l’exige.

Checklist finale

• chemin actif confirmé ;
• schéma consulté ;
• valeur relue après écriture ;
• secrets absents du fichier ;
• sessions et canaux testés ;
• tools et sandbox vérifiés ;
• rollback disponible.

Repère opérationnel supplémentaire

Le Gateway doit rester le point de référence opérationnel. Il porte les sessions, les connexions aux canaux et le routage ; un redémarrage ou une panne affecte donc toutes les surfaces qui en dépendent. En production, supervisez le processus, conservez une procédure de redémarrage, puis vérifiez son état avec openclaw gateway status. Les automations exigent elles aussi un Gateway actif au moment prévu. Cette topologie est plus simple à exploiter qu'une collection de scripts dispersés, mais elle impose de traiter le Gateway comme un service durable et non comme une commande ponctuelle.

Repère opérationnel supplémentaire

Le workspace facilite l'organisation, mais ce n'est pas une frontière de sécurité. Il fournit le répertoire de travail, les instructions, les skills et les fichiers de mémoire ; sans sandbox, un outil autorisé peut encore atteindre d'autres chemins de l'hôte. Pour un assistant exposé à plusieurs personnes, limitez les outils, activez l'isolation adaptée et séparez les Gateway lorsque les utilisateurs ne partagent pas le même niveau de confiance. Une allowlist de skills réduit ce que le modèle voit, mais ne remplace jamais une politique d'exécution shell.

Repère opérationnel supplémentaire

La validation doit porter sur un effet observable. Après une modification, lancez une demande courte, vérifiez le fichier ou le message produit, puis consultez les logs et l'historique de session en cas d'écart. Évitez de conclure qu'une opération a réussi uniquement parce que la CLI n'a pas retourné d'erreur. Pour les actions avec effets de bord, ajoutez une étape de lecture après écriture, un identifiant d'exécution et une règle d'idempotence. Cela réduit les doublons lors d'un retry ou d'une reprise après interruption.

Repère opérationnel supplémentaire

Les coûts et la latence dépendent davantage du modèle, du volume de contexte et du nombre d'appels d'outils que du nombre de fichiers de configuration. Commencez avec une mission étroite, un petit jeu de skills et une session clairement délimitée. Mesurez ensuite le temps de réponse, les appels échoués et la qualité de la sortie avant d'ajouter des agents ou des automatisations. Un workflow déterministe reste préférable lorsque la tâche se résume à transformer une entrée connue selon des règles stables.

Exemple concret

Vous devez ajouter un agent support sans lui donner les capacités du profil principal. Créez d’abord l’agent avec un workspace distinct, puis ajoutez une entrée support qui expose uniquement le skill support-runbook. Laissez le Gateway sur loopback et conservez le pairing du canal. N’ajoutez pas de shell au profil support.

Relisez la configuration avec openclaw config get agents.entries.support, vérifiez l’éligibilité via openclaw skills check --agent support, puis redémarrez si nécessaire. Envoyez un ticket autorisé : l’agent doit répondre depuis son workspace. Envoyez ensuite une demande de lecture hors périmètre : elle doit échouer. Exécutez openclaw security audit --deep et consignez les résultats. Si le Gateway ne démarre plus, lancez openclaw doctor, corrigez le chemin signalé et revenez à la copie connue comme valide. Cette recette couvre lecture, écriture, effet réel, refus et rollback.

Bonnes pratiques

Modifiez un champ à la fois et relisez sa valeur effective. Préférez le wizard, la Control UI ou openclaw config set pour éviter de remplacer accidentellement des tableaux de bindings ou d’allowlists. Gardez une sauvegarde récente et documentez les valeurs qui doivent survivre à une migration.

Ne confondez jamais skills, tools, plugins et sandbox. Un skill visible peut demander un tool refusé ; c’est une situation saine. Les secrets doivent venir de l’environnement ou d’un SecretRef compatible, pas du JSON5. Votre checklist de production doit inclure openclaw doctor, le statut du Gateway, un test de canal, un cas de refus, les logs et openclaw security audit --deep.

Questions fréquentes

Où se trouve la configuration OpenClaw ?

Par défaut, OpenClaw lit ~/.openclaw/openclaw.json. Vous pouvez remplacer ce chemin avec la variable prévue à cet effet. Confirmez toujours le fichier actif avant d’éditer, surtout si vous utilisez plusieurs profils, conteneurs ou utilisateurs système.

OpenClaw utilise-t-il un fichier YAML ?

Non pour sa configuration principale actuelle. Le Gateway lit un fichier JSON5 nommé openclaw.json. Les anciens exemples openclaw.yaml, les validations Pydantic et les blocs llm: de style Python ne correspondent pas au produit documenté aujourd’hui.

Comment valider une configuration OpenClaw ?

Consultez le schéma avec openclaw config schema, relisez les valeurs avec openclaw config get, puis lancez openclaw doctor. Vérifiez aussi le statut du Gateway et exécutez un tour réel. Après un changement de sécurité, complétez avec openclaw security audit --deep.

Comment stocker les clés API dans OpenClaw ?

Utilisez l’onboarding, les profils d’authentification, les variables d’environnement ou les SecretRef sur les champs compatibles. Ne placez pas de secret en clair dans openclaw.json, SKILL.md, MEMORY.md ou un dépôt. Faites tourner immédiatement une clé suspectée d’avoir fuité.

Articles liés

Une bonne configuration OpenClaw reste courte, lisible et prouvée par l’état du Gateway. Commencez par les valeurs par défaut, puis ajoutez modèles, agents, canaux et restrictions au rythme de tests observables.

• Installer OpenClaw
• Créer un agent OpenClaw
• Comprendre les agents OpenClaw
• Guide des skills OpenClaw
• Sécuriser OpenClaw