Configurazione

Helper di configurazione per modifiche non interattive in openclaw.json: ottieni/imposta/applica patch/rimuovi/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 di root

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

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 punti o parentesi:

openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id

Usa l'indice dell'elenco degli agenti per puntare a 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 vengono trattati come stringhe. Usa --strict-json per richiedere l'analisi JSON5. --json rimane supportato come alias legacy.

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

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 dell'analisi batch.

# config patch

Usa config patch quando vuoi incollare o passare tramite pipe una patch con forma di configurazione invece di eseguire molti comandi config set basati su percorso. 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 passare una patch su stdin tramite pipe, 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 i comandi provider.

La modalità percorso/valore JSON rimane 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 del 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", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "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 di scrittura

openclaw config set e gli altri writer di configurazione di proprietà di OpenClaw validano l'intera configurazione dopo la modifica prima di salvarla su disco. Se il nuovo payload non supera la validazione dello schema o sembra una sovrascrittura distruttiva, la configurazione attiva resta 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-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 con editor sono ancora consentite, ma il Gateway in esecuzione le tratta come non attendibili finché non vengono validate. Le modifiche dirette non valide fanno fallire l'avvio o vengono saltate dal ricaricamento a caldo; Gateway non riscrive openclaw.json. Esegui openclaw doctor --fix per riparare una configurazione con prefissi o sovrascritta, oppure per ripristinare l'ultima copia valida nota. Consulta risoluzione dei problemi del Gateway.

Il ripristino dell'intero file è riservato alla riparazione tramite doctor. Le modifiche allo schema dei Plugin o lo scostamento di minHostVersion restano evidenti invece di eseguire il rollback di impostazioni utente non correlate come modelli, provider, profili di autenticazione, canali, esposizione del 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 normale, non un symlink.

Riavvia il Gateway dopo le modifiche.

# Validare

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

openclaw config validate
openclaw config validate --json

Dopo che openclaw config validate riesce, puoi usare la TUI locale per far confrontare a un agente integrato la configurazione attiva con la documentazione mentre validi ogni modifica dallo stesso terminale:

openclaw chat

Poi all'interno della TUI:

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

Ciclo di riparazione tipico:

# Correlati

• Riferimento CLI
• Configurazione