Vai al contenuto principale
Helper di configurazione per modifiche non interattive in openclaw.json: ottieni/imposta/applica patch/annulla/file/schema/convalida valori per percorso e stampa il file di configurazione attivo. Esegui senza un sottocomando per aprire la procedura guidata di configurazione (come openclaw configure).
Quando OPENCLAW_NIX_MODE=1, OpenClaw tratta openclaw.json come immutabile. I comandi di sola lettura come config get, config file, config schema e config validate continuano a funzionare, ma i comandi che scrivono la configurazione rifiutano l’operazione. Gli agenti dovrebbero invece modificare il sorgente Nix dell’installazione; per la distribuzione proprietaria nix-openclaw, usa nix-openclaw Quick Start e imposta i valori sotto programs.openclaw.config o instances.<name>.config.

​
Opzioni radice

​
--section <section>
string
Filtro di sezione ripetibile della configurazione guidata quando esegui openclaw config senza un sottocomando.
Sezioni guidate supportate: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

​
Esempi

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

Stampa lo schema JSON generato per openclaw.json su stdout come JSON.
  • Lo schema di configurazione radice corrente, più un campo stringa $schema radice per gli strumenti dell’editor.
  • Metadati di documentazione title e description dei campi usati dalla Control UI.
  • I nodi oggetto annidati, con carattere jolly (*) e degli elementi di array ([]) ereditano gli stessi metadati title / description quando esiste documentazione del campo corrispondente.
  • Anche i rami anyOf / oneOf / allOf ereditano gli stessi metadati della documentazione quando esiste documentazione del campo corrispondente.
  • Metadati schema live di Plugin + canali al meglio possibile quando i manifest di runtime possono essere caricati.
  • Uno schema di fallback pulito anche quando la configurazione corrente non è valida.
config.schema.lookup restituisce un percorso di configurazione normalizzato con un nodo schema superficiale (title, description, type, enum, const, limiti comuni), metadati di suggerimento UI corrispondenti e riepiloghi immediati dei figli. Usalo per drill-down con ambito di percorso in Control UI o client personalizzati.
openclaw config schema
Reindirizzalo in un file quando vuoi ispezionarlo o convalidarlo con altri strumenti: 
openclaw config schema > openclaw.schema.json

​
Percorsi

I percorsi usano la notazione con punto o parentesi quadre. Racchiudi tra virgolette i percorsi con notazione a parentesi negli esempi di shell, così shell come zsh non espandono [0] come glob prima che OpenClaw riceva il percorso: 
openclaw config get agents.defaults.workspace
openclaw config get 'agents.list[0].id'
Usa l’indice dell’elenco agenti per selezionare un agente specifico: 
openclaw config get agents.list
openclaw config set 'agents.list[1].tools.exec.node' "node-id-or-name"

​
Valori

I valori vengono analizzati come JSON5 quando possibile; altrimenti sono trattati come stringhe. Usa --strict-json per richiedere l’analisi JSON standard senza fallback a stringa. --json resta supportato come alias legacy di --strict-json. 
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
Quando --strict-json è abilitato, la sintassi solo JSON5 come commenti, virgole finali o chiavi oggetto senza virgolette viene rifiutata. Ometti --strict-json per l’analisi dei valori JSON5 con fallback a stringa grezza. config get <path> --json stampa il valore grezzo come JSON invece di testo formattato per terminale.
Per impostazione predefinita, l’assegnazione di oggetti sostituisce il percorso di destinazione. I percorsi di mappe/elenchi protetti che comunemente contengono voci aggiunte dall’utente, come agents.defaults.models, models.providers, models.providers.<id>.models, plugins.entries e auth.profiles, rifiutano sostituzioni che rimuoverebbero voci esistenti a meno che non passi --replace.
Usa --merge quando aggiungi voci a quelle mappe: 
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
Usa --replace solo quando vuoi intenzionalmente che il valore fornito diventi il valore di destinazione completo.

​
Modalità di config set

openclaw config set supporta quattro stili di assegnazione: 
openclaw config set <path> <value>
Le assegnazioni SecretRef vengono rifiutate su superfici mutabili a runtime non supportate (per esempio hooks.token, commands.ownerDisplaySecret, i token Webhook di binding dei thread Discord e il JSON delle credenziali WhatsApp). Vedi Superficie credenziali SecretRef.
L’analisi batch usa sempre il payload batch (--batch-json/--batch-file) come fonte di verità. --strict-json / --json non modificano il comportamento di analisi batch.

​
config patch

Usa config patch quando vuoi incollare o convogliare una patch con forma di configurazione invece di eseguire molti comandi config set basati su percorsi. L’input è un oggetto JSON5. Gli oggetti vengono uniti ricorsivamente, gli array e i valori scalari sostituiscono il valore di destinazione e null elimina il percorso di destinazione. 
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5
Puoi anche convogliare una patch tramite stdin, utile per script di configurazione remota: 
ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5
Patch di esempio: 
{
  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 } },
      },
    },
  },
}
Usa --replace-path <path> quando un oggetto o array deve diventare esattamente il valore fornito invece di essere aggiornato ricorsivamente con patch: 
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'
--dry-run esegue controlli di schema e risolvibilità SecretRef senza scrivere. Le SecretRef basate su exec vengono saltate per impostazione predefinita durante il dry run; aggiungi --allow-exec quando vuoi intenzionalmente che il dry run esegua comandi provider. La modalità percorso/valore JSON resta supportata sia per SecretRef sia per provider: 
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

​
Flag builder provider

Le destinazioni del builder provider devono usare secrets.providers.<alias> come percorso.
  • --provider-source <env|file|exec>
  • --provider-timeout-ms <ms> (file, exec)
  • --provider-allowlist <ENV_VAR> (ripetibile)
  • --provider-path <path> (obbligatorio)
  • --provider-mode <singleValue|json>
  • --provider-max-bytes <bytes>
  • --provider-allow-insecure-path
  • --provider-command <path> (obbligatorio)
  • --provider-arg <arg> (ripetibile)
  • --provider-no-output-timeout-ms <ms>
  • --provider-max-output-bytes <bytes>
  • --provider-json-only
  • --provider-env <KEY=VALUE> (ripetibile)
  • --provider-pass-env <ENV_VAR> (ripetibile)
  • --provider-trusted-dir <path> (ripetibile)
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command
Esempio di provider exec rafforzato: 
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

Usa --dry-run per convalidare le modifiche senza scrivere 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
  • Modalità builder: esegue controlli di risolvibilità SecretRef per refs/provider modificati.
  • Modalità JSON (--strict-json, --json o modalità batch): esegue la convalida dello schema più i controlli di risolvibilità SecretRef.
  • La convalida dei criteri viene eseguita anche per superfici di destinazione SecretRef note e non supportate.
  • I controlli dei criteri valutano la configurazione completa dopo la modifica, quindi le scritture su oggetti padre (ad esempio impostare hooks come oggetto) non possono aggirare la convalida delle superfici non supportate.
  • I controlli SecretRef exec vengono saltati per impostazione predefinita durante il dry-run per evitare effetti collaterali dei comandi.
  • Usa --allow-exec con --dry-run per attivare i controlli SecretRef exec (questo può eseguire comandi del provider).
  • --allow-exec è solo per il dry-run e genera errore se usato senza --dry-run.
--dry-run --json stampa un report leggibile da macchina:
  • ok: se il dry-run è riuscito
  • operations: numero di assegnazioni valutate
  • checks: se sono stati eseguiti controlli di schema/risolvibilità
  • checks.resolvabilityComplete: se i controlli di risolvibilità sono stati eseguiti fino al completamento (false quando le refs exec vengono saltate)
  • refsChecked: numero di refs effettivamente risolte durante il dry-run
  • skippedExecRefs: numero di refs exec saltate perché --allow-exec non era impostato
  • errors: errori strutturati di percorso mancante, schema o risolvibilità quando ok=false

​
Forma dell’output 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
    },
  ],
}

{
  "ok": true,
  "operations": 1,
  "configPath": "~/.openclaw/openclaw.json",
  "inputModes": ["builder"],
  "checks": {
    "schema": false,
    "resolvability": true,
    "resolvabilityComplete": true
  },
  "refsChecked": 1,
  "skippedExecRefs": 0
}
  • config schema validation failed: la forma della configurazione dopo la modifica non è valida; correggi il percorso/valore o la forma dell’oggetto provider/ref.
  • Config policy validation failed: unsupported SecretRef usage: sposta quella credenziale di nuovo in input in testo semplice/stringa e mantieni SecretRefs solo sulle superfici supportate.
  • SecretRef assignment(s) could not be resolved: il provider/ref referenziato al momento non può essere risolto (variabile env mancante, puntatore file non valido, errore del provider exec o mancata corrispondenza provider/sorgente).
  • Dry run note: skipped <n> exec SecretRef resolvability check(s): il dry-run ha saltato le refs exec; riesegui con --allow-exec se ti serve la convalida della risolvibilità exec.
  • Per la modalità batch, correggi le voci non riuscite e riesegui --dry-run prima di scrivere.

​
Sicurezza in scrittura

openclaw config set e altri writer di configurazione di proprietà di OpenClaw convalidano la configurazione completa dopo la modifica prima di confermarla su disco. Se il nuovo payload non supera la convalida dello schema o sembra una sovrascrittura distruttiva, la configurazione attiva viene lasciata invariata e il payload rifiutato viene salvato accanto a essa come openclaw.json.rejected.*.
Il percorso della configurazione attiva deve essere un file regolare. I layout openclaw.json con symlink non sono supportati per le scritture; usa invece OPENCLAW_CONFIG_PATH per puntare direttamente al file reale.
Preferisci le scritture tramite CLI per piccole modifiche: 
openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate
Se una scrittura viene rifiutata, ispeziona il payload salvato e correggi la forma completa della configurazione: 
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate
Le scritture dirette nell’editor sono ancora consentite, ma il Gateway in esecuzione le tratta come non attendibili finché non vengono convalidate. Le modifiche dirette non valide impediscono l’avvio o vengono saltate dall’hot reload; il Gateway non riscrive openclaw.json. Esegui openclaw doctor --fix per riparare una configurazione con prefisso/sovrascritta o ripristinare l’ultima copia nota come valida. Vedi Risoluzione dei problemi del Gateway. Il ripristino dell’intero file è riservato alla riparazione tramite doctor. Le modifiche allo schema del Plugin o la discrepanza di minHostVersion restano esplicite invece di annullare impostazioni utente non correlate come modelli, provider, profili di autenticazione, canali, esposizione gateway, strumenti, memoria, browser o configurazione cron.

​
Sottocomandi

  • config file: stampa il percorso del file di configurazione attivo (risolto da OPENCLAW_CONFIG_PATH o dalla posizione predefinita). Il percorso deve indicare un file regolare, non un symlink.
Riavvia il gateway dopo le modifiche.

​
Convalida

Convalida la configurazione corrente rispetto allo schema attivo senza avviare il gateway. 
openclaw config validate
openclaw config validate --json
Dopo che openclaw config validate passa, puoi usare la TUI locale per far confrontare a un agente incorporato la configurazione attiva con la documentazione mentre convalidi ogni modifica dallo stesso terminale:
Se la convalida non sta già passando, inizia con openclaw configure o openclaw doctor --fix. openclaw chat non aggira la guardia contro configurazioni non valide.
openclaw chat
Poi dentro la TUI: 
!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor
Ciclo di riparazione tipico:
1

Confronta con la documentazione

Chiedi all’agente di confrontare la configurazione corrente con la pagina di documentazione pertinente e suggerire la correzione più piccola.
2

Applica modifiche mirate

Applica modifiche mirate con openclaw config set o openclaw configure.
3

Riconvalida

Riesegui openclaw config validate dopo ogni modifica.
4

Doctor per problemi di runtime

Se la convalida passa ma il runtime è ancora non integro, esegui openclaw doctor o openclaw doctor --fix per assistenza con migrazione e riparazione.

​
Correlati