OpenClaw legge una configurazione opzionale daDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
~/.openclaw/openclaw.json.
Il percorso della configurazione attiva deve essere un file regolare. I layout
openclaw.json con symlink non sono supportati per le scritture gestite da OpenClaw;
una scrittura atomica può sostituire il percorso invece di preservare il symlink.
Se mantieni la configurazione fuori dalla directory di stato predefinita, punta
OPENCLAW_CONFIG_PATH direttamente al file reale.
Se il file manca, OpenClaw usa valori predefiniti sicuri. Motivi comuni per aggiungere una configurazione:
- Collegare canali e controllare chi può inviare messaggi al bot
- Impostare modelli, strumenti, sandboxing o automazione (cron, hook)
- Regolare sessioni, media, networking o UI
config.schema.lookup per la documentazione
esatta a livello di campo prima di modificare la configurazione. Usa questa pagina
per indicazioni orientate alle attività e Riferimento configurazione
per la mappa più ampia dei campi e dei valori predefiniti.
Configurazione minima
Modifica della configurazione
- Procedura guidata interattiva
- CLI (comandi rapidi)
- UI di controllo
- Modifica diretta
Validazione rigorosa
openclaw config schema stampa lo JSON Schema canonico usato dalla UI di controllo
e dalla validazione. config.schema.lookup recupera un singolo nodo circoscritto
a un percorso più i riepiloghi dei figli per strumenti di approfondimento. I metadati
di documentazione dei campi title/description vengono propagati attraverso
oggetti annidati, wildcard (*), elementi di array ([]) e rami anyOf/
oneOf/allOf. Gli schemi runtime di plugin e canali vengono uniti quando il
registro dei manifest viene caricato.
Quando la validazione fallisce:
- Il Gateway non si avvia
- Funzionano solo i comandi diagnostici (
openclaw doctor,openclaw logs,openclaw health,openclaw status) - Esegui
openclaw doctorper vedere i problemi esatti - Esegui
openclaw doctor --fix(o--yes) per applicare le riparazioni
openclaw.json non supera la validazione (inclusa la validazione
locale del plugin), l’avvio del Gateway fallisce oppure il ricaricamento viene
saltato e il runtime corrente mantiene l’ultima configurazione accettata.
Esegui openclaw doctor --fix (o --yes) per riparare una configurazione con
prefissi/sovrascritta o ripristinare la copia dell’ultima configurazione valida.
La promozione a ultima configurazione valida viene saltata quando un candidato
contiene segnaposto di segreti redatti come ***.
Attività comuni
Configurare un canale (WhatsApp, Telegram, Discord, ecc.)
Configurare un canale (WhatsApp, Telegram, Discord, ecc.)
channels.<provider>. Vedi la pagina dedicata del canale per i passaggi di configurazione:- WhatsApp -
channels.whatsapp - Telegram -
channels.telegram - Discord -
channels.discord - Feishu -
channels.feishu - Google Chat -
channels.googlechat - Microsoft Teams -
channels.msteams - Slack -
channels.slack - Signal -
channels.signal - iMessage -
channels.imessage - Mattermost -
channels.mattermost
Scegliere e configurare i modelli
Scegliere e configurare i modelli
agents.defaults.modelsdefinisce il catalogo dei modelli e funge da allowlist per/model; le vociprovider/*filtrano/model,/modelse i selettori di modello ai provider selezionati pur continuando a usare la scoperta dinamica dei modelli.- Usa
openclaw config set agents.defaults.models '<json>' --strict-json --mergeper aggiungere voci alla allowlist senza rimuovere i modelli esistenti. Le sostituzioni semplici che rimuoverebbero voci vengono rifiutate a meno che tu non passi--replace. - I riferimenti ai modelli usano il formato
provider/model(ad es.anthropic/claude-opus-4-6). agents.defaults.imageMaxDimensionPxcontrolla il ridimensionamento delle immagini di transcript/strumenti (predefinito1200); valori più bassi di solito riducono l’uso di token vision nelle esecuzioni ricche di screenshot.- Vedi CLI modelli per cambiare modello nella chat e Failover modello per la rotazione dell’autenticazione e il comportamento di fallback.
- Per provider personalizzati/self-hosted, vedi Provider personalizzati nel riferimento.
Controllare chi può inviare messaggi al bot
Controllare chi può inviare messaggi al bot
dmPolicy:"pairing"(predefinito): i mittenti sconosciuti ricevono un codice di pairing monouso da approvare"allowlist": solo mittenti inallowFrom(o nello store degli abbinamenti consentiti)"open": consente tutti i DM in ingresso (richiedeallowFrom: ["*"])"disabled": ignora tutti i DM
groupPolicy + groupAllowFrom oppure allowlist specifiche del canale.Vedi il riferimento completo per i dettagli per canale.Configurare il gating delle menzioni nelle chat di gruppo
Configurare il gating delle menzioni nelle chat di gruppo
- Menzioni nei metadati: @-menzioni native (WhatsApp tap-to-mention, Telegram @bot, ecc.)
- Pattern di testo: pattern regex sicuri in
mentionPatterns - Risposte visibili:
messages.visibleRepliespuò richiedere globalmente gli invii tramite strumento messaggi;messages.groupChat.visibleReplieslo sovrascrive per gruppi/canali. - Vedi il riferimento completo per le modalità di risposta visibile, le sovrascritture per canale e la modalità self-chat.
Limitare le Skills per agente
Limitare le Skills per agente
agents.defaults.skills per una baseline condivisa, quindi sovrascrivi
agenti specifici con agents.list[].skills:- Ometti
agents.defaults.skillsper Skills senza restrizioni per impostazione predefinita. - Ometti
agents.list[].skillsper ereditare i valori predefiniti. - Imposta
agents.list[].skills: []per nessuna Skills. - Vedi Skills, Configurazione Skills e il Riferimento configurazione.
Regolare il monitoraggio dello stato dei canali del gateway
Regolare il monitoraggio dello stato dei canali del gateway
- Imposta
gateway.channelHealthCheckMinutes: 0per disabilitare globalmente i riavvii del monitoraggio dello stato. channelStaleEventThresholdMinutesdovrebbe essere maggiore o uguale all’intervallo di controllo.- Usa
channels.<provider>.healthMonitor.enabledochannels.<provider>.accounts.<id>.healthMonitor.enabledper disabilitare i riavvii automatici per un canale o un account senza disabilitare il monitor globale. - Vedi Controlli di stato per il debug operativo e il riferimento completo per tutti i campi.
Regolare il timeout dell'handshake WebSocket del gateway
Regolare il timeout dell'handshake WebSocket del gateway
- Il valore predefinito è
15000millisecondi. OPENCLAW_HANDSHAKE_TIMEOUT_MScontinua ad avere la precedenza per sovrascritture una tantum di servizio o shell.- Preferisci prima correggere stalli di avvio/event loop; questa manopola è per host sani ma lenti durante il warmup.
Configurare sessioni e reset
Configurare sessioni e reset
dmScope:main(condiviso) |per-peer|per-channel-peer|per-account-channel-peerthreadBindings: valori predefiniti globali per l’instradamento delle sessioni vincolate al thread (Discord supporta/focus,/unfocus,/agents,/session idlee/session max-age).- Vedi Gestione delle sessioni per ambito, collegamenti di identità e criterio di invio.
- Vedi riferimento completo per tutti i campi.
Abilita il sandboxing
Abilita il sandboxing
scripts/sandbox-setup.sh, oppure da un’installazione npm vedi il comando inline docker build in Sandboxing § Immagini e configurazione.Vedi Sandboxing per la guida completa e riferimento completo per tutte le opzioni.Abilita le push supportate da relay per le build iOS ufficiali
Abilita le push supportate da relay per le build iOS ufficiali
openclaw.json.Imposta questo nella configurazione del gateway:- Consente al gateway di inviare
push.test, solleciti di riattivazione e riattivazioni di riconnessione tramite il relay esterno. - Usa una concessione di invio con ambito di registrazione inoltrata dall’app iOS associata. Il gateway non ha bisogno di un token relay valido per tutta la distribuzione.
- Vincola 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 archiviata.
- Mantiene le build iOS locali/manuali su APNs diretto. Gli invii supportati da relay si applicano solo alle build distribuite ufficiali registrate tramite il relay.
- Deve corrispondere all’URL di base del relay incorporato nella build iOS ufficiale/TestFlight, così il traffico di registrazione e invio raggiunge la stessa distribuzione relay.
- Installa una build iOS ufficiale/TestFlight compilata con lo stesso URL di base del relay.
- Configura
gateway.push.apns.relay.baseUrlsul gateway. - Associa l’app iOS al gateway e lascia che sia le sessioni node sia quelle operatore si connettano.
- L’app iOS recupera l’identità del gateway, si registra con il relay usando App Attest più la ricevuta dell’app, quindi pubblica il payload
push.apns.registersupportato da relay sul gateway associato. - Il gateway archivia l’handle relay e la concessione di invio, quindi li usa per
push.test, solleciti di riattivazione e riattivazioni di riconnessione.
- Se passi l’app iOS a un gateway diverso, riconnetti l’app così può pubblicare una nuova registrazione relay vincolata a quel gateway.
- Se distribuisci una nuova build iOS che punta a una distribuzione relay diversa, l’app aggiorna la propria registrazione relay memorizzata nella cache invece di riutilizzare la vecchia origine relay.
OPENCLAW_APNS_RELAY_BASE_URLeOPENCLAW_APNS_RELAY_TIMEOUT_MSfunzionano ancora come override temporanei tramite env.OPENCLAW_APNS_RELAY_ALLOW_HTTP=truerimane una via di fuga di sviluppo solo per local loopback; non rendere persistenti URL relay HTTP nella configurazione.
Configura Heartbeat (check-in periodici)
Configura Heartbeat (check-in periodici)
every: stringa di durata (30m,2h). Imposta0mper disabilitare.target:last|none|<channel-id>(ad esempiodiscord,matrix,telegramowhatsapp)directPolicy:allow(predefinito) oblockper destinazioni Heartbeat in stile DM- Vedi Heartbeat per la guida completa.
Configura processi cron
Configura processi cron
sessionRetention: elimina le sessioni di esecuzione isolate completate dasessions.json(predefinito24h; impostafalseper disabilitare).runLog: eliminacron/runs/<jobId>.jsonlin base a dimensione e righe conservate.- Vedi Processi Cron per una panoramica della funzionalità ed esempi CLI.
Configura webhook (hook)
Configura webhook (hook)
- Tratta tutto il contenuto dei payload hook/webhook come input non attendibile.
- Usa un
hooks.tokendedicato; non riutilizzare il token Gateway condiviso. - L’autenticazione degli hook è solo tramite header (
Authorization: Bearer ...ox-openclaw-token); i token nella query string vengono rifiutati. hooks.pathnon può essere/; mantieni l’ingresso webhook su un sottopercorso dedicato come/hooks.- Mantieni disabilitati i flag di bypass per contenuti non sicuri (
hooks.gmail.allowUnsafeExternalContent,hooks.mappings[].allowUnsafeExternalContent) salvo per debug strettamente delimitato. - Se abiliti
hooks.allowRequestSessionKey, imposta anchehooks.allowedSessionKeyPrefixesper limitare le chiavi di sessione selezionate dal chiamante. - Per agenti guidati da hook, preferisci tier di modelli moderni e robusti e un criterio strumenti rigoroso (ad esempio solo messaggistica più sandboxing dove possibile).
Configura l'instradamento multi-agente
Configura l'instradamento multi-agente
Dividi la configurazione in più file ($include)
Dividi la configurazione in più file ($include)
$include per organizzare configurazioni di grandi dimensioni:- File singolo: sostituisce l’oggetto contenitore
- Array di file: merge profondo in ordine (l’ultimo prevale)
- Chiavi sorelle: 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
- Scritture di proprietà di OpenClaw: quando una scrittura modifica solo una sezione di primo livello
supportata da un include a file singolo come
plugins: { $include: "./plugins.json5" }, OpenClaw aggiorna quel file incluso e lascia intattoopenclaw.json - Write-through non supportato: include root, array di include e include con override di chiavi sorelle falliscono in modo chiuso per le scritture di proprietà di OpenClaw invece di appiattire la configurazione
- Confinamento: i percorsi
$includedevono risolversi sotto la directory che contieneopenclaw.json. Per condividere un albero tra macchine o utenti, impostaOPENCLAW_INCLUDE_ROOTSsu un elenco di percorsi (:su POSIX,;su Windows) di directory aggiuntive a cui gli include possono fare riferimento. I symlink vengono risolti e ricontrollati, quindi un percorso che lessicalmente si trova in una directory di configurazione ma il cui target reale esce da ogni root consentita viene comunque rifiutato. - Gestione degli 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 le modifiche automaticamente: per la maggior parte delle impostazioni non è necessario alcun riavvio manuale.
Le modifiche dirette ai file sono trattate come non attendibili finché non vengono validate. Il watcher attende
che il churn di scrittura temporanea/rinomina dell’editor si stabilizzi, legge il file finale e rifiuta
modifiche esterne non valide senza riscrivere openclaw.json. Le scritture di configurazione di proprietà di OpenClaw
usano lo stesso gate di schema prima della scrittura; sovrascritture distruttive come
la rimozione di gateway.mode o la riduzione del file di oltre la metà vengono rifiutate e
salvate come .rejected.* per l’ispezione.
Se vedi config reload skipped (invalid config) o l’avvio segnala Invalid config, ispeziona la configurazione, esegui openclaw config validate, quindi esegui openclaw doctor --fix per la riparazione. Vedi Risoluzione dei problemi del Gateway
per la checklist.
Modalità di ricaricamento
| Modalità | Comportamento |
|---|---|
hybrid (predefinita) | Applica a caldo istantaneamente le modifiche sicure. Riavvia automaticamente per quelle critiche. |
hot | Applica a caldo solo le modifiche sicure. Registra un avviso quando è necessario un riavvio: lo gestisci tu. |
restart | Riavvia il Gateway a ogni modifica della configurazione, sicura o meno. |
off | Disabilita il monitoraggio dei file. Le modifiche hanno effetto al successivo riavvio manuale. |
Cosa si applica a caldo e cosa richiede un riavvio
La maggior parte dei campi si applica a caldo senza downtime. In modalitàhybrid, le modifiche che richiedono riavvio vengono gestite automaticamente.
| Categoria | Campi | Riavvio necessario? |
|---|---|---|
| Canali | channels.*, web (WhatsApp) - tutti i canali integrati e Plugin | No |
| Agente e modelli | agent, agents, models, routing | No |
| Automazione | hooks, cron, agent.heartbeat | No |
| Sessioni e messaggi | session, messages | No |
| Strumenti e media | tools, browser, skills, mcp, audio, talk | No |
| UI e varie | ui, logging, identity, bindings | No |
| Server Gateway | gateway.* (port, bind, auth, tailscale, TLS, HTTP) | Sì |
| Infrastruttura | discovery, plugins | Sì |
gateway.reload e gateway.remote sono eccezioni: modificarli non attiva un riavvio.Pianificazione del ricaricamento
Quando modifichi un file sorgente a cui si fa riferimento tramite$include, OpenClaw pianifica
il ricaricamento dal layout scritto nel sorgente, non dalla vista in memoria appiattita.
Questo mantiene prevedibili le decisioni di hot-reload (applicazione a caldo vs riavvio) anche quando una
singola sezione di primo livello vive nel proprio file incluso, come
plugins: { $include: "./plugins.json5" }. La pianificazione del ricaricamento fallisce in modo chiuso se il
layout sorgente è ambiguo.
Config RPC (aggiornamenti programmatici)
Per gli strumenti che scrivono la configurazione tramite l’API Gateway, preferisci questo flusso:config.schema.lookupper ispezionare un sottoalbero (nodo schema superficiale + riepiloghi dei figli)config.getper recuperare lo snapshot corrente piùhashconfig.patchper aggiornamenti parziali (patch di unione JSON: gli oggetti si uniscono,nullelimina, gli array sostituiscono)config.applysolo quando intendi sostituire l’intera configurazioneupdate.runper self-update esplicito più riavvio; includicontinuationMessagequando la sessione post-riavvio deve eseguire un turno di follow-upupdate.statusper ispezionare l’ultimo sentinel di riavvio dell’aggiornamento e verificare la versione in esecuzione dopo un riavvio
config.schema.lookup come il primo punto di riferimento per la documentazione e i vincoli esatti
a livello di campo. Usa Riferimento di configurazione
quando serve la mappa di configurazione più ampia, i valori predefiniti o i link ai riferimenti dedicati
dei sottosistemi.
config.apply, config.patch, update.run) sono
limitate a 3 richieste ogni 60 secondi per deviceId+clientIp. Le richieste di riavvio
si aggregano e poi applicano un cooldown di 30 secondi tra i cicli di riavvio.
update.status è di sola lettura ma con ambito amministratore perché il sentinel di riavvio può
includere riepiloghi dei passaggi di aggiornamento e code dell’output dei comandi.config.apply sia config.patch accettano raw, baseHash, sessionKey,
note e restartDelayMs. baseHash è richiesto per entrambi i metodi quando una
configurazione esiste già.
Variabili d’ambiente
OpenClaw legge le variabili d’ambiente dal processo padre più:.envdalla directory di lavoro corrente (se presente)~/.openclaw/.env(fallback globale)
Importazione dell'ambiente shell (facoltativa)
Importazione dell'ambiente shell (facoltativa)
OPENCLAW_LOAD_SHELL_ENV=1Sostituzione di variabili d'ambiente nei valori di configurazione
Sostituzione di variabili d'ambiente nei valori di configurazione
${VAR_NAME}:- Solo nomi maiuscoli corrispondenti:
[A-Z_][A-Z0-9_]* - Le variabili mancanti/vuote generano un errore al momento del caricamento
- Esegui l’escape con
$${VAR}per l’output letterale - Funziona dentro i file
$include - Sostituzione inline:
"${BASE}/v1"→"https://api.example.com/v1"
Riferimenti segreti (env, file, exec)
Riferimenti segreti (env, file, exec)
secrets.providers per env/file/exec) sono in Gestione dei segreti.
I percorsi delle credenziali supportati sono elencati in Superficie delle credenziali SecretRef.Riferimento completo
Per il riferimento completo campo per campo, vedi Riferimento di configurazione.Correlati: Esempi di configurazione · Riferimento di configurazione · Doctor