Passer au contenu principal

​
Configuration 🔧

OpenClaw lit une configuration optionnelle depuis ~/.openclaw/openclaw.json. Si le fichier est absent, OpenClaw utilise des valeurs par défaut sûres. Raisons courantes d’ajouter une configuration :
  • Restreindre qui peut envoyer des messages au bot
  • Définir les modèles, outils, sandboxing ou automatisations (cron, hooks)
  • Ajuster les sessions, médias, réseau ou UI
Voir la référence complète pour tous les champs disponibles.
Nouveau dans la configuration ? Commencez avec openclaw onboard pour une configuration interactive, ou consultez le guide Configuration Examples pour des exemples complets prêts à copier-coller.

​
Configuration minimale

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

​
Modification de la configuration

openclaw onboard       # assistant de configuration complet
openclaw configure     # assistant de configuration

​
Validation stricte

OpenClaw n’accepte que les configurations correspondant entièrement au schéma. Les clés inconnues, types invalides ou valeurs incorrectes entraînent un refus de démarrage de la Gateway. La seule exception à la racine est $schema (string), pour permettre aux éditeurs d’attacher des métadonnées JSON Schema.
En cas d’échec de validation :
  • La Gateway ne démarre pas
  • Seules les commandes de diagnostic fonctionnent (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • Exécutez openclaw doctor pour voir les erreurs exactes
  • Exécutez openclaw doctor --fix (ou --yes) pour appliquer les réparations

​
Tâches courantes

Chaque canal possède sa section sous channels.<provider>. Consultez la page dédiée du canal pour les étapes détaillées :Tous les canaux partagent le même modèle de politique DM :
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // uniquement pour allowlist/open
    },
  },
}
Définissez le modèle principal et des replis optionnels :
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models définit le catalogue de modèles et sert de liste d’autorisation pour /model.
  • Les références de modèles utilisent le format provider/model (ex. anthropic/claude-opus-4-6).
  • Voir Models CLI pour changer de modèle en chat et Model Failover pour la rotation d’authentification et les replis.
  • Pour les fournisseurs personnalisés/self-hosted, voir Custom providers.
L’accès DM est contrôlé par canal via dmPolicy :
  • "pairing" (par défaut) : les expéditeurs inconnus reçoivent un code d’appairage unique
  • "allowlist" : seuls les expéditeurs dans allowFrom
  • "open" : autorise tous les DMs entrants (nécessite allowFrom: ["*"])
  • "disabled" : ignore tous les DMs
Pour les groupes, utilisez groupPolicy + groupAllowFrom.Voir la référence complète pour les détails par canal.
Les messages de groupe nécessitent par défaut une mention. Configurez les motifs par agent :
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • Mentions natives : @-mentions propres à la plateforme
  • Motifs texte : regex définies dans mentionPatterns
  • Voir la référence complète.
Les sessions contrôlent la continuité des conversations :
{
  session: {
    dmScope: "per-channel-peer",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
Exécutez les sessions agent dans des conteneurs Docker isolés :
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "agent",
      },
    },
  },
}
Construisez l’image une fois : scripts/sandbox-setup.shVoir Sandboxing.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every : durée (30m, 2h). 0m désactive.
  • target : last | whatsapp | telegram | discord | none
  • Voir Heartbeat.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}
Voir Cron jobs.
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
Voir la référence complète.
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}
Voir Multi-Agent.
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • Fichier unique : remplace l’objet
  • Tableau de fichiers : fusion profonde dans l’ordre
  • Clés sœurs : fusionnées après les inclusions
  • Inclusions imbriquées : jusqu’à 10 niveaux
  • Chemins relatifs : résolus depuis le fichier incluant
  • Erreurs : messages clairs pour fichiers manquants, erreurs de parsing ou boucles

​
Rechargement à chaud de la configuration

La Gateway surveille ~/.openclaw/openclaw.json et applique automatiquement les changements.

​
Modes de rechargement

ModeComportement
hybrid (défaut)Applique à chaud les changements sûrs. Redémarre automatiquement si nécessaire.
hotApplique uniquement les changements sûrs. Avertit si redémarrage requis.
restartRedémarre la Gateway pour tout changement.
offDésactive la surveillance.
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
Variables d’environnement

OpenClaw lit les variables d’environnement du processus parent ainsi que :
  • .env dans le répertoire courant
  • ~/.openclaw/.env
Aucun fichier .env ne remplace une variable déjà définie. 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Si activé et que des clés attendues sont absentes, OpenClaw exécute votre shell de connexion et importe uniquement les clés manquantes :
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Équivalent variable d’environnement : OPENCLAW_LOAD_SHELL_ENV=1
Référencez des variables avec ${VAR_NAME} :
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
Règles :
  • Noms en majuscules uniquement : [A-Z_][A-Z0-9_]*
  • Variable manquante → erreur au chargement
  • Échapper avec $${VAR}
  • Fonctionne dans les fichiers $include
  • Substitution inline : "${BASE}/v1" → "https://api.example.com/v1"
Voir Environment.

​
Référence complète

Pour la référence détaillée champ par champ, voir Configuration Reference.
Related: Configuration Examples · Configuration Reference · Doctor