Config

Helpers de configuration pour les modifications non interactives dans openclaw.json : get/set/patch/unset/file/schema/validate des valeurs par chemin et imprimer le fichier de configuration actif. Exécuter sans sous-commande pour ouvrir l’assistant de configuration (identique à openclaw configure).

Note

Lorsque OPENCLAW_NIX_MODE=1, OpenClaw traite openclaw.json comme immuable. Les commandes en lecture seule telles que config get, config file, config schema et config validate fonctionnent toujours, mais les rédacteurs de configuration refusent. Les agents doivent modifier la source Nix pour l’installation à la place ; pour la distribution nix-openclaw de première partie, utilisez nix-openclaw Quick Start et définissez des valeurs sous programs.openclaw.config ou `instances.

.config`.

Options racines

Filtre de section d'installation 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

Imprimer le schéma JSON généré pour openclaw.json vers stdout en tant que JSON.

Ce qu'il inclut

• Le schéma de configuration racine actuel, plus un champ de chaîne $schema racine pour les outils de l’éditeur.
• Les métadonnées de documentation des champs title et description utilisées par l’interface de contrôle.
• Les nœuds d’objet imbriqué, de caractère générique (*) et d’élément de tableau ([]) héritent des mêmes métadonnées title / description lorsqu’une documentation de champ correspondante existe.
• Les branches anyOf / oneOf / allOf héritent également des mêmes métadonnées de documentation lorsqu’une documentation de champ correspondante existe.
• Métadonnées de schéma du plugin dynamique + du channel (au mieux) lorsque les manifestes d’exécution peuvent être chargés.
• Un schéma de repli propre même lorsque la configuration actuelle est invalide.

RPCRPC 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 communes), les métadonnées d’indicateur d’interface correspondantes et les résumés des enfants immédiats. Utilisez-le pour un forage étendu au chemin dans l’interface de contrôle ou les clients personnalisés.

openclaw config schema

Redirigez-le vers un fichier lorsque vous souhaitez 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 des agents pour cibler un agent spécifique :

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

Valeurs

Les valeurs sont analysées en tant que JSON5 lorsque possible ; sinon, elles sont traitées comme des chaînes de caractères. Utilisez --strict-json pour exiger l’analyse JSON5. --json reste pris en charge en tant qu’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 au format JSON au lieu du texte formaté pour le terminal.

Note

L’assignation d’objet remplace le chemin cible par défaut. Les chemins de carte/liste protégés qui contiennent généralement des entrées ajoutées par l’utilisateur, telles que agents.defaults.models, models.providers, `models.providers.

.models, plugins.entriesetauth.profiles, refusent les remplacements qui supprimeraient les entrées existantes, sauf si vous passez —replace`.

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

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 config set

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

Mode ValeurMode constructeur SecretRefMode constructeur de fournisseurMode par lot

openclaw config set

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

Le mode constructeur de fournisseur cible uniquement les chemins `secrets.providers.

` :

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

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

Warning

Les affectations SecretRef sont rejetées sur les surfaces mutables au runtime non prises en charge (par exemple

hooks.token

,

commands.ownerDisplaySecret

DiscordWhatsApp, les jetons de webhook de liaison de thread Discord et les identifiants JSON WhatsApp). Voir

SecretRef Credential Surface

.

L’analyse par lot 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 lot.

config patch

Utilisez config patch lorsque vous souhaitez coller ou rediriger un correctif ayant la forme d’une configuration au lieu d’exécuter plusieurs commandes config set basées sur des chemins. L’entrée est un objet JSON5. Les objets fusionnent de manière récursive, 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 également rediriger un correctif via 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 des vérifications de schéma et de résolubilité SecretRef sans écrire. Les SecretRefs basés sur Exec sont ignorés par défaut lors de l’exécution à vide (dry-run) ; ajoutez --allow-exec lorsque vous souhaitez intentionnellement que l’exécution à vide exécute les commandes du provider.

Le mode chemin/valeur JSON reste pris en charge pour les SecretRefs et les providers :

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

Indicateurs du constructeur de provider

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

Indicateurs communs

• `—provider-source

-—provider-timeout-ms

(file, exec`)

Provider d'environnement (--provider-source env)

• `—provider-allowlist

` (répétable)

Provider de fichier (--provider-source file)

• `—provider-path

(requis) -—provider-mode

-—provider-max-bytes

-—provider-allow-insecure-path`

Provider d'exécution (--provider-source exec)

• `—provider-command

(requis) -—provider-arg

(répétable) -—provider-no-output-timeout-ms

-—provider-max-output-bytes

-—provider-json-only -—provider-env

(répétable) -—provider-pass-env

(répétable) -—provider-trusted-dir

(répétable) -—provider-allow-insecure-path -—provider-allow-symlink-command`

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

Dry run

Utilisez --dry-run pour valider les modifications sans écrire 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

Comportement du dry-run

• Mode Builder : exécute les vérifications de résolvabilité SecretRef pour les refs/providers modifiés.
• Mode JSON (--strict-json, --json, ou mode batch) : exécute la validation de schéma ainsi que les vérifications de résolvabilité SecretRef.
• La validation de stratégie s’exécute également pour les surfaces cibles SecretRef non prises en charge connues.
• Les vérifications de stratégie évaluent la configuration complète après modification, de sorte que les écritures d’objets parents (par exemple, définir hooks comme un objet) ne peuvent pas contourner la validation des surfaces non prises en charge.
• Les vérifications Exec SecretRef sont ignorées par défaut lors du dry-run pour éviter les effets secondaires des commandes.
• Utilisez --allow-exec avec --dry-run pour activer les vérifications Exec SecretRef (cela peut exécuter des commandes de provider).
• --allow-exec est réservé au dry-run et génère une erreur s’il est utilisé sans --dry-run.

--dry-run -- fields

--dry-run --json imprime un rapport lisible par la machine :

• ok : indique si le dry-run a réussi
• operations : nombre d’assignations évaluées
• checks : indique si les vérifications de schéma/de résolvabilité ont été exécutées
• checks.resolvabilityComplete : indique si les vérifications de résolvabilité ont été exécutées jusqu’au bout (false lorsque les exec refs sont ignorés)
• refsChecked : nombre de refs effectivement résolues pendant le dry-run
• skippedExecRefs : nombre d’exec refs ignorées car --allow-exec n’était pas défini
• errors : échecs structurés de chemin manquant, de schéma ou de résolvabilité 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, // present for resolvability errors
    },
  ],
}

Exemple de succèsExemple 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": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
      "ref": "env:default:MISSING_TEST_SECRET"
    }
  ]
}

Si le dry-run échoue

• config schema validation failed : la forme de votre config après modification est invalide ; corrigez le chemin/valeur ou la forme de l’objet provider/ref.
• Config policy validation failed: unsupported SecretRef usage : remettez cet identifiant en entrée en texte brut/chaîne et gardez les SecretRefs uniquement sur les surfaces prises en charge.
• SecretRef assignment(s) could not be resolved : le provider/ref référencé ne peut pas actuellement être résolu (env var manquante, pointeur de fichier invalide, échec du provider d’exécution, ou inadéquation provider/source).
• `Dry run note: skipped

exec SecretRef resolvability check(s): le dry-run a ignoré les refs d'exécution ; relancez avec—allow-exec` si vous avez besoin de la validation de la résolution d’exécution.

• Pour le mode batch, corrigez les entrées en échec et relancez --dry-run avant l’écriture.

Sécurité d’écriture

openclaw config set et autres rédacteurs de config appartenant à OpenClaw valident l’intégralité de la config après modification avant de la valider sur le disque. Si le nouveau payload échoue à la validation du schéma ou ressemble à un écrasement destructeur, la config active est laissée telle quelle et le payload rejeté est enregistré à côté sous openclaw.json.rejected.*.

Warning

Le chemin de la config active doit être un fichier régulier. Les dispositions

openclaw.json

liées par un lien symbolique ne sont pas prises en charge pour l’écriture ; utilisez

OPENCLAW_CONFIG_PATH

pour pointer directement vers le fichier réel à la place.

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, inspectez le payload enregistré et corrigez la forme complète de la config :

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

Les écritures directes par l’éditeur sont toujours autorisées, mais le Gateway en cours d’exécution les considère comme non fiables jusqu’à ce qu’elles soient validées. Les modifications directes invalides entraînent un échec du démarrage ou sont ignorées lors du rechargement à chaud ; le Gateway ne réécrit pas openclaw.json. Exécutez openclaw doctor --fix pour réparer la config préfixée/écrasée ou restaurer la dernière copie connue bonne. Voir Dépannage Gateway.

La récupération de fichier complet est réservée à la réparation via doctor. Les modifications de schéma de plug-in ou le désalignement minHostVersion restent bruyants au lieu d’annuler les paramètres utilisateur non liés tels que les modèles, les fournisseurs, les profils d’authentification, les canaux, l’exposition de la passerelle, les outils, la mémoire, le navigateur ou la configuration cron.

Sous-commandes

• config file : Afficher le chemin du fichier de configuration actif (résolu à partir de OPENCLAW_CONFIG_PATH ou de l’emplacement par défaut). Le chemin doit désigner un fichier régulier, et non un lien symbolique.

Redémarrez la passerelle après les modifications.

Valider

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

openclaw config validate
openclaw config validate --json

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

Note

Si la validation échoue déjà, commencez par

openclaw configure

ou

openclaw doctor --fix

.

openclaw chat

ne contourne pas la protection de configuration invalide.

openclaw chat

Ensuite, à l’intérieur du TUI :

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

Boucle de réparation typique :

1. Comparer avec la documentation

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

2. Appliquer des modifications ciblées

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

3. Re-valider

   Relancez openclaw config validate après chaque modification.

4. Doctor pour les problèmes d'exécution

   Si la validation réussit mais que l’exécution est toujours défaillante, exécutez openclaw doctor ou openclaw doctor --fix pour obtenir de l’aide à la migration et à la réparation.

Connexes

• Référence CLI
• Configuration