Configurazione

Ogni canale dispone della propria sezione di configurazione in channels.<provider>. Consultare la pagina dedicata al canale per i passaggi di configurazione:

• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• iMessage - channels.imessage
• Mattermost - channels.mattermost
• Microsoft Teams - channels.msteams
• Signal - channels.signal
• Slack - channels.slack
• Telegram - channels.telegram
• WhatsApp - channels.whatsapp

Tutti i canali condividono lo stesso modello di criteri per i messaggi diretti:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // solo per allowlist/open    },  },}

Impostare il modello principale e i fallback facoltativi:

{  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 elenco consentito per /model; le voci provider/* filtrano /model, /models e i selettori dei modelli limitandoli ai provider selezionati, pur continuando a utilizzare il rilevamento dinamico dei modelli.
• Utilizzare openclaw config set agents.defaults.models '<json>' --strict-json --merge per aggiungere voci all'elenco consentito senza rimuovere i modelli esistenti. Le sostituzioni semplici che rimuoverebbero delle voci vengono rifiutate, a meno che non venga passato --replace.
• I riferimenti ai modelli utilizzano il formato provider/model (ad esempio anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx controlla il ridimensionamento verso il basso delle immagini di trascrizioni e strumenti (valore predefinito 1200); valori inferiori riducono generalmente l'utilizzo di token visivi nelle esecuzioni con molte schermate.
• Consultare CLI dei modelli per cambiare modello nella chat e Failover dei modelli per la rotazione dell'autenticazione e il comportamento di fallback.
• Per provider personalizzati o self-hosted, consultare Provider personalizzati nel riferimento.

L'accesso ai messaggi diretti è controllato per ciascun canale tramite dmPolicy (valore predefinito "pairing"):

• "pairing": i mittenti sconosciuti ricevono un codice di associazione monouso da approvare
• "allowlist": sono ammessi solo i mittenti presenti in allowFrom (o nell'archivio degli elementi consentiti associati)
• "open": consente tutti i messaggi diretti in entrata (richiede allowFrom: ["*"])
• "disabled": ignora tutti i messaggi diretti

Per i gruppi, utilizzare groupPolicy ("allowlist" | "open" | "disabled") insieme a groupAllowFrom o agli elenchi consentiti specifici del canale.

Consultare il riferimento completo per i dettagli relativi a ciascun canale.

Per impostazione predefinita, i messaggi di gruppo richiedono una menzione. Configurare i modelli di attivazione per ciascun agente. Le normali risposte di gruppo o del canale vengono pubblicate automaticamente; attivare il percorso dello strumento per messaggi nelle stanze condivise in cui l'agente deve decidere quando intervenire:

{  messages: {    visibleReplies: "automatic", // impostare "message_tool" per richiedere ovunque l'invio tramite lo strumento per messaggi    groupChat: {      visibleReplies: "message_tool", // consenso esplicito; l'output visibile richiede message(action=send)      unmentionedInbound: "room_event", // le conversazioni di gruppo sempre attive senza menzioni costituiscono un contesto silenzioso    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Menzioni nei metadati: @-menzioni native (toccare per menzionare in WhatsApp, @bot in Telegram e così via)
• Modelli di testo: modelli regex sicuri in mentionPatterns
• Risposte visibili: messages.visibleReplies può richiedere globalmente l'invio tramite lo strumento per messaggi; messages.groupChat.visibleReplies sostituisce questa impostazione per gruppi e canali.
• Consultare il riferimento completo per le modalità di risposta visibile, le sostituzioni specifiche per canale e la modalità di chat con sé stessi.

Utilizzare agents.defaults.skills come base condivisa, quindi sostituirla per agenti specifici con agents.list[].skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // eredita github, weather      { id: "docs", skills: ["docs-search"] }, // sostituisce le impostazioni predefinite      { id: "locked-down", skills: [] }, // nessuna skill    ],  },}

• Omettere agents.defaults.skills per consentire tutte le Skills per impostazione predefinita.
• Omettere agents.list[].skills per ereditare le impostazioni predefinite.
• Impostare agents.list[].skills: [] per non consentire alcuna skill.
• Consultare Skills, Configurazione delle Skills e il Riferimento della configurazione.

Controllare con quale aggressività 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 },        },      },    },  },}

• I valori mostrati sono quelli predefiniti. Impostare gateway.channelHealthCheckMinutes: 0 per disabilitare globalmente i riavvii del monitoraggio dello stato.
• channelStaleEventThresholdMinutes deve essere maggiore o uguale all'intervallo di controllo.
• Utilizzare channels.<provider>.healthMonitor.enabled o channels.<provider>.accounts.<id>.healthMonitor.enabled per disabilitare i riavvii automatici di un singolo canale o account senza disabilitare il monitoraggio globale.
• Consultare Controlli dello stato per il debug operativo e il riferimento completo per tutti i campi.

Concedere ai client locali più tempo per completare l'handshake WebSocket precedente all'autenticazione su host sovraccarichi o a bassa potenza:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Il valore predefinito è 15000 millisecondi.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS continua ad avere la precedenza per le sostituzioni una tantum del servizio o della shell.
• È preferibile correggere prima gli stalli di avvio o del ciclo degli eventi; questa impostazione è destinata agli host integri ma lenti durante il riscaldamento.

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 (condiviso) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: valori predefiniti globali per l'instradamento delle sessioni associate ai thread. /focus, /unfocus, /agents, /session idle e /session max-age consentono di associare, dissociare, elencare e regolare questa impostazione per ogni sessione (Discord associa i thread, Telegram associa gli argomenti/le conversazioni).
• Consultare Gestione delle sessioni per ambiti, collegamenti delle identità e criteri di invio.
• Consultare il riferimento completo per tutti i campi.

Eseguire le sessioni degli agenti in runtime sandbox isolati:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

Creare prima l'immagine: da un checkout del codice sorgente eseguire scripts/sandbox-setup.sh; per un'installazione npm, consultare il comando docker build incorporato in Sandboxing § Immagini e configurazione.

Consultare Sandboxing per la guida completa e il riferimento completo per tutte le opzioni.

Le notifiche push supportate dal relay per le build pubbliche dell'App Store utilizzano il relay OpenClaw ospitato: https://ios-push-relay.openclaw.ai.

Le distribuzioni di relay personalizzate richiedono un percorso di build/distribuzione iOS deliberatamente separato, il cui URL del relay corrisponda all'URL del relay del gateway. Se si utilizza una build con relay personalizzato, impostare quanto segue nella configurazione del gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Facoltativo. Valore predefinito: 10000          timeoutMs: 10000,        },      },    },  },}

Equivalente CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

Effetti:

• Consente al gateway di inviare push.test, solleciti di riattivazione e riattivazioni per la riconnessione tramite il relay esterno.
• Utilizza un'autorizzazione di invio limitata alla registrazione, inoltrata dall'app iOS associata. Il gateway non necessita di un token del relay valido per l'intera distribuzione.
• Associa ogni registrazione supportata dal relay all'identità del gateway a cui è stata associata l'app iOS, impedendo a un altro gateway di riutilizzare la registrazione memorizzata.
• Mantiene le build iOS locali/manuali su APNs diretto. Gli invii supportati dal relay si applicano solo alle build distribuite ufficialmente che si sono registrate tramite il relay.
• Deve corrispondere all'URL di base del relay incorporato nella build iOS, affinché il traffico di registrazione e invio raggiunga la stessa distribuzione del relay.

Flusso end-to-end:

1. Installare l'app iOS ufficiale.
2. Facoltativo: configurare gateway.push.apns.relay.baseUrl sul gateway solo quando si utilizza una build con relay personalizzato deliberatamente separata.
3. Associare l'app iOS al gateway e consentire la connessione sia delle sessioni del Node sia di quelle dell'operatore.
4. L'app iOS recupera l'identità del gateway, si registra presso il relay utilizzando App Attest insieme alla ricevuta dell'app, quindi pubblica il payload push.apns.register supportato dal relay sul gateway associato.
5. Il gateway memorizza l'handle del relay e l'autorizzazione di invio, quindi li utilizza per push.test, i solleciti di riattivazione e le riattivazioni per la riconnessione.

Note operative:

• Se si collega l'app iOS a un gateway diverso, riconnettere l'app affinché possa pubblicare una nuova registrazione del relay associata a tale gateway.
• Se si distribuisce una nuova build iOS che punta a una distribuzione del relay diversa, l'app aggiorna la registrazione del relay memorizzata nella cache anziché riutilizzare la precedente origine del relay.

Nota sulla compatibilità:

• OPENCLAW_APNS_RELAY_BASE_URL e OPENCLAW_APNS_RELAY_TIMEOUT_MS continuano a funzionare come sostituzioni temporanee tramite variabili di ambiente.
• Gli URL del relay personalizzati del gateway devono corrispondere all'URL di base del relay incorporato nella build iOS; il canale di rilascio pubblico dell'App Store rifiuta le sostituzioni personalizzate dell'URL del relay iOS.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true rimane un meccanismo di emergenza di sviluppo limitato al loopback; non salvare in modo permanente URL HTTP del relay nella configurazione.

Consultare 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). Impostare 0m per disabilitare. Valore predefinito: 30m.
• target: last | none | <channel-id> (ad esempio discord, matrix, telegram o whatsapp)
• directPolicy: allow (valore predefinito) o block per destinazioni Heartbeat di tipo DM
• Consultare Heartbeat per la guida completa.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // valore predefinito; distribuzione Cron + esecuzione isolata dei turni dell'agente Cron    sessionRetention: "24h",  },}

• sessionRetention: elimina dalle righe delle sessioni SQLite le sessioni di esecuzione isolate completate (valore predefinito 24h; impostare false per disabilitare).
• La cronologia delle esecuzioni conserva automaticamente le 2000 righe terminali più recenti per ogni processo; le righe perse mantengono la propria finestra di pulizia di 24 ore.
• Consultare Processi Cron per una panoramica della funzionalità ed esempi CLI.

Abilitare gli 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 sulla sicurezza:

• Considerare tutto il contenuto dei payload di hook/Webhook come input non attendibile.
• Utilizzare un hooks.token dedicato; non riutilizzare segreti di autenticazione del Gateway attivi (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN oppure gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• L'autenticazione degli hook avviene esclusivamente tramite intestazione (Authorization: Bearer ... o x-openclaw-token); i token nella stringa di query vengono rifiutati.
• hooks.path non può essere /; mantenere l'ingresso Webhook in un sottopercorso dedicato, ad esempio /hooks.
• Mantenere disabilitati i flag che ignorano i controlli sui contenuti non sicuri (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), salvo durante attività di debug strettamente circoscritte.
• Se si abilita hooks.allowRequestSessionKey, impostare anche hooks.allowedSessionKeyPrefixes per limitare le chiavi di sessione selezionate dal chiamante.
• Per gli agenti attivati dagli hook, preferire livelli di modelli moderni e robusti e criteri rigorosi per gli strumenti (ad esempio, solo messaggistica più sandboxing ove possibile).

Consultare il riferimento completo per tutte le opzioni di mappatura e l'integrazione con Gmail.

Eseguire più agenti isolati con spazi di lavoro 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" } },  ],}

Consultare Multi-agente e il riferimento completo per le regole di associazione e i profili di accesso specifici per ogni agente.

Utilizzare $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 contenitore
• Array di file: unione profonda in ordine (prevale l'ultimo), fino a 10 livelli di nidificazione
• Chiavi allo stesso livello: unite dopo le inclusioni (sovrascrivono i valori inclusi)
• Percorsi relativi: risolti rispetto al file che esegue l'inclusione
• Formato del percorso: i percorsi di inclusione non devono contenere byte nulli e devono essere rigorosamente più corti di 4096 caratteri sia prima sia dopo la risoluzione
• Scritture gestite da OpenClaw: quando una scrittura modifica una sola sezione di primo livello basata sull'inclusione di un singolo file, come plugins: { $include: "./plugins.json5" }, OpenClaw aggiorna tale file incluso e lascia invariato openclaw.json
• Scrittura passante non supportata: le inclusioni radice, gli array di inclusioni e le inclusioni con sostituzioni allo stesso livello impediscono in modo sicuro le scritture gestite da OpenClaw, anziché appiattire la configurazione
• Confinamento: i percorsi $include devono risolversi all'interno della directory contenente openclaw.json. Per condividere un albero tra macchine o utenti, impostare OPENCLAW_INCLUDE_ROOTS su un elenco di percorsi (: su POSIX, ; su Windows) delle directory aggiuntive a cui le inclusioni possono fare riferimento. I collegamenti simbolici vengono risolti e ricontrollati, pertanto un percorso che lessicalmente si trova in una directory di configurazione, ma la cui destinazione reale esce da tutte le radici consentite, viene comunque rifiutato.
• Gestione degli errori: errori chiari per file mancanti, errori di analisi, inclusioni circolari, formato del percorso non valido e lunghezza eccessiva