Configuration et opérations

Configuration

OpenClaw lit une configuration JSON5 optionnelle depuis ~/.openclaw/openclaw.json. Si le fichier est absent, OpenClaw utilise des valeurs par défaut sûres. Les raisons courantes d'ajouter une configuration :

Connecter des canaux et contrôler qui peut envoyer des messages au bot
Définir des modèles, outils, sandboxing ou automatisation (cron, hooks)
Ajuster les sessions, médias, réseau ou interface utilisateur

Consultez la référence complète pour tous les champs disponibles.

💡 Nouveau avec la configuration ? Commencez avec openclaw onboard pour une installation interactive, ou consultez le guide Exemples de configuration pour des configurations complètes à copier-coller.

Configuration minimale

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

Édition de la configuration

openclaw onboard       # assistant d'installation complet
openclaw configure     # assistant de configuration

Validation stricte

⚠️ OpenClaw n'accepte que les configurations qui correspondent entièrement au schéma. Les clés inconnues, les types malformés ou les valeurs invalides font que la passerelle refuse de démarrer. La seule exception au niveau racine est $schema (chaîne), permettant aux éditeurs d'attacher des métadonnées de schéma JSON.

Lorsque la validation échoue :

La passerelle 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 problèmes exacts
Exécutez openclaw doctor --fix (ou --yes) pour appliquer des corrections

Tâches courantes

Configurer un canal (WhatsApp, Telegram, Discord, etc.)

Choisir et configurer des modèles

Contrôler qui peut envoyer des messages au bot

Configurer le filtrage des mentions en groupe

Configurer les sessions et réinitialisations

Activer le sandboxing

Configurer le heartbeat (vérifications périodiques)

Configurer les tâches cron

Configurer les webhooks (hooks)

Configurer le routage multi-agent

Diviser la configuration en plusieurs fichiers ($include)

Rechargement à chaud de la configuration

La passerelle surveille ~/.openclaw/openclaw.json et applique les changements automatiquement — aucun redémarrage manuel n'est nécessaire pour la plupart des paramètres.

Modes de rechargement

Mode	Comportement
`hybrid` (par défaut)	Applique à chaud les changements sûrs instantanément. Redémarre automatiquement pour les changements critiques.
`hot`	Applique à chaud uniquement les changements sûrs. Enregistre un avertissement lorsqu'un redémarrage est nécessaire — vous le gérez.
`restart`	Redémarre la passerelle à chaque changement de configuration, sûr ou non.
`off`	Désactive la surveillance de fichier. Les changements prennent effet au prochain redémarrage manuel.

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

Ce qui s'applique à chaud vs ce qui nécessite un redémarrage

La plupart des champs s'appliquent à chaud sans interruption. En mode hybrid, les changements nécessitant un redémarrage sont gérés automatiquement.

Catégorie	Champs	Redémarrage nécessaire ?
Canaux	`channels.*`, `web` (WhatsApp) — tous les canaux intégrés et d'extension	Non
Agent & modèles	`agent`, `agents`, `models`, `routing`	Non
Automatisation	`hooks`, `cron`, `agent.heartbeat`	Non
Sessions & messages	`session`, `messages`	Non
Outils & médias	`tools`, `browser`, `skills`, `audio`, `talk`	Non
UI & divers	`ui`, `logging`, `identity`, `bindings`	Non
Serveur de passerelle	`gateway.*` (port, bind, auth, tailscale, TLS, HTTP)	Oui
Infrastructure	`discovery`, `canvasHost`, `plugins`	Oui

ℹ️ gateway.reload et gateway.remote sont des exceptions — les modifier ne déclenche pas de redémarrage.

RPC de configuration (mises à jour programmatiques)

ℹ️ Les RPC d'écriture du plan de contrôle (config.apply, config.patch, update.run) sont limités à 3 requêtes par 60 secondes par deviceId+clientIp. Lorsque limité, le RPC retourne UNAVAILABLE avec retryAfterMs.

config.apply (remplacement complet)

config.patch (mise à jour partielle)

Variables d'environnement

OpenClaw lit les variables d'env depuis le processus parent plus :

.env depuis le répertoire de travail courant (si présent)
~/.openclaw/.env (repli global)

Aucun fichier ne remplace les variables d'env existantes. Vous pouvez également définir des variables d'env en ligne dans la configuration :

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Importation d'env shell (optionnel)

Substitution de variables d'env dans les valeurs de configuration

Références secrètes (env, fichier, exec)

Voir Environnement pour la préséance et les sources complètes.

Référence complète

Pour la référence complète champ par champ, voir Référence de configuration.

Liés : Exemples de configuration · Référence de configuration · Doctor

Runbook de la passerelle Référence de configuration