​

Riferimento della configurazione

• openclaw config schema stampa lo Schema JSON live usato per la convalida e per la Control UI, con i metadati bundled/plugin/canale uniti quando disponibili
• config.schema.lookup restituisce un nodo dello schema limitato a un percorso per gli strumenti di analisi dettagliata
• pnpm config:docs:check / pnpm config:docs:gen convalidano l’hash di baseline della documentazione di configurazione rispetto alla superficie dello schema corrente

• Riferimento della configurazione della memoria per agents.defaults.memorySearch.*, memory.qmd.*, memory.citations e la configurazione dreaming sotto plugins.entries.memory-core.config.dreaming
• Comandi slash per il catalogo corrente dei comandi integrati + bundled
• pagine del canale/plugin proprietario per le superfici di comando specifiche del canale

​

Canali

​

Accesso DM e gruppi

​

Override del modello per canale

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

​

Valori predefiniti dei canali e heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: criterio gruppo di fallback quando groupPolicy a livello provider non è impostato.
• channels.defaults.contextVisibility: modalità predefinita di visibilità del contesto supplementare per tutti i canali. Valori: all (predefinito, include tutto il contesto citato/thread/cronologia), allowlist (include solo il contesto da mittenti presenti nella allowlist), allowlist_quote (come allowlist ma mantiene il contesto esplicito di citazione/risposta). Override per canale: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: include gli stati dei canali integri nell’output heartbeat.
• channels.defaults.heartbeat.showAlerts: include gli stati degradati/di errore nell’output heartbeat.
• channels.defaults.heartbeat.useIndicator: mostra un output heartbeat compatto in stile indicatore.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Token del bot: channels.telegram.botToken oppure channels.telegram.tokenFile (solo file regolari; i symlink vengono rifiutati), con TELEGRAM_BOT_TOKEN come fallback per l’account predefinito.
• L’opzione facoltativa channels.telegram.defaultAccount sovrascrive la selezione dell’account predefinito quando corrisponde a un ID account configurato.
• Nelle configurazioni multi-account (2+ ID account), imposta un valore predefinito esplicito (channels.telegram.defaultAccount oppure channels.telegram.accounts.default) per evitare il routing di fallback; openclaw doctor avvisa quando questo manca o non è valido.
• configWrites: false blocca le scritture di configurazione avviate da Telegram (migrazioni ID supergruppo, /config set|unset).
• Le voci bindings[] di primo livello con type: "acp" configurano binding ACP persistenti per gli argomenti del forum (usa il formato canonico chatId:topic:topicId in match.peer.id). La semantica dei campi è condivisa in ACP Agents.
• Le anteprime di stream Telegram usano sendMessage + editMessageText (funziona nelle chat dirette e di gruppo).
• Criterio di retry: vedi Retry policy.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (progress maps to partial on Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, con DISCORD_BOT_TOKEN come fallback per l’account predefinito.
• Le chiamate dirette in uscita che forniscono un token Discord esplicito usano quel token per la chiamata; le impostazioni di retry/criterio dell’account provengono comunque dall’account selezionato nello snapshot runtime attivo.
• L’opzione facoltativa channels.discord.defaultAccount sovrascrive la selezione dell’account predefinito quando corrisponde a un ID account configurato.
• Usa user:<id> (DM) o channel:<id> (canale guild) per i target di consegna; gli ID numerici senza prefisso vengono rifiutati.
• Gli slug delle guild sono in minuscolo con gli spazi sostituiti da -; le chiavi dei canali usano il nome in formato slug (senza #). Preferisci gli ID delle guild.
• I messaggi creati dal bot vengono ignorati per impostazione predefinita. allowBots: true li abilita; usa allowBots: "mentions" per accettare solo i messaggi dei bot che menzionano il bot (i propri messaggi restano comunque filtrati).
• channels.discord.guilds.<id>.ignoreOtherMentions (e gli override a livello canale) elimina i messaggi che menzionano un altro utente o ruolo ma non il bot (escludendo @everyone/@here).
• maxLinesPerMessage (predefinito 17) divide i messaggi alti anche quando restano sotto 2000 caratteri.
• channels.discord.threadBindings controlla il routing vincolato ai thread Discord:
  • enabled: override Discord per le funzionalità di sessione vincolate ai thread (/focus, /unfocus, /agents, /session idle, /session max-age e consegna/routing associati)
  • idleHours: override Discord per il disaccoppiamento automatico per inattività in ore (0 disabilita)
  • maxAgeHours: override Discord per l’età massima rigida in ore (0 disabilita)
  • spawnSubagentSessions: interruttore opt-in per la creazione/associazione automatica dei thread di sessions_spawn({ thread: true })
• Le voci bindings[] di primo livello con type: "acp" configurano binding ACP persistenti per canali e thread (usa l’id del canale/thread in match.peer.id). La semantica dei campi è condivisa in ACP Agents.
• channels.discord.ui.components.accentColor imposta il colore di accento per i contenitori Discord components v2.
• channels.discord.voice abilita le conversazioni nei canali vocali Discord e gli override facoltativi di auto-join + TTS.
• channels.discord.voice.daveEncryption e channels.discord.voice.decryptionFailureTolerance vengono passati a @discordjs/voice come opzioni DAVE (true e 24 per impostazione predefinita).
• OpenClaw tenta inoltre il recupero della ricezione vocale uscendo e rientrando in una sessione vocale dopo ripetuti errori di decrittazione.
• channels.discord.streaming è la chiave canonica della modalità di stream. I valori legacy streamMode e booleani streaming vengono migrati automaticamente.
• channels.discord.autoPresence mappa la disponibilità runtime alla presenza del bot (healthy => online, degraded => idle, exhausted => dnd) e consente override facoltativi del testo di stato.
• channels.discord.dangerouslyAllowNameMatching riabilita la corrispondenza per nome/tag modificabile (modalità di compatibilità break-glass).
• channels.discord.execApprovals: consegna nativa Discord delle approvazioni exec e autorizzazione degli approvatori.
  • enabled: true, false o "auto" (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da approvers o commands.ownerAllowFrom.
  • approvers: ID utente Discord autorizzati ad approvare le richieste exec. Se omesso, usa commands.ownerAllowFrom come fallback.
  • agentFilter: allowlist facoltativa di ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti.
  • sessionFilter: pattern facoltativi di chiavi sessione (sottostringa o regex).
  • target: dove inviare i prompt di approvazione. "dm" (predefinito) li invia ai DM degli approvatori, "channel" li invia al canale di origine, "both" li invia a entrambi. Quando il target include "channel", i pulsanti possono essere usati solo dagli approvatori risolti.
  • cleanupAfterResolve: quando true, elimina i DM di approvazione dopo approvazione, rifiuto o timeout.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• JSON dell’account di servizio: inline (serviceAccount) o basato su file (serviceAccountFile).
• È supportato anche SecretRef dell’account di servizio (serviceAccountRef).
• Fallback env: GOOGLE_CHAT_SERVICE_ACCOUNT o GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Usa spaces/<spaceId> o users/<userId> per i target di consegna.
• channels.googlechat.dangerouslyAllowNameMatching riabilita la corrispondenza modificabile del principal email (modalità di compatibilità break-glass).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // use Slack native streaming API when mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Socket mode richiede sia botToken sia appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN come fallback env dell’account predefinito).
• HTTP mode richiede botToken più signingSecret (alla radice o per account).
• botToken, appToken, signingSecret e userToken accettano stringhe in chiaro o oggetti SecretRef.
• Gli snapshot degli account Slack espongono campi per origine/stato delle credenziali, come botTokenSource, botTokenStatus, appTokenStatus e, in modalità HTTP, signingSecretStatus. configured_unavailable significa che l’account è configurato tramite SecretRef ma il comando/percorso runtime corrente non ha potuto risolvere il valore del segreto.
• configWrites: false blocca le scritture di configurazione avviate da Slack.
• L’opzione facoltativa channels.slack.defaultAccount sovrascrive la selezione dell’account predefinito quando corrisponde a un ID account configurato.
• channels.slack.streaming.mode è la chiave canonica della modalità di stream Slack. channels.slack.streaming.nativeTransport controlla il trasporto streaming nativo di Slack. I valori legacy streamMode, booleani streaming e nativeStreaming vengono migrati automaticamente.
• Usa user:<id> (DM) o channel:<id> per i target di consegna.

• Lo streaming nativo di Slack, insieme allo stato del thread in stile assistente Slack “is typing…”, richiede un target di risposta nel thread. I DM di primo livello restano fuori thread per impostazione predefinita, quindi usano typingReaction o la consegna normale invece dell’anteprima in stile thread.
• typingReaction aggiunge una reazione temporanea al messaggio Slack in ingresso mentre una risposta è in esecuzione, poi la rimuove al completamento. Usa uno shortcode emoji Slack come "hourglass_flowing_sand".
• channels.slack.execApprovals: consegna nativa Slack delle approvazioni exec e autorizzazione degli approvatori. Stesso schema di Discord: enabled (true/false/"auto"), approvers (ID utente Slack), agentFilter, sessionFilter e target ("dm", "channel" o "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath deve essere un percorso (ad esempio /api/channels/mattermost/command), non un URL completo.
• commands.callbackUrl deve risolversi all’endpoint gateway OpenClaw ed essere raggiungibile dal server Mattermost.
• I callback slash nativi sono autenticati con i token per comando restituiti da Mattermost durante la registrazione del comando slash. Se la registrazione fallisce o non viene attivato alcun comando, OpenClaw rifiuta i callback con Unauthorized: invalid command token.
• Per host callback privati/tailnet/interni, Mattermost può richiedere che ServiceSettings.AllowedUntrustedInternalConnections includa l’host/dominio del callback. Usa valori host/dominio, non URL completi.
• channels.mattermost.configWrites: consenti o nega le scritture di configurazione avviate da Mattermost.
• channels.mattermost.requireMention: richiede @mention prima di rispondere nei canali.
• channels.mattermost.groups.<channelId>.requireMention: override per canale della limitazione tramite menzione ("*" per il predefinito).
• L’opzione facoltativa channels.mattermost.defaultAccount sovrascrive la selezione dell’account predefinito quando corrisponde a un ID account configurato.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account: vincola l’avvio del canale a una specifica identità account Signal.
• channels.signal.configWrites: consenti o nega le scritture di configurazione avviate da Signal.
• L’opzione facoltativa channels.signal.defaultAccount sovrascrive la selezione dell’account predefinito quando corrisponde a un ID account configurato.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

• I percorsi chiave principali trattati qui: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• L’opzione facoltativa channels.bluebubbles.defaultAccount sovrascrive la selezione dell’account predefinito quando corrisponde a un ID account configurato.
• Le voci bindings[] di primo livello con type: "acp" possono associare conversazioni BlueBubbles a sessioni ACP persistenti. Usa un handle BlueBubbles o una stringa target (chat_id:*, chat_guid:*, chat_identifier:*) in match.peer.id. Semantica condivisa dei campi: ACP Agents.
• La configurazione completa del canale BlueBubbles è documentata in BlueBubbles.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• L’opzione facoltativa channels.imessage.defaultAccount sovrascrive la selezione dell’account predefinito quando corrisponde a un ID account configurato.
• Richiede Full Disk Access al database Messaggi.
• Preferisci target chat_id:<id>. Usa imsg chats --limit 20 per elencare le chat.
• cliPath può puntare a un wrapper SSH; imposta remoteHost (host o user@host) per il recupero degli allegati tramite SCP.
• attachmentRoots e remoteAttachmentRoots limitano i percorsi degli allegati in ingresso (predefinito: /Users/*/Library/Messages/Attachments).
• SCP usa il controllo rigoroso della chiave host, quindi assicurati che la chiave host del relay esista già in ~/.ssh/known_hosts.
• channels.imessage.configWrites: consenti o nega le scritture di configurazione avviate da iMessage.
• Le voci bindings[] di primo livello con type: "acp" possono associare conversazioni iMessage a sessioni ACP persistenti. Usa un handle normalizzato o un target chat esplicito (chat_id:*, chat_guid:*, chat_identifier:*) in match.peer.id. Semantica condivisa dei campi: ACP Agents.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• L’autenticazione tramite token usa accessToken; l’autenticazione tramite password usa userId + password.
• channels.matrix.proxy instrada il traffico HTTP Matrix attraverso un proxy HTTP(S) esplicito. Gli account nominati possono sovrascriverlo con channels.matrix.accounts.<id>.proxy.
• channels.matrix.network.dangerouslyAllowPrivateNetwork consente homeserver privati/interni. proxy e questo opt-in di rete sono controlli indipendenti.
• channels.matrix.defaultAccount seleziona l’account preferito nelle configurazioni multi-account.
• channels.matrix.autoJoin ha valore predefinito off, quindi le stanze invitate e i nuovi inviti in stile DM vengono ignorati finché non imposti autoJoin: "allowlist" con autoJoinAllowlist o autoJoin: "always".
• channels.matrix.execApprovals: consegna nativa Matrix delle approvazioni exec e autorizzazione degli approvatori.
  • enabled: true, false o "auto" (predefinito). In modalità auto, le approvazioni exec si attivano quando gli approvatori possono essere risolti da approvers o commands.ownerAllowFrom.
  • approvers: ID utente Matrix (ad es. @owner:example.org) autorizzati ad approvare richieste exec.
  • agentFilter: allowlist facoltativa di ID agente. Omettila per inoltrare le approvazioni per tutti gli agenti.
  • sessionFilter: pattern facoltativi di chiavi sessione (sottostringa o regex).
  • target: dove inviare i prompt di approvazione. "dm" (predefinito), "channel" (stanza di origine) o "both".
  • Override per account: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope controlla come i DM Matrix vengono raggruppati in sessioni: per-user (predefinito) condivide per peer instradato, mentre per-room isola ogni stanza DM.
• I probe di stato Matrix e le ricerche live nella directory usano lo stesso criterio proxy del traffico runtime.
• La configurazione completa di Matrix, le regole di targeting e gli esempi di configurazione sono documentati in Matrix.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• I percorsi chiave principali trattati qui: channels.msteams, channels.msteams.configWrites.
• La configurazione completa di Teams (credenziali, webhook, criterio DM/gruppi, override per team/per canale) è documentata in Microsoft Teams.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• I percorsi chiave principali trattati qui: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• L’opzione facoltativa channels.irc.defaultAccount sovrascrive la selezione dell’account predefinito quando corrisponde a un ID account configurato.
• La configurazione completa del canale IRC (host/porta/TLS/canali/allowlist/limitazione tramite menzione) è documentata in IRC.

​

Multi-account (tutti i canali)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default viene usato quando accountId viene omesso (CLI + routing).
• I token env si applicano solo all’account default.
• Le impostazioni base del canale si applicano a tutti gli account salvo override per account.
• Usa bindings[].match.accountId per instradare ogni account a un agente diverso.
• Se aggiungi un account non predefinito tramite openclaw channels add (o onboarding del canale) mentre sei ancora su una configurazione di canale top-level a singolo account, OpenClaw promuove prima i valori top-level a singolo account con ambito account nella mappa account del canale, così l’account originale continua a funzionare. La maggior parte dei canali li sposta in channels.<channel>.accounts.default; Matrix può invece preservare un target nominato/predefinito esistente corrispondente.
• I binding esistenti solo-canale (senza accountId) continuano a corrispondere all’account predefinito; i binding con ambito account restano facoltativi.
• openclaw doctor --fix ripara anche le forme miste spostando i valori top-level a singolo account con ambito account nell’account promosso scelto per quel canale. La maggior parte dei canali usa accounts.default; Matrix può preservare un target nominato/predefinito esistente corrispondente.

​

Altri canali di estensione

​

Limitazione tramite menzione nelle chat di gruppo

• Menzioni nei metadati: @-mention native della piattaforma. Ignorate nella modalità self-chat di WhatsApp.
• Pattern di testo: pattern regex sicuri in agents.list[].groupChat.mentionPatterns. I pattern non validi e le ripetizioni annidate non sicure vengono ignorati.
• La limitazione tramite menzione viene applicata solo quando il rilevamento è possibile (menzioni native o almeno un pattern).

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

Limiti della cronologia DM

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

Modalità self-chat

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

Comandi (gestione dei comandi chat)

{
  commands: {
    native: "auto", // register native commands when supported
    nativeSkills: "auto", // register native skill commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    mcp: false, // allow /mcp
    plugins: false, // allow /plugins
    debug: false, // allow /debug
    restart: true, // allow /restart + gateway restart tool
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

Valori predefiniti degli agenti

​

agents.defaults.workspace

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

​

agents.defaults.repoRoot

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

​

agents.defaults.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 avere Skills senza restrizioni per impostazione predefinita.
• Ometti agents.list[].skills per ereditare i valori predefiniti.
• Imposta agents.list[].skills: [] per non avere Skills.
• Un elenco non vuoto agents.list[].skills è l’insieme finale per quell’agente; non viene unito ai valori predefiniti.

​

agents.defaults.skipBootstrap

{
  agents: { defaults: { skipBootstrap: true } },
}

​

agents.defaults.contextInjection

• "continuation-skip": i turni di continuazione sicura (dopo una risposta completata dell’assistente) saltano la reiniezione del bootstrap della workspace, riducendo la dimensione del prompt. Le esecuzioni heartbeat e i tentativi successivi alla compattazione ricostruiscono comunque il contesto.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": non iniettare mai testo di avviso nel prompt di sistema.
• "once": inietta l’avviso una sola volta per ogni firma di troncamento univoca (consigliato).
• "always": inietta l’avviso a ogni esecuzione quando esiste un troncamento.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.userTimezone

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

​

agents.defaults.timeFormat

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // global default provider params
      embeddedHarness: {
        runtime: "auto", // auto | pi | registered harness id, e.g. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: accetta sia una stringa ("provider/model") sia un oggetto ({ primary, fallbacks }).
  • La forma stringa imposta solo il modello primario.
  • La forma oggetto imposta il primario più i modelli di failover ordinati.
• imageModel: accetta sia una stringa ("provider/model") sia un oggetto ({ primary, fallbacks }).
  • Usato dal percorso dello strumento image come configurazione del modello di visione.
  • Usato anche come routing di fallback quando il modello selezionato/predefinito non può accettare input immagine.
• imageGenerationModel: accetta sia una stringa ("provider/model") sia un oggetto ({ primary, fallbacks }).
  • Usato dalla capacità condivisa di generazione immagini e da qualsiasi futura superficie di strumento/plugin che generi immagini.
  • Valori tipici: google/gemini-3.1-flash-image-preview per la generazione immagini Gemini nativa, fal/fal-ai/flux/dev per fal, oppure openai/gpt-image-1 per OpenAI Images.
  • Se selezioni direttamente un provider/modello, configura anche l’autenticazione/la chiave API del provider corrispondente (ad esempio GEMINI_API_KEY o GOOGLE_API_KEY per google/*, OPENAI_API_KEY per openai/*, FAL_KEY per fal/*).
  • Se omesso, image_generate può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione immagini registrati in ordine di ID provider.
• musicGenerationModel: accetta sia una stringa ("provider/model") sia un oggetto ({ primary, fallbacks }).
  • Usato dalla capacità condivisa di generazione musicale e dallo strumento integrato music_generate.
  • Valori tipici: google/lyria-3-clip-preview, google/lyria-3-pro-preview o minimax/music-2.5+.
  • Se omesso, music_generate può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione musicale registrati in ordine di ID provider.
  • Se selezioni direttamente un provider/modello, configura anche l’autenticazione/la chiave API del provider corrispondente.
• videoGenerationModel: accetta sia una stringa ("provider/model") sia un oggetto ({ primary, fallbacks }).
  • Usato dalla capacità condivisa di generazione video e dallo strumento integrato video_generate.
  • Valori tipici: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash o qwen/wan2.7-r2v.
  • Se omesso, video_generate può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider di generazione video registrati in ordine di ID provider.
  • Se selezioni direttamente un provider/modello, configura anche l’autenticazione/la chiave API del provider corrispondente.
  • Il provider bundled di generazione video Qwen supporta fino a 1 video in uscita, 1 immagine in ingresso, 4 video in ingresso, durata di 10 secondi e opzioni a livello provider size, aspectRatio, resolution, audio e watermark.
• pdfModel: accetta sia una stringa ("provider/model") sia un oggetto ({ primary, fallbacks }).
  • Usato dallo strumento pdf per il routing del modello.
  • Se omesso, lo strumento PDF usa come fallback imageModel, poi il modello di sessione/predefinito risolto.
• pdfMaxBytesMb: limite predefinito della dimensione PDF per lo strumento pdf quando maxBytesMb non viene passato al momento della chiamata.
• pdfMaxPages: numero massimo predefinito di pagine considerate dalla modalità fallback di estrazione nello strumento pdf.
• verboseDefault: livello verboso predefinito per gli agenti. Valori: "off", "on", "full". Predefinito: "off".
• elevatedDefault: livello predefinito di output elevato per gli agenti. Valori: "off", "on", "ask", "full". Predefinito: "on".
• model.primary: formato provider/model (ad esempio openai/gpt-5.4). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca del provider configurato per quell’esatto ID modello e solo dopo usa come fallback il provider predefinito configurato (comportamento di compatibilità deprecato, quindi preferisci provider/model esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw usa come fallback il primo provider/modello configurato invece di mostrare un valore predefinito obsoleto di un provider rimosso.
• models: il catalogo e la allowlist dei modelli configurati per /model. Ogni voce può includere alias (scorciatoia) e params (specifici del provider, ad esempio temperature, maxTokens, cacheRetention, context1m).
• params: parametri globali predefiniti del provider applicati a tutti i modelli. Impostati in agents.defaults.params (ad es. { cacheRetention: "long" }).
• Precedenza di unione di params (config): agents.defaults.params (base globale) viene sovrascritto da agents.defaults.models["provider/model"].params (per modello), quindi agents.list[].params (ID agente corrispondente) sovrascrive per chiave. Vedi Prompt Caching per i dettagli.
• embeddedHarness: criterio predefinito del runtime embedded a basso livello dell’agente. Usa runtime: "auto" per lasciare che gli harness plugin registrati rivendichino i modelli supportati, runtime: "pi" per forzare l’harness PI integrato, oppure un ID harness registrato come runtime: "codex". Imposta fallback: "none" per disabilitare il fallback automatico a PI.
• I writer di configurazione che modificano questi campi (ad esempio /models set, /models set-image e i comandi di aggiunta/rimozione fallback) salvano la forma canonica a oggetto e preservano gli elenchi fallback esistenti quando possibile.
• maxConcurrent: numero massimo di esecuzioni parallele di agenti tra le sessioni (ogni sessione resta comunque serializzata). Predefinito: 4.

​

agents.defaults.embeddedHarness

{
  agents: {
    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

• runtime: "auto", "pi" o un ID harness plugin registrato. Il plugin bundled Codex registra codex.
• fallback: "pi" o "none". "pi" mantiene l’harness PI integrato come fallback di compatibilità. "none" fa fallire la selezione di un harness plugin mancante o non supportato invece di usare silenziosamente PI.
• Override d’ambiente: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> sovrascrive runtime; OPENCLAW_AGENT_HARNESS_FALLBACK=none disabilita il fallback a PI per quel processo.
• Per distribuzioni solo Codex, imposta model: "codex/gpt-5.4", embeddedHarness.runtime: "codex" e embeddedHarness.fallback: "none".
• Questo controlla solo l’harness della chat embedded. Generazione media, visione, PDF, musica, video e TTS usano comunque le rispettive impostazioni provider/modello.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• I backend CLI sono orientati prima di tutto al testo; gli strumenti sono sempre disabilitati.
• Le sessioni sono supportate quando sessionArg è impostato.
• Il pass-through delle immagini è supportato quando imageArg accetta percorsi di file.

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: stringa di durata (ms/s/m/h). Predefinito: 30m (autenticazione con chiave API) o 1h (autenticazione OAuth). Imposta 0m per disabilitare.
• includeSystemPromptSection: quando è false, omette la sezione Heartbeat dal prompt di sistema e salta l’iniezione di HEARTBEAT.md nel contesto bootstrap. Predefinito: true.
• suppressToolErrorWarnings: quando è true, sopprime i payload di avviso degli errori degli strumenti durante le esecuzioni heartbeat.
• timeoutSeconds: tempo massimo in secondi consentito per un turno agente heartbeat prima che venga interrotto. Lascialo non impostato per usare agents.defaults.timeoutSeconds.
• directPolicy: criterio di consegna diretta/DM. allow (predefinito) consente la consegna a target diretto. block sopprime la consegna a target diretto ed emette reason=dm-blocked.
• lightContext: quando è true, le esecuzioni heartbeat usano un contesto bootstrap leggero e mantengono solo HEARTBEAT.md tra i file bootstrap della workspace.
• isolatedSession: quando è true, ogni heartbeat viene eseguito in una sessione nuova senza cronologia conversazionale precedente. Stesso schema di isolamento di cron sessionTarget: "isolated". Riduce il costo in token per heartbeat da circa 100K a circa 2-5K token.
• Per agente: imposta agents.list[].heartbeat. Quando un qualsiasi agente definisce heartbeat, gli heartbeat vengono eseguiti solo da quegli agenti.
• Gli heartbeat eseguono turni agente completi: intervalli più brevi consumano più token.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id di un plugin provider di compattazione registrato (opzionale)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserva esattamente gli ID di deployment, gli ID dei ticket e le coppie host:port.", // usato quando identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disabilita la reiniezione
        model: "openrouter/anthropic/claude-sonnet-4-6", // override opzionale del modello solo per la compattazione
        notifyUser: true, // invia un breve avviso quando inizia la compattazione (predefinito: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "La sessione si sta avvicinando alla compattazione. Archivia ora i ricordi durevoli.",
          prompt: "Scrivi eventuali note durature in memory/YYYY-MM-DD.md; rispondi con l'esatto token silenzioso NO_REPLY se non c'è nulla da archiviare.",
        },
      },
    },
  },
}

• mode: default o safeguard (riepilogo suddiviso in blocchi per cronologie lunghe). Vedi Compaction.
• provider: id di un plugin provider di compattazione registrato. Quando impostato, viene chiamato summarize() del provider invece del riepilogo LLM integrato. In caso di errore, torna a quello integrato. Impostare un provider forza mode: "safeguard". Vedi Compaction.
• timeoutSeconds: numero massimo di secondi consentiti per una singola operazione di compattazione prima che OpenClaw la interrompa. Predefinito: 900.
• identifierPolicy: strict (predefinito), off o custom. strict antepone linee guida integrate per la conservazione di identificatori opachi durante il riepilogo della compattazione.
• identifierInstructions: testo personalizzato facoltativo per la conservazione degli identificatori usato quando identifierPolicy=custom.
• postCompactionSections: nomi facoltativi di sezioni H2/H3 di AGENTS.md da reiniettare dopo la compattazione. Il valore predefinito è ["Session Startup", "Red Lines"]; imposta [] per disabilitare la reiniezione. Se non è impostato o viene impostato esplicitamente a quella coppia predefinita, anche le intestazioni meno recenti Every Session/Safety sono accettate come fallback legacy.
• model: override facoltativo provider/model-id solo per il riepilogo della compattazione. Usalo quando la sessione principale deve mantenere un modello ma i riepiloghi di compattazione devono essere eseguiti con un altro; se non impostato, la compattazione usa il modello primario della sessione.
• notifyUser: quando true, invia un breve avviso all’utente quando inizia la compattazione (per esempio, “Compattazione del contesto in corso…”). Disabilitato per impostazione predefinita per mantenere la compattazione silenziosa.
• memoryFlush: turno agentico silenzioso prima della compattazione automatica per archiviare ricordi durevoli. Saltato quando il workspace è in sola lettura.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // durata (ms/s/m/h), unità predefinita: minuti
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Contenuto del vecchio risultato dello strumento cancellato]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

Streaming a blocchi

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (usa minMs/maxMs)
    },
  },
}

• I canali non Telegram richiedono *.blockStreaming: true esplicito per abilitare le risposte a blocchi.
• Override per canale: channels.<channel>.blockStreamingCoalesce (e varianti per account). Signal/Slack/Discord/Google Chat usano per impostazione predefinita minChars: 1500.
• humanDelay: pausa casuale tra le risposte a blocchi. natural = 800–2500 ms. Override per agente: agents.list[].humanDelay.

​

Indicatori di digitazione

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Valori predefiniti: instant per chat dirette/menzioni, message per chat di gruppo senza menzione.
• Override per sessione: session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Sono supportati anche SecretRef / contenuti inline:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // opzionale
          gatewayEndpoint: "https://lab.example", // opzionale
          policy: "strict", // id criterio OpenShell opzionale
          providers: ["openai"], // opzionale
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # immagine sandbox principale
scripts/sandbox-browser-setup.sh   # immagine browser opzionale

​

agents.list (override per agente)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // oppure { primary, fallbacks }
        thinkingDefault: "high", // override del livello di thinking per agente
        reasoningDefault: "on", // override della visibilità del ragionamento per agente
        fastModeDefault: false, // override della modalità rapida per agente
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // sostituisce per chiave i params corrispondenti in defaults.models
        skills: ["docs-search"], // sostituisce agents.defaults.skills quando impostato
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: id agente stabile (obbligatorio).
• default: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se non ne è impostato nessuno, la prima voce della lista è quella predefinita.
• model: la forma stringa sostituisce solo primary; la forma oggetto { primary, fallbacks } sostituisce entrambi ([] disabilita i fallback globali). I job cron che sostituiscono solo primary continuano a ereditare i fallback predefiniti, a meno che tu non imposti fallbacks: [].
• params: parametri stream per agente fusi sopra la voce di modello selezionata in agents.defaults.models. Usalo per override specifici dell’agente come cacheRetention, temperature o maxTokens senza duplicare l’intero catalogo modelli.
• skills: allowlist facoltativa di Skills per agente. Se omesso, l’agente eredita agents.defaults.skills quando impostato; una lista esplicita sostituisce i valori predefiniti invece di fonderli, e [] significa nessuna Skills.
• thinkingDefault: valore predefinito facoltativo del livello di thinking per agente (off | minimal | low | medium | high | xhigh | adaptive). Sostituisce agents.defaults.thinkingDefault per questo agente quando non è impostato alcun override per messaggio o per sessione.
• reasoningDefault: valore predefinito facoltativo della visibilità del ragionamento per agente (on | off | stream). Si applica quando non è impostato alcun override del ragionamento per messaggio o per sessione.
• fastModeDefault: valore predefinito facoltativo per agente per la modalità rapida (true | false). Si applica quando non è impostato alcun override della modalità rapida per messaggio o per sessione.
• embeddedHarness: override facoltativo del criterio harness di basso livello per agente. Usa { runtime: "codex", fallback: "none" } per rendere un agente solo Codex mentre gli altri agenti mantengono il fallback PI predefinito.
• runtime: descrittore runtime facoltativo per agente. Usa type: "acp" con i valori predefiniti di runtime.acp (agent, backend, mode, cwd) quando l’agente deve usare per impostazione predefinita sessioni harness ACP.
• identity.avatar: percorso relativo al workspace, URL http(s) o URI data:.
• identity deriva i valori predefiniti: ackReaction da emoji, mentionPatterns da name/emoji.
• subagents.allowAgents: allowlist di id agente per sessions_spawn (["*"] = qualsiasi; predefinito: solo lo stesso agente).
• Protezione di ereditarietà sandbox: se la sessione richiedente è in sandbox, sessions_spawn rifiuta le destinazioni che verrebbero eseguite senza sandbox.
• subagents.requireAgentId: quando è true, blocca le chiamate sessions_spawn che omettono agentId (forza la selezione esplicita del profilo; predefinito: false).

​

Routing multi-agente

{
  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" } },
  ],
}

​

Campi di corrispondenza del binding

• type (facoltativo): route per il routing normale (se manca, il tipo predefinito è route), acp per binding persistenti di conversazioni ACP.
• match.channel (obbligatorio)
• match.accountId (facoltativo; * = qualsiasi account; omesso = account predefinito)
• match.peer (facoltativo; { kind: direct|group|channel, id })
• match.guildId / match.teamId (facoltativo; specifico del canale)
• acp (facoltativo; solo per type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (esatto, senza peer/guild/team)
5. match.accountId: "*" (esteso all’intero canale)
6. Agente predefinito

​

Profili di accesso per agente

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

​

Sessione

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // salta il fork del thread padre sopra questo conteggio di token (0 disabilita)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // durata oppure false
      maxDiskBytes: "500mb", // budget rigido facoltativo
      highWaterBytes: "400mb", // obiettivo di pulizia facoltativo
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // autofocus off predefinito per inattività in ore (`0` disabilita)
      maxAgeHours: 0, // età massima rigida predefinita in ore (`0` disabilita)
    },
    mainKey: "main", // legacy (il runtime usa sempre "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Messaggi

{
  messages: {
    responsePrefix: "🦞", // oppure "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disabilita
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Prefisso della risposta

​

Reazione di conferma

• Per impostazione predefinita usa identity.emoji dell’agente attivo, altrimenti "👀". Imposta "" per disabilitare.
• Override per canale: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Ordine di risoluzione: account → canale → messages.ackReaction → fallback identity.
• Ambito: group-mentions (predefinito), group-all, direct, all.
• removeAckAfterReply: rimuove la conferma dopo la risposta su Slack, Discord e Telegram.
• messages.statusReactions.enabled: abilita le reazioni di stato del ciclo di vita su Slack, Discord e Telegram. Su Slack e Discord, se non impostato mantiene abilitate le reazioni di stato quando le reazioni di conferma sono attive. Su Telegram, impostalo esplicitamente su true per abilitare le reazioni di stato del ciclo di vita.

​

Debounce in ingresso

​

TTS (sintesi vocale)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}