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

When OPENCLAW_NIX_MODE=1, OpenClaw treats openclaw.json as immutable. Read-only commands such as config get, config file, config schema, and config validate still work, but config writers refuse. Agents should edit the Nix source for the install instead; for the first-party nix-openclaw distribution, use nix-openclaw Quick Start and set values under programs.openclaw.config or `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 crochet. Mettez entre guillemets les chemins en notation entre crochets dans les exemples de shell afin que des shells tels que zsh ne développent pas [0] en tant que glob avant que OpenClaw ne reçoive le chemin :

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 si 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 historique.

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 imprime la valeur brute en JSON au lieu de texte formaté pour le terminal.

Note

L’assignation d’objet remplace le chemin cible par défaut. Les chemins de map/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 des entrées existantes, sauf si vous passez —replace`.

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

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 souhaitez 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 du builder 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 du builder 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 modifiables à l’exécution non prises en charge (par exemple

hooks.token

,

commands.ownerDisplaySecret

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

Surface des identifiants SecretRef

.

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 structuré comme une configuration au lieu d’exécuter plusieurs commandes config set basées sur un chemin. L’entrée est un objet JSON5. Les objets fusionnent 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 é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ésolvabilité SecretRef sans écrire. Les SecretRef basés sur Exec sont ignorés par défaut lors d’un essai à blanc (dry-run); ajoutez --allow-exec si vous souhaitez intentionnellement que l’essai à blanc 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 générateur de provider doivent utiliser secrets.providers.<alias> comme chemin.

Drapeaux communs

• `—provider-source

-—provider-timeout-ms

(file, exec`)

Provider Env (--provider-source env)

• `—provider-allowlist

` (répétable)

Provider 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 du schéma ainsi que les vérifications de résolvabilité SecretRef.
• La validation de stratégie s’exécute également pour les surfaces de cible SecretRef connues comme non prises en charge.
• Les vérifications de stratégie évaluent la configuration complète 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 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 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/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 réellement résolues lors du 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 clair (string) 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 actuellement pas ê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 exec refs ; relancez avec—allow-exec` si vous avez besoin d’une validation de la résolvabilité par exécution.

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

Sécurité d’écriture

openclaw config set et les autres writers de config détenus par 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 agencements

openclaw.json

liés par lien symbolique ne sont pas pris 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 de 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 non valides échouent au 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 la configuration préfixée/écrasée ou restaurer la dernière copie connue bonne. Voir Dépannage Gateway.

La récupération de fichier entier est réservée à la réparation du docteur. Les modifications de schéma de plugin ou le décalage minHostVersion restent audibles 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 : Affiche le chemin du fichier de configuration actif (résolu à partir de OPENCLAW_CONFIG_PATH ou de l’emplacement par défaut). Le chemin doit nommer 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 le TUI local pour qu’un agent intégré compare la configuration active avec la documentation pendant que vous validez chaque modification à partir du même terminal :

Note

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

openclaw configure

ou

openclaw doctor --fix

.

openclaw chat

ne contourne pas la garde 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. Docteur pour les problèmes d'exécution

   Si la validation réussit mais que l’exécution est encore 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