Configurazione

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

Opzioni radice

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

config schema

Stampa lo schema JSON generato per openclaw.json su stdout come JSON.

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

Usa l'indice dell'elenco agenti per selezionare un agente specifico:

openclaw config get agents.listopenclaw 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-jsonopenclaw 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.

Usa --merge quando aggiungi voci a quelle mappe:

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

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>

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

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

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-runopenclaw 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.json5ssh 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.

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

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}

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

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

Preferisci le scritture tramite CLI per piccole modifiche:

openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw 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 | headopenclaw 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 validateopenclaw 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:

openclaw chat

Poi dentro la TUI:

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

Ciclo di riparazione tipico:

Correlati

• Riferimento CLI
• Configurazione