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, consulta il riferimento di configurazione.

# Impostazioni predefinite degli agenti

# agents.defaults.workspace

Predefinito: ~/.openclaw/workspace.

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

# agents.defaults.repoRoot

Radice del repository opzionale mostrata nella riga Runtime del prompt di sistema. Se non impostata, OpenClaw la rileva automaticamente risalendo dalla workspace.

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

# agents.defaults.skills

Allowlist di Skills predefinita opzionale 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 Skills senza restrizioni per impostazione predefinita.
• Ometti agents.list[].skills per ereditare i valori predefiniti.
• Imposta agents.list[].skills: [] per nessuna Skill.
• Una lista agents.list[].skills non vuota è il set finale per quell'agente; non viene unita ai valori predefiniti.

# agents.defaults.skipBootstrap

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

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

# agents.defaults.skipOptionalBootstrapFiles

Salta la creazione di file opzionali selezionati della workspace continuando a scrivere i file di bootstrap richiesti. Valori validi: SOUL.md, USER.md, HEARTBEAT.md e IDENTITY.md.

{
  agents: {
    defaults: {
      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
    },
  },
}

# agents.defaults.contextInjection

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

• "continuation-skip": i turni di continuazione sicuri (dopo una risposta dell'assistente completata) saltano il reinserimento del bootstrap della workspace, riducendo la dimensione del prompt. Le esecuzioni Heartbeat e i tentativi post-Compaction ricostruiscono comunque il contesto.
• "never": disabilita il bootstrap della workspace e l'inserimento dei file di contesto a ogni turno. Usalo solo per agenti che gestiscono completamente il ciclo di vita del proprio prompt (motori di contesto personalizzati, runtime nativi che costruiscono il proprio contesto o workflow specializzati senza bootstrap). Anche i turni di Heartbeat e di ripristino da Compaction saltano l'inserimento.

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

# agents.defaults.bootstrapMaxChars

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

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

# agents.defaults.bootstrapTotalMaxChars

Numero massimo totale di caratteri inseriti tra tutti i file di bootstrap della workspace. Predefinito: 60000.

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

# agents.defaults.bootstrapPromptTruncationWarning

Controlla l'avviso del prompt di sistema visibile all'agente quando il contesto di bootstrap viene troncato. Predefinito: "once".

• "off": non inserire mai testo di avviso sul troncamento nel prompt di sistema.
• "once": inserisci un avviso conciso una volta per ogni firma di troncamento univoca (consigliato).
• "always": inserisci un avviso conciso a ogni esecuzione quando esiste un troncamento.

I conteggi raw/inseriti dettagliati e i campi di tuning della configurazione restano nella diagnostica come report e log di contesto/stato; il contesto utente/runtime WebChat ordinario riceve solo l'avviso conciso di ripristino.

{
  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 suddivisi per sottosistema invece di passare tutti attraverso un'unica manopola generica.

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: normale inserimento del bootstrap della workspace.
• agents.defaults.startupContext.*: preambolo una tantum di reset/avvio dell'esecuzione del modello, inclusi i file giornalieri recenti memory/*.md. I comandi bare chat /new e /reset vengono confermati senza invocare il modello.
• skills.limits.*: la lista compatta di Skills inserita nel prompt di sistema.
• agents.defaults.contextLimits.*: estratti runtime limitati e blocchi inseriti di proprietà del runtime.
• memory.qmd.limits.*: dimensionamento dello snippet di ricerca memoria indicizzato e dell'inserimento.

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 preambolo di avvio del primo turno inserito nelle esecuzioni del modello di reset/avvio. I comandi bare chat /new e /reset confermano il reset senza invocare il modello, quindi non caricano questo preambolo.

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

# agents.defaults.contextLimits

Valori predefiniti condivisi per superfici di contesto runtime limitate.

{
  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 dei risultati degli strumenti usato per risultati persistiti e ripristino da overflow.
• postCompactionMaxChars: limite dell'estratto AGENTS.md usato durante l'inserimento di aggiornamento post-Compaction.

# agents.list[].contextLimits

Override per agente per le manopole contextLimits condivise. 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 la lista compatta di Skills inserita 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 per il budget del prompt delle Skills.

{
  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 transcript/strumenti prima delle chiamate ai provider. Predefinito: 1200.

Valori più bassi di solito riducono l'uso di token visivi e la dimensione del payload della richiesta per esecuzioni con molti screenshot. Valori più alti conservano 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). Ripiega sul fuso orario dell'host.

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

# agents.defaults.timeFormat

Formato dell'ora 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
      agentRuntime: {
        id: "pi", // pi | auto | registered harness id, e.g. codex
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: accetta una stringa ("provider/model") oppure 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 una stringa ("provider/model") oppure un oggetto ({ primary, fallbacks }).
  • Usato dal percorso dello strumento image come configurazione del modello di visione.
  • Usato anche come instradamento di fallback quando il modello selezionato/predefinito non può accettare input immagine.
  • Preferisci riferimenti provider/model espliciti. Gli ID semplici sono accettati per compatibilità; se un ID semplice corrisponde univocamente a una voce configurata abilitata alle immagini in models.providers.*.models, OpenClaw lo qualifica per quel provider. Le corrispondenze configurate ambigue richiedono un prefisso provider esplicito.
• imageGenerationModel: accetta una stringa ("provider/model") oppure un oggetto ({ primary, fallbacks }).
  • Usato dalla capacità condivisa di generazione immagini e da qualsiasi futura superficie strumento/Plugin che genera immagini.
  • Valori tipici: google/gemini-3.1-flash-image-preview per la generazione immagini nativa di Gemini, fal/fal-ai/flux/dev per fal, openai/gpt-image-2 per OpenAI Images, oppure openai/gpt-image-1.5 per output OpenAI PNG/WebP con sfondo trasparente.
  • Se selezioni direttamente un provider/modello, configura anche l’autenticazione del provider corrispondente (per esempio GEMINI_API_KEY o GOOGLE_API_KEY per google/*, OPENAI_API_KEY o OpenAI Codex OAuth per openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY per fal/*).
  • Se omesso, image_generate può comunque inferire un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider registrati per la generazione immagini in ordine di ID provider.
• musicGenerationModel: accetta una stringa ("provider/model") oppure 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 oppure minimax/music-2.6.
  • Se omesso, music_generate può comunque inferire un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider registrati per la generazione musicale in ordine di ID provider.
  • Se selezioni direttamente un provider/modello, configura anche l’autenticazione/chiave API del provider corrispondente.
• videoGenerationModel: accetta una stringa ("provider/model") oppure 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 oppure qwen/wan2.7-r2v.
  • Se omesso, video_generate può comunque inferire un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider registrati per la generazione video in ordine di ID provider.
  • Se selezioni direttamente un provider/modello, configura anche l’autenticazione/chiave API del provider corrispondente.
  • Il provider di generazione video Qwen incluso supporta fino a 1 video di output, 1 immagine di input, 4 video di input, 10 secondi di durata e opzioni a livello di provider size, aspectRatio, resolution, audio e watermark.
• pdfModel: accetta una stringa ("provider/model") oppure 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 di dimensione PDF predefinito per lo strumento pdf quando maxBytesMb non viene passato al momento della chiamata.
• pdfMaxPages: numero massimo predefinito di pagine considerate dalla modalità di fallback dell’estrazione nello strumento pdf.
• verboseDefault: livello verboso predefinito per gli agenti. Valori: "off", "on", "full". Predefinito: "off".
• toolProgressDetail: modalità di dettaglio per i riepiloghi strumenti di /verbose e le righe strumento delle bozze di avanzamento. Valori: "explain" (predefinito, etichette umane compatte) oppure "raw" (aggiunge comando/dettaglio grezzo quando disponibile). agents.list[].toolProgressDetail per agente sovrascrive questo valore predefinito.
• reasoningDefault: visibilità predefinita del ragionamento per gli agenti. Valori: "off", "on", "stream". agents.list[].reasoningDefault per agente sovrascrive questo valore predefinito. I valori predefiniti di ragionamento configurati vengono applicati solo per proprietari, mittenti autorizzati o contesti Gateway di amministratore operatore quando non è impostata alcuna sovrascrittura di ragionamento per messaggio o sessione.
• elevatedDefault: livello predefinito di output elevato per gli agenti. Valori: "off", "on", "ask", "full". Predefinito: "on".
• model.primary: formato provider/model (ad es. openai/gpt-5.5 per accesso con chiave API OpenAI o Codex OAuth). Se ometti il provider, OpenClaw prova prima un alias, poi una corrispondenza univoca di 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 dei modelli configurato e l’allowlist per /model. Ogni voce può includere alias (scorciatoia) e params (specifici del provider, per esempio temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, chat_template_kwargs, extra_body/extraBody).
  • Modifiche sicure: usa openclaw config set agents.defaults.models '<json>' --strict-json --merge per aggiungere voci. config set rifiuta sostituzioni che rimuoverebbero voci allowlist esistenti a meno che non passi --replace.
  • I flussi di configurazione/onboarding con ambito provider uniscono i modelli provider selezionati in questa mappa e conservano i provider non correlati già configurati.
  • Per modelli OpenAI Responses diretti, la Compaction lato server è abilitata automaticamente. Usa params.responsesServerCompaction: false per interrompere l’iniezione di context_management, oppure params.responsesCompactThreshold per sovrascrivere la soglia. Vedi Compaction lato server OpenAI.
• params: parametri provider predefiniti globali applicati a tutti i modelli. Impostati in agents.defaults.params (ad es. { cacheRetention: "long" }).
• Precedenza di unione di params (configurazione): agents.defaults.params (base globale) è 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.
• params.extra_body/params.extraBody: JSON avanzato pass-through unito nei corpi delle richieste api: "openai-completions" per proxy compatibili con OpenAI. Se entra in conflitto con chiavi di richiesta generate, il corpo extra ha la precedenza; le route completions non native rimuovono comunque store specifico di OpenAI dopo l’unione.
• params.chat_template_kwargs: argomenti chat-template compatibili con vLLM/OpenAI uniti nei corpi di richiesta di primo livello api: "openai-completions". Per vllm/nemotron-3-* con thinking disattivato, il Plugin vLLM incluso invia automaticamente enable_thinking: false e force_nonempty_content: true; chat_template_kwargs esplicito sovrascrive i valori predefiniti generati, ed extra_body.chat_template_kwargs mantiene comunque la precedenza finale. Per i controlli thinking di vLLM Qwen, imposta params.qwenThinkingFormat su "chat-template" oppure "top-level" in quella voce modello.
• compat.supportedReasoningEfforts: elenco degli sforzi di ragionamento compatibili con OpenAI per modello. Includi "xhigh" per endpoint personalizzati che lo accettano davvero; OpenClaw espone quindi /think xhigh nei menu dei comandi, nelle righe sessione del Gateway, nella validazione delle patch di sessione, nella validazione CLI agente e nella validazione llm-task per quel provider/modello configurato. Usa compat.reasoningEffortMap quando il backend richiede un valore specifico del provider per un livello canonico.
• params.preserveThinking: consenso esplicito solo Z.AI per il thinking conservato. Quando abilitato e il thinking è attivo, OpenClaw invia thinking.clear_thinking: false e riproduce il precedente reasoning_content; vedi thinking Z.AI e thinking conservato.
• agentRuntime: criterio predefinito del runtime agente di basso livello. Un ID omesso usa come predefinito OpenClaw Pi. Usa id: "pi" per forzare l’harness PI integrato, id: "auto" per lasciare che gli harness Plugin registrati rivendichino i modelli supportati e usare PI quando nessuno corrisponde, un ID harness registrato come id: "codex" per richiedere quell’harness, oppure un alias backend CLI supportato come id: "claude-cli". I runtime Plugin espliciti falliscono in modo chiuso quando l’harness non è disponibile o fallisce. Mantieni i riferimenti modello canonici come provider/model; seleziona Codex, Claude CLI, Gemini CLI e altri backend di esecuzione tramite la configurazione runtime invece dei prefissi provider runtime legacy. Vedi Runtime agenti per come questo differisce dalla selezione provider/modello.
• Gli writer di configurazione che modificano questi campi (per esempio /models set, /models set-image e i comandi di aggiunta/rimozione fallback) salvano la forma oggetto canonica e conservano le liste di fallback esistenti quando possibile.
• maxConcurrent: numero massimo di esecuzioni agente parallele tra sessioni (ogni sessione resta comunque serializzata). Predefinito: 4.

# agents.defaults.agentRuntime

agentRuntime controlla quale esecutore di basso livello esegue i turni agente. La maggior parte dei deployment dovrebbe mantenere il runtime OpenClaw Pi predefinito. Usalo quando un Plugin attendibile fornisce un harness nativo, come l’harness app-server Codex incluso, oppure quando vuoi un backend CLI supportato come Claude CLI. Per il modello mentale, vedi Runtime agenti.

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

• id: "auto", "pi", un ID harness Plugin registrato oppure un alias backend CLI supportato. Il Plugin Codex incluso registra codex; il Plugin Anthropic incluso fornisce il backend CLI claude-cli.
• id: "auto" consente agli harness Plugin registrati di rivendicare i turni supportati e usa PI quando nessun harness corrisponde. Un runtime Plugin esplicito come id: "codex" richiede quell’harness e fallisce in modo chiuso se non è disponibile o fallisce.
• Sovrascrittura d’ambiente: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> sovrascrive id per quel processo.
• I modelli agente OpenAI usano l’harness Codex per impostazione predefinita; agentRuntime.id: "codex" resta valido quando vuoi renderlo esplicito.
• Per i deployment Claude CLI, preferisci model: "anthropic/claude-opus-4-7" più agentRuntime.id: "claude-cli". I riferimenti modello legacy claude-cli/claude-opus-4-7 funzionano ancora per compatibilità, ma la nuova configurazione dovrebbe mantenere canonica la selezione provider/modello e mettere il backend di esecuzione in agentRuntime.id.
• Le chiavi dei criteri runtime più vecchie vengono riscritte in agentRuntime da openclaw doctor --fix.
• La scelta dell’harness viene fissata per ID sessione dopo la prima esecuzione incorporata. Le modifiche a configurazione/env influenzano le sessioni nuove o reimpostate, non una trascrizione esistente. Le sessioni OpenAI legacy con cronologia della trascrizione ma senza pin registrato usano Codex; i pin OpenAI PI obsoleti possono essere riparati con openclaw doctor --fix. /status riporta il runtime effettivo, per esempio Runtime: OpenClaw Pi Default oppure Runtime: OpenAI Codex.
• Questo controlla solo l’esecuzione dei turni agente testuali. Generazione media, visione, PDF, musica, video e TTS usano ancora le rispettive impostazioni provider/modello.

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

I tuoi alias configurati hanno sempre la precedenza sui valori predefiniti.

I modelli Z.AI GLM-4.x abilitano automaticamente la modalità di ragionamento a meno che tu non imposti --thinking off o definisca autonomamente 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 per impostazione predefinita il ragionamento adaptive quando non è impostato alcun livello di ragionamento esplicito.

# agents.defaults.cliBackends

Backend CLI facoltativi per esecuzioni di fallback solo testuali (senza chiamate agli strumenti). Utili come backup quando i provider API non riescono.

{
  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",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

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

# agents.defaults.systemPromptOverride

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

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

# agents.defaults.promptOverlays

Overlay dei prompt indipendenti dal provider applicati per famiglia di modelli. Gli ID dei modelli della famiglia GPT-5 ricevono il contratto comportamentale 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 dello stile di interazione amichevole.
• "off" disabilita solo il livello amichevole; il contratto comportamentale GPT-5 contrassegnato resta abilitato.
• Il valore legacy plugins.entries.openai.config.personality viene ancora letto quando questa impostazione condivisa non è impostata.

# agents.defaults.heartbeat

Esecuzioni periodiche di 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)
        skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes
        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 su 0m per disabilitare.
• includeSystemPromptSection: quando è false, omette la sezione Heartbeat dal prompt di sistema e salta l’iniezione di HEARTBEAT.md nel contesto di bootstrap. Predefinito: true.
• suppressToolErrorWarnings: quando è true, sopprime i payload di avviso sugli errori degli strumenti durante le esecuzioni di heartbeat.
• timeoutSeconds: tempo massimo in secondi consentito per un turno dell’agente heartbeat prima che venga interrotto. Lascia non impostato per usare agents.defaults.timeoutSeconds.
• directPolicy: criterio di recapito diretto/DM. allow (predefinito) consente il recapito a destinazione diretta. block sopprime il recapito a destinazione diretta ed emette reason=dm-blocked.
• lightContext: quando è true, le esecuzioni di heartbeat usano un contesto di bootstrap leggero e mantengono solo HEARTBEAT.md dai file di bootstrap dell’area di lavoro.
• isolatedSession: quando è true, ogni heartbeat viene eseguito in una sessione nuova senza cronologia di conversazione precedente. Stesso schema di isolamento di cron sessionTarget: "isolated". Riduce il costo in token per heartbeat da ~100K a ~2-5K token.
• skipWhenBusy: quando è true, le esecuzioni di heartbeat vengono rinviate su corsie occupate aggiuntive: lavoro di sottoagenti o comandi annidati. Le corsie Cron rinviano sempre gli heartbeat, anche senza questo flag.
• Per agente: imposta agents.list[].heartbeat. Quando un agente definisce heartbeat, solo quegli agenti eseguono heartbeat.
• Gli heartbeat eseguono turni completi dell’agente: intervalli più brevi consumano più token.

# agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          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 o safeguard (riepilogo a blocchi per cronologie lunghe). Vedi Compaction.
• provider: ID di un provider Plugin di compaction registrato. Quando impostato, viene chiamato summarize() del provider invece del riepilogo LLM integrato. In caso di errore, ripiega su quello integrato. Impostare un provider forza mode: "safeguard". Vedi Compaction.
• timeoutSeconds: secondi massimi consentiti per una singola operazione di compaction prima che OpenClaw la interrompa. Predefinito: 900.
• keepRecentTokens: budget del punto di taglio Pi per mantenere testualmente la coda più recente della trascrizione. /compact manuale lo rispetta quando è impostato esplicitamente; altrimenti la compaction manuale è un checkpoint rigido.
• identifierPolicy: strict (predefinito), off o custom. strict antepone la guida integrata per la conservazione degli identificatori opachi durante il riepilogo di compaction.
• identifierInstructions: testo personalizzato facoltativo per la conservazione degli identificatori usato quando identifierPolicy=custom.
• qualityGuard: controlli con nuovo tentativo in caso di output malformato per riepiloghi safeguard. Abilitato per impostazione predefinita in modalità safeguard; imposta enabled: false per saltare l’audit.
• midTurnPrecheck: controllo facoltativo della pressione del ciclo strumenti Pi. Quando enabled: true, OpenClaw controlla la pressione del contesto dopo l’aggiunta dei risultati degli strumenti e prima della chiamata successiva al modello. Se il contesto non rientra più, interrompe il tentativo corrente prima di inviare il prompt e riutilizza il percorso di recupero del precheck esistente per troncare i risultati degli strumenti o compattare e riprovare. Funziona con entrambe le modalità di compaction default e safeguard. Predefinito: disabilitato.
• postCompactionSections: nomi di sezioni H2/H3 facoltative di AGENTS.md da reiniettare dopo la compaction. Predefinito: ["Session Startup", "Red Lines"]; imposta [] per disabilitare la reiniezione. Quando non impostato o impostato esplicitamente su quella coppia predefinita, anche le intestazioni precedenti Every Session/Safety sono accettate come fallback legacy.
• model: override facoltativo provider/model-id solo per il riepilogo di compaction. Usalo quando la sessione principale deve mantenere un modello ma i riepiloghi di compaction devono essere eseguiti su un altro; quando non impostato, la compaction usa il modello primario della sessione.
• maxActiveTranscriptBytes: soglia di byte facoltativa (number o stringhe come "20mb") che attiva la normale compaction locale prima di un’esecuzione quando il JSONL attivo supera la soglia. Richiede truncateAfterCompaction affinché una compaction riuscita possa ruotare verso una trascrizione successore più piccola. Disabilitato quando non impostato o 0.
• notifyUser: quando true, invia brevi avvisi all’utente quando la compaction inizia e quando termina (per esempio, "Compacting context..." e "Compaction complete"). Disabilitato per impostazione predefinita per mantenere silenziosa la compaction.
• memoryFlush: turno agentico silenzioso prima della compaction automatica per archiviare memorie durevoli. Imposta model su un provider/modello esatto come ollama/qwen3:8b quando questo turno di housekeeping deve restare su un modello locale; l’override non eredita la catena di fallback della sessione attiva. Saltato quando l’area di lavoro è in sola lettura.

# agents.defaults.contextPruning

Elimina i vecchi risultati degli strumenti dal contesto in memoria prima dell’invio all’LLM. Non modifica la cronologia della sessione su disco.

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        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"] },
      },
    },
  },
}

Vedi Eliminazione delle sessioni per i dettagli del comportamento.

# 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 (use minMs/maxMs)
    },
  },
}

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

Vedi Streaming per dettagli su comportamento e suddivisione in blocchi.

# 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.

Vedi Indicatori di digitazione.

# agents.defaults.sandbox

Sandboxing opzionale per l'agente incorporato. 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",
          // SecretRefs / inline contents also supported:
          // 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", // optional
        gatewayEndpoint: "https://lab.example", // optional
        policy: "strict", // optional OpenShell policy id
        providers: ["openai"], // optional
        autoProviders: true,
        timeoutSeconds: 120,
      },
    },
  },
},
}

Il sandboxing del browser e sandbox.docker.binds sono solo Docker.

Crea immagini (da un checkout dei sorgenti):

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

Per installazioni npm senza un checkout dei sorgenti, vedi Sandboxing § Immagini e configurazione per comandi docker build inline.

# agents.list (override per agente)

Usa agents.list[].tts per assegnare a un agente il proprio provider TTS, voce, modello, stile o modalità TTS automatica. Il blocco dell'agente viene unito in profondità sopra messages.tts, quindi le credenziali condivise possono restare in un unico punto mentre i singoli agenti sovrascrivono solo i campi voce o provider di cui hanno bisogno. L'override dell'agente attivo si applica alle risposte vocali automatiche, a /tts audio, /tts status e allo strumento agente tts. Vedi Text-to-speech per esempi di provider e precedenza.

{
  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
        agentRuntime: { id: "auto" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        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 prima voce dell'elenco è il valore predefinito.
• model: la forma stringa imposta un primario rigoroso per agente senza fallback del modello; anche la forma oggetto { primary } è rigorosa, a meno che tu non aggiunga fallbacks. Usa { primary, fallbacks: [...] } per abilitare il fallback per quell'agente, oppure { primary, fallbacks: [] } per rendere esplicito il comportamento rigoroso. I Cron job che sovrascrivono solo primary ereditano comunque i fallback predefiniti, a meno che tu non imposti fallbacks: [].
• params: parametri di stream per agente uniti sopra la voce del modello selezionata in agents.defaults.models. Usalo per override specifici dell'agente come cacheRetention, temperature o maxTokens senza duplicare l'intero catalogo dei modelli.
• tts: override opzionali della sintesi vocale per agente. Il blocco viene unito in profondità sopra messages.tts, quindi mantieni le credenziali condivise del provider e la policy di fallback in messages.tts e imposta qui solo valori specifici della persona, come provider, voce, modello, stile o modalità automatica.
• skills: allowlist opzionale delle skill per agente. Se omesso, l'agente eredita agents.defaults.skills quando impostato; un elenco esplicito sostituisce i valori predefiniti invece di unirli, e [] significa nessuna skill.
• thinkingDefault: livello di thinking predefinito opzionale 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. Il profilo provider/modello selezionato controlla quali valori sono validi; per Google Gemini, adaptive mantiene il thinking dinamico gestito dal provider (thinkingLevel omesso su Gemini 3/3.1, thinkingBudget: -1 su Gemini 2.5).
• reasoningDefault: visibilità predefinita opzionale del ragionamento per agente (on | off | stream). Sovrascrive agents.defaults.reasoningDefault per questo agente quando non è impostato alcun override del ragionamento per messaggio o sessione.
• fastModeDefault: valore predefinito opzionale per agente per la modalità veloce (true | false). Si applica quando non è impostato alcun override della modalità veloce per messaggio o sessione.
• agentRuntime: override opzionale della policy di runtime di basso livello per agente. Usa { id: "codex" } per rendere un agente solo Codex mentre gli altri agenti mantengono il fallback PI predefinito in modalità auto.
• runtime: descrittore di runtime opzionale 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 con 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 target espliciti sessions_spawn.agentId (["*"] = qualsiasi; valore predefinito: solo lo stesso agente). Includi l'id del richiedente quando devono essere consentite chiamate agentId rivolte a se stesso.
• Protezione dell'ereditarietà della sandbox: se la sessione del richiedente è in sandbox, sessions_spawn rifiuta i target che verrebbero eseguiti senza sandbox.
• subagents.requireAgentId: quando è true, blocca le chiamate sessions_spawn che omettono agentId (forza la selezione esplicita del profilo; valore predefinito: false).

# Routing multi-agente

Esegui più agenti isolati all'interno di un solo Gateway. Consulta 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 dei binding

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

Ordine di corrispondenza deterministico:

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (esatto, nessun peer/guild/team)
5. match.accountId: "*" (a livello di canale)
6. Agente predefinito

All'interno di ogni livello, vince la prima voce bindings corrispondente.

Per le voci type: "acp", OpenClaw risolve in base all'identità esatta della conversazione (match.channel + account + match.peer.id) e non usa l'ordine dei livelli di binding di route sopra.

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

Consulta 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",
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      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",
    },
  },
}

# Messaggi

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "steer", // steer | queue (legacy one-at-a-time) | followup | collect | steer-backlog | steer+backlog | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "steer",
        telegram: "steer",
      },
    },
    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 la più specifica): account → canale → globale. "" disabilita e interrompe la cascata. "auto" deriva [{identity.name}].

Variabili del template:

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

# 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 dell'identità.
• Ambito: group-mentions (predefinito), group-all, direct, all.
• removeAckAfterReply: rimuove la conferma dopo la risposta sui canali che supportano le reazioni, come Slack, Discord, Telegram, WhatsApp e BlueBubbles.
• 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

Raggruppa i messaggi rapidi di solo testo dello stesso mittente in un singolo turno dell'agente. Media/allegati vengono inviati subito. I comandi di controllo bypassano il debounce.

# 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",
      providers: {
        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,
          },
        },
        microsoft: {
          voice: "en-US-AvaMultilingualNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        },
        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 valore predefinito false (opt-in).
• Le chiavi API usano come fallback ELEVENLABS_API_KEY/XI_API_KEY e OPENAI_API_KEY.
• I provider vocali inclusi sono di proprietà del plugin. Se plugins.allow è impostato, includi ogni plugin provider TTS che vuoi usare, ad esempio microsoft per Edge TTS. L'id provider legacy edge è accettato come alias di microsoft.
• providers.openai.baseUrl sovrascrive l'endpoint TTS di OpenAI. L'ordine di risoluzione è configurazione, poi OPENAI_TTS_BASE_URL, poi https://api.openai.com/v1.
• Quando providers.openai.baseUrl punta a un endpoint non OpenAI, OpenClaw lo tratta come un server TTS compatibile con OpenAI e allenta la convalida 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",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime",
          voice: "alloy",
        },
      },
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• talk.provider deve corrispondere a una chiave in talk.providers quando sono configurati più provider Talk.
• Le chiavi Talk piatte legacy (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) esistono solo per compatibilità. Esegui openclaw doctor --fix per riscrivere la configurazione persistente in talk.providers.<provider>.
• Gli ID voce usano come fallback ELEVENLABS_VOICE_ID o SAG_VOICE_ID.
• providers.*.apiKey accetta stringhe in testo semplice 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 descrittivi.
• providers.mlx.modelId seleziona il repository Hugging Face usato dall'helper MLX locale di macOS. Se omesso, macOS usa mlx-community/Soprano-80M-bf16.
• La riproduzione MLX su macOS passa attraverso l'helper incluso openclaw-mlx-tts quando presente, oppure tramite un eseguibile in PATH; OPENCLAW_MLX_TTS_BIN sovrascrive il percorso dell'helper per lo sviluppo.
• speechLocale imposta l'id locale BCP 47 usato dal riconoscimento vocale Talk su iOS/macOS. Lascialo non impostato per usare il valore predefinito del dispositivo.
• silenceTimeoutMs controlla per quanto tempo la modalità Talk attende 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 di configurazione — tutte le altre chiavi di configurazione
• Configurazione — attività comuni e configurazione rapida
• Esempi di configurazione