Configurazione — agenti

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

Valori predefiniti dell’agente

`agents.defaults.workspace`

Predefinito: ~/.openclaw/workspace.

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

`agents.defaults.repoRoot`

Radice del repository opzionale mostrata nella riga Runtime del prompt di sistema. Se non impostata, OpenClaw la rileva automaticamente risalendo dall’area di lavoro.

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

`agents.defaults.skills`

Allowlist predefinita opzionale delle Skills 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 è il set finale per quell’agente; non viene unito ai valori predefiniti.

`agents.defaults.skipBootstrap`

Disabilita la creazione automatica dei file di bootstrap dell’area di lavoro (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 dell’area di lavoro 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 dell’area di lavoro vengono iniettati nel prompt di sistema. Predefinito: "always".

"continuation-skip": i turni di continuazione sicuri (dopo una risposta completata dell’assistente) saltano la reiniezione del bootstrap dell’area di lavoro, riducendo la dimensione del prompt. Le esecuzioni Heartbeat e i tentativi post-Compaction ricostruiscono comunque il contesto.
"never": disabilita il bootstrap dell’area di lavoro 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 dell’area di lavoro prima del troncamento. Predefinito: 12000.

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

`agents.defaults.bootstrapTotalMaxChars`

Numero massimo totale di caratteri iniettati tra tutti i file di bootstrap dell’area di lavoro. 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 e log di contesto/stato; il contesto utente/runtime WebChat ordinario riceve solo l’avviso conciso di recupero.

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

Mappa della proprietà del budget di contesto

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

agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: normale iniezione del bootstrap dell’area di lavoro.
agents.defaults.startupContext.*: preambolo una tantum dell’esecuzione modello di 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 delle Skills iniettato nel prompt di sistema.
agents.defaults.contextLimits.*: estratti runtime limitati e blocchi iniettati di proprietà del runtime.
memory.qmd.limits.*: snippet di ricerca memoria indicizzato e dimensionamento dell’iniezione.

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 modello di 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 i metadati di troncamento e l’avviso di continuazione.
memoryGetDefaultLines: finestra di righe predefinita di memory_get quando lines viene omesso.
toolResultMaxChars: limite dei risultati strumenti live usato per risultati persistiti e recupero da overflow.
postCompactionMaxChars: limite dell’estratto AGENTS.md usato durante l’iniezione di aggiornamento post-Compaction.

`agents.list[].contextLimits`

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

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

`skills.limits.maxSkillsPromptChars`

Limite globale per l’elenco compatto delle 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 del 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 trascrizione/strumenti prima delle chiamate al provider. Predefinito: 1200. Valori più bassi di solito riducono l’utilizzo di token di visione e la dimensione del payload della richiesta per esecuzioni ricche di screenshot. Valori più alti preservano più dettagli visivi.

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

`agents.defaults.userTimezone`

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

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

`agents.defaults.timeFormat`

Formato dell’ora nel prompt di sistema. Predefinito: auto (preferenza del sistema operativo).

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

`agents.defaults.model`

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // global default provider params
      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 modello 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 con supporto immagini in models.providers.*.models, OpenClaw lo qualifica con quel provider. 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 genera immagini.
- Valori tipici: google/gemini-3.1-flash-image-preview per la generazione immagini Gemini nativa, fal/fal-ai/flux/dev per fal, openai/gpt-image-2 per OpenAI Images, oppure openai/gpt-image-1.5 per output OpenAI PNG/WebP con sfondo trasparente.
- Se selezioni direttamente un provider/modello, configura anche l’autenticazione del provider corrispondente (per esempio GEMINI_API_KEY o GOOGLE_API_KEY per google/*, OPENAI_API_KEY o OpenAI Codex OAuth per openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY per fal/*).
- Se omesso, image_generate può comunque inferire un provider predefinito supportato da autenticazione. Prova prima il provider predefinito corrente, poi i restanti provider 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 o 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/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 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/la chiave API del provider corrispondente.
- Il provider di generazione video Qwen incluso supporta fino a 1 video di output, 1 immagine di input, 4 video di input, 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 il routing del modello.
- Se omesso, lo strumento PDF usa come fallback imageModel, poi il 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 dell’estrazione nello strumento pdf.
verboseDefault: livello verboso predefinito per gli agenti. Valori: "off", "on", "full". Predefinito: "off".
toolProgressDetail: modalità di dettaglio per i riepiloghi strumenti di /verbose e le righe degli strumenti 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à predefinita del ragionamento per gli agenti. Valori: "off", "on", "stream". agents.list[].reasoningDefault per agente sovrascrive questo valore predefinito. I valori predefiniti di ragionamento configurati vengono applicati solo per proprietari, mittenti autorizzati o contesti Gateway di amministratore operatore quando non è impostata alcuna sovrascrittura del 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 l’allowlist per /model. Ogni voce può includere alias (scorciatoia) e params (specifici del provider, per esempio temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, chat_template_kwargs, extra_body/extraBody).
- 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 esistenti dell’allowlist, a meno che tu non passi --replace.
- I flussi di configurazione/onboarding con ambito provider uniscono i modelli del provider selezionato 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) 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 pass-through avanzato unito nei corpi delle richieste api: "openai-completions" per proxy compatibili con OpenAI. Se entra in conflitto con chiavi di richiesta generate, il corpo extra prevale; le route completions non native rimuovono comunque successivamente store specifico di OpenAI.
params.chat_template_kwargs: argomenti chat-template compatibili con vLLM/OpenAI uniti nei corpi delle richieste api: "openai-completions" di primo livello. 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 di thinking Qwen in vLLM, imposta params.qwenThinkingFormat a "chat-template" o "top-level" su quella voce modello.
compat.thinkingFormat: stile del payload di 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 sui backend della famiglia Qwen che supportano kwargs chat-template a livello di richiesta, come vLLM. OpenClaw mappa il thinking disabilitato a false e il thinking abilitato a true.
compat.supportedReasoningEfforts: elenco per modello degli effort di ragionamento compatibili con OpenAI. Includi "xhigh" per endpoint personalizzati che lo accettano davvero; OpenClaw quindi espone /think xhigh nei menu dei comandi, nelle righe di sessione Gateway, nella validazione delle patch di sessione, nella validazione della CLI agente e nella validazione di 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 il thinking è attivo, OpenClaw invia thinking.clear_thinking: false e riproduce il reasoning_content precedente; vedi thinking Z.AI e thinking preservato.
localService: gestore di processo opzionale a livello di provider per server di modelli 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 è attivo, attende fino a readyTimeoutMs, poi invia la richiesta del 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 di modelli locali.
La policy di runtime appartiene ai provider o ai modelli, non a agents.defaults. Usa models.providers.<provider>.agentRuntime per regole valide per tutto il 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 OpenAI ufficiale selezionano Codex per impostazione predefinita.
Gli strumenti di scrittura della configurazione che modificano questi campi (per esempio /models set, /models set-image e i comandi per aggiungere/rimuovere fallback) salvano la forma oggetto canonica e preservano gli elenchi di fallback esistenti quando possibile.
maxConcurrent: numero massimo di esecuzioni agenti parallele 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 di 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 di 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 del runtime. Esegui openclaw doctor --fix per rimuovere valori obsoleti.
I modelli agente OpenAI usano l’harness Codex per impostazione predefinita; agentRuntime.id: "codex" del provider/modello rimane 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 inserire il backend di esecuzione nella policy di runtime del provider/modello.
Questo controlla solo l’esecuzione dei turni agente testuali. Generazione media, visione, PDF, musica, video e TTS continuano a usare le rispettive impostazioni provider/modello.

Abbreviazioni 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 autonomamente agents.defaults.models["zai/<model>"].params.thinking. I modelli Z.AI abilitano tool_stream per impostazione predefinita per lo streaming delle chiamate agli strumenti. Imposta agents.defaults.models["zai/<model>"].params.tool_stream su false per disabilitarlo. I modelli Anthropic Claude 4.6 usano per impostazione predefinita il ragionamento adaptive quando non è impostato alcun livello di ragionamento esplicito.

`agents.defaults.cliBackends`

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

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

I backend CLI danno priorità 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 in modo sicuro 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 ri-seminano comunque mai dai dati grezzi.

`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 di 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 amichevole dello stile di interazione.

{
  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 resta abilitato.
Il valore legacy plugins.entries.openai.config.personality viene ancora letto quando questa impostazione condivisa non è configurata.

`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 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). 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 Heartbeat.
timeoutSeconds: tempo massimo in secondi consentito per un turno agente Heartbeat prima che venga interrotto. Lascia 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 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 del 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 rimandate sulle corsie extra occupate di quell’agente: il suo subagente indicizzato per chiave di sessione o il lavoro di comandi annidati. Le corsie Cron rimandano sempre gli Heartbeat, anche senza questo flag.
Per agente: imposta agents.list[].heartbeat. Quando un agente definisce heartbeat, solo quegli agenti eseguono Heartbeat.
Gli Heartbeat eseguono turni 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: 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 plugin provider di Compaction registrato. Quando è impostato, viene chiamato summarize() del provider invece del riepilogo LLM integrato. In caso di errore ripiega sull’implementazione integrata. 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: 900.
keepRecentTokens: budget del punto di taglio di Pi per mantenere letteralmente la coda più recente della trascrizione. /compact manuale lo rispetta quando è impostato esplicitamente; altrimenti la Compaction manuale è un checkpoint rigido.
identifierPolicy: strict (predefinito), off o custom. strict antepone 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 riepiloghi safeguard. Abilitato per impostazione predefinita in modalità safeguard; imposta enabled: false per saltare l’audit.
midTurnPrecheck: controllo opzionale della pressione del ciclo strumenti di Pi. 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ù, interrompe il tentativo corrente prima di inviare il prompt e riusa il percorso di recupero precheck esistente per troncare i risultati degli strumenti o eseguire 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 reiniettare dopo la Compaction. Predefinito: ["Session Startup", "Red Lines"]; imposta [] per disabilitare la reiniezione. Quando non è impostato o è impostato esplicitamente su quella coppia predefinita, vengono accettati anche i titoli precedenti Every Session/Safety 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 Compaction locale normale prima di un’esecuzione quando il JSONL attivo supera la soglia. Richiede truncateAfterCompaction in modo che una Compaction riuscita possa ruotare verso una trascrizione successiva più piccola. Disabilitato quando non è impostato o è 0.
notifyUser: quando è true, invia brevi notifiche all’utente quando la Compaction inizia e quando viene completata (per esempio, “Compacting context…” e “Compaction complete”). Disabilitato per impostazione predefinita per mantenere la Compaction silenziosa.
memoryFlush: turno agentico silenzioso prima della Compaction automatica per memorizzare ricordi 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.runRetries`

Limiti di iterazione dei nuovi tentativi del ciclo di esecuzione esterno per il runner Pi incorporato, per prevenire cicli di esecuzione infiniti durante il recupero da errori. Nota che questa impostazione attualmente si applica solo al runtime agente incorporato, non ai runtime ACP o CLI.

{
  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 minimo assoluto per le iterazioni di nuovo tentativo. Predefinito: 32.
max: limite massimo assoluto per le iterazioni di nuovo tentativo, per impedire esecuzioni incontrollate. Predefinito: 160.

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

cache-ttl mode behavior

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

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

I blocchi immagine non vengono mai ridotti o 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.

Consulta Pruning della sessione per i dettagli sul comportamento.

Streaming a blocchi

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

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

Consulta Streaming per i dettagli su comportamento e suddivisione in chunk.

Indicatori di digitazione

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

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

Consulta Indicatori di digitazione.

`agents.defaults.sandbox`

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

Sandbox details

Backend:

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

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

target: destinazione SSH nel formato user@host[:port]
command: comando del client SSH (predefinito: ssh)
workspaceRoot: root remota assoluta usata per workspace per ambito
identityFile / certificateFile / knownHostsFile: file locali esistenti passati a OpenSSH
identityData / certificateData / knownHostsData: contenuti inline o SecretRef che OpenClaw materializza in file temporanei a runtime
strictHostKeyChecking / updateHostKeys: controlli della policy delle chiavi host 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 attivo 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 per file e i percorsi media tramite SSH
non sincronizza automaticamente le modifiche remote verso l’host
non supporta i 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 e workspace per sessione
agent: un container e un workspace per agente (predefinito)
shared: container e workspace condivisi (nessun 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 rimane canonico
remote: inizializza il remoto una volta quando viene creata la sandbox, poi mantiene canonico il workspace remoto

In modalità remote, le modifiche locali all’host apportate fuori da OpenClaw non vengono sincronizzate automaticamente nella sandbox dopo il passaggio di inizializzazione. Il trasporto avviene via 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 egress di rete, root scrivibile, utente root.I container usano per impostazione predefinita network: "none" — impostalo su "bridge" (o su una rete bridge personalizzata) se l’agente necessita di accesso in uscita. "host" è bloccato. "container:<id>" è bloccato per impostazione predefinita, a meno che tu non imposti esplicitamente sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true (break-glass).Gli allegati in ingresso vengono posizionati in media/inbound/* nel workspace attivo.docker.binds monta directory host aggiuntive; i bind globali e per agente vengono uniti.Browser in sandbox (sandbox.browser.enabled): Chromium + CDP in un container. URL noVNC inserito nel prompt di sistema. Non richiede browser.enabled in openclaw.json. L’accesso dell’osservatore noVNC usa l’autenticazione VNC per impostazione predefinita e OpenClaw emette un URL token di breve durata (invece di esporre la password nell’URL condiviso).

allowHostControl: false (predefinito) impedisce alle sessioni sandbox di puntare al browser dell’host.
network usa per impostazione predefinita openclaw-sandbox-browser (rete bridge dedicata). Impostalo su bridge solo quando vuoi esplicitamente la 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.
I valori predefiniti di avvio sono definiti in scripts/sandbox-browser-entrypoint.sh e ottimizzati per host container:
- --remote-debugging-address=127.0.0.1
- --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
- --user-data-dir=${HOME}/.chrome
- --no-first-run
- --no-default-browser-check
- --disable-3d-apis
- --disable-gpu
- --disable-software-rasterizer
- --disable-dev-shm-usage
- --disable-background-networking
- --disable-features=TranslateUI
- --disable-breakpad
- --disable-crash-reporter
- --renderer-process-limit=2
- --no-zygote
- --metrics-recording-only
- --disable-extensions (abilitato per impostazione predefinita)
- --disable-3d-apis, --disable-software-rasterizer e --disable-gpu sono abilitati per impostazione predefinita e possono essere disabilitati con OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 se l’uso di WebGL/3D lo richiede.
- OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 riabilita le estensioni se il tuo 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 processo 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, consulta 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 dell’agente si unisce in profondità a messages.tts, quindi le credenziali condivise possono restare in un unico posto mentre i singoli agenti sovrascrivono solo i campi voce o provider di cui hanno bisogno. La sovrascrittura dell’agente attivo si applica alle risposte vocali automatiche, a /tts audio, /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 è il default.
model: la forma stringa imposta un primario rigoroso per agente senza fallback del modello; anche la forma oggetto { primary } è rigorosa, a meno che tu non aggiunga fallbacks. Usa { primary, fallbacks: [...] } per abilitare il fallback per quell’agente, oppure { primary, fallbacks: [] } per rendere esplicito il comportamento rigoroso. I 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 alla voce del modello selezionato in agents.defaults.models. Usalo per sovrascritture specifiche dell’agente come cacheRetention, temperature o maxTokens senza duplicare l’intero catalogo dei modelli.
tts: sovrascritture facoltative della sintesi vocale per agente. Il blocco si unisce in profondità a 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 delle skill per agente. Se omessa, l’agente eredita agents.defaults.skills quando è impostato; un elenco esplicito sostituisce i default invece di unirsi a essi, 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 è impostata alcuna sovrascrittura per messaggio o sessione. Il profilo del provider/modello selezionato controlla quali valori sono validi; per Google Gemini, adaptive mantiene il pensiero dinamico di proprietà del provider (thinkingLevel omesso su Gemini 3/3.1, thinkingBudget: -1 su Gemini 2.5).
reasoningDefault: visibilità del ragionamento predefinita facoltativa per agente (on | off | stream). Sovrascrive agents.defaults.reasoningDefault per questo agente quando non è impostata alcuna sovrascrittura del ragionamento per messaggio o sessione.
fastModeDefault: default facoltativo per agente per la modalità veloce (true | false). Si applica quando non è impostata alcuna sovrascrittura della modalità veloce per messaggio o sessione.
models: catalogo dei modelli/sovrascritture di runtime facoltativi per agente indicizzati da id completi provider/model. Usa models["provider/model"].agentRuntime per eccezioni di runtime per agente.
runtime: descrittore di runtime facoltativo per agente. Usa type: "acp" con i default di runtime.acp (agent, backend, mode, cwd) quando l’agente deve usare di default sessioni dell’harness ACP.
identity.avatar: percorso relativo al workspace, URL http(s) o URI data:.
identity deriva i default: ackReaction da emoji, mentionPatterns da name/emoji.
subagents.allowAgents: allowlist di id agente per target espliciti sessions_spawn.agentId (["*"] = qualsiasi; default: solo lo stesso agente). Includi l’id del richiedente quando devono essere consentite chiamate agentId indirizzate a sé stesso.
Protezione dell’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; default: false).

Routing multi-agente

Esegui più agenti isolati dentro un solo Gateway. Vedi Multi-Agent.

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

Campi di corrispondenza dei binding

type (facoltativo): route per il routing normale (il tipo mancante usa route come default), 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 indicato.

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

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

Sessione

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    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 della sessione

scope: strategia di raggruppamento della sessione di base per 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 (usa solo quando è previsto un contesto condiviso).
dmScope: come vengono raggruppati i DM.
- main: tutti i DM 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 di sessioni tra canali. I comandi Dock come /dock_discord usano la stessa mappa per cambiare la rotta di risposta della sessione attiva verso un altro peer di canale collegato; vedi Docking dei canali.
reset: criterio di reset principale. daily esegue il reset all’ora locale atHour; idle esegue il reset dopo idleMinutes. Quando entrambi sono configurati, prevale quello che scade per primo. La freschezza del reset giornaliero usa sessionStartedAt della riga di sessione; la freschezza del reset 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). dm legacy 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 agent-to-agent (intero, intervallo: 0-20, predefinito: 5). 0 disabilita il concatenamento ping-pong.
sendPolicy: corrispondenza per channel, chatType (direct|group|channel, con alias legacy dm), keyPrefix o rawKeyPrefix. La prima regola di negazione prevale.
maintenance: controlli di pulizia + conservazione dello store delle 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 di dimensioni di 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 archivi di trascrizioni *.reset.<timestamp>. Per impostazione predefinita usa pruneAfter; imposta false per disabilitare.
- maxDiskBytes: budget disco opzionale per la directory delle sessioni. In modalità warn registra avvisi; in modalità enforce rimuove prima gli artifact/sessioni più vecchi.
- highWaterBytes: target opzionale dopo la pulizia del budget. Per impostazione predefinita è 80% di maxDiskBytes.
threadBindings: valori predefiniti globali per funzionalità di sessione vincolate ai thread.
- enabled: interruttore predefinito principale (i provider possono eseguire override; Discord usa channels.discord.threadBindings.enabled)
- idleHours: inattività predefinita in ore per auto-unfocus (0 disabilita; i provider possono eseguire override)
- maxAgeHours: età massima rigida predefinita in ore (0 disabilita; i provider possono eseguire override)
- spawnSessions: gate predefinito per creare sessioni di lavoro vincolate ai thread da sessions_spawn e spawn di thread ACP. Per impostazione predefinita è true quando i binding dei thread sono abilitati; provider/account possono eseguire override.
- defaultSpawnContext: contesto subagent nativo predefinito per spawn vincolati ai thread ("fork" o "isolated"). Per impostazione predefinita è "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 ragionamento corrente	`high`, `low`, `off`
`{identity.name}`	Nome dell’identità dell’agente	(uguale a `"auto"`)

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

Reazione di ack

Per impostazione predefinita usa identity.emoji dell’agente attivo, altrimenti "👀". Imposta "" per disabilitare.
Override per canale: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
Ordine di risoluzione: account → canale → messages.ackReaction → fallback identità.
Ambito: group-mentions (predefinito), group-all, direct, all.
removeAckAfterReply: rimuove l’ack 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 mantiene abilitate le reazioni di stato quando le reazioni di ack sono attive. Su Telegram, impostalo 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 vengono inviati immediatamente. I comandi di controllo bypassano il debouncing.

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 override delle preferenze locali, e /tts status mostra lo stato effettivo.
summaryModel esegue l’override di agents.defaults.model.primary per l’auto-riassunto.
modelOverrides è abilitato per impostazione predefinita; modelOverrides.allowProvider ha valore predefinito false (opt-in).
Le chiavi API usano come fallback ELEVENLABS_API_KEY/XI_API_KEY e OPENAI_API_KEY.
I provider vocali inclusi sono di proprietà dei Plugin. Se plugins.allow è impostato, includi ogni Plugin provider TTS che vuoi usare, per esempio microsoft per Edge TTS. L’ID provider legacy edge è accettato come alias di microsoft.
providers.openai.baseUrl esegue l’override dell’endpoint OpenAI TTS. L’ordine di risoluzione è configurazione, poi OPENAI_TTS_BASE_URL, poi https://api.openai.com/v1.
Quando providers.openai.baseUrl punta a un endpoint non OpenAI, OpenClaw lo tratta come un server TTS compatibile con OpenAI e allenta la 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 persistente in talk.providers.<provider>.
Gli ID voce usano come fallback 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 incluso openclaw-mlx-tts quando presente, oppure un eseguibile in PATH; OPENCLAW_MLX_TTS_BIN esegue l’override del 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 comportamento normale 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. 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 vocale può essere configurato senza perdere la guida predefinita di openclaw_agent_consult.

Correlati

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

Documentation Index

​Valori predefiniti dell’agente

​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 della proprietà del budget di contesto

​agents.defaults.startupContext

​agents.defaults.contextLimits

​agents.list[].contextLimits

​skills.limits.maxSkillsPromptChars

​agents.list[].skillsLimits.maxSkillsPromptChars

​agents.defaults.imageMaxDimensionPx

​agents.defaults.userTimezone

​agents.defaults.timeFormat

​agents.defaults.model

​Policy di runtime

​agents.defaults.cliBackends

​agents.defaults.systemPromptOverride

​agents.defaults.promptOverlays

​agents.defaults.heartbeat

​agents.defaults.compaction

​agents.defaults.runRetries

​agents.defaults.contextPruning

​Streaming a blocchi

​Indicatori di digitazione

​agents.defaults.sandbox

​agents.list (override per agente)

​Routing multi-agente

​Campi di corrispondenza dei binding

​Profili di accesso per agente

​Sessione

​Messaggi

​Prefisso di risposta

​Reazione di ack

​Debounce in ingresso

​TTS (text-to-speech)

​Talk

​Correlati