Configurazione — agenti

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

Valori predefiniti degli agenti

`agents.defaults.workspace`

Predefinito: ~/.openclaw/workspace.

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

`agents.defaults.repoRoot`

Root 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 Skills.
Un elenco agents.list[].skills non vuoto è l’insieme finale per quell’agente; non viene unito ai valori predefiniti.

`agents.defaults.skipBootstrap`

Disabilita la creazione automatica dei file 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 dei file opzionali selezionati della workspace continuando comunque 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 iniettati nel prompt di sistema. Predefinito: "always".

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

{
  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 iniettati tra tutti i file di bootstrap della workspace. Predefinito: 60000.

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

`agents.defaults.bootstrapPromptTruncationWarning`

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

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

I conteggi grezzi/iniettati dettagliati e i campi di regolazione della configurazione restano nella diagnostica, ad esempio report di contesto/stato e log; il contesto utente/runtime WebChat di routine riceve solo l’avviso conciso di recupero.

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

Mappa di proprietà dei budget di contesto

OpenClaw ha più budget di prompt/contesto ad alto volume, e sono intenzionalmente suddivisi per sottosistema invece di passare tutti attraverso una singola manopola generica.

agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: normale iniezione del bootstrap della workspace.
agents.defaults.startupContext.*: preambolo una tantum dell’esecuzione del modello al reset/avvio, inclusi i file memory/*.md giornalieri recenti. I comandi chat semplici /new e /reset vengono confermati senza invocare il modello.
skills.limits.*: l’elenco compatto di Skills iniettato nel prompt di sistema.
agents.defaults.contextLimits.*: estratti runtime limitati e blocchi iniettati di proprietà del runtime.
memory.qmd.limits.*: dimensionamento di snippet e iniezione per la ricerca indicizzata in memoria.

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 iniettato nelle esecuzioni del modello al reset/avvio. I comandi chat semplici /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 dei risultati live degli strumenti usato per risultati persistiti e recupero degli overflow.
postCompactionMaxChars: limite dell’estratto AGENTS.md usato durante l’iniezione di aggiornamento successiva alla 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 l’elenco compatto di Skills iniettato 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 per il lato più lungo dell’immagine nei blocchi immagine di transcript/strumenti prima delle chiamate al provider. Predefinito: 1200. Valori inferiori di solito riducono l’uso di token visivi e la dimensione del payload della richiesta per esecuzioni con molti screenshot. Valori superiori preservano più dettagli visivi.

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

`agents.defaults.userTimezone`

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

{
  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
      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 suo 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 in modo univoco a una voce configurata con supporto 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 superficie futura di strumento/plugin che generi 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 output OpenAI PNG/WebP con sfondo trasparente.
- Se selezioni direttamente un provider/modello, configura anche l’autenticazione 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 dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i provider di generazione immagini registrati rimanenti in ordine di ID provider.
musicGenerationModel: accetta una stringa ("provider/model") oppure un oggetto ({ primary, fallbacks }).
- Usato dalla capacità condivisa di generazione musica e dallo strumento integrato music_generate.
- Valori tipici: google/lyria-3-clip-preview, google/lyria-3-pro-preview o minimax/music-2.6.
- Se omesso, music_generate può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i provider di generazione musica registrati rimanenti in ordine di ID provider.
- Se selezioni direttamente un provider/modello, configura anche l’autenticazione/la 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 o qwen/wan2.7-r2v.
- Se omesso, video_generate può comunque dedurre un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i provider di generazione video registrati rimanenti in ordine di ID provider.
- Se selezioni direttamente un provider/modello, configura anche l’autenticazione/la chiave API del provider corrispondente.
- Il provider Qwen di generazione video incluso supporta fino a 1 video di output, 1 immagine di input, 4 video di input, durata di 10 secondi 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 predefinito della dimensione PDF per lo strumento pdf quando maxBytesMb non viene passato al momento della chiamata.
pdfMaxPages: numero massimo predefinito di pagine considerate dalla modalità di fallback di estrazione nello strumento pdf.
verboseDefault: livello verbose predefinito per gli agenti. Valori: "off", "on", "full". Predefinito: "off".
toolProgressDetail: modalità di dettaglio per i riepiloghi strumenti /verbose e le righe di strumento nelle bozze di avanzamento. Valori: "explain" (predefinito, etichette umane compatte) o "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. Le impostazioni predefinite di ragionamento configurate vengono applicate 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 (per 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 con provider configurato per quell’ID modello esatto, 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 provider rimosso.
models: il catalogo modelli configurato e la 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).
- Usa voci provider/* come "openai-codex/*": {} o "vllm/*": {} per mostrare tutti i modelli rilevati per i provider selezionati senza elencare manualmente ogni ID modello.
- 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 diretti OpenAI Responses, 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 (per es. { cacheRetention: "long" }).
Precedenza di unione di params (configurazione): agents.defaults.params (base globale) viene sovrascritto da agents.defaults.models["provider/model"].params (per modello), poi agents.list[].params (ID agente corrispondente) sovrascrive per chiave. Vedi Prompt Caching per i dettagli.
params.extra_body/params.extraBody: JSON avanzato pass-through unito nei corpi richiesta api: "openai-completions" per proxy compatibili con OpenAI. Se collide con chiavi di richiesta generate, vince il corpo extra; le route completions non native rimuovono comunque in seguito store solo OpenAI.
params.chat_template_kwargs: argomenti chat-template compatibili vLLM/OpenAI uniti nei corpi 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 espliciti sovrascrivono i valori predefiniti generati, e extra_body.chat_template_kwargs ha comunque la precedenza finale. Per i controlli thinking di Qwen vLLM, imposta params.qwenThinkingFormat su "chat-template" o "top-level" in quella voce modello.
compat.thinkingFormat: stile del payload thinking compatibile con OpenAI. Usa "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.
compat.supportedReasoningEfforts: elenco di sforzi di ragionamento compatibili con OpenAI per modello. Includi "xhigh" per endpoint personalizzati che lo accettano davvero; OpenClaw quindi espone /think xhigh nei menu comandi, nelle righe sessione Gateway, nella validazione delle patch di sessione, nella validazione CLI dell’agente e nella validazione llm-task per quel provider/modello configurato. Usa compat.reasoningEffortMap quando il backend vuole 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 reasoning_content precedente; vedi thinking Z.AI e thinking preservato.
localService: gestore di processi opzionale a livello di provider per server modello locali/self-hosted. Quando il modello selezionato appartiene a quel provider, OpenClaw sonda healthUrl (o baseUrl + "/models"), avvia command con args se l’endpoint non risponde, attende fino a readyTimeoutMs, poi invia la richiesta modello. command deve essere un percorso assoluto. idleStopMs: 0 mantiene il processo attivo finché OpenClaw non esce; un valore positivo arresta il processo avviato da OpenClaw dopo quel numero di millisecondi di inattività. Vedi Servizi modello locali.
La policy di runtime appartiene ai provider o ai modelli, non ad agents.defaults. Usa models.providers.<provider>.agentRuntime per regole a livello di 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.
Gli scrittori 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 preservano gli elenchi fallback esistenti quando possibile.
maxConcurrent: numero massimo di esecuzioni parallele di agenti tra sessioni (ogni sessione resta comunque serializzata). Predefinito: 4.

Policy di runtime

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

id: "auto", "pi", un ID harness plugin registrato o 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 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.
Le chiavi runtime dell’intero agente sono legacy. agents.defaults.agentRuntime, agents.list[].agentRuntime, i pin runtime di sessione e OPENCLAW_AGENT_RUNTIME vengono ignorati dalla selezione runtime. Esegui openclaw doctor --fix per rimuovere i valori obsoleti.
I modelli agente OpenAI usano per impostazione predefinita l’harness Codex; agentRuntime.id: "codex" per provider/modello resta valido quando vuoi renderlo esplicito.
Per distribuzioni Claude CLI, preferisci model: "anthropic/claude-opus-4-7" più agentRuntime.id: "claude-cli" con ambito modello. 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 nella policy runtime provider/modello.
Questo controlla solo l’esecuzione dei turni agente testuali. Generazione media, visione, PDF, musica, video e TTS usano comunque le rispettive impostazioni provider/modello.

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

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

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 personalmente 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 opzionali per esecuzioni di fallback solo testuali (senza chiamate agli strumenti). Utili come backup quando i provider API non funzionano.

{
  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.
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 sicure invalidate da una coda limitata del transcript OpenClaw grezzo prima che esista il primo riepilogo di compaction. Le modifiche al profilo di autenticazione o all’epoca delle credenziali non eseguono comunque mai un reseed grezzo.

`agents.defaults.systemPromptOverride`

Sostituisce l’intero prompt di sistema assemblato da OpenClaw con una stringa fissa. Impostalo a livello predefinito (agents.defaults.systemPromptOverride) o per agente (agents.list[].systemPromptOverride). I valori per agente hanno 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 di comportamento condiviso tra provider; personality controlla solo il livello dello stile di interazione amichevole.

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

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

`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). Impostalo 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 per errori degli strumenti durante le esecuzioni di Heartbeat.
timeoutSeconds: tempo massimo in secondi consentito per un turno dell’agente Heartbeat prima che venga interrotto. Lascialo non impostato per usare agents.defaults.timeoutSeconds.
directPolicy: criterio di consegna diretta/DM. allow (predefinito) consente la consegna a destinazione diretta. block sopprime la consegna 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 circa 100K a circa 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 gli 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 sul comportamento integrato. Impostare un provider forza mode: "safeguard". Vedi Compaction.
timeoutSeconds: numero massimo di secondi consentito 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 del transcript. /compact manuale 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 degli identificatori opachi durante il riepilogo di 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 strumenti Pi. Quando enabled: true, OpenClaw controlla la pressione del contesto dopo che i risultati degli strumenti sono stati aggiunti e prima della successiva chiamata al modello. Se il contesto non entra 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 oppure compattare e riprovare. Funziona sia con la modalità di compaction default sia con safeguard. Predefinito: disabilitato.
postCompactionSections: nomi opzionali di sezioni H2/H3 di AGENTS.md da reiniettare dopo la compaction. Valore 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 opzionale 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 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 in modo che una compaction riuscita possa ruotare a un transcript successore più piccolo. 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 della compaction automatica per archiviare memorie durevoli. Imposta model su un provider/modello esatto come ollama/qwen3:8b quando questo turno di manutenzione 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`

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

comportamento della modalità cache-ttl

mode: "cache-ttl" abilita i passaggi di pruning.
ttl controlla con quale frequenza il pruning può essere eseguito di nuovo (dopo l’ultimo accesso alla cache).
Il pruning prima esegue il soft-trim dei risultati degli strumenti sovradimensionati, poi, se necessario, esegue l’hard-clear dei risultati degli strumenti più vecchi.

Soft-trim mantiene inizio + fine e inserisce ... al centro.Hard-clear sostituisce l’intero risultato dello strumento con il placeholder.Note:

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

Vedi Pruning della sessione per i dettagli sul comportamento.

Streaming dei 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-2500 ms. Override per agente: agents.list[].humanDelay.

Vedi Streaming per i dettagli su comportamento e suddivisione in blocchi.

Indicatori di digitazione

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

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

Vedi Indicatori di digitazione.

`agents.defaults.sandbox`

Sandboxing facoltativo per l’agente 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"],
      },
    },
  },
}

Dettagli della sandbox

Backend:

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

Quando viene selezionato backend: "openshell", le impostazioni specifiche del runtime passano a plugins.entries.openshell.config.Configurazione del backend SSH:

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

Precedenza dell’autenticazione SSH:

identityData prevale su identityFile
certificateData prevale su certificateFile
knownHostsData prevale su knownHostsFile
I valori *Data basati su SecretRef vengono risolti dallo snapshot del runtime dei segreti attivi prima dell’avvio della sessione sandbox

Comportamento del backend SSH:

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

Accesso al workspace:

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

Ambito:

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

Configurazione del Plugin OpenShell:

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

Modalità OpenShell:

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

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

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

Il sandboxing del browser e sandbox.docker.binds sono disponibili solo con Docker. Crea le immagini (da un checkout del sorgente):

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

Per installazioni npm senza checkout del sorgente, vedi Sandboxing § Immagini e configurazione per i 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 agente esegue un deep merge su messages.tts, così le credenziali condivise possono restare in un solo 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, a /tts status e allo strumento agente tts. Vedi Sintesi vocale 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
        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 stabile dell’agente (obbligatorio).
default: quando ne sono impostati più di uno, vince il primo (viene registrato un avviso). Se nessuno è impostato, la prima voce dell’elenco è quella predefinita.
model: la forma stringa imposta un primario rigoroso per agente senza fallback del modello; anche la forma oggetto { primary } è rigorosa, a meno che non si aggiungano fallbacks. Usa { primary, fallbacks: [...] } per abilitare il fallback per quell’agente, oppure { primary, fallbacks: [] } per rendere esplicito il comportamento rigoroso. I processi Cron che sovrascrivono solo primary ereditano comunque i fallback predefiniti, a meno che non imposti fallbacks: [].
params: parametri di flusso 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 facoltativi della sintesi vocale per agente. Il blocco esegue un’unione profonda sopra messages.tts, quindi mantieni le credenziali condivise dei 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 facoltativa delle 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 ragionamento 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 del provider/modello selezionato controlla quali valori sono validi; per Google Gemini, adaptive mantiene il ragionamento dinamico gestito dal provider (thinkingLevel omesso su Gemini 3/3.1, thinkingBudget: -1 su Gemini 2.5).
reasoningDefault: visibilità predefinita facoltativa del reasoning per agente (on | off | stream). Sovrascrive agents.defaults.reasoningDefault per questo agente quando non è impostato alcun override del reasoning per messaggio o sessione.
fastModeDefault: valore predefinito facoltativo per agente per la modalità veloce (true | false). Si applica quando non è impostato alcun override della modalità veloce per messaggio o sessione.
models: catalogo modelli/override runtime facoltativi per agente, indicizzati per 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 di runtime.acp (agent, backend, mode, cwd) quando l’agente deve usare per impostazione predefinita le sessioni dell’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 degli ID agente per target espliciti sessions_spawn.agentId (["*"] = qualsiasi; predefinito: solo lo stesso agente). Includi l’ID del richiedente quando devono essere consentite chiamate agentId rivolte a sé stesso.
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

Esegui più agenti isolati dentro un unico Gateway. Consulta Multi-Agent.

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

Campi di corrispondenza del binding

type (facoltativo): route per il routing normale (il tipo mancante assume route come valore 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 }

Ordine di corrispondenza deterministico:

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

All’interno di 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

Accesso completo (nessuna sandbox)

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

Strumenti di sola lettura + workspace

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

Nessun accesso al filesystem (solo messaggistica)

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

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

Dettagli dei campi sessione

scope: strategia di raggruppamento della sessione di base per i contesti di chat di gruppo.
- per-sender (predefinito): ogni mittente ottiene una sessione isolata all’interno di un contesto di canale.
- global: tutti i partecipanti in un contesto di canale condividono una singola sessione (usare solo quando è previsto un contesto condiviso).
dmScope: come vengono raggruppati i messaggi diretti.
- main: tutti i messaggi diretti condividono la sessione principale.
- per-peer: isola per id mittente tra i canali.
- per-channel-peer: isola per canale + mittente (consigliato per caselle di posta multiutente).
- per-account-channel-peer: isola per account + canale + mittente (consigliato per multi-account).
identityLinks: mappa gli id canonici ai peer con prefisso provider per la condivisione delle sessioni tra canali. Comandi Dock come /dock_discord usano la stessa mappa per cambiare la route di risposta della sessione attiva verso un altro peer di canale collegato; vedi Docking dei canali.
reset: criterio di reimpostazione principale. daily reimposta all’ora locale atHour; idle reimposta dopo idleMinutes. Quando entrambi sono configurati, prevale quello che scade per primo. La freschezza della reimpostazione giornaliera usa sessionStartedAt della riga di sessione; la freschezza della reimpostazione per inattività usa lastInteractionAt. Scritture in background/eventi di sistema come Heartbeat, risvegli Cron, notifiche exec e contabilità del Gateway possono aggiornare updatedAt, ma non mantengono fresche le sessioni giornaliere/per inattività.
resetByType: override per tipo (direct, group, thread). Il valore legacy dm è accettato come alias di direct.
mainKey: campo legacy. Il runtime usa sempre "main" per il bucket principale della chat diretta.
agentToAgent.maxPingPongTurns: numero massimo di turni di risposta reciproca tra agenti durante scambi agente-agente (intero, intervallo: 0-5). 0 disabilita il concatenamento ping-pong.
sendPolicy: corrispondenza per channel, chatType (direct|group|channel, con alias legacy dm), keyPrefix o rawKeyPrefix. La prima negazione prevale.
maintenance: controlli di pulizia + conservazione dell’archivio sessioni.
- mode: warn emette solo avvisi; enforce applica la pulizia.
- pruneAfter: soglia di età per voci obsolete (predefinito 30d).
- maxEntries: numero massimo di voci in sessions.json (predefinito 500). Il runtime scrive la pulizia in batch con un piccolo buffer high-water per limiti dimensionati per la produzione; openclaw sessions cleanup --enforce applica il limite immediatamente.
- rotateBytes: deprecato e ignorato; openclaw doctor --fix lo rimuove dalle configurazioni più vecchie.
- resetArchiveRetention: conservazione per gli archivi di trascrizioni *.reset.<timestamp>. Il valore predefinito è pruneAfter; impostare false per disabilitare.
- maxDiskBytes: budget disco opzionale per la directory delle sessioni. In modalità warn registra avvisi; in modalità enforce rimuove prima gli artefatti/le sessioni più vecchi.
- highWaterBytes: obiettivo opzionale dopo la pulizia del budget. Il valore predefinito è 80% di maxDiskBytes.
threadBindings: impostazioni predefinite globali per le funzionalità di sessione vincolate ai thread.
- enabled: interruttore predefinito principale (i provider possono eseguire l’override; Discord usa channels.discord.threadBindings.enabled)
- idleHours: disattivazione automatica predefinita per inattività in ore (0 disabilita; i provider possono eseguire l’override)
- maxAgeHours: età massima rigida predefinita in ore (0 disabilita; i provider possono eseguire l’override)
- spawnSessions: gate predefinito per creare sessioni di lavoro vincolate ai thread da sessions_spawn e spawn di thread ACP. Il valore predefinito è true quando i vincoli di thread sono abilitati; provider/account possono eseguire l’override.
- defaultSpawnContext: contesto subagent nativo predefinito per gli spawn vincolati ai thread ("fork" o "isolated"). Il valore predefinito è "fork".

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 il più specifico): account → canale → globale. "" disabilita e interrompe la cascata. "auto" deriva [{identity.name}]. Variabili del template:

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

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

Reazione di conferma

Il valore predefinito è identity.emoji dell’agente attivo, altrimenti "👀". Impostare "" 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 iMessage.
messages.statusReactions.enabled: abilita le reazioni di stato del ciclo di vita su Slack, Discord e Telegram. Su Slack e Discord, se non impostato, le reazioni di stato restano abilitate quando le reazioni di conferma sono attive. Su Telegram, impostarlo esplicitamente a true per abilitare le reazioni di stato del ciclo di vita.

Debounce in ingresso

Raggruppa messaggi rapidi di solo testo dallo stesso mittente in un singolo turno dell’agente. Media/allegati svuotano immediatamente il batch. I comandi di controllo bypassano il debounce.

TTS (text-to-speech)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      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ò eseguire l’override delle preferenze locali, e /tts status mostra lo stato effettivo.
summaryModel esegue l’override di agents.defaults.model.primary per il riepilogo automatico.
modelOverrides è abilitato per impostazione predefinita; modelOverrides.allowProvider è false per impostazione predefinita (opt-in).
Le chiavi API ripiegano su 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 esegue l’override dell’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 server TTS compatibile con OpenAI e allenta la validazione di modello/voce.

Talk

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

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      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",
          voice: "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 ripiegano su ELEVENLABS_VOICE_ID o SAG_VOICE_ID.
providers.*.apiKey accetta stringhe in chiaro 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 un eseguibile su PATH; OPENCLAW_MLX_TTS_BIN esegue l’override del percorso dell’helper per lo sviluppo.
consultThinkingLevel controlla il livello di pensiero per l’esecuzione completa dell’agente OpenClaw dietro le chiamate Control UI Talk realtime openclaw_agent_consult. Lasciare non impostato per preservare il normale comportamento di sessione/modello.
consultFastMode imposta un override 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. Lasciare 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).
realtime.instructions aggiunge istruzioni di sistema rivolte al provider al prompt realtime integrato di OpenClaw, così lo stile vocale può essere configurato senza perdere la guida predefinita di openclaw_agent_consult.

Correlati

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

Gateway

Remote access

Security

Nodes and media

Web interfaces

Documentation Index

​Valori predefiniti degli agenti

​agents.defaults.workspace

​agents.defaults.repoRoot

​agents.defaults.skills

​agents.defaults.skipBootstrap

​agents.defaults.skipOptionalBootstrapFiles

​agents.defaults.contextInjection

​agents.defaults.bootstrapMaxChars

​agents.defaults.bootstrapTotalMaxChars

​agents.defaults.bootstrapPromptTruncationWarning

​Mappa di proprietà dei budget di contesto

​agents.defaults.startupContext

​agents.defaults.contextLimits

​agents.list[].contextLimits

​skills.limits.maxSkillsPromptChars

​agents.list[].skillsLimits.maxSkillsPromptChars

​agents.defaults.imageMaxDimensionPx

​agents.defaults.userTimezone

​agents.defaults.timeFormat

​agents.defaults.model

​Policy di runtime

​agents.defaults.cliBackends

​agents.defaults.systemPromptOverride

​agents.defaults.promptOverlays

​agents.defaults.heartbeat

​agents.defaults.compaction

​agents.defaults.contextPruning

​Streaming dei blocchi

​Indicatori di digitazione

​agents.defaults.sandbox

​agents.list (override per agente)

​Routing multi-agente

​Campi di corrispondenza del binding

​Profili di accesso per agente

​Sessione

​Messaggi

​Prefisso di risposta

​Reazione di conferma

​Debounce in ingresso

​TTS (text-to-speech)

​Talk

​Correlati