Configurazione — agenti

Chiavi di configurazione con ambito agente sotto agents.*, multiAgent.*, session.*, messages.* e talk.*. Per canali, strumenti, runtime del gateway e altre chiavi di primo livello, vedi Riferimento della configurazione.

Valori predefiniti degli agenti

`agents.defaults.workspace`

Predefinito: ~/.openclaw/workspace.

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

`agents.defaults.repoRoot`

Root del repository facoltativa mostrata nella riga Runtime del prompt di sistema. Se non impostata, OpenClaw la rileva automaticamente risalendo dal workspace.

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

`agents.defaults.skills`

Allowlist predefinita facoltativa delle skill per gli agenti che non impostano 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 skill senza restrizioni per impostazione predefinita.
Ometti agents.list[].skills per ereditare i valori predefiniti.
Imposta agents.list[].skills: [] per nessuna skill.
Un elenco agents.list[].skills non vuoto è l’insieme finale per quell’agente; non viene unito ai valori predefiniti.

`agents.defaults.skipBootstrap`

Disabilita la creazione automatica dei file bootstrap del workspace (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md).

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

`agents.defaults.contextInjection`

Controlla quando i file bootstrap del workspace vengono inseriti nel prompt di sistema. Predefinito: "always".

"continuation-skip": i turni di continuazione sicuri (dopo una risposta completata dell’assistente) saltano la reiniezione bootstrap del workspace, riducendo la dimensione del prompt. Le esecuzioni Heartbeat e i nuovi tentativi post-Compaction ricostruiscono comunque il contesto.

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

`agents.defaults.bootstrapMaxChars`

Numero massimo di caratteri per file bootstrap del workspace prima del troncamento. Predefinito: 12000.

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

`agents.defaults.bootstrapTotalMaxChars`

Numero massimo totale di caratteri inseriti in tutti i file bootstrap del workspace. Predefinito: 60000.

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

`agents.defaults.bootstrapPromptTruncationWarning`

Controlla il testo di avviso visibile all’agente quando il contesto bootstrap viene troncato. Predefinito: "once".

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

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

Mappa di proprietà del budget di contesto

OpenClaw ha più budget di prompt/contesto ad alto volume e sono intenzionalmente divisi per sottosistema invece di fluire tutti attraverso un’unica manopola generica.

agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: normale inserimento bootstrap del workspace.
agents.defaults.startupContext.*: preludio di avvio una tantum per /new e /reset, inclusi i recenti file giornalieri memory/*.md.
skills.limits.*: l’elenco compatto delle skill inserito nel prompt di sistema.
agents.defaults.contextLimits.*: estratti runtime delimitati e blocchi posseduti dal runtime inseriti.
memory.qmd.limits.*: dimensionamento di snippet e inserimento per la ricerca in memoria indicizzata.

Usa l’override per agente corrispondente solo quando un agente necessita di un budget diverso:

agents.list[].skillsLimits.maxSkillsPromptChars
agents.list[].contextLimits.*

`agents.defaults.startupContext`

Controlla il preludio di avvio del primo turno inserito nelle esecuzioni bare /new e /reset.

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

`agents.defaults.contextLimits`

Valori predefiniti condivisi per le superfici di contesto runtime delimitate.

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

memoryGetMaxChars: limite predefinito dell’estratto memory_get prima che vengano aggiunti metadati di troncamento e avviso di continuazione.
memoryGetDefaultLines: finestra di righe predefinita di memory_get quando lines è omesso.
toolResultMaxChars: limite live del risultato dello strumento usato per risultati persistiti e recupero overflow.
postCompactionMaxChars: limite dell’estratto AGENTS.md usato durante l’inserimento di refresh post-Compaction.

`agents.list[].contextLimits`

Override per agente delle manopole condivise contextLimits. I campi omessi ereditano da agents.defaults.contextLimits.

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

`skills.limits.maxSkillsPromptChars`

Limite globale per l’elenco compatto delle skill inserito nel prompt di sistema. Questo non influisce sulla lettura dei file SKILL.md su richiesta.

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

`agents.list[].skillsLimits.maxSkillsPromptChars`

Override per agente del budget del prompt delle skill.

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

`agents.defaults.imageMaxDimensionPx`

Dimensione massima in pixel del lato più lungo dell’immagine nei blocchi immagine di trascrizione/strumento prima delle chiamate al provider. Predefinito: 1200. Valori più bassi di solito riducono l’uso di vision-token e la dimensione del payload della richiesta per esecuzioni ricche di screenshot. Valori più alti preservano più dettagli visivi.

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

`agents.defaults.userTimezone`

Fuso orario per il contesto del prompt di sistema (non per i timestamp dei messaggi). Fallback al fuso orario dell’host.

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

`agents.defaults.timeFormat`

Formato orario nel prompt di sistema. Predefinito: auto (preferenza del sistema operativo).

{
  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-2",
        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 suo modello vision.
- Usato anche come instradamento 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 tool/Plugin che generi immagini.
- Valori tipici: google/gemini-3.1-flash-image-preview per la generazione nativa di immagini Gemini, fal/fal-ai/flux/dev per fal, oppure openai/gpt-image-2 per OpenAI Images.
- Se selezioni direttamente un provider/modello, configura anche l’autenticazione corrispondente del provider (ad esempio GEMINI_API_KEY o GOOGLE_API_KEY per google/*, OPENAI_API_KEY o OpenAI Codex OAuth per openai/gpt-image-2, FAL_KEY per fal/*).
- Se omesso, image_generate può comunque dedurre un provider predefinito supportato da auth. 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 auth. 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’auth/chiave API corrispondente del provider.
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 auth. 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’auth/chiave API corrispondente del provider.
- Il provider bundle di generazione video Qwen supporta fino a 1 video di output, 1 immagine di input, 4 video di input, 10 secondi di durata 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 l’instradamento del modello.
- Se omesso, lo strumento PDF ripiega su imageModel, poi sul modello risolto della sessione/predefinito.
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 verbose predefinito per gli agenti. Valori: "off", "on", "full". Predefinito: "off".
elevatedDefault: livello predefinito di output elevated per gli agenti. Valori: "off", "on", "ask", "full". Predefinito: "on".
model.primary: formato provider/model (ad esempio openai/gpt-5.4 per accesso con chiave API oppure openai-codex/gpt-5.5 per Codex OAuth). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca del provider configurato per quell’esatto id modello e solo dopo ripiega sul provider predefinito configurato (comportamento di compatibilità deprecato, quindi preferisci provider/model esplicito). Se quel provider non espone più il modello predefinito configurato, OpenClaw ripiega sul primo provider/modello configurato invece di mostrare un valore predefinito obsoleto di un provider rimosso.
models: il catalogo di modelli configurato e la allowlist per /model. Ogni voce può includere alias (scorciatoia) e params (specifici del provider, ad esempio temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold).
- Modifiche sicure: usa openclaw config set agents.defaults.models '<json>' --strict-json --merge per aggiungere voci. config set rifiuta sostituzioni che rimuoverebbero voci esistenti della allowlist a meno che tu non passi --replace.
- I flussi configure/onboarding con ambito provider uniscono i modelli provider selezionati in questa mappa e preservano i provider non correlati già configurati.
- Per i modelli diretti OpenAI Responses, la Compaction lato server viene abilitata automaticamente. Usa params.responsesServerCompaction: false per smettere di inserire context_management, oppure params.responsesCompactThreshold per sovrascrivere la soglia. Vedi OpenAI server-side compaction.
params: parametri provider predefiniti globali applicati a tutti i modelli. Impostati in agents.defaults.params (ad esempio { cacheRetention: "long" }).
precedenza di unione di params (configurazione): agents.defaults.params (base globale) viene sovrascritto da agents.defaults.models["provider/model"].params (per modello), poi agents.list[].params (id agente corrispondente) sovrascrive per chiave. Vedi Prompt Caching per i dettagli.
embeddedHarness: policy predefinita del runtime embedded dell’agente a basso livello. Usa runtime: "auto" per lasciare che gli harness dei 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.
Gli strumenti di scrittura della configurazione che modificano questi campi (ad esempio /models set, /models set-image e i comandi add/remove di fallback) salvano la forma oggetto canonica e preservano gli elenchi di fallback esistenti quando possibile.
maxConcurrent: massimo numero di esecuzioni parallele degli agenti tra sessioni (ogni sessione resta comunque serializzata). Predefinito: 4.

`agents.defaults.embeddedHarness`

embeddedHarness controlla quale esecutore a basso livello esegue i turni embedded dell’agente. La maggior parte delle distribuzioni dovrebbe mantenere il valore predefinito { runtime: "auto", fallback: "pi" }. Usalo quando un Plugin attendibile fornisce un harness nativo, come l’harness bundle Codex app-server.

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

runtime: "auto", "pi" o un id harness Plugin registrato. Il Plugin Codex bundle registra codex.
fallback: "pi" o "none". "pi" mantiene l’harness PI integrato come fallback di compatibilità quando non viene selezionato alcun harness Plugin. "none" fa fallire la selezione di harness Plugin mancante o non supportata invece di usare silenziosamente PI. Gli errori dell’harness Plugin selezionato vengono sempre mostrati direttamente.
Override tramite ambiente: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> sovrascrive runtime; OPENCLAW_AGENT_HARNESS_FALLBACK=none disabilita il fallback PI per quel processo.
Per distribuzioni solo Codex, imposta model: "openai/gpt-5.5", embeddedHarness.runtime: "codex" e embeddedHarness.fallback: "none".
La scelta dell’harness viene fissata per id sessione dopo la prima esecuzione embedded. Le modifiche config/env influiscono su sessioni nuove o reimpostate, non su una trascrizione esistente. Le sessioni legacy con cronologia della trascrizione ma senza fissaggio registrato vengono trattate come fissate a PI. /status mostra id harness non-PI come codex accanto a Fast.
Questo controlla solo l’harness chat embedded. Generazione multimediale, vision, PDF, musica, video e TTS continuano a usare le rispettive impostazioni provider/modello.

Scorciatoie alias integrate (si applicano solo quando il modello è in agents.defaults.models):

Alias	Modello
`opus`	`anthropic/claude-opus-4-6`
`sonnet`	`anthropic/claude-sonnet-4-6`
`gpt`	`openai/gpt-5.4` o GPT-5.5 Codex OAuth configurato
`gpt-mini`	`openai/gpt-5.4-mini`
`gpt-nano`	`openai/gpt-5.4-nano`
`gemini`	`google/gemini-3.1-pro-preview`
`gemini-flash`	`google/gemini-3-flash-preview`
`gemini-flash-lite`	`google/gemini-3.1-flash-lite-preview`

Gli alias da te configurati prevalgono sempre su quelli predefiniti. I modelli Z.AI GLM-4.x abilitano automaticamente la modalità thinking a meno che tu non imposti --thinking off o definisca tu stesso agents.defaults.models["zai/<model>"].params.thinking. I modelli Z.AI abilitano tool_stream per impostazione predefinita per lo streaming delle chiamate agli strumenti. Imposta agents.defaults.models["zai/<model>"].params.tool_stream su false per disabilitarlo. I modelli Anthropic Claude 4.6 usano adaptive thinking per impostazione predefinita quando non è impostato alcun livello di thinking esplicito.

`agents.defaults.cliBackends`

Backend CLI facoltativi per esecuzioni di fallback solo testo (senza chiamate a strumenti). Utili come backup quando i provider API falliscono.

{
  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 text-first; 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`

Sostituisce l’intero prompt di sistema assemblato da OpenClaw con una stringa fissa. Impostalo a livello predefinito (agents.defaults.systemPromptOverride) o per agente (agents.list[].systemPromptOverride). I valori per agente hanno precedenza; un valore vuoto o composto solo da spazi viene ignorato. Utile per esperimenti controllati sul prompt.

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

`agents.defaults.promptOverlays`

Overlay di prompt indipendenti dal provider applicati per famiglia di modelli. Gli id modello della famiglia GPT-5 ricevono il contratto di comportamento condiviso tra provider; personality controlla solo il livello dello stile di interazione amichevole.

{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: {
          personality: "friendly", // friendly | on | off
        },
      },
    },
  },
}

"friendly" (predefinito) e "on" abilitano il livello di stile di interazione amichevole.
"off" disabilita solo il livello amichevole; il contratto di comportamento GPT-5 con tag resta abilitato.
Il valore legacy plugins.entries.openai.config.personality viene ancora letto quando questa impostazione condivisa non è impostata.

`agents.defaults.heartbeat`

Esecuzioni periodiche 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 (auth con chiave API) oppure 1h (auth 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 per 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 diretti. block sopprime la consegna a target diretti 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 del workspace.
isolatedSession: quando è true, ogni Heartbeat viene eseguito in una sessione nuova senza cronologia conversazionale precedente. Stesso pattern di isolamento di Cron sessionTarget: "isolated". Riduce il costo in token per Heartbeat da ~100K a ~2-5K token.
Per agente: imposta agents.list[].heartbeat. Quando un qualunque agente definisce heartbeat, solo quegli agenti eseguono Heartbeat.
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 Compaction registrato (facoltativo)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // usato quando identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disabilita la reiniezione
        model: "openrouter/anthropic/claude-sonnet-4-6", // override facoltativo del modello solo per Compaction
        notifyUser: true, // invia brevi notifiche quando la Compaction inizia e termina (predefinito: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

mode: default oppure safeguard (riassunto a blocchi per cronologie lunghe). Vedi Compaction.
provider: id di un Plugin provider di Compaction registrato. Quando impostato, viene chiamato summarize() del provider invece del riassunto LLM integrato. In caso di errore, ricade sull’implementazione integrata. Impostare un provider forza mode: "safeguard". Vedi Compaction.
timeoutSeconds: massimo numero di secondi consentiti per una singola operazione di Compaction prima che OpenClaw la interrompa. Predefinito: 900.
identifierPolicy: strict (predefinito), off o custom. strict antepone una guida integrata per la conservazione di identificatori opachi durante il riassunto della Compaction.
identifierInstructions: testo facoltativo personalizzato per la conservazione degli identificatori usato quando identifierPolicy=custom.
postCompactionSections: nomi facoltativi di sezioni H2/H3 di AGENTS.md da reinserire dopo la Compaction. Predefinito ["Session Startup", "Red Lines"]; imposta [] per disabilitare la reiniezione. Quando non impostato o impostato esplicitamente a quella coppia predefinita, vengono accettate anche le vecchie intestazioni Every Session/Safety come fallback legacy.
model: override facoltativo provider/model-id solo per il riassunto della Compaction. Usalo quando la sessione principale deve mantenere un modello ma i riassunti di Compaction devono essere eseguiti su un altro; se non impostato, la Compaction usa il modello primario della sessione.
notifyUser: quando true, invia brevi notifiche all’utente quando la Compaction inizia e quando termina (ad esempio “Compacting context…” e “Compaction complete”). Disabilitato per impostazione predefinita per mantenere la Compaction silenziosa.
memoryFlush: turno agentic silenzioso prima della auto-Compaction per archiviare memorie durature. Saltato quando il workspace è in sola lettura.

`agents.defaults.contextPruning`

Esegue il pruning dei vecchi risultati degli strumenti dal contesto in memoria prima di inviarlo all’LLM. Non modifica la cronologia della sessione su disco.

{
  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: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

Comportamento della modalità cache-ttl

mode: "cache-ttl" abilita i passaggi di pruning.
ttl controlla quanto spesso il pruning può essere eseguito di nuovo (dopo l’ultimo tocco della cache).
Il pruning prima riduce in modo soft i risultati degli strumenti troppo grandi, poi se necessario svuota in modo hard i risultati più vecchi.

Soft-trim mantiene inizio + fine e inserisce ... nel mezzo.Hard-clear sostituisce l’intero risultato dello strumento con il segnaposto.Note:

I blocchi immagine non vengono mai ridotti o svuotati.
I rapporti sono basati sui caratteri (approssimativi), non su conteggi esatti di token.
Se esistono meno di keepLastAssistants messaggi dell’assistente, il pruning viene saltato.

Vedi Session Pruning per i dettagli sul comportamento.

Block streaming

{
  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 diversi da 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–2500ms. Override per agente: agents.list[].humanDelay.

Vedi Streaming per i dettagli su comportamento e chunking.

Indicatori di digitazione

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

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

Vedi Indicatori di digitazione.

`agents.defaults.sandbox`

Sandboxing facoltativo per l’agente embedded. Vedi Sandboxing per la guida completa.

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

Dettagli della sandbox

Backend:

docker: runtime Docker locale (predefinito)
ssh: runtime remoto generico basato su SSH
openshell: runtime OpenShell

Quando viene selezionato backend: "openshell", le impostazioni specifiche del runtime si spostano in plugins.entries.openshell.config.Configurazione backend SSH:

target: target SSH nel formato user@host[:port]
command: comando client SSH (predefinito: ssh)
workspaceRoot: root remota assoluta usata per workspace per ambito
identityFile / certificateFile / knownHostsFile: file locali esistenti passati a OpenSSH
identityData / certificateData / knownHostsData: contenuti inline o SecretRef che OpenClaw materializza in file temporanei a runtime
strictHostKeyChecking / updateHostKeys: manopole di policy delle chiavi host OpenSSH

Precedenza auth SSH:

identityData prevale su identityFile
certificateData prevale su certificateFile
knownHostsData prevale su knownHostsFile
I valori *Data supportati da SecretRef vengono risolti dallo snapshot attivo del runtime dei secret prima che inizi la sessione sandbox

Comportamento backend SSH:

inizializza il workspace remoto una volta dopo create o recreate
poi mantiene canonico il workspace SSH remoto
instrada exec, gli strumenti file e i percorsi dei contenuti multimediali tramite SSH
non sincronizza automaticamente le modifiche remote verso l’host
non supporta container browser sandbox

Accesso al workspace:

none: workspace sandbox per ambito sotto ~/.openclaw/sandboxes
ro: workspace sandbox in /workspace, workspace agente montato in sola lettura in /agent
rw: workspace agente montato in lettura/scrittura in /workspace

Ambito:

session: container + workspace per sessione
agent: un container + workspace per agente (predefinito)
shared: container e workspace condivisi (nessun isolamento tra sessioni)

Configurazione Plugin OpenShell:

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

Modalità OpenShell:

mirror: inizializza il remoto dal locale prima di exec, sincronizza di nuovo dopo exec; il workspace locale resta canonico
remote: inizializza il remoto una volta quando la sandbox viene creata, poi mantiene canonico il workspace remoto

In modalità remote, le modifiche locali sull’host effettuate fuori da OpenClaw non vengono sincronizzate automaticamente nella sandbox dopo il passaggio di inizializzazione. Il trasporto avviene tramite SSH verso la sandbox OpenShell, ma il Plugin gestisce il ciclo di vita della sandbox e l’eventuale sincronizzazione mirror.setupCommand viene eseguito una volta dopo la creazione del container (tramite sh -lc). Richiede uscita di rete, root scrivibile e utente root.I container usano per impostazione predefinita network: "none" — imposta "bridge" (o una rete bridge personalizzata) se l’agente ha bisogno di accesso in uscita. "host" è bloccato. "container:<id>" è bloccato per impostazione predefinita a meno che tu non imposti esplicitamente sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true (break-glass).Gli allegati in ingresso vengono preparati in media/inbound/* nel workspace attivo.docker.binds monta directory host aggiuntive; i bind globali e per agente vengono uniti.Browser sandboxed (sandbox.browser.enabled): Chromium + CDP in un container. L’URL noVNC viene inserito nel prompt di sistema. Non richiede browser.enabled in openclaw.json. L’accesso osservatore noVNC usa per impostazione predefinita l’autenticazione VNC e OpenClaw emette un URL con token a breve durata (invece di esporre la password nell’URL condiviso).

allowHostControl: false (predefinito) impedisce alle sessioni sandboxed di puntare al browser host.
network assume per impostazione predefinita openclaw-sandbox-browser (rete bridge dedicata). Impostalo su bridge solo quando vuoi esplicitamente connettività bridge globale.
cdpSourceRange limita facoltativamente l’ingresso CDP al margine del container a un intervallo CIDR (ad esempio 172.21.0.1/32).
sandbox.browser.binds monta directory host aggiuntive solo nel container browser sandbox. Quando impostato (incluso []), sostituisce docker.binds per il container browser.
I valori predefiniti di avvio sono definiti in scripts/sandbox-browser-entrypoint.sh e ottimizzati per host container:
- --remote-debugging-address=127.0.0.1
- --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
- --user-data-dir=${HOME}/.chrome
- --no-first-run
- --no-default-browser-check
- --disable-3d-apis
- --disable-gpu
- --disable-software-rasterizer
- --disable-dev-shm-usage
- --disable-background-networking
- --disable-features=TranslateUI
- --disable-breakpad
- --disable-crash-reporter
- --renderer-process-limit=2
- --no-zygote
- --metrics-recording-only
- --disable-extensions (abilitato per impostazione predefinita)
- --disable-3d-apis, --disable-software-rasterizer e --disable-gpu sono abilitati per impostazione predefinita e possono essere disabilitati con OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 se l’uso di WebGL/3D lo richiede.
- OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 riabilita le estensioni se il tuo flusso di lavoro dipende da esse.
- --renderer-process-limit=2 può essere modificato con OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>; imposta 0 per usare il limite di processi predefinito di Chromium.
- più --no-sandbox e --disable-setuid-sandbox quando noSandbox è abilitato.
- I valori predefiniti sono la baseline dell’immagine container; usa un’immagine browser personalizzata con un entrypoint personalizzato per modificare i valori predefiniti del container.

Il browser sandboxing e sandbox.docker.binds sono disponibili solo con Docker. Costruisci le immagini:

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

`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", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        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 nessuno è impostato, la voce predefinita è la prima dell’elenco.
model: la forma stringa sovrascrive solo primary; la forma oggetto { primary, fallbacks } sovrascrive entrambi ([] disabilita i fallback globali). I Cron job che sovrascrivono solo primary ereditano comunque i fallback predefiniti a meno che tu non imposti fallbacks: [].
params: params di stream per agente uniti 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 di skill facoltativa per agente. Se omessa, l’agente eredita agents.defaults.skills quando impostato; un elenco esplicito sostituisce i valori predefiniti invece di unirli, e [] significa nessuna skill.
thinkingDefault: livello thinking predefinito facoltativo per agente (off | minimal | low | medium | high | xhigh | adaptive | max). Sovrascrive agents.defaults.thinkingDefault per questo agente quando non è impostato alcun override per messaggio o sessione.
reasoningDefault: visibilità predefinita facoltativa del reasoning per agente (on | off | stream). Si applica quando non è impostato alcun override di reasoning per messaggio o sessione.
fastModeDefault: valore predefinito facoltativo per agente per la modalità fast (true | false). Si applica quando non è impostato alcun override di modalità fast per messaggio o sessione.
embeddedHarness: override facoltativo per agente della policy dell’harness a basso livello. 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 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 (["*"] = qualunque; predefinito: solo lo stesso agente).
Guard di ereditarietà della sandbox: se la sessione richiedente è sandboxed, sessions_spawn rifiuta target che verrebbero eseguiti senza sandbox.
subagents.requireAgentId: quando è true, blocca le chiamate sessions_spawn che omettono agentId (forza la selezione esplicita del profilo; predefinito: false).

Instradamento multi-agente

Esegui più agenti isolati all’interno di un unico Gateway. Vedi Multi-Agent.

{
  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 l’instradamento normale (type mancante usa route come predefinito), acp per binding persistenti di conversazioni ACP.
match.channel (obbligatorio)
match.accountId (facoltativo; * = qualunque account; omesso = account predefinito)
match.peer (facoltativo; { kind: direct|group|channel, id })
match.guildId / match.teamId (facoltativi; specifici del canale)
acp (facoltativo; solo per type: "acp"): { mode, label, cwd, backend }

Ordine di corrispondenza deterministico:

match.peer
match.guildId
match.teamId
match.accountId (esatto, senza peer/guild/team)
match.accountId: "*" (a livello di canale)
Agente predefinito

All’interno di ciascun livello, vince la prima voce bindings corrispondente. Per le voci type: "acp", OpenClaw risolve per identità esatta della conversazione (match.channel + account + match.peer.id) e non usa l’ordine dei livelli di binding route sopra.

Profili di accesso per agente

Accesso completo (senza sandbox)

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

Strumenti + workspace di sola lettura

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

Nessun accesso al filesystem (solo messaggistica)

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

Vedi Sandbox e strumenti multi-agente per i dettagli sulla precedenza.

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, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

Dettagli dei campi della sessione

scope: strategia base di raggruppamento delle sessioni per i contesti di chat di gruppo.
- per-sender (predefinito): ogni mittente ottiene una sessione isolata all’interno di un contesto canale.
- global: tutti i partecipanti in un contesto canale condividono una singola sessione (usalo solo quando il contesto condiviso è intenzionale).
dmScope: come vengono raggruppate le DM.
- main: tutte le DM condividono la sessione principale.
- per-peer: isola per id mittente tra i canali.
- per-channel-peer: isola per canale + mittente (consigliato per inbox multiutente).
- per-account-channel-peer: isola per account + canale + mittente (consigliato per multi-account).
identityLinks: mappa gli id canonici ai peer con prefisso provider per la condivisione delle sessioni tra canali.
reset: policy di reset primaria. daily reimposta a atHour in ora locale; idle reimposta dopo idleMinutes. Quando sono configurati entrambi, prevale quello che scade per primo.
resetByType: override per tipo (direct, group, thread). Il legacy dm è accettato come alias di direct.
parentForkMaxTokens: totalTokens massimo della sessione parent consentito quando si crea una sessione thread forked (predefinito 100000).
- Se totalTokens del parent è superiore a questo valore, OpenClaw avvia una nuova sessione thread invece di ereditare la cronologia della trascrizione del parent.
- Imposta 0 per disabilitare questa guardia e consentire sempre il fork del parent.
mainKey: campo legacy. Il runtime usa sempre "main" per il bucket principale delle chat dirette.
agentToAgent.maxPingPongTurns: numero massimo di turni di risposta tra agenti durante gli scambi agente-a-agente (intero, intervallo: 0–5). 0 disabilita la catena ping-pong.
sendPolicy: corrispondenza tramite channel, chatType (direct|group|channel, con alias legacy dm), keyPrefix o rawKeyPrefix. Vince il primo deny.
maintenance: controlli di pulizia e retention dell’archivio sessioni.
- mode: warn emette solo avvisi; enforce applica la pulizia.
- pruneAfter: soglia di età per le voci obsolete (predefinito 30d).
- maxEntries: numero massimo di voci in sessions.json (predefinito 500).
- rotateBytes: ruota sessions.json quando supera questa dimensione (predefinito 10mb).
- resetArchiveRetention: retention per gli archivi di trascrizione *.reset.<timestamp>. Predefinito uguale a pruneAfter; imposta false per disabilitare.
- maxDiskBytes: budget facoltativo del disco per la directory delle sessioni. In modalità warn registra avvisi; in modalità enforce rimuove prima gli artefatti/sessioni più vecchi.
- highWaterBytes: target facoltativo dopo la pulizia del budget. Predefinito 80% di maxDiskBytes.
threadBindings: valori predefiniti globali per le funzionalità di sessione legate ai thread.
- enabled: interruttore predefinito principale (i provider possono fare override; Discord usa channels.discord.threadBindings.enabled)
- idleHours: auto-unfocus predefinito per inattività in ore (0 disabilita; i provider possono fare override)
- maxAgeHours: età massima rigida predefinita in ore (0 disabilita; i provider possono fare override)

Messaggi

{
  messages: {
    responsePrefix: "🦞", // or "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 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

Prefisso di risposta

Override per canale/account: channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix. Risoluzione (vince il più specifico): account → canale → globale. "" disabilita e interrompe la cascata. "auto" deriva [{identity.name}]. Variabili template:

Variabile	Descrizione	Esempio
`{model}`	Nome breve del modello	`claude-opus-4-6`
`{modelFull}`	Identificatore completo del modello	`anthropic/claude-opus-4-6`
`{provider}`	Nome del provider	`anthropic`
`{thinkingLevel}`	Livello di thinking corrente	`high`, `low`, `off`
`{identity.name}`	Nome dell’identità dell’agente	(uguale a `"auto"`)

Le variabili non distinguono tra maiuscole e minuscole. {think} è un alias di {thinkingLevel}.

Reazione ack

Il valore predefinito è 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 l’ack 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 ack sono attive. Su Telegram, impostalo esplicitamente su true per abilitare le reazioni di stato del ciclo di vita.

Debounce in ingresso

Raggruppa messaggi rapidi solo testo dallo stesso mittente in un singolo turno dell’agente. I contenuti multimediali/allegati fanno flush immediato. I comandi di controllo aggirano il debounce.

TTS (text-to-speech)

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

auto controlla la modalità auto-TTS predefinita: off, always, inbound o tagged. /tts on|off può sovrascrivere le preferenze locali, e /tts status mostra lo stato effettivo.
summaryModel sovrascrive agents.defaults.model.primary per il riepilogo automatico.
modelOverrides è abilitato per impostazione predefinita; modelOverrides.allowProvider ha come predefinito false (opt-in).
Le chiavi API usano come fallback ELEVENLABS_API_KEY/XI_API_KEY e OPENAI_API_KEY.
openai.baseUrl sovrascrive l’endpoint TTS OpenAI. L’ordine di risoluzione è configurazione, poi OPENAI_TTS_BASE_URL, poi https://api.openai.com/v1.
Quando openai.baseUrl punta a un endpoint non OpenAI, OpenClaw lo tratta come un server TTS compatibile con OpenAI e rilassa la validazione di modello/voce.

Talk

Valori predefiniti per la modalità Talk (macOS/iOS/Android).

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
    },
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

talk.provider deve corrispondere a una chiave in talk.providers quando sono configurati più provider Talk.
Le chiavi legacy piatte di Talk (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) servono solo per compatibilità e vengono migrate automaticamente in talk.providers.<provider>.
Gli ID voce usano come fallback ELEVENLABS_VOICE_ID o SAG_VOICE_ID.
providers.*.apiKey accetta stringhe plaintext o oggetti SecretRef.
Il fallback ELEVENLABS_API_KEY si applica solo quando non è configurata alcuna chiave API Talk.
providers.*.voiceAliases consente alle direttive Talk di usare nomi amichevoli.
silenceTimeoutMs controlla quanto tempo la modalità Talk aspetta dopo il silenzio dell’utente prima di inviare la trascrizione. Se non impostato, mantiene la finestra di pausa predefinita della piattaforma (700 ms su macOS e Android, 900 ms su iOS).

Correlati

Riferimento della configurazione — tutte le altre chiavi di configurazione
Configurazione — attività comuni e configurazione rapida
Esempi di configurazione

Gateway

Remote access

Security

Nodes and media

Web interfaces

​Valori predefiniti degli agenti

​agents.defaults.workspace

​agents.defaults.repoRoot

​agents.defaults.skills

​agents.defaults.skipBootstrap

​agents.defaults.contextInjection

​agents.defaults.bootstrapMaxChars

​agents.defaults.bootstrapTotalMaxChars

​agents.defaults.bootstrapPromptTruncationWarning

​Mappa di proprietà del budget di contesto

​agents.defaults.startupContext

​agents.defaults.contextLimits

​agents.list[].contextLimits

​skills.limits.maxSkillsPromptChars

​agents.list[].skillsLimits.maxSkillsPromptChars

​agents.defaults.imageMaxDimensionPx

​agents.defaults.userTimezone

​agents.defaults.timeFormat

​agents.defaults.model

​agents.defaults.embeddedHarness

​agents.defaults.cliBackends

​agents.defaults.systemPromptOverride

​agents.defaults.promptOverlays

​agents.defaults.heartbeat

​agents.defaults.compaction

​agents.defaults.contextPruning

​Block streaming

​Indicatori di digitazione

​agents.defaults.sandbox

​agents.list (override per agente)

​Instradamento multi-agente

​Campi di corrispondenza del binding

​Profili di accesso per agente

​Sessione

​Messaggi

​Prefisso di risposta

​Reazione ack

​Debounce in ingresso

​TTS (text-to-speech)

​Talk

​Correlati