CLI commands

Configuration

Assistants non interactifs 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 contenant des crochets entre guillemets dans les exemples de shell afin que zsh ne développe pas [0] comme un motif générique :

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é des écritures.

`config schema`

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

Ce qu’il inclut

Le schéma racine actuel de la configuration, ainsi qu’un champ chaîne $schema à la racine pour les outils d’édition.
Les métadonnées de documentation title / description des champs utilisées par l’interface de contrôle.
Les nœuds d’objets imbriqués, génériques (*) et d’éléments de tableau ([]) héritent des mêmes métadonnées title / description lorsque la documentation des champs correspondants existe.
Les branches anyOf / oneOf / allOf héritent également des mêmes métadonnées de documentation.
Les métadonnées de schéma des Plugins et canaux actifs, 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 détaillée 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 ancien alias de --strict-json pour 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 de l’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 créateur 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 un correctif JSON5 ayant la structure de la 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 un correctif 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 correctif :

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 contrôles du schéma et de la capacité de résolution des SecretRefs sans écrire. Les SecretRefs reposant sur une commande sont ignorées par défaut pendant l’exécution à blanc ; ajoutez --allow-exec lorsque vous souhaitez intentionnellement que l’exécution à blanc lance les commandes des fournisseurs.

Exécution à blanc

--dry-run valide les modifications sans écrire dans openclaw.json. Disponible avec 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 de l’exécution à blanc

Mode générateur : exécute les vérifications de résolvabilité des SecretRef pour les références et fournisseurs modifiés.
Mode JSON (--strict-json, --json ou mode par lots) : exécute la validation du schéma ainsi que les vérifications de résolvabilité des SecretRef.
La validation de la stratégie s’exécute sur l’intégralité de la configuration après modification ; les écritures d’objets parents (par exemple, définir hooks comme un objet) ne peuvent donc pas contourner la validation des surfaces non prises en charge.
Les vérifications des SecretRef de type exec sont ignorées par défaut afin d’éviter les effets de bord des commandes ; transmettez --allow-exec pour les activer (cela peut exécuter les commandes des fournisseurs). --allow-exec est réservé à l’exécution à blanc et produit une erreur sans --dry-run.

Champs de --dry-run --json

ok : indique si l’exécution à blanc a réussi
operations : nombre d’affectations évaluées
checks : indique si les vérifications du schéma et de la résolvabilité ont été exécutées
checks.resolvabilityComplete : indique si les vérifications de résolvabilité ont été menées à terme (faux lorsque les références exec sont ignorées)
refsChecked : nombre de références effectivement résolues pendant l’exécution à blanc
skippedExecRefs : nombre de références exec ignorées parce que --allow-exec n’était pas défini
errors : échecs structurés concernant un chemin manquant, le schéma ou la résolvabilité 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, // present for resolvability errors    },  ],}

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},  "refsChecked": 1,  "skippedExecRefs": 0,  "errors": [    {      "kind": "resolvability",      "message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",      "ref": "env:default:MISSING_TEST_SECRET"    }  ]}

En cas d’échec de l’exécution à blanc

config schema validation failed : la structure de votre configuration après modification n’est pas valide ; corrigez le chemin ou la valeur, ou la structure de l’objet fournisseur ou référence.
Config policy validation failed: unsupported SecretRef usage : rétablissez cette information d’identification sous forme de texte brut ou de 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és ne peuvent pas être résolus actuellement (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ésolvabilité exec.
En 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 ou config unset, la CLI affiche l’une des trois indications suivantes afin de vous signaler 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 l’applique 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 inchangée et la charge utile rejetée est enregistrée à côté sous le nom openclaw.json.rejected.*.

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 l’intégralité de la structure de 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 empêchent 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 ou écrasée, ou restaurer la dernière copie valide connue. Consultez Dépannage du Gateway.

La récupération de l’intégralité du fichier est réservée aux réparations effectuées par doctor. Les modifications de schéma d’un Plugin ou les divergences de minHostVersion restent explicitement signalées au lieu d’entraîner la restauration de paramètres utilisateur sans rapport, comme les modèles, les fournisseurs, les profils d’authentification, les canaux, l’exposition du Gateway, les outils, la mémoire, le navigateur ou la configuration Cron.

Boucle de réparation

Une fois que openclaw config validate réussit, utilisez la TUI locale afin 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 la plus limitée.

Appliquer des modifications ciblées

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

Valider de 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’exécution reste défaillante, lancez openclaw doctor ou openclaw doctor --fix pour obtenir de l’aide sur 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`

Exécution à blanc

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 de 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

Exécution à blanc

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 de 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`