Vai al contenuto principale

​
Configurazione

OpenClaw legge una configurazione facoltativa da ~/.openclaw/openclaw.json. Se il file non esiste, OpenClaw usa impostazioni predefinite sicure. Motivi comuni per aggiungere una configurazione:
  • Connettere i canali e controllare chi può inviare messaggi al bot
  • Impostare modelli, strumenti, sandboxing o automazione (cron, hook)
  • Regolare sessioni, media, rete o UI
Consulta il riferimento completo per ogni campo disponibile.
Sei nuovo alla configurazione? Inizia con openclaw onboard per una configurazione interattiva, oppure dai un’occhiata alla guida Esempi di configurazione per configurazioni complete da copiare e incollare.

​
Configurazione minima

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

​
Modifica della configurazione

openclaw onboard       # flusso completo di onboarding
openclaw configure     # procedura guidata di configurazione

​
Validazione rigorosa

OpenClaw accetta solo configurazioni che corrispondono completamente allo schema. Chiavi sconosciute, tipi non validi o valori non validi fanno sì che il Gateway si rifiuti di avviarsi. L’unica eccezione a livello radice è $schema (stringa), così gli editor possono associare i metadati dello schema JSON.
Note sugli strumenti dello schema:
  • openclaw config schema stampa la stessa famiglia di schemi JSON usata da Control UI e dalla validazione della configurazione.
  • Considera l’output di quello schema come il contratto canonico leggibile dalle macchine per openclaw.json; questa panoramica e il riferimento della configurazione lo riassumono.
  • I valori dei campi title e description vengono riportati nell’output dello schema per gli strumenti di editing e dei moduli.
  • Le voci di oggetti annidati, wildcard (*) e elementi di array ([]) ereditano gli stessi metadati di documentazione quando esiste la documentazione del campo corrispondente.
  • Anche i rami di composizione anyOf / oneOf / allOf ereditano gli stessi metadati di documentazione, così le varianti union/intersection mantengono lo stesso aiuto per il campo.
  • config.schema.lookup restituisce un percorso di configurazione normalizzato con un nodo di schema superficiale (title, description, type, enum, const, limiti comuni e campi di validazione simili), i metadati di suggerimento UI corrispondenti e i riepiloghi immediati dei figli per gli strumenti di approfondimento.
  • Gli schemi runtime di plugin/canali vengono uniti quando il gateway può caricare il registro manifest corrente.
  • pnpm config:docs:check rileva disallineamenti tra gli artefatti baseline della configurazione orientati alla documentazione e la superficie di schema corrente.
Quando la validazione fallisce:
  • Il Gateway non si avvia
  • Funzionano solo i comandi diagnostici (openclaw doctor, openclaw logs, openclaw health, openclaw status)
  • Esegui openclaw doctor per vedere i problemi esatti
  • Esegui openclaw doctor --fix (o --yes) per applicare le correzioni

​
Attività comuni

Ogni canale ha una propria sezione di configurazione sotto channels.<provider>. Consulta la pagina dedicata del canale per i passaggi di configurazione:Tutti i canali condividono lo stesso schema per la policy dei messaggi diretti:
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // solo per allowlist/open
    },
  },
}
Imposta il modello primario ed eventuali fallback:
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models definisce il catalogo dei modelli e funge da allowlist per /model.
  • I riferimenti ai modelli usano il formato provider/model (ad esempio anthropic/claude-opus-4-6).
  • agents.defaults.imageMaxDimensionPx controlla il ridimensionamento delle immagini nel transcript/strumenti (predefinito 1200); valori inferiori di solito riducono l’uso di token di visione nelle esecuzioni ricche di screenshot.
  • Consulta Models CLI per cambiare modello in chat e Model Failover per il comportamento di rotazione dell’autenticazione e di fallback.
  • Per provider personalizzati/self-hosted, consulta Provider personalizzati nel riferimento.
L’accesso ai messaggi diretti è controllato per canale tramite dmPolicy:
  • "pairing" (predefinito): i mittenti sconosciuti ricevono un codice di pairing monouso da approvare
  • "allowlist": solo i mittenti in allowFrom (o nell’archivio allow dei paired)
  • "open": consente tutti i messaggi diretti in ingresso (richiede allowFrom: ["*"])
  • "disabled": ignora tutti i messaggi diretti
Per i gruppi, usa groupPolicy + groupAllowFrom o allowlist specifiche del canale.Consulta il riferimento completo per i dettagli per canale.
I messaggi di gruppo richiedono per impostazione predefinita una menzione obbligatoria. Configura i pattern per agente:
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • Menzioni nei metadati: menzioni @ native (@ con tocco su WhatsApp, @bot su Telegram, ecc.)
  • Pattern di testo: pattern regex sicuri in mentionPatterns
  • Consulta il riferimento completo per override per canale e modalità self-chat.
Usa agents.defaults.skills per una baseline condivisa, poi sostituisci agenti specifici con agents.list[].skills:
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // eredita github, weather
      { id: "docs", skills: ["docs-search"] }, // sostituisce i valori predefiniti
      { id: "locked-down", skills: [] }, // nessuna skill
    ],
  },
}
Controlla quanto aggressivamente il gateway riavvia i canali che sembrano inattivi:
{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • Imposta gateway.channelHealthCheckMinutes: 0 per disattivare globalmente i riavvii del monitoraggio dello stato.
  • channelStaleEventThresholdMinutes dovrebbe essere maggiore o uguale all’intervallo di controllo.
  • Usa channels.<provider>.healthMonitor.enabled o channels.<provider>.accounts.<id>.healthMonitor.enabled per disattivare i riavvii automatici per un canale o account senza disattivare il monitor globale.
  • Consulta Controlli dello stato per il debug operativo e il riferimento completo per tutti i campi.
Le sessioni controllano la continuità e l’isolamento delle conversazioni:
{
  session: {
    dmScope: "per-channel-peer",  // consigliato per più utenti
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
  • dmScope: main (condivisa) | per-peer | per-channel-peer | per-account-channel-peer
  • threadBindings: valori predefiniti globali per il routing delle sessioni associate ai thread (Discord supporta /focus, /unfocus, /agents, /session idle e /session max-age).
  • Consulta Gestione delle sessioni per ambito, collegamenti di identità e policy di invio.
  • Consulta il riferimento completo per tutti i campi.
Esegui le sessioni agente in container Docker isolati:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
Crea prima l’immagine: scripts/sandbox-setup.shConsulta Sandboxing per la guida completa e il riferimento completo per tutte le opzioni.
Il push basato su relay si configura in openclaw.json.Imposta questo nella configurazione del gateway:
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Facoltativo. Predefinito: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
Equivalente CLI:
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
Cosa fa:
  • Consente al gateway di inviare push.test, solleciti di riattivazione e riattivazioni di riconnessione tramite il relay esterno.
  • Usa un’autorizzazione di invio limitata alla registrazione inoltrata dall’app iOS associata. Il gateway non ha bisogno di un token relay valido per l’intero deployment.
  • Associa ogni registrazione supportata da relay all’identità del gateway con cui l’app iOS è stata associata, così un altro gateway non può riutilizzare la registrazione memorizzata.
  • Mantiene le build iOS locali/manuali su APNs diretto. Gli invii supportati da relay si applicano solo alle build ufficiali distribuite che si sono registrate tramite il relay.
  • Deve corrispondere al base URL del relay incorporato nella build iOS ufficiale/TestFlight, in modo che il traffico di registrazione e invio raggiunga lo stesso deployment relay.
Flusso end-to-end:
  1. Installa una build iOS ufficiale/TestFlight compilata con lo stesso base URL del relay.
  2. Configura gateway.push.apns.relay.baseUrl sul gateway.
  3. Associa l’app iOS al gateway e consenti la connessione sia della sessione node sia di quella operatore.
  4. L’app iOS recupera l’identità del gateway, si registra presso il relay usando App Attest più la ricevuta dell’app e quindi pubblica il payload push.apns.register supportato da relay nel gateway associato.
  5. Il gateway memorizza l’handle del relay e l’autorizzazione di invio, poi li usa per push.test, i solleciti di riattivazione e le riattivazioni di riconnessione.
Note operative:
  • Se sposti l’app iOS su un gateway diverso, riconnetti l’app in modo che possa pubblicare una nuova registrazione relay associata a quel gateway.
  • Se distribuisci una nuova build iOS che punta a un deployment relay diverso, l’app aggiorna la registrazione relay memorizzata nella cache invece di riutilizzare il vecchio relay di origine.
Nota di compatibilità:
  • OPENCLAW_APNS_RELAY_BASE_URL e OPENCLAW_APNS_RELAY_TIMEOUT_MS funzionano ancora come override temporanei tramite variabili di ambiente.
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true rimane una via di fuga per lo sviluppo solo loopback; non salvare URL relay HTTP nella configurazione.
Consulta App iOS per il flusso end-to-end e Flusso di autenticazione e fiducia per il modello di sicurezza del relay.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: stringa durata (30m, 2h). Imposta 0m per disabilitare.
  • target: last | none | <channel-id> (ad esempio discord, matrix, telegram o whatsapp)
  • directPolicy: allow (predefinito) o block per target heartbeat in stile DM
  • Consulta Heartbeat per la guida completa.
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention: elimina le sessioni isolate completate da sessions.json (predefinito 24h; imposta false per disabilitare).
  • runLog: pota cron/runs/<jobId>.jsonl per dimensione e righe mantenute.
  • Consulta Job cron per la panoramica della funzionalità e gli esempi CLI.
Abilita endpoint webhook HTTP sul Gateway:
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
Nota di sicurezza:
  • Tratta tutto il contenuto dei payload hook/webhook come input non attendibile.
  • Usa un hooks.token dedicato; non riutilizzare il token Gateway condiviso.
  • L’autenticazione degli hook è solo via header (Authorization: Bearer ... o x-openclaw-token); i token nella query string vengono rifiutati.
  • hooks.path non può essere /; mantieni l’ingresso dei webhook su un sottopercorso dedicato come /hooks.
  • Mantieni disattivati i flag di bypass per contenuti non sicuri (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) a meno che tu non stia facendo debug strettamente circoscritto.
  • Se abiliti hooks.allowRequestSessionKey, imposta anche hooks.allowedSessionKeyPrefixes per limitare le chiavi di sessione selezionate dal chiamante.
  • Per agenti guidati da hook, preferisci livelli di modello moderni e robusti e una policy degli strumenti rigorosa (ad esempio solo messaggistica più sandboxing dove possibile).
Consulta il riferimento completo per tutte le opzioni di mapping e l’integrazione Gmail.
Esegui più agenti isolati con workspace e sessioni separati:
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}
Consulta Multi-Agent e il riferimento completo per le regole di binding e i profili di accesso per agente.
Usa $include per organizzare configurazioni di grandi dimensioni:
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • File singolo: sostituisce l’oggetto che lo contiene
  • Array di file: unione profonda in ordine (quello successivo prevale)
  • Chiavi sibling: unite dopo gli include (sovrascrivono i valori inclusi)
  • Include annidati: supportati fino a 10 livelli di profondità
  • Percorsi relativi: risolti rispetto al file che include
  • Gestione errori: errori chiari per file mancanti, errori di parsing e include circolari

​
Ricaricamento a caldo della configurazione

Il Gateway monitora ~/.openclaw/openclaw.json e applica automaticamente le modifiche — per la maggior parte delle impostazioni non è necessario alcun riavvio manuale.

​
Modalità di ricaricamento

ModalitàComportamento
hybrid (predefinita)Applica a caldo istantaneamente le modifiche sicure. Riavvia automaticamente per quelle critiche.
hotApplica a caldo solo le modifiche sicure. Registra un avviso quando serve un riavvio — lo gestisci tu.
restartRiavvia il Gateway a ogni modifica della configurazione, sicura o meno.
offDisabilita il monitoraggio del file. Le modifiche hanno effetto al successivo riavvio manuale.
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
Cosa viene applicato a caldo e cosa richiede un riavvio

La maggior parte dei campi viene applicata a caldo senza downtime. In modalità hybrid, le modifiche che richiedono un riavvio vengono gestite automaticamente.
CategoriaCampiRiavvio necessario?
Canalichannels.*, web (WhatsApp) — tutti i canali integrati e di estensioneNo
Agente e modelliagent, agents, models, routingNo
Automazionehooks, cron, agent.heartbeatNo
Sessioni e messaggisession, messagesNo
Strumenti e mediatools, browser, skills, audio, talkNo
UI e varieui, logging, identity, bindingsNo
Server gatewaygateway.* (porta, bind, auth, tailscale, TLS, HTTP)Sì
Infrastrutturadiscovery, canvasHost, pluginsSì
gateway.reload e gateway.remote sono eccezioni: modificarli non attiva un riavvio.

​
Config RPC (aggiornamenti programmatici)

Le RPC di scrittura del control plane (config.apply, config.patch, update.run) sono soggette a rate limit di 3 richieste ogni 60 secondi per deviceId+clientIp. Quando viene applicato il limite, la RPC restituisce UNAVAILABLE con retryAfterMs.
Flusso sicuro/predefinito:
  • config.schema.lookup: ispeziona un sottoalbero di configurazione limitato a un percorso con un nodo di schema superficiale, metadati di suggerimento corrispondenti e riepiloghi immediati dei figli
  • config.get: recupera lo snapshot corrente + hash
  • config.patch: percorso di aggiornamento parziale preferito
  • config.apply: solo sostituzione completa della configurazione
  • update.run: autoaggiornamento esplicito + riavvio
Quando non stai sostituendo l’intera configurazione, preferisci config.schema.lookup e poi config.patch.
Valida + scrive l’intera configurazione e riavvia il Gateway in un unico passaggio.
config.apply sostituisce l’intera configurazione. Usa config.patch per aggiornamenti parziali, oppure openclaw config set per singole chiavi.
Parametri:
  • raw (stringa) — payload JSON5 per l’intera configurazione
  • baseHash (facoltativo) — hash della configurazione da config.get (obbligatorio quando la configurazione esiste)
  • sessionKey (facoltativo) — chiave di sessione per il ping di riattivazione dopo il riavvio
  • note (facoltativo) — nota per il sentinel di riavvio
  • restartDelayMs (facoltativo) — ritardo prima del riavvio (predefinito 2000)
Le richieste di riavvio vengono accorpate mentre una è già in attesa/in corso, e tra i cicli di riavvio si applica un cooldown di 30 secondi.
openclaw gateway call config.get --params '{}'  # acquisisci payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:direct:+15555550123"
}'
Unisce un aggiornamento parziale alla configurazione esistente (semantica JSON merge patch):
  • Gli oggetti vengono uniti ricorsivamente
  • null elimina una chiave
  • Gli array vengono sostituiti
Parametri:
  • raw (stringa) — JSON5 con solo le chiavi da modificare
  • baseHash (obbligatorio) — hash della configurazione da config.get
  • sessionKey, note, restartDelayMs — come in config.apply
Il comportamento di riavvio corrisponde a config.apply: riavvii in attesa accorpati più un cooldown di 30 secondi tra i cicli di riavvio.
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

​
Variabili di ambiente

OpenClaw legge le variabili di ambiente dal processo padre più:
  • .env dalla directory di lavoro corrente (se presente)
  • ~/.openclaw/.env (fallback globale)
Nessuno dei due file sovrascrive le variabili di ambiente esistenti. Puoi anche impostare variabili di ambiente inline nella configurazione: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Se abilitata e le chiavi previste non sono impostate, OpenClaw esegue la tua shell di login e importa solo le chiavi mancanti:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Equivalente come variabile di ambiente: OPENCLAW_LOAD_SHELL_ENV=1
Fai riferimento alle variabili di ambiente in qualsiasi valore stringa della configurazione con ${VAR_NAME}:
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
Regole:
  • Vengono riconosciuti solo nomi in maiuscolo corrispondenti a: [A-Z_][A-Z0-9_]*
  • Variabili mancanti/vuote generano un errore al momento del caricamento
  • Usa l’escape $${VAR} per un output letterale
  • Funziona all’interno dei file $include
  • Sostituzione inline: "${BASE}/v1" → "https://api.example.com/v1"
Per i campi che supportano oggetti SecretRef, puoi usare:
{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}
I dettagli di SecretRef (inclusi secrets.providers per env/file/exec) sono disponibili in Gestione dei segreti. I percorsi delle credenziali supportati sono elencati in Superficie delle credenziali SecretRef.
Consulta Ambiente per la precedenza completa e le origini.

​
Riferimento completo

Per il riferimento completo campo per campo, consulta Riferimento della configurazione.
Correlati: Esempi di configurazione · Riferimento della configurazione · Doctor