Configurazione

Ogni canale ha la propria sezione di configurazione sotto channels.<provider>. Consulta 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 modello di criterio 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 agisce come allowlist per /model.
• Usa openclaw config set agents.defaults.models '<json>' --strict-json --merge per aggiungere voci alla allowlist senza rimuovere modelli esistenti. Le sostituzioni semplici che rimuoverebbero voci vengono rifiutate a meno che non passi --replace.
• I riferimenti ai modelli usano il formato provider/model (ad es. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx controlla il ridimensionamento delle immagini di trascrizione/strumenti (predefinito 1200); valori più bassi di solito riducono l'uso di token visivi nelle esecuzioni ricche di screenshot.
• Consulta CLI modelli per cambiare modello in chat e Failover del modello per rotazione dell'autenticazione e comportamento di fallback.
• Per provider personalizzati/self-hosted, consulta Provider personalizzati nel riferimento.

L'accesso DM è controllato per canale tramite dmPolicy:

• "pairing" (predefinito): i mittenti sconosciuti ricevono un codice di associazione monouso da approvare
• "allowlist": solo i mittenti in allowFrom (o nell'archivio di autorizzazioni associato)
• "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 richiedono per impostazione predefinita una menzione obbligatoria. Configura i pattern di attivazione per agente e mantieni le risposte visibili nella stanza sul percorso predefinito dello strumento messaggi, a meno che tu non voglia intenzionalmente le risposte finali automatiche legacy:

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Menzioni nei metadati: @-mention native (menzione tramite tocco di WhatsApp, @bot di Telegram, ecc.)
• Pattern di testo: pattern regex sicuri in mentionPatterns
• Risposte visibili: messages.visibleReplies può richiedere invii tramite strumento messaggi a livello globale; messages.groupChat.visibleReplies lo sovrascrive per gruppi/canali.
• Consulta il riferimento completo per modalità di risposta visibile, override per canale e modalità self-chat.

Usa agents.defaults.skills per una base 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.
• Consulta Skills, Configurazione Skills e il Riferimento di configurazione.

Controlla quanto aggressivamente il Gateway riavvia 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 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 Controlli di stato per il debugging 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 ha ancora la precedenza per override una tantum di servizio o shell.
• Preferisci prima risolvere blocchi di avvio/event-loop; questa manopola è per host sani ma lenti durante il warmup.

Le sessioni controllano continuità e isolamento delle conversazioni:

{
  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 (condivisa) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: impostazioni predefinite globali per il routing delle sessioni vincolate al thread (Discord supporta /focus, /unfocus, /agents, /session idle e /session max-age).
• Consulta Gestione delle sessioni per ambiti, collegamenti di identità e criterio di invio.
• Consulta il riferimento completo per tutti i campi.

Esegui le sessioni agente 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 § Images and setup.

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

Le notifiche push tramite relay sono configurate in openclaw.json.

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 riattivazione e riattivazioni di riconnessione tramite il relay esterno.
• Usa un'autorizzazione di invio con ambito di registrazione inoltrata dall'app iOS abbinata. Il Gateway non richiede un token relay valido per tutta la distribuzione.
• Associa ogni registrazione tramite relay all'identità del Gateway con cui l'app iOS è stata abbinata, quindi un altro Gateway non può riutilizzare la registrazione archiviata.
• Mantiene le build iOS locali/manuali su APNs diretto. Gli invii tramite relay si applicano solo alle build distribuite ufficiali che si sono registrate tramite il relay.
• Deve corrispondere all'URL di base del relay incorporato nella build iOS ufficiale/TestFlight, in modo che il traffico di registrazione e di invio raggiunga la stessa distribuzione relay.

Flusso end-to-end:

1. Installa una build iOS ufficiale/TestFlight compilata con lo stesso URL di base del relay.
2. Configura gateway.push.apns.relay.baseUrl sul Gateway.
3. Abbina l'app iOS al Gateway e lascia che sia le sessioni node sia quelle 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 tramite relay sul Gateway abbinato.
5. Il Gateway archivia l'handle del relay e l'autorizzazione di invio, quindi li usa per push.test, solleciti di riattivazione e 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 una distribuzione relay diversa, l'app aggiorna la registrazione relay memorizzata 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 temporanei via env.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true rimane una via di fuga di sviluppo limitata al loopback; non salvare 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> (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: 2, // 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: riduce cron/runs/<jobId>.jsonl per dimensione e righe conservate.
• Consulta Processi Cron per la panoramica della funzionalità e gli 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 il token Gateway condiviso.
• 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 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 anche hooks.allowedSessionKeyPrefixes per limitare le chiavi di sessione selezionate dal chiamante.
• Per agenti guidati da hook, preferisci tier di modelli moderni robusti e una policy strumenti rigorosa (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-agente 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: uniti in profondità in ordine (gli ultimi prevalgono)
• 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 intatto openclaw.json
• Write-through non supportato: include radice, array di include e include con override sorelli 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 una lista di percorsi (: su POSIX, ; su Windows) di directory aggiuntive che gli include possono referenziare. 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 radice consentita viene comunque rifiutato.
• Gestione degli errori: errori chiari per file mancanti, errori di parsing e include circolari