Configuration

Aides de configuration pour les modifications non interactives dans openclaw.json : obtenir/définir/corriger/supprimer/fichier/schéma/valider des valeurs par chemin et afficher le fichier de configuration actif. Exécutez sans sous-commande pour ouvrir l’assistant de configuration (identique à openclaw configure).

# Options racine

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> Filtre de section de configuration guidée répétable lorsque vous exécutez openclaw config sans sous-commande.

Sections guidées prises en charge : workspace, model, web, gateway, daemon, channels, plugins, skills, health.

# Exemples

openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

# config schema

Affiche le schéma JSON généré pour openclaw.json sur stdout au format JSON.

openclaw config schema

Redirigez-le vers un fichier lorsque vous voulez l’inspecter ou le valider avec d’autres outils :

openclaw config schema > openclaw.schema.json

# Chemins

Les chemins utilisent la notation par point ou par crochets :

openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id

Utilisez l’index de la liste d’agents pour cibler un agent précis :

openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"

# Valeurs

Les valeurs sont analysées comme du JSON5 lorsque c’est possible ; sinon elles sont traitées comme des chaînes. Utilisez --strict-json pour exiger l’analyse JSON5. --json reste pris en charge comme alias hérité.

openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json

config get <path> --json affiche la valeur brute en JSON au lieu d’un texte formaté pour le terminal.

Utilisez --merge lorsque vous ajoutez des entrées à ces mappes :

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge

Utilisez --replace uniquement lorsque vous voulez intentionnellement que la valeur fournie devienne la valeur cible complète.

# Modes de config set

openclaw config set prend en charge quatre styles d’affectation :

openclaw config set <path> <value>

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN

openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-timeout-ms 5000

openclaw config set --batch-json '[
  {
    "path": "secrets.providers.default",
    "provider": { "source": "env" }
  },
  {
    "path": "channels.discord.token",
    "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
  }
]'

openclaw config set --batch-file ./config-set.batch.json --dry-run

L’analyse par lots utilise toujours la charge utile de lot (--batch-json/--batch-file) comme source de vérité. --strict-json / --json ne modifient pas le comportement d’analyse par lots.

# config patch

Utilisez config patch lorsque vous voulez coller ou transmettre par pipe un correctif ayant la forme d’une configuration, plutôt que d’exécuter de nombreuses commandes config set basées sur des chemins. L’entrée est un objet JSON5. Les objets sont fusionnés récursivement, les tableaux et les valeurs scalaires remplacent la valeur cible, et null supprime le chemin cible.

openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5

Vous pouvez aussi transmettre un correctif par stdin, ce qui est utile pour les scripts de configuration à distance :

ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

Exemple de correctif :

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
      groupPolicy: "open",
      requireMention: false,
    },
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
      dmPolicy: "disabled",
      dm: { enabled: false },
      groupPolicy: "allowlist",
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}

Utilisez --replace-path <path> lorsqu’un objet ou un tableau doit devenir exactement la valeur fournie au lieu d’être corrigé récursivement :

openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'

--dry-run exécute les vérifications de schéma et de résolubilité SecretRef sans écrire. Les SecretRefs basés sur exec sont ignorés par défaut pendant l’exécution à blanc ; ajoutez --allow-exec lorsque vous voulez intentionnellement que l’exécution à blanc exécute des commandes de fournisseur.

Le mode chemin/valeur JSON reste pris en charge pour les SecretRefs comme pour les fournisseurs :

openclaw config set channels.discord.token \
  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
  --strict-json

openclaw config set secrets.providers.vaultfile \
  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
  --strict-json

# Options du constructeur de fournisseur

Les cibles du constructeur de fournisseur doivent utiliser secrets.providers.<alias> comme chemin.

Exemple de fournisseur exec renforcé :

openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-json-only \
  --provider-pass-env VAULT_TOKEN \
  --provider-trusted-dir /usr/local/bin \
  --provider-timeout-ms 5000

# Exécution à blanc

Utilisez --dry-run pour valider les changements sans écrire dans openclaw.json.

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run \
  --json

openclaw config set channels.discord.token \
  --ref-provider vault \
  --ref-source exec \
  --ref-id discord/token \
  --dry-run \
  --allow-exec

# Structure de la sortie JSON

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "schema" | "resolvability",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

{
  "ok": true,
  "operations": 1,
  "configPath": "~/.openclaw/openclaw.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0
}

{
  "ok": false,
  "operations": 1,
  "configPath": "~/.openclaw/openclaw.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0,
  "errors": [
    {
      "kind": "resolvability",
      "message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
      "ref": "env:default:MISSING_TEST_SECRET"
    }
  ]
}

# Sécurité d’écriture

openclaw config set et les autres outils d’écriture de configuration appartenant à OpenClaw valident toute la configuration après modification avant de l’enregistrer sur le disque. Si la nouvelle charge utile échoue à la validation du schéma ou ressemble à un écrasement destructeur, la configuration active est laissée intacte et la charge utile rejetée est enregistrée à côté sous le nom openclaw.json.rejected.*.

Préférez les écritures via la CLI pour les petites modifications :

openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate

Si une écriture est rejetée, inspectez la charge utile enregistrée et corrigez la structure complète de la configuration :

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate

Les écritures directes dans un éditeur restent autorisées, mais le Gateway en cours d’exécution les traite comme non fiables jusqu’à ce qu’elles soient validées. Les modifications directes invalides font échouer le démarrage ou sont ignorées par le rechargement à chaud ; Gateway ne réécrit pas openclaw.json. Exécutez openclaw doctor --fix pour réparer une configuration préfixée/écrasée ou restaurer la dernière copie connue comme valide. Voir Dépannage de Gateway.

La récupération de fichier entier est réservée à la réparation par doctor. Les changements de schéma de Plugin ou les écarts de minHostVersion restent visibles au lieu d’annuler des paramètres utilisateur sans rapport, comme les modèles, providers, profils d’authentification, canaux, exposition du Gateway, outils, mémoire, navigateur ou configuration Cron.

# Sous-commandes

• config file : affiche le chemin du fichier de configuration actif (résolu depuis OPENCLAW_CONFIG_PATH ou l’emplacement par défaut). Le chemin doit désigner un fichier ordinaire, pas un lien symbolique.

Redémarrez le gateway après les modifications.

# Valider

Validez la configuration actuelle par rapport au schéma actif sans démarrer le gateway.

openclaw config validate
openclaw config validate --json

Après la réussite de openclaw config validate, vous pouvez utiliser la TUI locale pour qu’un agent intégré compare la configuration active avec la documentation pendant que vous validez chaque changement depuis le même terminal :

openclaw chat

Puis dans la TUI :

!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor

Boucle de réparation typique :

# Associés

• Référence CLI
• Configuration