Configuração — agentes

​

Padrões de agente

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skills

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

• Omita agents.defaults.skills para Skills irrestritas por padrão.
• Omita agents.list[].skills para herdar os padrões.
• Defina agents.list[].skills: [] para nenhuma Skill.
• Uma lista agents.list[].skills não vazia é o conjunto final para esse agente; ela não é mesclada com os padrões.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.skipOptionalBootstrapFiles

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

​

agents.defaults.contextInjection

• "continuation-skip": turnos de continuação seguros (após uma resposta concluída do assistente) ignoram a reinjeção de bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e novas tentativas pós-Compaction ainda reconstroem o contexto.
• "never": desativa a injeção de bootstrap do workspace e de arquivos de contexto em todos os turnos. Use isso apenas para agentes que controlam totalmente o ciclo de vida do próprio prompt (motores de contexto personalizados, runtimes nativos que constroem o próprio contexto ou fluxos de trabalho especializados sem bootstrap). Turnos de Heartbeat e de recuperação de Compaction também ignoram a injeção.

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

Substituições de perfil de bootstrap por agente

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

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": nunca injeta texto de aviso de truncamento no prompt do sistema.
• "once": injeta um aviso conciso uma vez por assinatura de truncamento exclusiva.
• "always": injeta um aviso conciso em toda execução quando há truncamento (recomendado).

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

​

Mapa de propriedade do orçamento de contexto

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: injeção normal de bootstrap do workspace.
• agents.defaults.startupContext.*: prelúdio único de execução de modelo em redefinição/inicialização, incluindo arquivos diários recentes memory/*.md. Comandos simples de chat /new e /reset são confirmados sem invocar o modelo.
• skills.limits.*: a lista compacta de Skills injetada no prompt do sistema.
• agents.defaults.contextLimits.*: trechos limitados de runtime e blocos injetados pertencentes ao runtime.
• memory.qmd.limits.*: dimensionamento de trecho e injeção de busca de memória indexada.

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

​

agents.defaults.startupContext

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

​

agents.defaults.contextLimits

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

• memoryGetMaxChars: limite padrão do trecho memory_get antes que metadados de truncamento e aviso de continuação sejam adicionados.
• memoryGetDefaultLines: janela de linhas padrão de memory_get quando lines é omitido.
• toolResultMaxChars: teto avançado de resultados de ferramentas ao vivo usado para resultados persistidos e recuperação de estouro. Deixe indefinido para o limite automático de contexto do modelo: 16000 caracteres abaixo de 100K tokens, 32000 caracteres em 100K+ tokens e 64000 caracteres em 200K+ tokens. Valores explícitos até 1000000 são aceitos para modelos de contexto longo, mas o limite efetivo ainda é limitado a cerca de 30% da janela de contexto do modelo. openclaw doctor --deep imprime o limite efetivo, e o doctor avisa apenas quando uma substituição explícita está obsoleta ou não tem efeito.
• postCompactionMaxChars: limite de trecho de AGENTS.md usado durante a injeção de atualização pós-Compaction.

​

agents.list[].contextLimits

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

​

skills.limits.maxSkillsPromptChars

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

​

agents.list[].skillsLimits.maxSkillsPromptChars

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

​

agents.defaults.imageMaxDimensionPx

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

​

agents.defaults.imageQuality

• auto: adapta aos limites do modelo e à contagem de imagens.
• efficient: prefere imagens menores para menor uso de tokens e bytes.
• balanced: usa a escala intermediária padrão.
• high: preserva mais detalhes para capturas de tela, diagramas e imagens de documentos.

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

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

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

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // global default provider params
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • A forma de string define apenas o modelo primário.
  • A forma de objeto define o primário mais modelos de failover ordenados.
• imageModel: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pelo caminho da ferramenta image como sua configuração de modelo de visão.
  • Também usado como roteamento de fallback quando o modelo selecionado/padrão não aceita entrada de imagem.
  • Prefira referências explícitas provider/model. IDs sem prefixo são aceitos para compatibilidade; se um ID sem prefixo corresponder exclusivamente a uma entrada configurada com suporte a imagens em models.providers.*.models, o OpenClaw o qualifica para esse provedor. Correspondências configuradas ambíguas exigem um prefixo de provedor explícito.
• imageGenerationModel: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pela capacidade compartilhada de geração de imagens e qualquer superfície futura de ferramenta/Plugin que gere imagens.
  • Valores típicos: google/gemini-3.1-flash-image-preview para geração nativa de imagens Gemini, fal/fal-ai/flux/dev para fal, openai/gpt-image-2 para OpenAI Images ou openai/gpt-image-1.5 para saída PNG/WebP da OpenAI com fundo transparente.
  • Se você selecionar um provedor/modelo diretamente, configure também a autenticação correspondente do provedor (por exemplo, GEMINI_API_KEY ou GOOGLE_API_KEY para google/*, OPENAI_API_KEY ou OpenAI Codex OAuth para openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY para fal/*).
  • Se omitido, image_generate ainda pode inferir um padrão de provedor respaldado por autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de imagens registrados, em ordem de ID de provedor.
• musicGenerationModel: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pela capacidade compartilhada de geração de música e pela ferramenta integrada music_generate.
  • Valores típicos: google/lyria-3-clip-preview, google/lyria-3-pro-preview ou minimax/music-2.6.
  • Se omitido, music_generate ainda pode inferir um padrão de provedor respaldado por autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de música registrados, em ordem de ID de provedor.
  • Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor.
• videoGenerationModel: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta integrada video_generate.
  • Valores típicos: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash ou qwen/wan2.7-r2v.
  • Se omitido, video_generate ainda pode inferir um padrão de provedor respaldado por autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de vídeo registrados, em ordem de ID de provedor.
  • Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor.
  • O Plugin oficial de geração de vídeo Qwen oferece suporte a até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, 10 segundos de duração e opções de nível de provedor size, aspectRatio, resolution, audio e watermark.
• pdfModel: aceita uma string ("provider/model") ou um objeto ({ primary, fallbacks }).
  • Usado pela ferramenta pdf para roteamento de modelo.
  • Se omitido, a ferramenta PDF recorre a imageModel e depois ao modelo resolvido da sessão/padrão.
• pdfMaxBytesMb: limite padrão de tamanho de PDF para a ferramenta pdf quando maxBytesMb não é passado no momento da chamada.
• pdfMaxPages: máximo padrão de páginas consideradas pelo modo de fallback de extração na ferramenta pdf.
• verboseDefault: nível verbose padrão para agentes. Valores: "off", "on", "full". Padrão: "off".
• toolProgressDetail: modo de detalhe para resumos de ferramentas de /verbose e linhas de ferramentas em rascunhos de progresso. Valores: "explain" (padrão, rótulos humanos compactos) ou "raw" (anexa comando/detalhe bruto quando disponível). agents.list[].toolProgressDetail por agente substitui esse padrão.
• reasoningDefault: visibilidade padrão de raciocínio para agentes. Valores: "off", "on", "stream". agents.list[].reasoningDefault por agente substitui esse padrão. Padrões de raciocínio configurados só são aplicados para proprietários, remetentes autorizados ou contextos Gateway de administrador-operador quando nenhuma substituição de raciocínio por mensagem ou sessão está definida.
• elevatedDefault: nível padrão de saída elevada para agentes. Valores: "off", "on", "ask", "full". Padrão: "on".
• model.primary: formato provider/model (por exemplo, openai/gpt-5.5 para acesso por chave de API da OpenAI ou Codex OAuth). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para esse ID de modelo exato e só então recorre ao provedor padrão configurado (comportamento de compatibilidade obsoleto, então prefira provider/model explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de expor um padrão obsoleto de provedor removido.
• models: o catálogo de modelos configurado e a lista de permissões para /model. Cada entrada pode incluir alias (atalho) e params (específico do provedor, por exemplo temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, roteamento OpenRouter provider, chat_template_kwargs, extra_body/extraBody).
  • Use entradas provider/*, como "openai/*": {} ou "vllm/*": {}, para mostrar todos os modelos descobertos para provedores selecionados sem listar manualmente cada ID de modelo.
  • Adicione agentRuntime a uma entrada provider/* quando todos os modelos descobertos dinamicamente para esse provedor devam usar o mesmo runtime. A política de runtime exata provider/model ainda prevalece sobre o curinga.
  • Edições seguras: use openclaw config set agents.defaults.models '<json>' --strict-json --merge para adicionar entradas. config set recusa substituições que removeriam entradas existentes da lista de permissões, a menos que você passe --replace.
  • Fluxos de configuração/onboarding com escopo de provedor mesclam modelos de provedor selecionados nesse mapa e preservam provedores não relacionados já configurados.
  • Para modelos OpenAI Responses diretos, a Compaction do lado do servidor é habilitada automaticamente. Use params.responsesServerCompaction: false para parar de injetar context_management, ou params.responsesCompactThreshold para substituir o limite. Consulte Compaction do lado do servidor da OpenAI.
• params: parâmetros padrão globais de provedor aplicados a todos os modelos. Definido em agents.defaults.params (por exemplo, { cacheRetention: "long" }).
• Precedência de mesclagem de params (configuração): agents.defaults.params (base global) é substituído por agents.defaults.models["provider/model"].params (por modelo) e, em seguida, agents.list[].params (ID de agente correspondente) substitui por chave. Consulte Cache de prompts para obter detalhes.
• models.providers.openrouter.params.provider: política padrão de roteamento de provedor para todo o OpenRouter. O OpenClaw encaminha isso para o objeto provider da requisição do OpenRouter; agents.defaults.models["openrouter/<model>"].params.provider por modelo e parâmetros de agente substituem por chave. Consulte roteamento de provedor OpenRouter.
• params.extra_body/params.extraBody: JSON avançado de repasse mesclado nos corpos de requisição api: "openai-completions" para proxies compatíveis com OpenAI. Se colidir com chaves de requisição geradas, o corpo extra prevalece; rotas de completions não nativas ainda removem store exclusivo da OpenAI depois disso.
• params.chat_template_kwargs: argumentos de template de chat compatíveis com vLLM/OpenAI mesclados nos corpos de requisição de nível superior api: "openai-completions". Para vllm/nemotron-3-* com raciocínio desativado, o Plugin vLLM incluído envia automaticamente enable_thinking: false e force_nonempty_content: true; chat_template_kwargs explícito substitui padrões gerados, e extra_body.chat_template_kwargs ainda tem precedência final. Modelos configurados de raciocínio vLLM Qwen e Nemotron expõem opções binárias de /think (off, on) em vez da escada de esforço multinível.
• compat.thinkingFormat: estilo de payload de raciocínio compatível com OpenAI. Use "together" para reasoning.enabled no estilo Together, "qwen" para enable_thinking de nível superior no estilo Qwen ou "qwen-chat-template" para chat_template_kwargs.enable_thinking em backends da família Qwen que oferecem suporte a kwargs de template de chat no nível da requisição, como vLLM. O OpenClaw mapeia raciocínio desabilitado para false e raciocínio habilitado para true, e modelos vLLM Qwen configurados expõem opções binárias de /think para esses formatos.
• compat.supportedReasoningEfforts: lista de esforço de raciocínio compatível com OpenAI por modelo. Inclua "xhigh" para endpoints personalizados que realmente o aceitam; então o OpenClaw expõe /think xhigh em menus de comando, linhas de sessão do Gateway, validação de patch de sessão, validação de CLI de agente e validação de llm-task para esse provedor/modelo configurado. Use compat.reasoningEffortMap quando o backend quiser um valor específico do provedor para um nível canônico.
• params.preserveThinking: opt-in exclusivo da Z.AI para raciocínio preservado. Quando habilitado e o raciocínio está ativo, o OpenClaw envia thinking.clear_thinking: false e reproduz reasoning_content anterior; consulte raciocínio e raciocínio preservado da Z.AI.
• localService: gerenciador de processo opcional em nível de provedor para servidores de modelo locais/auto-hospedados. Quando o modelo selecionado pertence a esse provedor, o OpenClaw sonda healthUrl (ou baseUrl + "/models"), inicia command com args se o endpoint estiver fora do ar, aguarda até readyTimeoutMs e então envia a requisição do modelo. command deve ser um caminho absoluto. idleStopMs: 0 mantém o processo ativo até o OpenClaw sair; um valor positivo interrompe o processo iniciado pelo OpenClaw após esse número de milissegundos ociosos. Consulte Serviços de modelo locais.
• A política de runtime pertence a provedores ou modelos, não a agents.defaults. Use models.providers.<provider>.agentRuntime para regras em todo o provedor ou agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime para regras específicas do modelo. Modelos de agente OpenAI no provedor oficial OpenAI selecionam Codex por padrão.
• Gravadores de configuração que alteram esses campos (por exemplo, /models set, /models set-image e comandos de adicionar/remover fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível.
• maxConcurrent: máximo de execuções paralelas de agentes entre sessões (cada sessão ainda é serializada). Padrão: 4.

​

Política de runtime

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

• id: "auto", "openclaw", um id de harness de Plugin registrado ou um alias de backend de CLI compatível. O Plugin Codex incluído registra codex; o Plugin Anthropic incluído fornece o backend de CLI claude-cli.
• id: "auto" permite que harnesses de Plugin registrados reivindiquem turnos compatíveis e usa OpenClaw quando nenhum harness corresponde. Um runtime de Plugin explícito, como id: "codex", exige esse harness e falha de forma fechada se ele estiver indisponível ou falhar.
• id: "pi" é aceito apenas como um alias obsoleto de openclaw para preservar configurações lançadas na v2026.5.22 e anteriores. Novas configurações devem usar openclaw.
• A precedência de runtime é primeiro a política exata do modelo (agents.list[].models["provider/model"], agents.defaults.models["provider/model"] ou models.providers.<provider>.models[]), depois agents.list[] / agents.defaults.models["provider/*"], e então a política de todo o provedor em models.providers.<provider>.agentRuntime.
• Chaves de runtime de agente inteiro são legadas. agents.defaults.agentRuntime, agents.list[].agentRuntime, pins de runtime de sessão e OPENCLAW_AGENT_RUNTIME são ignorados pela seleção de runtime. Execute openclaw doctor --fix para remover valores obsoletos.
• Modelos de agente OpenAI usam o harness Codex por padrão; agentRuntime.id: "codex" de provedor/modelo continua válido quando você quiser tornar isso explícito.
• Para implantações do Claude CLI, prefira model: "anthropic/claude-opus-4-8" mais agentRuntime.id: "claude-cli" com escopo de modelo. Referências de modelo legadas claude-cli/claude-opus-4-7 ainda funcionam por compatibilidade, mas novas configurações devem manter a seleção de provedor/modelo canônica e colocar o backend de execução na política de runtime de provedor/modelo.
• Isso controla apenas a execução de turnos de agente de texto. Geração de mídia, visão, PDF, música, vídeo e TTS ainda usam suas configurações de provedor/modelo.

​

agents.defaults.cliBackends

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

• Backends de CLI priorizam texto; ferramentas estão sempre desativadas.
• Sessões são compatíveis quando sessionArg está definido.
• Passagem direta de imagem é compatível quando imageArg aceita caminhos de arquivo.
• reseedFromRawTranscriptWhenUncompacted: true permite que um backend recupere sessões invalidadas seguras a partir de uma cauda limitada de transcrição bruta do OpenClaw antes que exista o primeiro resumo de Compaction. Mudanças de perfil de autenticação ou época de credenciais ainda nunca fazem reseed bruto.

​

agents.defaults.promptOverlays

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

• "friendly" (padrão) e "on" ativam a camada amigável de estilo de interação.
• "off" desativa apenas a camada amigável; o contrato de comportamento GPT-5 marcado permanece ativado.
• plugins.entries.openai.config.personality legado ainda é lido quando esta configuração compartilhada não está definida.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: string de duração (ms/s/m/h). Padrão: 30m (autenticação por chave de API) ou 1h (autenticação OAuth). Defina como 0m para desativar.
• includeSystemPromptSection: quando falso, omite a seção Heartbeat do prompt do sistema e pula a injeção de HEARTBEAT.md no contexto de bootstrap. Padrão: true.
• suppressToolErrorWarnings: quando verdadeiro, suprime payloads de aviso de erro de ferramenta durante execuções de Heartbeat.
• timeoutSeconds: tempo máximo em segundos permitido para um turno de agente de Heartbeat antes de ser abortado. Deixe indefinido para usar agents.defaults.timeoutSeconds quando definido; caso contrário, a cadência de Heartbeat limitada a 600 segundos.
• directPolicy: política de entrega direta/DM. allow (padrão) permite entrega para destino direto. block suprime entrega para destino direto e emite reason=dm-blocked.
• lightContext: quando verdadeiro, execuções de Heartbeat usam contexto de bootstrap leve e mantêm apenas HEARTBEAT.md dos arquivos de bootstrap do workspace.
• isolatedSession: quando verdadeiro, cada Heartbeat é executado em uma sessão nova, sem histórico de conversa anterior. Mesmo padrão de isolamento que sessionTarget: "isolated" de Cron. Reduz o custo de tokens por Heartbeat de ~100 mil para ~2-5 mil tokens.
• skipWhenBusy: quando verdadeiro, execuções de Heartbeat são adiadas nas lanes extras ocupadas desse agente: seu próprio subagente com chave de sessão ou trabalho de comando aninhado. Lanes de Cron sempre adiam Heartbeats, mesmo sem esta flag.
• Por agente: defina agents.list[].heartbeat. Quando qualquer agente define heartbeat, somente esses agentes executam Heartbeats.
• Heartbeats executam turnos completos de agente — intervalos mais curtos consomem mais tokens.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 180,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // opt in to AGENTS.md section reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default ou safeguard (sumarização em partes para históricos longos). Consulte Compaction.
• provider: id de um Plugin provedor de compaction registrado. Quando definido, o summarize() do provedor é chamado em vez da sumarização LLM integrada. Recorre à integrada em caso de falha. Definir um provedor força mode: "safeguard". Consulte Compaction.
• timeoutSeconds: máximo de segundos permitido para uma única operação de compaction antes que o OpenClaw a aborte. Padrão: 180.
• keepRecentTokens: orçamento de ponto de corte do agente para manter literalmente a parte mais recente da transcrição. O /compact manual respeita isso quando definido explicitamente; caso contrário, a compaction manual é um checkpoint rígido.
• identifierPolicy: strict (padrão), off ou custom. strict prefixa orientações integradas de retenção de identificadores opacos durante a sumarização de compaction.
• identifierInstructions: texto personalizado opcional de preservação de identificadores usado quando identifierPolicy=custom.
• qualityGuard: verificações de nova tentativa em saída malformada para resumos de safeguard. Habilitado por padrão no modo safeguard; defina enabled: false para ignorar a auditoria.
• midTurnPrecheck: verificação opcional de pressão do ciclo de ferramentas. Quando enabled: true, o OpenClaw verifica a pressão de contexto depois que os resultados das ferramentas são anexados e antes da próxima chamada ao modelo. Se o contexto não couber mais, ele aborta a tentativa atual antes de enviar o prompt e reutiliza o caminho de recuperação de pré-verificação existente para truncar resultados de ferramentas ou compactar e tentar novamente. Funciona com os modos de compaction default e safeguard. Padrão: desabilitado.
• postCompactionSections: nomes opcionais de seções H2/H3 do AGENTS.md para reinjetar após a compaction. A reinjeção fica desabilitada quando não definida ou definida como []. Definir explicitamente ["Session Startup", "Red Lines"] habilita esse par e preserva o fallback legado Every Session/Safety. Habilite isso somente quando o contexto extra valer o risco de duplicar orientações do projeto já capturadas no resumo de compaction.
• model: provider/model-id opcional ou alias simples de agents.defaults.models somente para sumarização de compaction. Aliases simples são resolvidos antes do despacho; IDs literais de modelo configurados mantêm precedência em colisões. Use isto quando a sessão principal deve manter um modelo, mas os resumos de compaction devem rodar em outro; quando não definido, a compaction usa o modelo primário da sessão.
• maxActiveTranscriptBytes: limite opcional em bytes (number ou strings como "20mb") que aciona a compaction local normal antes de uma execução quando o JSONL ativo ultrapassa o limite. Requer truncateAfterCompaction para que uma compaction bem-sucedida possa rotacionar para uma transcrição sucessora menor. Desabilitado quando não definido ou 0.
• notifyUser: quando true, envia avisos breves ao usuário quando a compaction começa e quando é concluída (por exemplo, “Compactando contexto…” e “Compaction concluída”). Desabilitado por padrão para manter a compaction silenciosa.
• memoryFlush: turno agêntico silencioso antes da compaction automática para armazenar memórias duráveis. Defina model para um provedor/modelo exato, como ollama/qwen3:8b, quando este turno de manutenção deve permanecer em um modelo local; a substituição não herda a cadeia de fallback da sessão ativa. Ignorado quando o workspace é somente leitura.

​

agents.defaults.runRetries

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

• base: número base de iterações de repetição de execução para o loop externo de execução. Padrão: 24.
• perProfile: iterações adicionais de repetição de execução concedidas por candidato de perfil de fallback. Padrão: 8.
• min: limite absoluto mínimo para iterações de repetição de execução. Padrão: 32.
• max: limite absoluto máximo para iterações de repetição de execução para evitar execução descontrolada. Padrão: 160.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

Streaming em blocos

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

• Canais que não sejam Telegram exigem *.blockStreaming: true explícito para habilitar respostas em blocos.
• Substituições por canal: channels.<channel>.blockStreamingCoalesce (e variantes por conta). Signal/Slack/Discord/Google Chat usam minChars: 1500 por padrão.
• humanDelay: pausa aleatória entre respostas em blocos. natural = 800–2500ms. Substituição por agente: agents.list[].humanDelay.

​

Indicadores de digitação

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

• Padrões: instant para chats diretos/menções, message para chats em grupo sem menção.
• Substituições por sessão: session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

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

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

​

agents.list (substituições por agente)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: id de agente estável (obrigatório).
• default: quando vários são definidos, o primeiro vence (aviso registrado). Se nenhum for definido, a primeira entrada da lista será o padrão.
• model: a forma em string define um primário estrito por agente sem fallback de modelo; a forma de objeto { primary } também é estrita, a menos que você adicione fallbacks. Use { primary, fallbacks: [...] } para optar esse agente em fallback, ou { primary, fallbacks: [] } para tornar o comportamento estrito explícito. Tarefas Cron que substituem apenas primary ainda herdam fallbacks padrão, a menos que você defina fallbacks: [].
• params: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em agents.defaults.models. Use isto para substituições específicas do agente, como cacheRetention, temperature ou maxTokens, sem duplicar todo o catálogo de modelos.
• tts: substituições opcionais de texto para fala por agente. O bloco faz uma mesclagem profunda sobre messages.tts, então mantenha credenciais de provedor compartilhadas e política de fallback em messages.tts e defina aqui somente valores específicos da persona, como provedor, voz, modelo, estilo ou modo automático.
• skills: lista de permissão opcional de Skills por agente. Se omitida, o agente herda agents.defaults.skills quando definido; uma lista explícita substitui os padrões em vez de mesclar, e [] significa sem Skills.
• thinkingDefault: nível de pensamento padrão opcional por agente (off | minimal | low | medium | high | xhigh | adaptive | max). Substitui agents.defaults.thinkingDefault para este agente quando nenhuma substituição por mensagem ou sessão estiver definida. O perfil de provedor/modelo selecionado controla quais valores são válidos; para Google Gemini, adaptive mantém o pensamento dinâmico controlado pelo provedor (thinkingLevel omitido no Gemini 3/3.1, thinkingBudget: -1 no Gemini 2.5).
• reasoningDefault: visibilidade de raciocínio padrão opcional por agente (on | off | stream). Substitui agents.defaults.reasoningDefault para este agente quando nenhuma substituição de raciocínio por mensagem ou sessão estiver definida.
• fastModeDefault: padrão opcional por agente para modo rápido ("auto" | true | false). Aplica-se quando nenhuma substituição de modo rápido por mensagem ou sessão estiver definida.
• models: catálogo de modelos/substituições de runtime opcionais por agente, indexados por ids completos provider/model. Use models["provider/model"].agentRuntime para exceções de runtime por agente.
• runtime: descritor de runtime opcional por agente. Use type: "acp" com padrões de runtime.acp (agent, backend, mode, cwd) quando o agente deve usar sessões de harness ACP por padrão.
• identity.avatar: caminho relativo ao espaço de trabalho, URL http(s) ou URI data:.
• Arquivos de imagem locais relativos ao espaço de trabalho em identity.avatar são limitados a 2 MB. URLs http(s) e URIs data: não são verificadas com o limite de tamanho de arquivo local.
• identity deriva padrões: ackReaction de emoji, mentionPatterns de name/emoji.
• subagents.allowAgents: lista de permissão de ids de agentes configurados para alvos explícitos sessions_spawn.agentId (["*"] = qualquer alvo configurado; padrão: somente o mesmo agente). Inclua o id do solicitante quando chamadas agentId autodirecionadas devem ser permitidas. Entradas obsoletas cuja configuração de agente foi excluída são rejeitadas por sessions_spawn e omitidas de agents_list; execute openclaw doctor --fix para limpá-las, ou adicione uma entrada mínima agents.list[] se esse alvo deve permanecer disponível para spawn enquanto herda os padrões.
• Guarda de herança de sandbox: se a sessão solicitante estiver em sandbox, sessions_spawn rejeita alvos que seriam executados sem sandbox.
• subagents.requireAgentId: quando verdadeiro, bloqueia chamadas sessions_spawn que omitem agentId (força seleção explícita de perfil; padrão: falso).

​

Roteamento multiagente

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

​

Campos de correspondência de binding

• type (opcional): route para roteamento normal (tipo ausente usa route por padrão), acp para bindings persistentes de conversa ACP.
• match.channel (obrigatório)
• match.accountId (opcional; * = qualquer conta; omitido = conta padrão)
• match.peer (opcional; { kind: direct|group|channel, id })
• match.guildId / match.teamId (opcional; específico do canal)
• acp (opcional; somente para type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exato, sem peer/guild/team)
5. match.accountId: "*" (abrangendo todo o canal)
6. Agente padrão

​

Perfis de acesso por agente

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

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

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

​

Sessão

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "enforce", // enforce (default) | warn
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Mensagens

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "followup", // steer | followup | collect | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Prefixo de resposta

​

Reação de confirmação

• O padrão é identity.emoji do agente ativo; caso contrário, "👀". Defina "" para desativar.
• Substituições por canal: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Ordem de resolução: conta → canal → messages.ackReaction → fallback de identidade.
• Escopo: group-mentions (padrão), group-all, direct, all.
• removeAckAfterReply: remove a confirmação após a resposta em canais compatíveis com reações, como Slack, Discord, Signal, Telegram, WhatsApp e iMessage.
• messages.statusReactions.enabled: ativa reações de status de ciclo de vida no Slack, Discord, Signal, Telegram e WhatsApp. No Slack e Discord, indefinido mantém as reações de status ativadas quando reações de confirmação estão ativas. No Signal, Telegram e WhatsApp, defina explicitamente como true para ativar reações de status de ciclo de vida.
• messages.statusReactions.emojis: substitui chaves de emoji de ciclo de vida: queued, thinking, compacting, tool, coding, web, deploy, build, concierge, done, error, stallSoft e stallHard. O Telegram permite apenas um conjunto fixo de reações, portanto emojis configurados sem suporte recorrem à variante de status compatível mais próxima para esse chat.

​

Debounce de entrada

​

TTS (texto para fala)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-5.4-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          speakerVoiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
        microsoft: {
          speakerVoice: "en-US-AvaMultilingualNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        },
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          speakerVoice: "alloy",
        },
      },
    },
  },
}

• auto controla o modo auto-TTS padrão: off, always, inbound ou tagged. /tts on|off pode substituir as preferências locais, e /tts status mostra o estado efetivo.
• summaryModel substitui agents.defaults.model.primary para resumo automático.
• modelOverrides é habilitado por padrão; modelOverrides.allowProvider usa false como padrão (adesão explícita).
• As chaves de API recorrem a ELEVENLABS_API_KEY/XI_API_KEY e OPENAI_API_KEY.
• Os provedores de fala incluídos são propriedade do Plugin. Se plugins.allow estiver definido, inclua cada Plugin de provedor de TTS que você quer usar, por exemplo microsoft para Edge TTS. O id de provedor legado edge é aceito como alias para microsoft.
• providers.openai.baseUrl substitui o endpoint de TTS da OpenAI. A ordem de resolução é configuração, depois OPENAI_TTS_BASE_URL, depois https://api.openai.com/v1.
• Quando providers.openai.baseUrl aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor TTS compatível com OpenAI e flexibiliza a validação de modelo/voz.

​

Fala

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2",
          speakerVoice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• talk.provider deve corresponder a uma chave em talk.providers quando vários provedores de Fala estiverem configurados.
• Chaves legadas planas de Fala (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) são apenas para compatibilidade. Execute openclaw doctor --fix para reescrever a configuração persistida em talk.providers.<provider>.
• IDs de voz recorrem a ELEVENLABS_VOICE_ID ou SAG_VOICE_ID.
• providers.*.apiKey aceita strings em texto puro ou objetos SecretRef.
• O fallback ELEVENLABS_API_KEY se aplica somente quando nenhuma chave de API de Fala estiver configurada.
• providers.*.voiceAliases permite que diretivas de Fala usem nomes amigáveis.
• providers.mlx.modelId seleciona o repositório do Hugging Face usado pelo helper MLX local do macOS. Se omitido, o macOS usa mlx-community/Soprano-80M-bf16.
• A reprodução MLX no macOS é executada pelo helper incluído openclaw-mlx-tts quando presente, ou por um executável no PATH; OPENCLAW_MLX_TTS_BIN substitui o caminho do helper para desenvolvimento.
• consultThinkingLevel controla o nível de raciocínio para a execução completa do agente OpenClaw por trás das chamadas openclaw_agent_consult realtime de Fala da Control UI. Deixe sem definir para preservar o comportamento normal de sessão/modelo.
• consultFastMode define uma substituição única de modo rápido para consultas realtime de Fala da Control UI sem alterar a configuração normal de modo rápido da sessão.
• speechLocale define o id de localidade BCP 47 usado pelo reconhecimento de fala de Fala no iOS/macOS. Deixe sem definir para usar o padrão do dispositivo.
• silenceTimeoutMs controla por quanto tempo o modo Fala espera após o silêncio do usuário antes de enviar a transcrição. Não definir mantém a janela de pausa padrão da plataforma (700 ms no macOS e Android, 900 ms no iOS).
• realtime.instructions acrescenta instruções de sistema voltadas ao provedor ao prompt realtime integrado do OpenClaw, para que o estilo de voz possa ser configurado sem perder a orientação padrão de openclaw_agent_consult.
• realtime.consultRouting controla o fallback de retransmissão do Gateway quando o provedor realtime produz uma transcrição final do usuário sem openclaw_agent_consult: provider-direct preserva respostas diretas do provedor, enquanto force-agent-consult encaminha a solicitação finalizada pelo OpenClaw.

​

Relacionado

• Referência de configuração — todas as outras chaves de configuração
• Configuração — tarefas comuns e configuração rápida
• Exemplos de configuração