Configurazione — agenti

​

Valori predefiniti degli agenti

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skills

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

• Ometti agents.defaults.skills per 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 è l’insieme finale per quell’agente; non viene unita ai valori predefiniti.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.skipOptionalBootstrapFiles

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

​

agents.defaults.contextInjection

• "continuation-skip": i turni di continuazione sicuri (dopo una risposta completata dell’assistente) saltano la reiniezione del bootstrap del workspace, riducendo la dimensione del prompt. Le esecuzioni Heartbeat e i nuovi tentativi post-Compaction ricostruiscono comunque il contesto.
• "never": disabilita il bootstrap del workspace e l’iniezione dei file di contesto a ogni turno. Usalo solo per agenti che possiedono 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 Heartbeat e di recupero da Compaction saltano l’iniezione.

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

Override del profilo di bootstrap per agente

{
  agents: {
    defaults: {
      contextInjection: "continuation-skip",
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 60000,
    },
    list: [
      {
        id: "strict-worker",
        contextInjection: "always",
        bootstrapMaxChars: 50000,
        bootstrapTotalMaxChars: 300000,
      },
    ],
  },
}

​

agents.defaults.bootstrapPromptTruncationWarning

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

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

​

Mappa della proprietà del budget di contesto

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: normale iniezione del bootstrap del workspace.
• agents.defaults.startupContext.*: preludio una tantum del run del modello per reset/avvio, inclusi i file memory/*.md giornalieri recenti. I comandi chat semplici /new e /reset vengono confermati senza invocare il modello.
• skills.limits.*: la lista compatta delle Skills iniettata nel prompt di sistema.
• agents.defaults.contextLimits.*: estratti runtime limitati e blocchi di proprietà del runtime iniettati.
• memory.qmd.limits.*: dimensionamento degli snippet indicizzati della ricerca in memoria e dell’iniezione.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextInjection
• agents.list[].bootstrapMaxChars
• agents.list[].bootstrapTotalMaxChars
• agents.list[].contextLimits.*

​

agents.defaults.startupContext

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

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        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 avanzato dei risultati degli strumenti live usato per risultati persistiti e recupero da overflow. Lascialo non impostato per il limite automatico del contesto del modello: 16000 caratteri sotto 100K token, 32000 caratteri a 100K+ token e 64000 caratteri a 200K+ token. Valori espliciti fino a 1000000 sono accettati per modelli a contesto lungo, ma il limite effettivo resta comunque limitato a circa il 30% della finestra di contesto del modello. openclaw doctor --deep stampa il limite effettivo, e doctor avvisa solo quando un override esplicito è obsoleto o non ha effetto.
• postCompactionMaxChars: limite dell’estratto AGENTS.md usato durante l’iniezione di aggiornamento post-Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000, // advanced ceiling for this agent
        },
      },
    ],
  },
}

​

skills.limits.maxSkillsPromptChars

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

​

agents.list[].skillsLimits.maxSkillsPromptChars

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

​

agents.defaults.imageMaxDimensionPx

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

​

agents.defaults.imageQuality

• auto: adatta ai limiti del modello e al numero di immagini.
• efficient: preferisci immagini più piccole per un uso inferiore di token e byte.
• balanced: usa la scala standard di compromesso.
• high: preserva più dettagli per screenshot, diagrammi e immagini di documenti.

{
  agents: { defaults: { imageQuality: "auto" } },
}

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

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

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-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
      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 routing 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 in modo univoco a una voce configurata compatibile con 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 Gemini, fal/fal-ai/flux/dev per fal, openai/gpt-image-2 per OpenAI Images, oppure openai/gpt-image-1.5 per l’output OpenAI PNG/WebP con sfondo trasparente.
  • Se selezioni direttamente un provider/modello, configura anche l’autenticazione provider corrispondente (ad 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 di generazione immagini registrati 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 di generazione musicale registrati in ordine di ID provider.
  • Se selezioni direttamente un provider/modello, configura anche l’autenticazione/chiave API 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 di generazione video registrati in ordine di ID provider.
  • Se selezioni direttamente un provider/modello, configura anche l’autenticazione/chiave API provider corrispondente.
  • Il Plugin ufficiale 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 di provider size, aspectRatio, resolution, audio e watermark.
• pdfModel: accetta una stringa ("provider/model") oppure un oggetto ({ primary, fallbacks }).
  • Usato dallo strumento pdf per il routing del modello.
  • Se omesso, lo strumento PDF passa in fallback a imageModel, poi al modello risolto della sessione/predefinito.
• pdfMaxBytesMb: limite predefinito di dimensione PDF per lo strumento pdf quando maxBytesMb non viene passato al momento della chiamata.
• pdfMaxPages: numero massimo predefinito di pagine considerate dalla modalità di fallback di 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 /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à del ragionamento predefinita 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 operator-admin 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 modelli configurato e allowlist per /model. Ogni voce può includere alias (scorciatoia) e params (specifici del provider, ad esempio temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, routing OpenRouter provider, chat_template_kwargs, extra_body/extraBody).
  • Usa voci provider/* come "openai/*": {} o "vllm/*": {} per mostrare tutti i modelli scoperti per i provider selezionati senza elencare manualmente ogni ID modello.
  • Aggiungi agentRuntime a una voce provider/* quando ogni modello scoperto dinamicamente per quel provider deve usare lo stesso runtime. La policy runtime esatta provider/model prevale comunque sul carattere jolly.
  • 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 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 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.
• models.providers.openrouter.params.provider: policy predefinita di routing provider a livello OpenRouter. OpenClaw la inoltra all’oggetto provider della richiesta OpenRouter; agents.defaults.models["openrouter/<model>"].params.provider per modello e i parametri agente sovrascrivono per chiave. Vedi routing provider OpenRouter.
• params.extra_body/params.extraBody: JSON avanzato pass-through unito nei body di richiesta api: "openai-completions" per proxy compatibili con OpenAI. Se entra in conflitto con chiavi di richiesta generate, il body extra prevale; le route completions non native rimuovono comunque dopo store specifico di OpenAI.
• params.chat_template_kwargs: argomenti chat-template compatibili con vLLM/OpenAI uniti nei body 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, e extra_body.chat_template_kwargs ha comunque la precedenza finale. I modelli thinking Qwen e Nemotron vLLM configurati espongono scelte binarie /think (off, on) invece della scala di effort a più livelli.
• compat.thinkingFormat: stile del payload thinking compatibile con OpenAI. Usa "together" per reasoning.enabled in stile Together, "qwen" per enable_thinking di primo livello in stile Qwen, oppure "qwen-chat-template" per chat_template_kwargs.enable_thinking su backend della famiglia Qwen che supportano kwargs chat-template a livello di richiesta, come vLLM. OpenClaw mappa thinking disabilitato a false e thinking abilitato a true, e i modelli Qwen vLLM configurati espongono scelte binarie /think per questi formati.
• compat.supportedReasoningEfforts: elenco di effort di ragionamento compatibili con OpenAI per modello. Includi "xhigh" per endpoint personalizzati che lo accettano realmente; OpenClaw espone quindi /think xhigh nei menu comandi, nelle righe di sessione Gateway, nella validazione patch 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: opt-in solo Z.AI per thinking preservato. Quando abilitato e thinking è attivo, OpenClaw invia thinking.clear_thinking: false e riproduce il precedente reasoning_content; vedi thinking Z.AI e thinking preservato.
• localService: process manager opzionale a livello di provider per server di modelli locali/self-hosted. Quando il modello selezionato appartiene a quel provider, OpenClaw sonda healthUrl (oppure baseUrl + "/models"), avvia command con args se l’endpoint non è raggiungibile, attende fino a readyTimeoutMs, poi invia la richiesta modello. command deve essere un percorso assoluto. idleStopMs: 0 mantiene il processo attivo fino all’uscita di OpenClaw; un valore positivo arresta il processo avviato da OpenClaw dopo quel numero di millisecondi di inattività. Vedi Servizi di modelli locali.
• La policy runtime appartiene ai provider o ai modelli, non ad agents.defaults. Usa models.providers.<provider>.agentRuntime per regole a livello provider oppure agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime per regole specifiche del modello. I modelli agente OpenAI sul provider ufficiale OpenAI selezionano Codex per impostazione predefinita.
• I writer di configurazione che modificano questi campi (ad esempio /models set, /models set-image e i comandi di aggiunta/rimozione fallback) salvano la forma oggetto canonica e preservano gli elenchi fallback esistenti quando possibile.
• maxConcurrent: numero massimo di esecuzioni agente parallele tra sessioni (ogni sessione resta comunque serializzata). Predefinito: 4.

​

Policy runtime

{
  models: {
    providers: {
      openai: {
        agentRuntime: { id: "codex" },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      models: {
        "anthropic/claude-opus-4-8": {
          agentRuntime: { id: "claude-cli" },
        },
        "vllm/*": {
          agentRuntime: { id: "openclaw" },
        },
      },
    },
  },
}

• id: "auto", "openclaw", un id di harness plugin registrato o un alias di backend CLI supportato. Il plugin Codex integrato registra codex; il plugin Anthropic integrato fornisce il backend CLI claude-cli.
• id: "auto" consente agli harness plugin registrati di rivendicare i turni supportati e usa OpenClaw quando nessun harness corrisponde. Un runtime plugin esplicito come id: "codex" richiede quell’harness e fallisce in modo chiuso se non è disponibile o fallisce.
• id: "pi" è accettato solo come alias deprecato per openclaw per preservare le configurazioni distribuite dalla v2026.5.22 e precedenti. Le nuove configurazioni dovrebbero usare openclaw.
• La precedenza del runtime è prima la policy esatta del modello (agents.list[].models["provider/model"], agents.defaults.models["provider/model"] o models.providers.<provider>.models[]), poi agents.list[] / agents.defaults.models["provider/*"], quindi la policy a livello di provider in models.providers.<provider>.agentRuntime.
• Le chiavi runtime dell’intero agente sono legacy. agents.defaults.agentRuntime, agents.list[].agentRuntime, i pin runtime di sessione e OPENCLAW_AGENT_RUNTIME sono ignorati dalla selezione del runtime. Esegui openclaw doctor --fix per rimuovere i valori obsoleti.
• I modelli agente OpenAI usano l’harness Codex per impostazione predefinita; provider/modello agentRuntime.id: "codex" rimane valido quando vuoi renderlo esplicito.
• Per i deployment Claude CLI, preferisci model: "anthropic/claude-opus-4-8" più agentRuntime.id: "claude-cli" con ambito modello. I riferimenti modello legacy claude-cli/claude-opus-4-7 funzionano ancora per compatibilità, ma le nuove configurazioni dovrebbero mantenere canonica la selezione provider/modello e mettere il backend di esecuzione nella policy runtime provider/modello.
• Questo controlla solo l’esecuzione dei turni agente testuali. Generazione di media, visione, PDF, musica, video e TTS usano ancora le rispettive impostazioni provider/modello.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "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 al testo; gli strumenti sono sempre disabilitati.
• Le sessioni sono supportate quando sessionArg è impostato.
• Il pass-through delle immagini è supportato quando imageArg accetta percorsi di file.
• reseedFromRawTranscriptWhenUncompacted: true consente a un backend di recuperare sessioni invalidate sicure da una coda limitata della trascrizione OpenClaw grezza prima che esista il primo riepilogo di Compaction. Le modifiche al profilo di autenticazione o all’epoca delle credenziali non eseguono comunque mai un nuovo seed grezzo.

​

agents.defaults.promptOverlays

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

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

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for this agent's 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 di errore degli strumenti durante le esecuzioni Heartbeat.
• timeoutSeconds: tempo massimo in secondi consentito per un turno agente Heartbeat prima che venga interrotto. Lascia non impostato per usare agents.defaults.timeoutSeconds quando impostato, altrimenti la cadenza Heartbeat limitata a 600 secondi.
• directPolicy: policy di consegna diretta/DM. allow (predefinito) consente la consegna al target diretto. block sopprime la consegna al target diretto ed emette reason=dm-blocked.
• lightContext: quando è true, le esecuzioni Heartbeat usano un contesto di bootstrap leggero e mantengono solo HEARTBEAT.md dai file di bootstrap del workspace.
• 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 circa 100K a circa 2-5K token.
• skipWhenBusy: quando è true, le esecuzioni Heartbeat vengono rinviate sulle corsie occupate aggiuntive di quell’agente: il lavoro del proprio subagente con chiave di sessione o dei comandi annidati. Le corsie Cron rinviano sempre gli Heartbeat, anche senza questo flag.
• Per agente: imposta agents.list[].heartbeat. Quando qualsiasi 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 of a registered compaction provider plugin (optional)
        timeoutSeconds: 180,
        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 tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // opt in to AGENTS.md section 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 suddiviso in blocchi per cronologie lunghe). Vedi Compaction.
• provider: id di un plugin provider di Compaction registrato. Quando è impostato, viene chiamato summarize() del provider invece del riepilogo LLM integrato. In caso di errore torna al comportamento integrato. Impostare un provider forza mode: "safeguard". Vedi Compaction.
• timeoutSeconds: numero massimo di secondi consentiti per una singola operazione di Compaction prima che OpenClaw la interrompa. Predefinito: 180.
• keepRecentTokens: budget del punto di taglio dell’agente per conservare testualmente la coda più recente della trascrizione. Il comando manuale /compact lo rispetta quando è impostato esplicitamente; altrimenti la Compaction manuale è un checkpoint rigido.
• identifierPolicy: strict (predefinito), off o custom. strict antepone indicazioni integrate per la conservazione di identificatori opachi durante il riepilogo della Compaction.
• identifierInstructions: testo personalizzato opzionale per la conservazione degli identificatori, usato quando identifierPolicy=custom.
• qualityGuard: controlli con nuovo tentativo in caso di output malformato per i riepiloghi safeguard. Abilitato per impostazione predefinita in modalità safeguard; imposta enabled: false per saltare l’audit.
• midTurnPrecheck: controllo opzionale della pressione del ciclo degli strumenti. Quando enabled: true, OpenClaw controlla la pressione del contesto dopo l’aggiunta dei risultati degli strumenti e prima della successiva chiamata al modello. Se il contesto non rientra più nei limiti, interrompe il tentativo corrente prima di inviare il prompt e riusa il percorso di recupero del precheck esistente per troncare i risultati degli strumenti oppure eseguire la Compaction e riprovare. Funziona con entrambe le modalità di Compaction, default e safeguard. Predefinito: disabilitato.
• postCompactionSections: nomi opzionali di sezioni H2/H3 di AGENTS.md da reinserire dopo la Compaction. Il reinserimento è disabilitato quando non è impostato o è impostato su []. Impostare esplicitamente ["Session Startup", "Red Lines"] abilita quella coppia e preserva il fallback legacy Every Session/Safety. Abilitalo solo quando il contesto extra vale il rischio di duplicare indicazioni di progetto già catturate nel riepilogo della Compaction.
• model: provider/model-id opzionale o alias semplice da agents.defaults.models solo per il riepilogo della Compaction. Gli alias semplici vengono risolti prima dell’invio; gli ID modello letterali configurati mantengono la precedenza in caso di collisioni. Usalo quando la sessione principale deve mantenere un modello, ma i riepiloghi della Compaction devono essere eseguiti su un altro; se non è impostato, la Compaction usa il modello principale della sessione.
• maxActiveTranscriptBytes: soglia opzionale in byte (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 successiva più piccola. Disabilitato quando non impostato o 0.
• notifyUser: quando true, invia brevi avvisi 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 agentico silenzioso prima dell’auto-Compaction per salvare memorie durevoli. Imposta model su un provider/modello esatto come ollama/qwen3:8b quando questo turno di manutenzione deve rimanere su un modello locale; l’override non eredita la catena di fallback della sessione attiva. Saltato quando il workspace è in sola lettura.

​

agents.defaults.runRetries

{
  agents: {
    defaults: {
      runRetries: {
        base: 24,
        perProfile: 8,
        min: 32,
        max: 160,
      },
    },
    list: [
      {
        id: "main",
        runRetries: { max: 50 }, // optional per-agent overrides
      },
    ],
  },
}

• base: numero base di iterazioni di nuovo tentativo per il ciclo di esecuzione esterno. Predefinito: 24.
• perProfile: iterazioni aggiuntive di nuovo tentativo concesse per ogni candidato profilo di fallback. Predefinito: 8.
• min: limite assoluto minimo per le iterazioni di nuovo tentativo. Predefinito: 32.
• max: limite assoluto massimo per le iterazioni di nuovo tentativo, per prevenire esecuzioni fuori controllo. Predefinito: 160.

​

agents.defaults.contextPruning

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

​

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 diversi da Telegram richiedono *.blockStreaming: true esplicito per abilitare le risposte a blocchi.
• Override del canale: 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-2500 ms. Override per agente: agents.list[].humanDelay.

​

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 menzioni.
• Override per sessione: session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // 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,
        },
      },
    },
  },
}

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

​

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
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "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 (avviso registrato). Se nessuno è impostato, la prima voce dell’elenco è il valore predefinito.
• model: la forma stringa imposta un primario per agente rigoroso 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 job Cron 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 selezionato in agents.defaults.models. Usalo per override specifici dell’agente come cacheRetention, temperature o maxTokens senza duplicare l’intero catalogo dei modelli.
• tts: override facoltativi di sintesi vocale per agente. Il blocco viene unito in profondità sopra messages.tts, quindi mantieni le credenziali dei provider condivisi 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 facoltativa di skill 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 di pensiero 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. Il profilo provider/modello selezionato controlla quali valori sono validi; per Google Gemini, adaptive mantiene il pensiero dinamico gestito dal provider (thinkingLevel omesso su Gemini 3/3.1, thinkingBudget: -1 su Gemini 2.5).
• reasoningDefault: visibilità predefinita facoltativa 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: impostazione predefinita facoltativa per agente per la modalità veloce ("auto" | true | false). Si applica quando non è impostato alcun override della modalità veloce per messaggio o sessione.
• models: override facoltativi del catalogo modelli/runtime per agente, indicizzati da id completi provider/model. Usa models["provider/model"].agentRuntime per eccezioni runtime per agente.
• 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:.
• I file immagine identity.avatar locali relativi al workspace sono limitati a 2 MB. Gli URL http(s) e gli URI data: non vengono controllati con il limite locale di dimensione file.
• identity deriva i valori predefiniti: ackReaction da emoji, mentionPatterns da name/emoji.
• subagents.allowAgents: allowlist di id agente configurati per target espliciti sessions_spawn.agentId (["*"] = qualsiasi target configurato; predefinito: solo lo stesso agente). Includi l’id del richiedente quando le chiamate agentId autoindirizzate devono essere consentite. Le voci obsolete la cui configurazione agente è stata eliminata vengono rifiutate da sessions_spawn e omesse da agents_list; esegui openclaw doctor --fix per ripulirle, oppure aggiungi una voce minima agents.list[] se quel target deve restare generabile ereditando i valori predefiniti.
• Guardia di ereditarietà della sandbox: se la sessione 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; predefinito: false).

​

Routing multi-agente

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

​

Campi di corrispondenza dei binding

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

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

​

Profili di accesso per agente

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

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

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

​

Sessione

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "enforce", // enforce (default) | warn
      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: "followup", // steer | followup | collect | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Prefisso della risposta

​

Reazione di conferma

• Il valore predefinito è identity.emoji dell’agente attivo, altrimenti "👀". Imposta "" per disabilitarla.
• Override per canale: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Ordine di risoluzione: account → canale → messages.ackReaction → fallback 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, Signal, Telegram, WhatsApp e iMessage.
• messages.statusReactions.enabled: abilita le reazioni di stato del ciclo di vita su Slack, Discord, Signal, Telegram e WhatsApp. Su Slack e Discord, se non impostato mantiene abilitate le reazioni di stato quando le reazioni di conferma sono attive. Su Signal, Telegram e WhatsApp, impostalo esplicitamente a true per abilitare le reazioni di stato del ciclo di vita.
• messages.statusReactions.emojis: esegue l’override delle chiavi emoji del ciclo di vita: queued, thinking, compacting, tool, coding, web, deploy, build, concierge, done, error, stallSoft e stallHard. Telegram consente solo un set fisso di reazioni, quindi le emoji configurate non supportate ripiegano sulla variante di stato supportata più vicina per quella chat.

​

Debounce in ingresso

​

TTS (sintesi vocale)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-5.4-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          speakerVoiceId: "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: {
          speakerVoice: "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",
          speakerVoice: "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 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 del 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 considera un server TTS compatibile con OpenAI e allenta la convalida di modello/voce.

​

Talk

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "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: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2",
          speakerVoice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      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) sono solo per compatibilità. Esegui openclaw doctor --fix per riscrivere la configurazione persistita in talk.providers.<provider>.
• Gli ID voce usano come fallback ELEVENLABS_VOICE_ID o SAG_VOICE_ID.
• providers.*.apiKey accetta stringhe in testo normale 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 openclaw-mlx-tts incluso quando presente, oppure tramite un eseguibile su PATH; OPENCLAW_MLX_TTS_BIN sovrascrive il percorso dell’helper per lo sviluppo.
• consultThinkingLevel controlla il livello di ragionamento per l’esecuzione completa dell’agente OpenClaw dietro le chiamate Control UI Talk realtime openclaw_agent_consult. Lascia non impostato per preservare il normale comportamento di sessione/modello.
• consultFastMode imposta una sovrascrittura fast-mode una tantum per le consultazioni Control UI Talk realtime senza modificare l’impostazione fast-mode normale della sessione.
• speechLocale imposta l’id locale BCP 47 usato dal riconoscimento vocale Talk di iOS/macOS. Lascia 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 on macOS and Android, 900 ms on iOS).
• realtime.instructions aggiunge istruzioni di sistema rivolte al provider al prompt realtime integrato di OpenClaw, così lo stile della voce può essere configurato senza perdere le indicazioni predefinite di openclaw_agent_consult.
• realtime.consultRouting controlla il fallback del relay Gateway quando il provider realtime produce una trascrizione utente finale senza openclaw_agent_consult: provider-direct preserva le risposte dirette del provider, mentre force-agent-consult instrada la richiesta finalizzata attraverso OpenClaw.

​

Correlati

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