CLI commands

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.

Options racines

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="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

bash

openclaw config fileopenclaw config --section modelopenclaw config --section gateway --section daemonopenclaw config schemaopenclaw config get browser.executablePathopenclaw 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 --mergeopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKENopenclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode jsonopenclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config unset plugins.entries.brave.config.webSearch.apiKeyopenclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-runopenclaw config validateopenclaw 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 :

bash

openclaw config get agents.defaults.workspaceopenclaw config get 'agents.list[0].id'openclaw config get agents.listopenclaw 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.

bash

openclaw config get browser.executablePathopenclaw 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.

bash

openclaw config schemaopenclaw config schema > openclaw.schema.json

`config validate`

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

bash

openclaw config validateopenclaw config validate --json

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.

bash

openclaw config set agents.defaults.heartbeat.every "0m"openclaw config set gateway.port 19001 --strict-jsonopenclaw 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.

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

bash

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --mergeopenclaw 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

bash

openclaw config set <path> <value>

Mode de création de SecretRef

bash

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

Mode de création de fournisseur

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

bash

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

Mode par lots

bash

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" }  }]'

bash

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

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 :

bash

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é :

bash

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.

bash

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

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

bash

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

Exemple de modification :

json5

{  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 :

bash

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.

bash

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

json5

{  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

json

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

Exemple d'échec

json

{  "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.

Privilégiez les écritures via la CLI pour les petites modifications :

bash

openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw config validate

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

bash

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".rejected.* 2>/dev/null | headopenclaw 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 :

bash

openclaw chat

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

text

!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.

Pages connexes

Was this useful?

Configuration

Options racines

Exemples

Chemins

`config get`

`config file`

`config schema`

`config validate`

Valeurs

Modes de `config set`

Mode valeur

Mode de création de SecretRef

Mode de création de fournisseur

Mode par lots

Options de création de fournisseur

`config patch`

Simulation

Structure de la sortie JSON

Exemple de réussite

Exemple d'échec

Application des modifications

Sécurité des écritures

Boucle de réparation

Comparer avec la documentation

Appliquer des modifications ciblées

Valider à nouveau

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

Pages connexes

On this page

Molty

Options racines

Exemples

Chemins

config get

config file

config schema

config validate

Valeurs

Modes de config set

Mode valeur

Mode de création de SecretRef

Mode de création de fournisseur

Mode par lots

Options de création de fournisseur

config patch

Simulation

Structure de la sortie JSON

Exemple de réussite

Exemple d'échec

Application des modifications

Sécurité des écritures

Boucle de réparation

Comparer avec la documentation

Appliquer des modifications ciblées

Valider à nouveau

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

Pages connexes

On this page

`config get`

`config file`

`config schema`

`config validate`

Modes de `config set`

`config patch`