Configurazione

Ogni canale ha la propria sezione di configurazione sotto 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

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"], // only for allowlist/open    },  },}

Imposta il modello principale e i fallback opzionali:

{  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; le voci provider/* filtrano /model, /models e i selettori di modelli sui provider selezionati, continuando a usare la scoperta dinamica dei modelli.
• Usa openclaw config set agents.defaults.models '<json>' --strict-json --merge per aggiungere voci all’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 (es. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx controlla il ridimensionamento di immagini di transcript/strumenti (predefinito 1200); valori più bassi di solito riducono l’uso di token visivi nelle esecuzioni ricche di screenshot.
• Vedi CLI dei modelli per cambiare modello in chat e Failover dei modelli per la rotazione dell’autenticazione e il comportamento di 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 di pairing monouso da approvare
• "allowlist": solo mittenti in allowFrom (o nell’archivio allow abbinato)
• "open": consenti tutti i DM in ingresso (richiede allowFrom: ["*"])
• "disabled": ignora tutti i DM

Per i gruppi, usa groupPolicy + groupAllowFrom oppure allowlist specifiche del canale.

Vedi il riferimento completo per i dettagli per canale.

I messaggi di gruppo richiedono per impostazione predefinita una menzione obbligatoria. Configura i pattern di trigger per agente. Le risposte normali di gruppo/canale vengono pubblicate automaticamente; abilita esplicitamente il percorso dello strumento messaggi per le stanze condivise in cui l’agente deve decidere quando parlare:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Menzioni da metadati: @-menzioni native (tap-to-mention di WhatsApp, @bot di Telegram, ecc.)
• Pattern di testo: pattern regex sicuri in mentionPatterns
• Risposte visibili: messages.visibleReplies può richiedere globalmente invii tramite strumento messaggi; messages.groupChat.visibleReplies lo sovrascrive per gruppi/canali.
• Vedi il riferimento completo per le modalità di risposta visibile, gli override per canale e la modalità self-chat.

Usa agents.defaults.skills per una baseline condivisa, poi sovrascrivi agenti specifici con agents.list[].skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults      { id: "locked-down", skills: [] }, // no skills    ],  },}

• Ometti agents.defaults.skills per Skills senza restrizioni per impostazione predefinita.
• Ometti agents.list[].skills per ereditare le impostazioni predefinite.
• Imposta agents.list[].skills: [] per nessuna Skills.
• Vedi Skills, Configurazione Skills e il Riferimento alla configurazione.

Controlla 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 },        },      },    },  },}

• Imposta gateway.channelHealthCheckMinutes: 0 per disabilitare globalmente i riavvii del monitoraggio della salute.
• channelStaleEventThresholdMinutes deve 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 un account senza disabilitare il monitoraggio globale.
• Vedi Controlli di salute per il debug operativo e il riferimento completo per tutti i campi.

Dai ai client locali più tempo per completare l’handshake WebSocket pre-autenticazione su host carichi o a bassa potenza:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Il valore predefinito è 15000 millisecondi.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS continua ad avere precedenza per override una tantum del servizio o della shell.
• Preferisci prima correggere stalli di avvio/event loop; questa manopola è per host sani ma lenti durante il warmup.

Le sessioni controllano la continuità e l’isolamento della conversazione:

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    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: impostazioni predefinite globali per l'instradamento delle sessioni vincolate ai thread (Discord supporta /focus, /unfocus, /agents, /session idle e /session max-age).
• Consulta Gestione delle sessioni per ambito, collegamenti di identità e criteri di invio.
• Consulta il riferimento completo per tutti i campi.

Esegui le sessioni degli agenti in runtime sandbox isolati:

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

Crea prima l'immagine: da un checkout del sorgente esegui scripts/sandbox-setup.sh, oppure da un'installazione npm consulta il comando inline docker build in Sandboxing § Immagini e configurazione.

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

Le notifiche push basate su relay per le build pubbliche dell'App Store usano il relay OpenClaw ospitato: https://ios-push-relay.openclaw.ai.

Le distribuzioni relay personalizzate richiedono un percorso di build/distribuzione iOS deliberatamente separato il cui URL relay corrisponda all'URL relay del gateway. Se usi una build relay personalizzata, imposta questo nella configurazione del gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 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 risveglio e risvegli di riconnessione tramite il relay esterno.
• Usa una concessione di invio con ambito di registrazione inoltrata dall'app iOS abbinata. Il gateway non necessita di un token relay valido per l'intera distribuzione.
• Vincola ogni registrazione basata su relay all'identità del gateway con cui l'app iOS è stata abbinata, così un altro gateway non può riutilizzare la registrazione archiviata.
• Mantiene le build iOS locali/manuali su APNs diretto. Gli invii basati su relay si applicano solo alle build distribuite ufficiali registrate tramite il relay.
• Deve corrispondere all'URL di base del relay integrato nella build iOS, così il traffico di registrazione e invio raggiunge la stessa distribuzione relay.

Flusso end-to-end:

1. Installa l'app iOS ufficiale.
2. Facoltativo: configura gateway.push.apns.relay.baseUrl sul gateway solo quando usi una build relay personalizzata deliberatamente separata.
3. Abbina l'app iOS al gateway e lascia che sia le sessioni del nodo sia quelle dell'operatore si connettano.
4. 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.register basato su relay verso il gateway abbinato.
5. Il gateway archivia l'handle relay e la concessione di invio, poi li usa per push.test, solleciti di risveglio e risvegli di riconnessione.

Note operative:

• 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 registrazione relay nella cache invece di riutilizzare la vecchia origine relay.

Nota di compatibilità:

• OPENCLAW_APNS_RELAY_BASE_URL e OPENCLAW_APNS_RELAY_TIMEOUT_MS continuano a funzionare come override env temporanei.
• Gli URL relay gateway personalizzati devono corrispondere all'URL di base del relay integrato nella build iOS. Il canale di rilascio pubblico App Store rifiuta gli override URL relay iOS personalizzati.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true resta una via di uscita di sviluppo solo local loopback; non rendere persistenti nella configurazione URL relay HTTP.

Consulta App iOS per il flusso end-to-end e Autenticazione e flusso di fiducia 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> (per esempio discord, matrix, telegram o whatsapp)
• directPolicy: allow (predefinito) o block per destinazioni Heartbeat in stile DM
• Consulta Heartbeat per la guida completa.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: elimina da sessions.json le sessioni di esecuzione isolate completate (predefinito 24h; imposta false per disabilitare).
• runLog: elimina le righe conservate della cronologia esecuzioni Cron per processo. maxBytes resta accettato per i log di esecuzione più vecchi basati su file.
• Consulta processi Cron per una panoramica della funzionalità ed esempi CLI.

Abilita 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 di sicurezza:

• Tratta tutto il contenuto dei payload hook/Webhook come input non attendibile.
• Usa un hooks.token dedicato; non riutilizzare segreti di autenticazione Gateway attivi (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN o gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• L'autenticazione hook è solo tramite 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, ad esempio /hooks.
• Mantieni disabilitati i flag di bypass dei contenuti non sicuri (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) salvo per debug con ambito strettamente limitato.
• 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 robusti e criteri rigorosi per gli strumenti (per 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 regole di associazione 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: uniti in profondità 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 relativamente al file includente
• Formato percorso: i percorsi di include non devono contenere byte nulli e devono essere strettamente più brevi di 4096 caratteri prima e dopo la risoluzione
• 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 intatto openclaw.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 $include devono risolversi sotto la directory che contiene openclaw.json. Per condividere un albero tra macchine o utenti, imposta OPENCLAW_INCLUDE_ROOTS su 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 errori: errori chiari per file mancanti, errori di parsing, include circolari, formato percorso non valido e lunghezza eccessiva