Configuration

Aides non interactives pour openclaw.json : obtenir/définir/modifier/supprimer une valeur par chemin, afficher le schéma, valider ou afficher le chemin du fichier actif. Exécutez openclaw config sans sous-commande pour ouvrir le même assistant guidé que openclaw configure.

Lorsque OPENCLAW_NIX_MODE=1, OpenClaw considère openclaw.json comme immuable. Les commandes en lecture seule (config get, config file, config schema, config validate) fonctionnent toujours ; les commandes d’écriture de configuration refusent toute modification. Modifiez plutôt la source Nix de l’installation ; pour la distribution nix-openclaw officielle, consultez le démarrage rapide de nix-openclaw et définissez les valeurs sous programs.openclaw.config ou instances.<name>.config.

Options racines

string

Filtre de section répétable pour la configuration guidée lorsque vous exécutez openclaw config sans sous-commande.

Sections guidées : 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

Chemins

Notation par points ou crochets. Placez les chemins utilisant des crochets entre guillemets dans les exemples de shell afin que zsh ne développe pas [0] comme un motif glob :

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

`config get`

Lit une valeur depuis l’instantané expurgé de la configuration (les secrets ne sont jamais affichés). --json affiche la valeur brute au format JSON ; sinon, les chaînes, nombres et booléens sont affichés sans mise en forme, tandis que les objets et tableaux sont affichés au format JSON mis en forme.

openclaw config get browser.executablePath
openclaw config get agents.defaults.model --json

`config file`

Affiche le chemin du fichier de configuration actif, déterminé à partir de OPENCLAW_CONFIG_PATH ou de l’emplacement par défaut. Le chemin désigne un fichier ordinaire, et non un lien symbolique ; consultez Sécurité d’écriture.

`config schema`

Affiche sur la sortie standard le schéma JSON généré pour openclaw.json.

Contenu inclus

Le schéma actuel de la configuration racine, ainsi qu’un champ de chaîne racine $schema destiné aux outils d’édition.
Les métadonnées de documentation des champs title / description utilisées par l’interface de contrôle.
Les nœuds d’objet imbriqué, génériques (*) et d’élément de tableau ([]) héritent des mêmes métadonnées title / description lorsque la documentation du champ correspondant existe.
Les branches anyOf / oneOf / allOf héritent également des mêmes métadonnées de documentation.
Les métadonnées de schéma en direct des plugins et canaux, dans la mesure du possible, lorsque les manifestes d’exécution peuvent être chargés.
Un schéma de repli propre même lorsque la configuration actuelle est invalide.

RPC d’exécution associé

config.schema.lookup renvoie un chemin de configuration normalisé avec un nœud de schéma superficiel (title, description, type, enum, const, limites courantes), les métadonnées d’indication d’interface correspondantes et les résumés des enfants immédiats. Utilisez-le pour une exploration limitée à un chemin dans l’interface de contrôle ou dans des clients personnalisés.

openclaw config schema
openclaw config schema > openclaw.schema.json

`config validate`

Valide la configuration actuelle par rapport au schéma actif sans démarrer le Gateway.

openclaw config validate
openclaw config validate --json

Si la validation échoue déjà, commencez par openclaw configure ou openclaw doctor --fix. openclaw chat ne contourne pas la protection contre les configurations invalides.

Valeurs

Les valeurs sont analysées comme du JSON5 lorsque cela est possible ; sinon, elles sont traitées comme des chaînes brutes. Utilisez --strict-json pour exiger du JSON standard sans repli vers une chaîne (la syntaxe propre à JSON5, comme les commentaires, les virgules finales ou les clés sans guillemets, est alors rejetée). --json est un alias historique de --strict-json sur config set.

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 au format JSON au lieu d’un texte mis en forme pour le terminal.

L’affectation d’un objet remplace par défaut le chemin cible. Les chemins protégés qui contiennent généralement des entrées ajoutées par l’utilisateur refusent les remplacements qui supprimeraient des entrées existantes, sauf si vous transmettez --replace : agents.defaults.models, agents.list, models.providers, models.providers.<id>, models.providers.<id>.models, plugins.entries et auth.profiles.

Utilisez --merge lors de l’ajout d’entrées à ces tables de correspondance :

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 la valeur fournie doit intentionnellement devenir la valeur cible complète.

Modes de `config set`

Mode valeur
Mode de création de SecretRef
Mode de création de fournisseur
Mode par lots

openclaw config set <path> <value>

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

Cible uniquement les chemins secrets.providers.<alias> :

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

Les affectations SecretRef sont rejetées sur les surfaces modifiables à l’exécution qui ne les prennent pas en charge (par exemple hooks.token, commands.ownerDisplaySecret, les jetons Webhook de liaison aux fils Discord et le JSON des identifiants WhatsApp). Consultez Surface d’identifiants SecretRef.

L’analyse par lots utilise toujours la charge utile du lot (--batch-json/--batch-file) comme source de vérité ; --strict-json / --json ne modifient pas le comportement d’analyse par lots. Le mode chemin/valeur JSON fonctionne également directement pour les SecretRefs et 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 de création de fournisseur

Les cibles du générateur de fournisseur doivent utiliser secrets.providers.<alias> comme chemin.

Options communes

--provider-source <env|file|exec>
--provider-timeout-ms <ms> (file, exec)

Fournisseur d’environnement (--provider-source env)

--provider-allowlist <ENV_VAR> (répétable)

Fournisseur de fichier (--provider-source file)

--provider-path <path> (obligatoire)
--provider-mode <singleValue|json>
--provider-max-bytes <bytes>
--provider-allow-insecure-path

Fournisseur d’exécution (--provider-source exec)

--provider-command <path> (obligatoire)
--provider-arg <arg> (répétable)
--provider-no-output-timeout-ms <ms>
--provider-max-output-bytes <bytes>
--provider-json-only
--provider-env <KEY=VALUE> (répétable)
--provider-pass-env <ENV_VAR> (répétable)
--provider-trusted-dir <path> (répétable)
--provider-allow-insecure-path
--provider-allow-symlink-command

Exemple de fournisseur d’exécution 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

`config patch`

Collez ou transmettez par canal une modification JSON5 ayant la forme d’une configuration au lieu d’exécuter de nombreuses commandes config set fondées sur des chemins. Les objets sont fusionnés récursivement ; les tableaux et les valeurs scalaires remplacent la cible ; null supprime le chemin cible.

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

Transmettez une modification via l’entrée standard pour les scripts de configuration à distance :

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

Exemple de modification :

{
  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.6-sol" },
      models: {
        "openai/gpt-5.6-sol": { params: { fastMode: true } },
      },
    },
  },
}

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

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

--dry-run exécute les vérifications du schéma et de la résolvabilité des SecretRefs sans effectuer d’écriture. Les SecretRefs reposant sur une exécution sont ignorées par défaut lors d’une simulation ; ajoutez --allow-exec lorsque vous souhaitez intentionnellement que la simulation exécute les commandes du fournisseur.

Simulation

--dry-run valide les modifications sans écrire dans openclaw.json. Disponible sur config set, config patch et config unset.

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

Comportement du mode simulation

Mode constructeur : exécute des contrôles de résolubilité des SecretRef pour les références/fournisseurs modifiés.
Mode JSON (--strict-json, --json ou mode par lots) : exécute la validation du schéma ainsi que les contrôles de résolubilité des SecretRef.
La validation de la politique s’effectue sur l’intégralité de la configuration après modification, afin que les écritures d’objets parents (par exemple, définir hooks comme un objet) ne puissent pas contourner la validation des surfaces non prises en charge.
Les contrôles des SecretRef de type exec sont ignorés par défaut afin d’éviter les effets secondaires des commandes ; transmettez --allow-exec pour les activer (cela peut exécuter des commandes de fournisseur). --allow-exec est réservé au mode simulation et génère une erreur sans --dry-run.

Champs de --dry-run --json

ok : indique si la simulation a réussi
operations : nombre d’affectations évaluées
checks : indique si les contrôles de schéma/résolubilité ont été exécutés
checks.resolvabilityComplete : indique si les contrôles de résolubilité ont été menés à terme (faux lorsque les références exec sont ignorées)
refsChecked : nombre de références effectivement résolues pendant la simulation
skippedExecRefs : nombre de références exec ignorées parce que --allow-exec n’était pas défini
errors : échecs structurés de chemin manquant, de schéma ou de résolubilité lorsque ok=false

Structure de la sortie JSON

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder" | "unset", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "missing-path" | "schema" | "resolvability",
      message: string,
      ref?: string, // présent pour les erreurs de résolubilité
    },
  ],
}

Exemple de réussite
Exemple d'échec

{
  "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": "Erreur : la variable d'environnement \"MISSING_TEST_SECRET\" n'est pas définie.",
      "ref": "env:default:MISSING_TEST_SECRET"
    }
  ]
}

En cas d'échec de la simulation

config schema validation failed : la structure de votre configuration après modification n’est pas valide ; corrigez le chemin/la valeur ou la structure de l’objet fournisseur/référence.
Config policy validation failed: unsupported SecretRef usage : rétablissez cette information d’identification sous forme de texte brut/chaîne ; utilisez les SecretRef uniquement sur les surfaces prises en charge.
SecretRef assignment(s) could not be resolved : le fournisseur ou la référence indiqué ne peut actuellement pas être résolu (variable d’environnement manquante, pointeur de fichier non valide, échec du fournisseur exec ou incompatibilité entre le fournisseur et la source).
Dry run note: skipped <n> exec SecretRef resolvability check(s) : relancez avec --allow-exec si vous devez valider la résolubilité exec.
Pour le mode par lots, corrigez les entrées en échec et relancez --dry-run avant d’effectuer l’écriture.

Application des modifications

Après chaque exécution réussie de config set / config patch / config unset, la CLI affiche l’une des trois indications suivantes pour vous informer si le Gateway doit être redémarré :

Indication	Signification
`Restart the gateway to apply.`	Le chemin modifié nécessite un redémarrage complet.
`Change will apply without restarting the gateway.`	Le rechargement à chaud le prend en compte automatiquement.
`No gateway restart needed.`	Aucun élément pertinent pour l’exécution n’a été modifié.

Les écritures dans plugins.entries (ou dans l’un de ses sous-chemins) nécessitent toujours un redémarrage, car la CLI ne peut pas garantir que les métadonnées de rechargement de chaque plugin sont chargées.

Sécurité des écritures

openclaw config set et les autres outils d’écriture de configuration appartenant à OpenClaw valident l’intégralité de la configuration après modification avant de l’enregistrer sur le disque. Si la nouvelle charge utile échoue à la validation du schéma ou semble écraser des données de manière destructive, la configuration active reste intacte et la charge utile rejetée est enregistrée à côté sous le nom openclaw.json.rejected.*. Les écritures appartenant à OpenClaw resérialisent le JSON5 en JSON standard. Lorsque la source contient des commentaires, l’outil d’écriture émet un avertissement juste avant de les supprimer ; utilisez directement un éditeur s’il est important de conserver les commentaires.

Le chemin de la configuration active doit désigner un fichier ordinaire. Les structures openclaw.json utilisant des liens symboliques ne sont pas prises en charge pour les écritures ; utilisez plutôt OPENCLAW_CONFIG_PATH pour pointer directement vers le fichier réel.

Privilégiez 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, examinez 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 considère comme non fiables jusqu’à leur validation. Les modifications directes non valides font échouer le démarrage ou sont ignorées par le rechargement à chaud ; le 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 valide connue. Consultez Dépannage du Gateway. La récupération du fichier entier est réservée aux réparations effectuées par doctor. Les modifications du schéma d’un plugin ou les incohérences de minHostVersion restent signalées explicitement au lieu d’entraîner la restauration d’autres paramètres utilisateur sans rapport, tels que la configuration des modèles, des fournisseurs, des profils d’authentification, des canaux, de l’exposition du Gateway, des outils, de la mémoire, du navigateur ou de Cron.

Boucle de réparation

Une fois que openclaw config validate réussit, utilisez la TUI locale pour qu’un agent intégré compare la configuration active à la documentation pendant que vous validez chaque modification depuis le même terminal :

openclaw chat

Dans la TUI, un ! initial exécute une commande shell locale littérale (après une demande de confirmation unique par session) :

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

Comparer avec la documentation

Demandez à l’agent de comparer votre configuration actuelle à la page de documentation pertinente et de suggérer la correction minimale.

Appliquer des modifications ciblées

Appliquez des modifications ciblées avec openclaw config set ou openclaw configure.

Valider à nouveau

Relancez openclaw config validate après chaque modification.

Utiliser doctor pour les problèmes d'exécution

Si la validation réussit, mais que l’environnement d’exécution présente toujours des problèmes, exécutez openclaw doctor ou openclaw doctor --fix pour obtenir de l’aide concernant la migration et la réparation.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

Options racines

Exemples

Chemins

`config get`

`config file`

`config schema`

`config validate`

Valeurs

Modes de `config set`

Options de création de fournisseur

`config patch`

Simulation

Structure de la sortie JSON

Application des modifications

Sécurité des écritures

Boucle de réparation

Pages connexes

​Options racines

​Exemples

​Chemins

​config get

​config file

​config schema

​config validate

​Valeurs

​Modes de config set

​Options de création de fournisseur

​config patch

​Simulation

​Structure de la sortie JSON

​Application des modifications

​Sécurité des écritures

​Boucle de réparation

​Pages connexes

Options racines

Exemples

Chemins

`config get`

`config file`

`config schema`

`config validate`

Valeurs

Modes de `config set`

Options de création de fournisseur

`config patch`

Simulation

Structure de la sortie JSON

Application des modifications

Sécurité des écritures

Boucle de réparation

Pages connexes