Vai al contenuto principale

​
Configurazione

OpenClaw legge una configurazione facoltativa in da ~/.openclaw/openclaw.json. Se il file manca, 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)
  • Ottimizzare sessioni, media, rete o UI
Consulta il riferimento completo per ogni campo disponibile.
Sei nuovo alla configurazione? Inizia con openclaw onboard per la configurazione interattiva, oppure consulta la 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"] } },
}

​
Modificare la 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 root è $schema (stringa), così gli editor possono collegare metadati JSON Schema.
Note sugli strumenti di schema:
  • openclaw config schema stampa la stessa famiglia di JSON Schema usata dalla UI di controllo e dalla validazione della configurazione.
  • I valori title e description dei campi vengono riportati nell’output dello schema per editor e strumenti per moduli.
  • Le voci di oggetti annidati, wildcard (*) e elementi di array ([]) ereditano gli stessi metadati di documentazione dove esiste documentazione di 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 i campi.
  • 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), metadati di suggerimento UI corrispondenti e riepiloghi dei figli immediati per strumenti di analisi dettagliata.
  • Gli schemi runtime di plugin/canale vengono uniti quando il gateway riesce a caricare il registro manifest 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 riparazioni

​
Attività comuni

Ogni canale ha la propria sezione di configurazione sotto channels.<provider>. Consulta la pagina dedicata al canale per i passaggi di configurazione:Tutti i canali condividono lo stesso pattern di policy DM:
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // solo per allowlist/open
    },
  },
}
Imposta il modello principale e gli 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 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 in trascrizione/strumenti (predefinito 1200); valori inferiori in genere riducono l’uso di token vision nelle esecuzioni ricche di screenshot.
  • Vedi Models CLI per cambiare modello in chat e Model Failover per il comportamento di rotazione auth e fallback.
  • Per provider personalizzati/self-hosted, vedi Provider personalizzati nel riferimento.
L’accesso DM è controllato per canale tramite dmPolicy:
  • "pairing" (predefinito): i mittenti sconosciuti ricevono un codice pairing monouso da approvare
  • "allowlist": solo i mittenti in allowFrom (o nello store paired allow)
  • "open": consente tutti i DM in ingresso (richiede allowFrom: ["*"])
  • "disabled": ignora tutti i DM
Per i gruppi, usa groupPolicy + groupAllowFrom o allowlist specifiche del canale.Consulta il riferimento completo per i dettagli per canale.
I messaggi di gruppo per impostazione predefinita richiedono una menzione. Configura i pattern per agente:
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • Menzioni nei metadati: @-mention native (tap-to-mention di WhatsApp, @bot di 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, quindi fai override di agenti specifici con agents.list[].skills:
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // eredita github, weather
      { id: "docs", skills: ["docs-search"] }, // sostituisce i default
      { id: "locked-down", skills: [] }, // nessuna Skills
    ],
  },
}
  • Ometti agents.defaults.skills per avere Skills senza restrizioni per impostazione predefinita.
  • Ometti agents.list[].skills per ereditare i valori predefiniti.
  • Imposta agents.list[].skills: [] per nessuna Skills.
  • Consulta Skills, Config Skills e il Riferimento configurazione.
Controlla quanto aggressivamente il gateway riavvia i canali che sembrano obsoleti:
{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • Imposta gateway.channelHealthCheckMinutes: 0 per disabilitare 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 disabilitare i riavvii automatici per un canale o account senza disabilitare il monitor globale.
  • Consulta Health Checks per il debug operativo e il riferimento completo per tutti i campi.
Le sessioni controllano continuità e isolamento della conversazione:
{
  session: {
    dmScope: "per-channel-peer",  // consigliato per multiutente
    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 l’instradamento 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
      },
    },
  },
}
Costruisci prima l’immagine: scripts/sandbox-setup.shConsulta Sandboxing per la guida completa e il riferimento completo per tutte le opzioni.
Il push supportato da relay si configura in openclaw.json.Imposta questo nella configurazione 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, wake nudges e wake di riconnessione tramite il relay esterno.
  • Usa un permesso di invio limitato alla registrazione inoltrato dall’app iOS paired. Il gateway non ha bisogno di un token relay valido per tutta la distribuzione.
  • Associa ogni registrazione supportata da relay all’identità del gateway con cui l’app iOS ha effettuato il pairing, così un altro gateway non può riutilizzare la registrazione memorizzata.
  • Mantiene le build iOS locali/manuali su APNs diretti. 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, così il traffico di registrazione e invio raggiunge la stessa distribuzione 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. Esegui il pairing dell’app iOS con il gateway e lascia che si connettano sia le sessioni node sia quelle operator.
  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 sul gateway paired.
  5. Il gateway memorizza l’handle relay e il permesso di invio, poi li usa per push.test, wake nudges e wake di riconnessione.
Note operative:
  • Se sposti l’app iOS su un gateway diverso, ricollega l’app così potrà pubblicare una nuova registrazione relay associata a quel gateway.
  • Se distribuisci una nuova build iOS che punta a una distribuzione relay diversa, l’app aggiorna la registrazione relay memorizzata invece di riutilizzare la vecchia origine relay.
Nota di compatibilità:
  • OPENCLAW_APNS_RELAY_BASE_URL e OPENCLAW_APNS_RELAY_TIMEOUT_MS funzionano ancora come override temporanei via env.
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true rimane una via di fuga di sviluppo solo loopback; non mantenere URL relay HTTP nella configurazione.
Consulta App iOS per il flusso end-to-end e Flusso di autenticazione e attendibilità per il modello di sicurezza del relay.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every: stringa di durata (30m, 2h). Imposta 0m per disabilitare.
  • target: last | none | <channel-id> (ad esempio discord, matrix, telegram o whatsapp)
  • directPolicy: allow (predefinito) oppure 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 in base a dimensione e righe mantenute.
  • Consulta Cron jobs 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 condiviso del Gateway.
  • L’autenticazione hook è solo header (Authorization: Bearer ... o x-openclaw-token); i token nella query string vengono rifiutati.
  • hooks.path non può essere /; mantieni l’ingresso webhook su un sottopercorso dedicato come /hooks.
  • Mantieni disabilitati i flag di bypass per contenuto non sicuro (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) a meno che tu non stia facendo debug molto mirato.
  • Se abiliti hooks.allowRequestSessionKey, imposta anche hooks.allowedSessionKeyPrefixes per limitare le chiavi di sessione selezionabili dal chiamante.
  • Per agenti guidati da hook, preferisci livelli di modello moderni e forti e una policy 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 separate:
{
  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 regole di binding e profili di accesso per agente.
Usa $include per organizzare configurazioni grandi:
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • File singolo: sostituisce l’oggetto contenitore
  • Array di file: deep-merge in ordine (l’ultimo vince)
  • Chiavi sibling: unite dopo gli include (sovrascrivono i valori inclusi)
  • Include annidati: supportati fino a 10 livelli di profondità
  • Percorsi relativi: risolti relativamente al file che include
  • Gestione errori: errori chiari per file mancanti, errori di parsing e include circolari

​
Hot reload della configurazione

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

​
Modalità di ricarica

ModalitàComportamento
hybrid (predefinita)Applica a caldo immediatamente le modifiche sicure. Si riavvia automaticamente per quelle critiche.
hotApplica a caldo solo le modifiche sicure. Registra un avviso quando è necessario un riavvio — lo gestisci tu.
restartRiavvia il Gateway a ogni modifica della configurazione, sicura o meno.
offDisabilita l’osservazione 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 built-in ed extensionNo
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.

​
RPC di configurazione (aggiornamenti programmatici)

Le RPC di scrittura del control-plane (config.apply, config.patch, update.run) hanno un rate limit di 3 richieste per 60 secondi per deviceId+clientIp. Quando il limite viene raggiunto, 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 dei figli immediati
  • config.get: recupera l’istantanea corrente + hash
  • config.patch: percorso preferito per aggiornamenti parziali
  • config.apply: sostituzione completa della configurazione solo
  • update.run: auto-aggiornamento esplicito + riavvio
Quando non stai sostituendo l’intera configurazione, preferisci config.schema.lookup 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 di configurazione da config.get (obbligatorio quando la configurazione esiste)
  • sessionKey (facoltativo) — chiave di sessione per il ping di wake-up post-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 si applica un cooldown di 30 secondi tra i cicli di riavvio.
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 sostituiscono
Parametri:
  • raw (stringa) — JSON5 con solo le chiavi da modificare
  • baseHash (obbligatorio) — hash di configurazione da config.get
  • sessionKey, note, restartDelayMs — uguali a 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 d’ambiente

OpenClaw legge le variabili d’ambiente dal processo padre più:
  • .env dalla directory di lavoro corrente (se presente)
  • ~/.openclaw/.env (fallback globale)
Nessuno dei due file sovrascrive le variabili d’ambiente esistenti. Puoi anche impostare variabili d’ambiente inline nella configurazione: 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
Se abilitato e le chiavi previste non sono impostate, OpenClaw esegue la shell di login e importa solo le chiavi mancanti:
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
Equivalente come variabile d’ambiente: OPENCLAW_LOAD_SHELL_ENV=1
Fai riferimento alle variabili d’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 maiuscoli corrispondenti a: [A-Z_][A-Z0-9_]*
  • Variabili mancanti/vuote generano un errore al caricamento
  • Esegui l’escape con $${VAR} per output letterale
  • Funziona nei 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 su SecretRef (inclusi secrets.providers per env/file/exec) sono in Gestione dei secret. I percorsi credenziali supportati sono elencati in Superficie credenziali SecretRef.
Consulta Ambiente per la precedenza completa e le sorgenti.

​
Riferimento completo

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