OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Configurazione

Helper non interattivi per openclaw.json: ottenere/impostare/modificare/rimuovere un valore in base al percorso, stampare lo schema, convalidare oppure stampare il percorso del file attivo. Eseguire openclaw config senza sottocomandi per aprire la stessa procedura guidata di openclaw configure.

Opzioni principali

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc2VjdGlvbiA8c2VjdGlvbg " type="string"> Filtro ripetibile per le sezioni della configurazione guidata quando si esegue openclaw config senza sottocomandi.

Sezioni guidate: workspace, model, web, gateway, daemon, channels, plugins, skills, health.

Esempi

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

Percorsi

Notazione con punti o parentesi quadre. Racchiudere tra virgolette i percorsi con parentesi negli esempi della shell, affinché zsh non espanda tramite glob [0]:

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

Legge un valore dall'istantanea oscurata della configurazione (i segreti non vengono mai stampati). --json stampa il valore non elaborato come JSON; altrimenti stringhe/numeri/valori booleani vengono stampati senza formattazione, mentre oggetti/array vengono stampati come JSON formattato.

bash
openclaw config get browser.executablePathopenclaw config get agents.defaults.model --json

config file

Stampa il percorso del file di configurazione attivo, risolto da OPENCLAW_CONFIG_PATH o dalla posizione predefinita. Il percorso identifica un file normale, non un collegamento simbolico; vedere Sicurezza della scrittura.

config schema

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

Contenuto
  • Lo schema di configurazione principale corrente, più un campo stringa principale $schema per gli strumenti dell'editor.
  • Metadati della documentazione dei campi title / description usati dalla Control UI.
  • I nodi di oggetti annidati, caratteri jolly (*) ed elementi di array ([]) ereditano gli stessi metadati title / description quando esiste la documentazione dei campi corrispondente.
  • Anche i rami anyOf / oneOf / allOf ereditano gli stessi metadati della documentazione.
  • Metadati dello schema di Plugin e canali in tempo reale, secondo il criterio del massimo sforzo, quando è possibile caricare i manifest di runtime.
  • Uno schema di ripiego pulito anche quando la configurazione corrente non è valida.
RPC di runtime correlata

config.schema.lookup restituisce un percorso di configurazione normalizzato con un nodo di schema superficiale (title, description, type, enum, const, limiti comuni), i metadati dei suggerimenti dell'interfaccia utente corrispondenti e i riepiloghi dei nodi figli immediati. Usarlo per l'analisi dettagliata limitata al percorso nella Control UI o nei client personalizzati.

bash
openclaw config schemaopenclaw config schema > openclaw.schema.json

config validate

Convalida la configurazione corrente rispetto allo schema attivo senza avviare il Gateway.

bash
openclaw config validateopenclaw config validate --json

Valori

Quando possibile, i valori vengono analizzati come JSON5; altrimenti vengono trattati come stringhe non elaborate. Usare --strict-json per richiedere JSON standard senza ripiego su stringa (la sintassi esclusiva di JSON5, come commenti, virgole finali o chiavi senza virgolette, viene quindi rifiutata). --json è un alias legacy di --strict-json su 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 stampa il valore non elaborato come JSON invece del testo formattato per il terminale.

Usare --merge quando si aggiungono voci a tali mappe:

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

Usare --replace solo quando il valore fornito deve intenzionalmente diventare il valore completo della destinazione.

Modalità di config set

Modalità valore

bash
openclaw config set <path> <value>

Modalità generatore SecretRef

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

Modalità generatore di provider

Destinata esclusivamente ai percorsi 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

Modalità batch

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'analisi batch usa sempre il payload batch (--batch-json/--batch-file) come fonte attendibile; --strict-json / --json non modificano il comportamento dell'analisi batch.

La modalità percorso/valore JSON funziona direttamente anche per SecretRef e provider:

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

Flag del generatore di provider

Le destinazioni del generatore di provider devono usare secrets.providers.<alias> come percorso.

Flag comuni
  • --provider-source <env|file|exec>
  • --provider-timeout-ms <ms> (file, exec)
Provider di ambiente (--provider-source env)
  • --provider-allowlist &lt;ENV_VAR&gt; (ripetibile)
Provider di file (--provider-source file)
  • --provider-path <path> (obbligatorio)
  • --provider-mode <singleValue|json>
  • --provider-max-bytes <bytes>
  • --provider-allow-insecure-path
Provider di esecuzione (--provider-source exec)
  • --provider-command <path> (obbligatorio)
  • --provider-arg <arg> (ripetibile)
  • --provider-no-output-timeout-ms <ms>
  • --provider-max-output-bytes <bytes>
  • --provider-json-only
  • --provider-env &lt;KEY=VALUE&gt; (ripetibile)
  • --provider-pass-env &lt;ENV_VAR&gt; (ripetibile)
  • --provider-trusted-dir <path> (ripetibile)
  • --provider-allow-insecure-path
  • --provider-allow-symlink-command

Esempio di provider di esecuzione con protezione avanzata:

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

Incollare o inviare tramite pipe una patch JSON5 con la stessa struttura della configurazione, invece di eseguire molti comandi config set basati sui percorsi. Gli oggetti vengono uniti ricorsivamente; gli array e i valori scalari sostituiscono la destinazione; null elimina il percorso di destinazione.

bash
openclaw config patch --file ./openclaw.patch.json5 --dry-runopenclaw config patch --file ./openclaw.patch.json5

Inviare una patch tramite stdin per gli script di configurazione remota:

bash
ssh user@gateway-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5ssh user@gateway-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

Esempio di patch:

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 } },      },    },  },}

Usare --replace-path <path> quando un oggetto o un array deve diventare esattamente il valore fornito anziché essere modificato ricorsivamente:

bash
openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'

--dry-run esegue i controlli dello schema e della risolvibilità dei SecretRef senza scrivere. Per impostazione predefinita, durante la simulazione i SecretRef basati sull'esecuzione vengono ignorati; aggiungere --allow-exec quando si desidera intenzionalmente che la simulazione esegua i comandi del provider.

Simulazione

--dry-run convalida le modifiche senza scrivere openclaw.json. Disponibile su config set, config patch e 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
Comportamento della simulazione
  • Modalità builder: esegue i controlli di risolvibilità di SecretRef per i riferimenti/provider modificati.
  • Modalità JSON (--strict-json, --json o modalità batch): esegue la convalida dello schema e i controlli di risolvibilità di SecretRef.
  • La convalida dei criteri viene eseguita sull'intera configurazione risultante dalla modifica, quindi le scritture dell'oggetto padre (ad esempio, impostando hooks come oggetto) non possono aggirare la convalida delle superfici non supportate.
  • Per impostazione predefinita, i controlli delle SecretRef exec vengono ignorati per evitare effetti collaterali dei comandi; passare --allow-exec per abilitarli (ciò potrebbe eseguire i comandi del provider). --allow-exec è disponibile solo in modalità simulazione e genera un errore senza --dry-run.
Campi di --dry-run --json
  • ok: indica se la simulazione è riuscita
  • operations: numero di assegnazioni valutate
  • checks: indica se sono stati eseguiti i controlli dello schema/della risolvibilità
  • checks.resolvabilityComplete: indica se i controlli di risolvibilità sono stati completati (false quando i riferimenti exec vengono ignorati)
  • refsChecked: numero di riferimenti effettivamente risolti durante la simulazione
  • skippedExecRefs: numero di riferimenti exec ignorati perché --allow-exec non era impostato
  • errors: errori strutturati relativi a percorsi mancanti, schema o risolvibilità quando ok=false

Struttura dell'output 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, // presente per gli errori di risolvibilità    },  ],}

Esempio di esito positivo

json
{  "ok": true,  "operations": 1,  "configPath": "~/.openclaw/openclaw.json",  "inputModes": ["builder"],  "checks": {    "schema": false,    "resolvability": true,    "resolvabilityComplete": true  },  "refsChecked": 1,  "skippedExecRefs": 0}

Esempio di errore

json
{  "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": "Errore: la variabile di ambiente \"MISSING_TEST_SECRET\" non è impostata.",      "ref": "env:default:MISSING_TEST_SECRET"    }  ]}
Se la simulazione non riesce
  • config schema validation failed: la struttura della configurazione risultante dalla modifica non è valida; correggere il percorso/valore o la struttura dell'oggetto provider/riferimento.
  • Config policy validation failed: unsupported SecretRef usage: riportare la credenziale all'input in testo normale/stringa; mantenere le SecretRef solo sulle superfici supportate.
  • SecretRef assignment(s) could not be resolved: al momento non è possibile risolvere il provider/riferimento specificato (variabile di ambiente mancante, puntatore al file non valido, errore del provider exec o mancata corrispondenza tra provider e origine).
  • Dry run note: skipped <n> exec SecretRef resolvability check(s): eseguire nuovamente con --allow-exec se è necessaria la convalida della risolvibilità exec.
  • Per la modalità batch, correggere le voci non riuscite ed eseguire nuovamente --dry-run prima della scrittura.

Applicazione delle modifiche

Dopo ogni esecuzione riuscita di config set / config patch / config unset, la CLI mostra uno dei tre suggerimenti seguenti per indicare se il Gateway richiede un riavvio:

Suggerimento Significato
Restart the gateway to apply. Il percorso modificato richiede un riavvio completo.
Change will apply without restarting the gateway. Il ricaricamento a caldo lo rileva automaticamente.
No gateway restart needed. Non è cambiato nulla di rilevante per il runtime.

Le scritture in plugins.entries (o in qualsiasi relativo percorso secondario) richiedono sempre un riavvio, poiché la CLI non può verificare che siano caricati i metadati di ricaricamento di ogni plugin.

Sicurezza della scrittura

openclaw config set e gli altri strumenti di scrittura della configurazione gestiti da OpenClaw convalidano l'intera configurazione risultante dalla modifica prima di salvarla su disco. Se il nuovo payload non supera la convalida dello schema o sembra una sovrascrittura distruttiva, la configurazione attiva rimane invariata e il payload rifiutato viene salvato accanto a essa come openclaw.json.rejected.*.

Le scritture gestite da OpenClaw serializzano nuovamente JSON5 come JSON standard. Quando l'origine contiene commenti, lo strumento di scrittura mostra un avviso immediatamente prima di rimuoverli; utilizzare direttamente un editor quando è importante conservarli.

Per le piccole modifiche, preferire le scritture tramite CLI:

bash
openclaw config set gateway.reload.mode hybrid --dry-runopenclaw config set gateway.reload.mode hybridopenclaw config validate

Se una scrittura viene rifiutata, esaminare il payload salvato e correggere l'intera struttura della configurazione:

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

Le scritture dirette tramite editor sono comunque consentite, ma il Gateway in esecuzione le considera non attendibili finché non vengono convalidate. Le modifiche dirette non valide impediscono l'avvio o vengono ignorate dal ricaricamento a caldo; il Gateway non riscrive openclaw.json. Eseguire openclaw doctor --fix per riparare una configurazione con prefisso o sovrascritta oppure per ripristinare l'ultima copia valida nota. Consultare Risoluzione dei problemi del Gateway.

Il ripristino dell'intero file è riservato alla riparazione tramite doctor. Le modifiche allo schema dei plugin o la mancata corrispondenza di minHostVersion continuano a generare errori espliciti anziché ripristinare impostazioni utente non correlate, come modelli, provider, profili di autenticazione, canali, esposizione del gateway, strumenti, memoria, browser o configurazione cron.

Ciclo di riparazione

Dopo il completamento di openclaw config validate, utilizzare la TUI locale per consentire a un agente incorporato di confrontare la configurazione attiva con la documentazione mentre ogni modifica viene convalidata dallo stesso terminale:

bash
openclaw chat

All'interno della TUI, un ! iniziale esegue un comando shell locale letterale (dopo una richiesta di conferma una tantum per sessione):

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

  • Confrontare con la documentazione

    Chiedere all'agente di confrontare la configurazione corrente con la pagina pertinente della documentazione e di suggerire la correzione minima.

  • Applicare modifiche mirate

    Applicare modifiche mirate con openclaw config set o openclaw configure.

  • Convalidare nuovamente

    Eseguire nuovamente openclaw config validate dopo ogni modifica.

  • Usare doctor per i problemi di runtime

    Se la convalida riesce ma il runtime presenta ancora problemi, eseguire openclaw doctor o openclaw doctor --fix per ottenere assistenza con la migrazione e la riparazione.

    • Argomenti correlati

    Was this useful?
    On this page

    On this page