Referência de configuração

Referência em nível de campo para ~/.openclaw/openclaw.json: chaves, valores padrão e links para páginas mais detalhadas dos subsistemas. Para orientações de configuração voltadas a tarefas, consulte Configuração. Os catálogos de comandos pertencentes a canais e plugins e os ajustes avançados de memória/QMD estão em suas próprias páginas, não aqui.

O formato da configuração é JSON5 (comentários e vírgulas finais são permitidos). Todos os campos são opcionais; o OpenClaw usa valores padrão seguros quando eles são omitidos.

O código prevalece sobre esta página:

• openclaw config schema exibe o JSON Schema ativo usado para validação e pela interface de controle, com os metadados de itens integrados/plugins/canais mesclados.
• Os agentes devem chamar a ação config.schema.lookup da ferramenta gateway para obter um único nó exato do esquema, restrito ao caminho, antes de editar a configuração.
• pnpm config:docs:check / pnpm config:docs:gen validam o hash de referência desta documentação em relação à superfície atual do esquema.

Referências detalhadas específicas:

• Referência de configuração de memória para agents.defaults.memorySearch.*, memory.qmd.*, memory.citations e a configuração de Dreaming em plugins.entries.memory-core.config.dreaming.
• Comandos de barra para o catálogo atual de comandos integrados + incluídos.
• Páginas dos canais/plugins responsáveis pelas superfícies de comandos específicas de cada canal.

Canais

As chaves de configuração específicas de cada canal estão em Configuração — canais: channels.* para Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e outros canais incluídos (autenticação, controle de acesso, múltiplas contas, restrição por menção).

Padrões do agente, múltiplos agentes, sessões e mensagens

Consulte Configuração — agentes para:

• agents.defaults.* (espaço de trabalho, modelo, raciocínio, Heartbeat, memória, mídia, Skills, sandbox)
• multiAgent.* (roteamento e vinculações de múltiplos agentes)
• session.* (ciclo de vida da sessão, Compaction, remoção)
• messages.* (entrega de mensagens, TTS, renderização de markdown)
• talk.* (modo de conversa)
  • talk.consultThinkingLevel: substituição do nível de raciocínio para toda a execução do agente OpenClaw por trás das consultas em tempo real do Talk na interface de controle
  • talk.consultFastMode: substituição pontual do modo rápido para consultas em tempo real do Talk na interface de controle
  • talk.speechLocale: identificador de localidade BCP 47 opcional para o reconhecimento de fala do Talk no iOS/macOS
  • talk.silenceTimeoutMs: quando não definido, o Talk mantém a janela de pausa padrão da plataforma antes de enviar a transcrição (700 ms on macOS and Android, 900 ms on iOS)
  • talk.realtime.consultRouting: fallback de retransmissão do Gateway para transcrições finalizadas do Talk em tempo real que ignoram openclaw_agent_consult

Ferramentas e provedores personalizados

A política de ferramentas, as opções experimentais, a configuração de ferramentas baseadas em provedores e a configuração de provedores personalizados / URLs base ficam em Configuração — ferramentas e provedores personalizados.

Modelos

As definições de provedores, as listas de modelos permitidos e a configuração de provedores personalizados ficam em Configuração — ferramentas e provedores personalizados. A raiz models também controla o comportamento global do catálogo de modelos.

{  models: {    // Opcional. Padrão: true. Requer a reinicialização do Gateway quando alterado.    pricing: { enabled: false },  },}

• models.mode: comportamento do catálogo de provedores (merge ou replace).
• models.providers: mapa de provedores personalizados indexado pelo id do provedor.
• models.providers.*.localService: gerenciador opcional de processos sob demanda para servidores locais de modelos. O OpenClaw consulta o endpoint de integridade configurado, inicia o command absoluto quando necessário, aguarda até que esteja pronto e então envia a solicitação ao modelo. Consulte Serviços locais de modelos.
• models.pricing.enabled: controla a inicialização em segundo plano dos preços, que começa depois que os processos auxiliares e canais alcançam o caminho de prontidão do Gateway. Quando false, o Gateway ignora as buscas dos catálogos de preços do OpenRouter e do LiteLLM; os valores models.providers.*.models[].cost configurados continuam funcionando para estimativas locais de custo.

MCP

As definições de servidores MCP gerenciadas pelo OpenClaw ficam em mcp.servers e são consumidas pelo OpenClaw incorporado e por outros adaptadores de runtime. Os comandos openclaw mcp list, show, set e unset gerenciam esse bloco sem se conectar ao servidor de destino durante as edições de configuração.

{  mcp: {    // Opcional. Padrão: 600000 ms (10 minutos). Defina como 0 para desativar a remoção por inatividade.    sessionIdleTtlMs: 600000,    servers: {      docs: {        command: "npx",        args: ["-y", "@modelcontextprotocol/server-fetch"],      },      remote: {        url: "https://example.com/mcp",        transport: "streamable-http", // streamable-http | sse        timeout: 20,        connectTimeout: 5,        supportsParallelToolCalls: true,        headers: {          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",        },        auth: "oauth",        oauth: {          scope: "docs.read",        },        sslVerify: true,        clientCert: "/path/to/client.crt",        clientKey: "/path/to/client.key",        toolFilter: {          include: ["search_*"],          exclude: ["admin_*"],        },        // Controles opcionais de projeção do servidor de aplicativos Codex.        codex: {          agents: ["main"],          defaultToolsApprovalMode: "approve", // auto | prompt | approve        },      },    },  },}

• mcp.servers: definições nomeadas de servidores MCP stdio ou remotos para runtimes que expõem as ferramentas MCP configuradas. As entradas remotas usam transport: "streamable-http" ou transport: "sse"; type: "http" é um alias nativo da CLI que openclaw mcp set e openclaw doctor --fix normalizam para o campo canônico transport.
• mcp.servers.<name>.enabled: defina como false para manter uma definição de servidor salva, mas excluí-la da descoberta de MCP e da projeção de ferramentas do OpenClaw incorporado.
• mcp.servers.<name>.timeout / requestTimeoutMs: tempo limite por servidor para solicitações MCP, em segundos ou milissegundos.
• mcp.servers.<name>.connectTimeout / connectionTimeoutMs: tempo limite por servidor para conexão, em segundos ou milissegundos.
• mcp.servers.<name>.supportsParallelToolCalls: indicação opcional de simultaneidade para adaptadores que podem escolher se devem emitir chamadas paralelas de ferramentas MCP.
• mcp.servers.<name>.auth: defina como "oauth" para servidores MCP HTTP que exigem OAuth. Execute openclaw mcp login <name> para armazenar tokens no estado do OpenClaw.
• mcp.servers.<name>.oauth: substituições opcionais de escopo OAuth, URL de redirecionamento e URL de metadados do cliente.
• mcp.servers.<name>.sslVerify, clientCert, clientKey: controles TLS HTTP para endpoints privados e TLS mútuo.
• mcp.servers.<name>.toolFilter: seleção opcional de ferramentas por servidor. include limita as ferramentas MCP descobertas aos nomes correspondentes; exclude oculta os nomes correspondentes. As entradas são nomes exatos de ferramentas MCP ou padrões glob simples com *. Servidores com recursos ou prompts também geram nomes de ferramentas utilitárias (resources_list, resources_read, prompts_list, prompts_get), e esses nomes usam o mesmo filtro.
• mcp.servers.<name>.codex: controles opcionais de projeção do servidor de aplicativos Codex. Esse bloco é composto por metadados do OpenClaw apenas para threads do servidor de aplicativos Codex; ele não afeta sessões ACP, a configuração genérica do ambiente Codex nem outros adaptadores de runtime. Uma lista não vazia em codex.agents limita o servidor aos ids de agentes do OpenClaw listados. Listas de agentes com escopo vazias, em branco ou inválidas são rejeitadas pela validação da configuração e omitidas pelo caminho de projeção do runtime, em vez de se tornarem globais. codex.defaultToolsApprovalMode emite o default_tools_approval_mode nativo do Codex para esse servidor. O OpenClaw remove o bloco codex antes de passar a configuração nativa mcp_servers ao Codex. Omita o bloco para manter o servidor projetado para todos os agentes do servidor de aplicativos Codex com o comportamento padrão de aprovação MCP do Codex.
• mcp.sessionIdleTtlMs: TTL de inatividade para runtimes MCP integrados com escopo de sessão. Execuções incorporadas pontuais solicitam limpeza ao fim da execução; esse TTL funciona como proteção para sessões de longa duração e futuros chamadores.
• As alterações em mcp.* são aplicadas a quente por meio do descarte dos runtimes MCP em cache da sessão. A próxima descoberta ou utilização de ferramentas os recria com base na nova configuração, de modo que as entradas removidas de mcp.servers sejam eliminadas imediatamente, em vez de aguardar o TTL de inatividade.
• A descoberta em runtime também respeita as notificações de alteração na lista de ferramentas MCP, descartando o catálogo em cache dessa sessão. Servidores que anunciam recursos ou prompts recebem ferramentas utilitárias para listar/ler recursos e listar/obter prompts. Falhas repetidas nas chamadas de ferramentas pausam brevemente o servidor afetado antes que outra chamada seja tentada.

Consulte MCP e Backends da CLI para saber mais sobre o comportamento em runtime.

Skills

{  skills: {    allowBundled: ["gemini", "peekaboo"],    load: {      extraDirs: ["~/Projects/agent-scripts/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },    install: {      preferBrew: true,      nodeManager: "npm", // npm | pnpm | yarn | bun      allowUploadedArchives: false,    },    workshop: {      allowSymlinkTargetWrites: false,    },    entries: {      "image-lab": {        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // ou string em texto simples        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },      },      peekaboo: { enabled: true },      sag: { enabled: false },    },  },}

• allowBundled: lista opcional de permissão apenas para skills integradas (skills gerenciadas/do espaço de trabalho não são afetadas).
• load.extraDirs: raízes adicionais de skills compartilhadas (menor precedência).
• load.allowSymlinkTargets: raízes de destino reais confiáveis para as quais os links simbólicos de skills podem apontar quando o link está fora da raiz de origem configurada.
• workshop.allowSymlinkTargetWrites: permite que a aplicação do Skill Workshop grave por meio de destinos de links simbólicos já confiáveis (padrão: false).
• install.preferBrew: quando verdadeiro, prioriza os instaladores do Homebrew quando brew está disponível antes de recorrer a outros tipos de instalador.
• install.nodeManager: preferência de instalador do Node para as especificações metadata.openclaw.install (npm | pnpm | yarn | bun).
• install.allowUploadedArchives: permite que clientes confiáveis operator.admin do Gateway instalem arquivos zip privados preparados por meio de skills.upload.* (padrão: false). Isso habilita apenas o caminho de arquivos enviados; as instalações normais do ClawHub não exigem essa opção.
• entries.<skillKey>.enabled: false desativa uma skill mesmo que ela esteja integrada/instalada.
• entries.<skillKey>.apiKey: conveniência para skills que declaram uma variável de ambiente principal (string em texto simples ou objeto SecretRef).
• limits.maxCandidatesPerRoot, limits.maxSkillsLoadedPerSource, limits.maxSkillsInPrompt, limits.maxSkillsPromptChars, limits.maxSkillFileBytes: limitam a descoberta de skills e o prompt de skills apresentado ao modelo.
• As configurações de autonomia/aprovação do Skill Workshop (workshop.autonomous.enabled, workshop.approvalPolicy, workshop.maxPending, workshop.maxSkillBytes) estão documentadas em Configuração de Skills.

Plugins

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: [],    load: {      paths: ["~/Projects/oss/voice-call-plugin"],    },    entries: {      "voice-call": {        enabled: true,        hooks: {          allowPromptInjection: false,        },        config: { provider: "twilio" },      },    },  },}

• Carregados de diretórios de pacotes ou bundles em ~/.openclaw/extensions e <workspace>/.openclaw/extensions, além de arquivos ou diretórios listados em plugins.load.paths.
• Coloque arquivos de plugin independentes em plugins.load.paths; as raízes de extensões descobertas automaticamente ignoram arquivos .js, .mjs e .ts no nível superior, para que scripts auxiliares nessas raízes não bloqueiem a inicialização.
• A descoberta aceita plugins nativos do OpenClaw, além de bundles compatíveis do Codex e do Claude, incluindo bundles do Claude sem manifesto que usam o layout padrão.
• Alterações na configuração exigem a reinicialização do gateway.
• allow: lista de permissões opcional (somente os plugins listados são carregados). deny prevalece.
• plugins.entries.<id>.apiKey: campo de conveniência para a chave de API no nível do plugin (quando compatível com o plugin).
• plugins.entries.<id>.env: mapa de variáveis de ambiente com escopo do plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: quando false, o núcleo bloqueia before_prompt_build e ignora campos que modificam o prompt do before_agent_start legado, preservando os campos legados modelOverride e providerOverride. Aplica-se a hooks de plugins nativos e a diretórios de hooks fornecidos por bundles compatíveis.
• plugins.entries.<id>.hooks.allowConversationAccess: quando true, plugins confiáveis não incluídos no bundle podem ler o conteúdo bruto da conversa em hooks tipados como llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize e agent_end.
• plugins.entries.<id>.subagent.allowModelOverride: confia explicitamente neste plugin para solicitar substituições de provider e model por execução em execuções de subagentes em segundo plano.
• plugins.entries.<id>.subagent.allowedModels: lista de permissões opcional de destinos canônicos provider/model para substituições de subagentes confiáveis. Use "*" somente quando quiser permitir intencionalmente qualquer modelo.
• plugins.entries.<id>.llm.allowModelOverride: confia explicitamente neste plugin para solicitar substituições de modelo para api.runtime.llm.complete.
• plugins.entries.<id>.llm.allowedModels: lista de permissões opcional de destinos canônicos provider/model para substituições confiáveis de conclusão de LLM do plugin. Use "*" somente quando quiser permitir intencionalmente qualquer modelo.
• plugins.entries.<id>.llm.allowAgentIdOverride: confia explicitamente neste plugin para executar api.runtime.llm.complete com um id de agente diferente do padrão.
• plugins.entries.<id>.config: objeto de configuração definido pelo plugin (validado pelo esquema do plugin nativo do OpenClaw quando disponível).
• As configurações de conta e de runtime do plugin de canal ficam em channels.<id> e devem ser descritas pelos metadados channelConfigs do manifesto do plugin proprietário, não por um registro central de opções do OpenClaw.

Configuração do plugin do harness do Codex

O plugin codex incluído no bundle é responsável pelas configurações nativas do harness do servidor de aplicativos do Codex em plugins.entries.codex.config. Consulte a referência do harness do Codex para ver toda a superfície de configuração e Harness do Codex para conhecer o modelo de runtime.

codexPlugins aplica-se somente às sessões que selecionam o harness nativo do Codex. Ele não habilita plugins do Codex para execuções de provedores do OpenClaw, associações de conversas ACP nem qualquer harness que não seja do Codex.

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_all_plugins: true,            allow_destructive_actions: "auto",            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",                allow_destructive_actions: false,              },            },          },        },      },    },  },}

• plugins.entries.codex.config.codexPlugins.enabled: habilita o suporte nativo a plugins/aplicativos do Codex para o harness do Codex. Padrão: false.
• plugins.entries.codex.config.codexPlugins.allow_all_plugins: expõe todos os aplicativos atualmente acessíveis conectados à conta autenticada do Codex em cada nova thread nativa do Codex. Padrão: false.
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: política padrão de ações destrutivas para solicitações de aplicativos de plugins configurados. Use true para aceitar esquemas seguros de aprovação do Codex sem solicitar confirmação, false para recusá-los, "auto" para encaminhar aprovações exigidas pelo Codex pelas aprovações de plugins do OpenClaw ou "ask" para solicitar confirmação para cada ação de gravação/destrutiva do plugin sem aprovação duradoura. O modo "ask" limpa as substituições duradouras de aprovação por ferramenta do Codex para o aplicativo afetado e seleciona o revisor humano de aprovações desse aplicativo antes do início da thread do Codex. Padrão: true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: habilita uma entrada de plugin configurada quando codexPlugins.enabled global também é verdadeiro. Padrão: true para entradas explícitas.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: identidade estável do marketplace, obrigatória junto com pluginName para cada entrada resolvida. Compatível com "openai-curated" e "workspace-directory". Entradas sem qualquer um dos campos de identidade são ignoradas.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: identidade estável do plugin do Codex, obrigatória junto com marketplaceName. Uma entrada workspace-directory deve usar exatamente o summary.id qualificado pelo marketplace retornado por plugin/list, por exemplo, "example-plugin@workspace-directory".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: substituição da ação destrutiva por plugin. Quando omitida, o valor global de allow_destructive_actions é usado. O valor por plugin aceita as mesmas políticas true, false, "auto" ou "ask".

Cada aplicativo de plugin admitido que usa "ask" encaminha as solicitações de aprovação desse aplicativo ao revisor humano. Outros aplicativos e aprovações da thread que não são de aplicativos mantêm o revisor configurado, portanto políticas mistas de plugins não herdam o comportamento de "ask".

codexPlugins.enabled é a diretiva global de habilitação. Entradas explícitas de plugins gravadas pela migração constituem o conjunto duradouro de instalações selecionadas e de elegibilidade para reparo. Entradas workspace-directory configuradas manualmente já devem estar instaladas e habilitadas, e seus aplicativos proprietários devem estar acessíveis; o OpenClaw não os instala nem os autentica. Se o Codex rejeitar a solicitação explícita do catálogo do workspace, as entradas habilitadas do workspace falham de modo fechado com marketplace_missing, enquanto as entradas selecionadas do catálogo padrão permanecem disponíveis. plugins["*"] não é compatível, não há uma opção install, e valores locais de marketplacePath intencionalmente não são campos de configuração porque são específicos do host. Consulte Plugins nativos do Codex para conhecer os requisitos de versão e prontidão do servidor de aplicativos.

As verificações de prontidão de app/list permanecem em cache por uma hora e são atualizadas assincronamente quando ficam obsoletas. A configuração de aplicativos da thread do Codex é calculada ao estabelecer a sessão do harness do Codex, não a cada interação; use /new, /reset ou reinicie o gateway depois de alterar a configuração de plugins nativos.

codexPlugins.allow_all_plugins captura todos os aplicativos da conta atualmente acessíveis em cada nova thread nativa do Codex. Ele não instala plugins nem aplicativos, e aplicativos inacessíveis permanecem excluídos. Os aplicativos da conta usam a política global codexPlugins.allow_destructive_actions. Entradas explícitas de plugins têm precedência quando o mesmo aplicativo está presente nos dois caminhos. Se não for possível ler app/list, a exposição de toda a conta falha de modo fechado.

• plugins.entries.firecrawl.config.webFetch: configurações do provedor de busca web do Firecrawl.
  • apiKey: chave de API opcional do Firecrawl para limites maiores (aceita SecretRef). Usa como alternativas plugins.entries.firecrawl.config.webSearch.apiKey, o campo legado tools.web.fetch.firecrawl.apiKey ou a variável de ambiente FIRECRAWL_API_KEY.
  • baseUrl: URL base da API do Firecrawl (padrão: https://api.firecrawl.dev; substituições auto-hospedadas devem apontar para endpoints privados/internos).
  • onlyMainContent: extrai somente o conteúdo principal das páginas (padrão: true).
  • maxAgeMs: idade máxima do cache em milissegundos (padrão: 172800000 / 2 dias).
  • timeoutSeconds: tempo limite da solicitação de extração em segundos (padrão: 60).
• plugins.entries.xai.config.xSearch: configurações do xAI X Search (pesquisa web do Grok).
  • enabled: habilita o provedor X Search.
  • model: modelo Grok a ser usado para pesquisa (por exemplo, "grok-4.3").
• plugins.entries.memory-core.config.dreaming: configurações de Dreaming da memória. Consulte Dreaming para ver as fases e os limites.
  • enabled: chave principal do Dreaming (padrão false).
  • frequency: cadência do cron para cada ciclo completo de Dreaming ("0 3 * * *" por padrão).
  • model: substituição opcional do modelo do subagente Dream Diary. Exige plugins.entries.memory-core.subagent.allowModelOverride: true; combine com allowedModels para restringir os destinos. Erros de modelo indisponível são repetidos uma vez com o modelo padrão da sessão; falhas de confiança ou de lista de permissões não usam uma alternativa silenciosamente.
  • a política e os limites das fases são detalhes de implementação (não são chaves de configuração voltadas ao usuário).
• A configuração completa da memória está na referência de configuração da memória:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• Plugins habilitados de bundles do Claude também podem fornecer padrões incorporados do OpenClaw por meio de settings.json; o OpenClaw os aplica como configurações sanitizadas do agente, não como patches brutos da configuração do OpenClaw.
• plugins.slots.memory: seleciona o id do plugin de memória ativo ou "none" para desabilitar plugins de memória.
• plugins.slots.contextEngine: seleciona o id do plugin ativo do mecanismo de contexto; usa "legacy" por padrão, a menos que você instale e selecione outro mecanismo.

Consulte Plugins.

Compromissos

commitments controla a memória inferida de acompanhamentos: o OpenClaw pode detectar verificações futuras nas interações da conversa e entregá-las por meio de execuções de heartbeat.

• commitments.enabled: habilita a extração oculta pelo LLM, o armazenamento e a entrega por heartbeat de compromissos inferidos de acompanhamento. Padrão: false.
• commitments.maxPerDay: número máximo de compromissos inferidos de acompanhamento entregues por sessão do agente em um dia corrido. Padrão: 3.

Consulte Compromissos inferidos.

Navegador

{  browser: {    enabled: true,    evaluateEnabled: true,    defaultProfile: "user",    ssrfPolicy: {      // dangerouslyAllowPrivateNetwork: true, // opte apenas para acesso confiável à rede privada      // allowPrivateNetwork: true, // alias legado      // hostnameAllowlist: ["*.example.com", "example.com"],      // allowedHostnames: ["localhost"],    },    tabCleanup: {      enabled: true,      idleMinutes: 120,      maxTabsPerSession: 8,      sweepMinutes: 5,    },    profiles: {      openclaw: { cdpPort: 18800, color: "#FF4500" },      work: {        cdpPort: 18801,        color: "#0066CC",        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",      },      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },    },    color: "#FF4500",    // headless: false,    // noSandbox: false,    // extraArgs: [],    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",    // attachOnly: false,  },}

• evaluateEnabled: false desativa act:evaluate e wait --fn.
• tabCleanup recupera as abas rastreadas do agente principal após um período de inatividade ou quando uma sessão excede seu limite. Defina idleMinutes: 0 ou maxTabsPerSession: 0 para desativar individualmente esses modos de limpeza.
• ssrfPolicy.dangerouslyAllowPrivateNetwork fica desativado quando não definido, portanto a navegação do navegador permanece restrita por padrão.
• Defina ssrfPolicy.dangerouslyAllowPrivateNetwork: true somente quando você confiar intencionalmente na navegação do navegador em redes privadas.
• No modo restrito, os endpoints de perfis CDP remotos (profiles.*.cdpUrl) estão sujeitos ao mesmo bloqueio de redes privadas durante as verificações de acessibilidade e descoberta.
• ssrfPolicy.allowPrivateNetwork continua sendo compatível como um alias legado.
• No modo restrito, use ssrfPolicy.hostnameAllowlist e ssrfPolicy.allowedHostnames para exceções explícitas.
• Perfis remotos permitem somente anexação (iniciar/parar/redefinir ficam desativados).
• profiles.*.cdpUrl aceita http://, https://, ws:// e wss://. Use HTTP(S) quando quiser que o OpenClaw descubra /json/version; use WS(S) quando seu provedor fornecer uma URL WebSocket direta do DevTools.
• remoteCdpTimeoutMs e remoteCdpHandshakeTimeoutMs se aplicam à acessibilidade CDP remota e attachOnly, além das solicitações de abertura de abas. Perfis de loopback gerenciados mantêm os padrões locais do CDP. A enumeração persistente de abas remotas do Playwright usa o maior valor como prazo limite da operação.
• Se um serviço CDP gerenciado externamente estiver acessível por loopback, defina attachOnly: true nesse perfil; caso contrário, o OpenClaw tratará a porta de loopback como um perfil de navegador gerenciado localmente e poderá relatar erros de propriedade da porta local.
• Perfis existing-session usam o Chrome MCP em vez do CDP e podem se conectar no host selecionado ou por meio de um Node de navegador conectado.
• Perfis existing-session podem definir userDataDir para direcionar a um perfil específico de navegador baseado em Chromium, como Brave ou Edge.
• Perfis existing-session podem definir cdpUrl quando o Chrome já estiver em execução por trás de um endpoint de descoberta HTTP(S) do DevTools ou de um endpoint WS(S) direto. Nesse modo, o OpenClaw passa o endpoint ao Chrome MCP em vez de usar a conexão automática; userDataDir é ignorado nos argumentos de inicialização do Chrome MCP.
• Perfis existing-session mantêm os limites atuais da rota do Chrome MCP: ações orientadas por snapshots/referências em vez de direcionamento por seletor CSS, hooks de upload de um único arquivo, sem substituições de tempo limite de diálogos, sem wait --load networkidle e sem responsebody, exportação para PDF, interceptação de downloads ou ações em lote.
• Perfis locais gerenciados openclaw atribuem automaticamente cdpPort e cdpUrl; defina cdpUrl explicitamente somente para perfis CDP remotos ou para anexação a endpoints de sessões existentes.
• Perfis locais gerenciados podem definir executablePath para substituir o browser.executablePath global nesse perfil. Use isso para executar um perfil no Chrome e outro no Brave.
• Perfis locais gerenciados usam browser.localLaunchTimeoutMs para a descoberta HTTP do CDP do Chrome após o início do processo e browser.localCdpReadyTimeoutMs para verificar a prontidão do websocket CDP após a inicialização. Aumente esses valores em hosts mais lentos nos quais o Chrome inicia corretamente, mas as verificações de prontidão concorrem com a inicialização. Ambos os valores devem ser inteiros positivos de até 120000 ms; valores de configuração inválidos são rejeitados.
• Ordem de detecção automática: navegador padrão, se baseado em Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
• browser.executablePath e browser.profiles.<name>.executablePath aceitam ~ e ~/... para o diretório inicial do seu sistema operacional antes da inicialização do Chromium. O userDataDir específico de cada perfil existing-session também expande o til.
• Serviço de controle: somente loopback (porta derivada de gateway.port, padrão 18791).
• extraArgs acrescenta flags adicionais de inicialização ao iniciar o Chromium localmente (por exemplo, --disable-gpu, dimensionamento de janela ou flags de depuração).

Interface do usuário

{  ui: {    seamColor: "#FF4500",    assistant: {      name: "OpenClaw",      avatar: "CB", // emoji, texto curto, URL de imagem ou URI de dados    },  },}

• seamColor: cor de destaque dos elementos visuais da interface do aplicativo nativo (tonalidade do balão do Modo de Conversa etc.).
• assistant: substituição da identidade na interface de controle. Usa como alternativa a identidade do agente ativo.

Gateway

{  gateway: {    mode: "local", // local | remoto    port: 18789,    bind: "loopback",    auth: {      mode: "token", // nenhum | token | senha | proxy confiável      token: "your-token",      // password: "your-password", // ou OPENCLAW_GATEWAY_PASSWORD      // trustedProxy: { userHeader: "x-forwarded-user" }, // para mode=trusted-proxy; consulte /gateway/trusted-proxy-auth      allowTailscale: true,      rateLimit: {        maxAttempts: 10,        windowMs: 60000,        lockoutMs: 300000,        exemptLoopback: true,      },    },    tailscale: {      mode: "off", // desativado | servir | funnel      resetOnExit: false,    },    controlUi: {      enabled: true,      basePath: "/openclaw",      // root: "dist/control-ui",      // toolTitles: false, // habilita títulos de finalidade gerados por IA para chamadas de ferramentas (consome tokens do modelo utilitário)      // embedSandbox: "scripts", // restrito | scripts | confiável      // allowExternalEmbedUrls: false, // perigoso: permite URLs http(s) externas absolutas para incorporação      // chatMessageMaxWidth: "min(1280px, 82%)", // largura máxima opcional da transcrição centralizada do chat      // allowedOrigins: ["https://control.example.com"], // obrigatório para a interface de controle fora do loopback      // dangerouslyAllowHostHeaderOriginFallback: false, // modo perigoso de fallback de origem pelo cabeçalho Host      // allowInsecureAuth: false,      // dangerouslyDisableDeviceAuth: false,    },    terminal: {      enabled: false,      // shell: "/bin/zsh",    },    remote: {      url: "ws://127.0.0.1:18789",      transport: "ssh", // ssh | direto      token: "your-token",      // password: "your-password",    },    trustedProxies: ["10.0.0.1"],    // Opcional. Padrão: false.    allowRealIpFallback: false,    nodes: {      pairing: {        // Opcional. Por padrão, não definido/desativado.        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],        // Aprovação automática verificada por SSH. Padrão: ativada (true).        // Defina como false para desativar somente a verificação SSH; isso não afeta        // autoApproveCidrs acima. Para pareamento manual de Nodes, defina como false E        // remova autoApproveCidrs. Passe um objeto para ajustar: { user, identity,        // timeoutMs, cidrs }.        sshVerify: true,      },      allowCommands: ["canvas.navigate"],      denyCommands: ["system.run"],    },    tools: {      // Bloqueios HTTP adicionais de /tools/invoke      deny: ["browser"],      // Remove ferramentas da lista padrão de bloqueio HTTP para chamadores proprietários/administradores      allow: ["gateway"],    },    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          timeoutMs: 10000,        },      },    },  },}

Endpoints compatíveis com OpenAI

• RPC HTTP de administração: desativado por padrão como o plugin admin-http-rpc. Ative o plugin para registrar POST /api/v1/admin/rpc. Consulte RPC HTTP de administração.
• Chat Completions: desativado por padrão. Ative com gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Proteção da entrada de URL da Responses:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist Listas de permissões vazias são tratadas como não definidas; use gateway.http.endpoints.responses.files.allowUrl=false e/ou gateway.http.endpoints.responses.images.allowUrl=false para desativar a busca de URLs.
• Cabeçalho opcional de proteção da resposta:
  • gateway.http.securityHeaders.strictTransportSecurity (defina somente para origens HTTPS sob seu controle; consulte Autenticação de proxy confiável)

Isolamento de múltiplas instâncias

Execute vários gateways em um host com portas e diretórios de estado exclusivos:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \OPENCLAW_STATE_DIR=~/.openclaw-a \openclaw gateway --port 19001

Flags de conveniência: --dev (usa ~/.openclaw-dev + porta 19001), --profile <name> (usa ~/.openclaw-<name>).

Consulte Vários Gateways.

gateway.tls

{  gateway: {    tls: {      enabled: false,      autoGenerate: false,      certPath: "/etc/openclaw/tls/server.crt",      keyPath: "/etc/openclaw/tls/server.key",      caPath: "/etc/openclaw/tls/ca-bundle.crt",    },  },}

• enabled: ativa a terminação TLS no listener do Gateway (HTTPS/WSS) (padrão: false).
• autoGenerate: gera automaticamente um par local de certificado/chave autoassinado quando arquivos explícitos não estão configurados; somente para uso local/desenvolvimento.
• certPath: caminho do sistema de arquivos para o arquivo do certificado TLS.
• keyPath: caminho do sistema de arquivos para o arquivo da chave privada TLS; mantenha as permissões restritas.
• caPath: caminho opcional do pacote de CAs para verificação de clientes ou cadeias de confiança personalizadas.

gateway.reload

{  gateway: {    reload: {      mode: "hybrid", // off | restart | hot | hybrid      debounceMs: 500,      deferralTimeoutMs: 300000,    },  },}

• mode: controla como as edições de configuração são aplicadas em tempo de execução.
  • "off": ignora edições em tempo real; as alterações exigem uma reinicialização explícita.
  • "restart": sempre reinicia o processo do Gateway quando a configuração muda.
  • "hot": aplica as alterações no processo sem reiniciar.
  • "hybrid" (padrão): primeiro tenta o recarregamento a quente; recorre à reinicialização, se necessário.
• debounceMs: janela de debounce em ms antes da aplicação das alterações de configuração (inteiro não negativo; padrão: 300).
• deferralTimeoutMs: tempo máximo opcional, em ms, para aguardar operações em andamento antes de forçar uma reinicialização ou o recarregamento a quente do canal. Omita-o para usar a espera limitada padrão (300000); defina 0 para aguardar indefinidamente e registrar periodicamente avisos de que ainda há operações pendentes.

Ambientes de workers na nuvem

Os workers na nuvem são opcionais. Se cloudWorkers estiver ausente ou profiles estiver vazio, o OpenClaw não aceitará a criação de novos workers. Os registros duráveis criados anteriormente ainda são reconciliados e permanecem visíveis; a projeção existente de Gateway/Node permanece inalterada.

Cada provedor de worker deve retornar uma hostKey SSH proveniente de uma saída de provisionamento confiável, exatamente no formato algorithm base64, sem nome de host nem comentário. O bootstrap grava essa chave em um arquivo known_hosts isolado, usa StrictHostKeyChecking=yes e falha antes de abrir uma conexão quando o provedor a omite. Não há fallback de confiança no primeiro uso.

A configuração do túnel ocorre sob demanda, e não como parte do provisionamento. Quando iniciado, o Gateway faz um encaminhamento reverso de um soquete Unix local ao worker para seu endpoint WebSocket de loopback. O soquete fica em um diretório remoto alocado aleatoriamente e acessível somente pelo proprietário; ao contrário de uma porta TCP de loopback, ele não pode ser acessado por outras contas em um worker multiusuário nem entrar em conflito com a porta de outro ambiente. Os keepalives SSH e o recuo limitado de reconexão são executados somente enquanto o proprietário do túnel continuar sendo o atual. A interrupção do túnel bloqueia as reconexões antes de encerrar o processo SSH.

O tráfego de controle e a transferência do workspace usam conexões SSH separadas. Ambos reutilizam a mesma identidade resolvida e o arquivo known_hosts isolado e fixado, mas a transferência do workspace não compartilha a multiplexação da conexão SSH com o túnel de longa duração; assim, o rsync não pode bloquear o tráfego de controle.

Perfil do Crabbox

O provedor crabbox incluído provisiona uma concessão compatível com SSH por meio da CLI local do Crabbox. O settings.provider interno seleciona o backend do Crabbox; ele é separado do id externo do provedor do OpenClaw.

{  cloudWorkers: {    profiles: {      production: {        provider: "crabbox",        install: "bundle", // Padrão; use "npm" somente para uma versão lançada do Gateway.        settings: {          provider: "aws",          class: "standard",          ttl: "24h",          idleTimeout: "60m",          // Caminho absoluto opcional. Padrão: irmão ../crabbox/bin/crabbox, depois PATH.          binary: "/usr/local/bin/crabbox",        },        lifetime: {          idleTimeoutMinutes: 60,          maxLifetimeMinutes: 1440,        },      },    },  },}

• settings.provider (obrigatório): backend do Crabbox repassado por --provider. Use um backend cuja saída de inspeção inclua um endpoint SSH; aws seleciona o backend direto da AWS.
• settings.class (obrigatório): classe de máquina do Crabbox passada para --class.
• settings.ttl e settings.idleTimeout (obrigatórios): strings positivas de duração do Go passadas para --ttl e --idle-timeout. Esses mecanismos de segurança do lado do provedor são distintos da política lifetime armazenada pelo OpenClaw abaixo.
• settings.binary: caminho absoluto opcional para o executável do Crabbox. Sem ele, o OpenClaw verifica o checkout irmão do Crabbox, depois as entradas executáveis em PATH e, por fim, invoca crabbox, para que a ausência da CLI continue sendo um erro visível do provedor.

Configurações desconhecidas são rejeitadas. As credenciais do Crabbox e a configuração de conta específica do backend continuam sob responsabilidade do Crabbox; não as coloque em settings. O OpenClaw invoca somente a CLI local e não faz chamadas de rede ao provedor a partir deste plugin. O provisionamento sempre passa --keep=true; o OpenClaw controla o ciclo de vida externo e destrói a concessão com crabbox stop.

Perfil de desenvolvimento SSH estático

{  cloudWorkers: {    profiles: {      development: {        provider: "static-ssh",        settings: {          host: "worker.example.test",          port: 22,          user: "openclaw",          hostKey: "ssh-ed25519 <base64-public-host-key>",          keyRef: {            source: "env",            provider: "default",            id: "OPENCLAW_WORKER_SSH_KEY",          },        },        lifetime: {          idleTimeoutMinutes: 60,          maxLifetimeMinutes: 1440,        },      },    },  },}

• profiles: perfis nomeados de workers com ids não vazios e sem espaços em branco nas extremidades. Cada perfil seleciona um provedor registrado por um plugin.
• provider: id não vazio do provedor de workers. Os exemplos usam o provedor crabbox incluído e o provedor static-ssh do QA Lab.
• install: método de instalação do worker. "bundle" (padrão) transfere um pacote com hash de conteúdo do build instalado do Gateway e oferece suporte a versões lançadas, de desenvolvimento e ainda não lançadas. "npm" é uma otimização opcional para uma versão empacotada sem modificações; instala openclaw@<exact gateway version> a partir do registro npm público e nunca instala latest.
• Os plugins de provedor incluídos são selecionados automaticamente quando configurados, mas as desativações explícitas e plugins.allow ainda se aplicam. Inclua o id do provedor (por exemplo, crabbox) quando houver uma lista de permissões configurada. Os plugins de provedores externos também devem estar instalados e explicitamente ativados.
• settings: JSON limitado sob responsabilidade do provedor. O plugin selecionado define e valida suas chaves; use objetos SecretRef para valores que contenham segredos. O provedor SSH estático exige host, user, hostKey e keyRef; o padrão de port é 22. hostKey deve ser uma única linha de chave pública de host OpenSSH (algorithm base64) obtida do host conhecido ou de outro canal confiável, sem prefixo de opções.
• lifetime.idleTimeoutMinutes: minutos expressos como inteiro positivo, armazenados para uma política posterior de recuperação por inatividade.
• lifetime.maxLifetimeMinutes: minutos expressos como inteiro positivo, armazenados para uma política posterior de ciclo de vida.

Um runtime Node compatível (22.19+, 23.11+ ou 24+) já deve estar instalado no worker. O método opcional "npm" também exige npm e acesso HTTPS de saída ao registro npm público. A configuração da cadeia de ferramentas com acesso à rede é uma política do provedor; o bootstrap informa um erro acionável em vez de instalar as cadeias de ferramentas por conta própria.

Essa base instala e verifica o build do Gateway e fornece o ciclo de vida de início/interrupção do túnel, mas não inicia a CLI geral do OpenClaw. O ponto de entrada autocontido do worker e o loop serão implementados no próximo marco de workers na nuvem.

Cada registro durável de ambiente retém suas configurações validadas de provedor, seu método de instalação resolvido e sua política de ciclo de vida em um snapshot do perfil no momento da criação. Alterar ou remover um perfil nomeado afeta novas criações; os registros existentes continuam a reconciliação do ciclo de vida com esse snapshot, desde que o plugin proprietário continue disponível.

Os valores de ciclo de vida são apenas dados na primeira versão de workers na nuvem; a aplicação automática será implementada em um trabalho posterior do ciclo de vida. Alterações de perfil exigem a reinicialização do Gateway.

Hooks

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    maxBodyBytes: 262144,    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: true,    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],    allowedAgentIds: ["hooks", "main"],    presets: ["gmail"],    transformsDir: "~/.openclaw/hooks/transforms",    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "hooks",        wakeMode: "now",        name: "Gmail",        sessionKey: "hook:gmail:{{messages[0].id}}",        messageTemplate: "De: {{messages[0].from}}\nAssunto: {{messages[0].subject}}\n{{messages[0].snippet}}",        deliver: true,        channel: "last",        model: "openai/gpt-5.4-mini",      },    ],  },}

Autenticação: Authorization: Bearer <token> ou x-openclaw-token: <token>. Tokens de hook na string de consulta são rejeitados.

Notas de validação e segurança:

• hooks.enabled=true exige um hooks.token não vazio.
• hooks.token deve ser diferente da autenticação ativa por segredo compartilhado do Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN ou gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD); a inicialização registra um aviso de segurança não fatal quando detecta reutilização.
• openclaw security audit sinaliza a reutilização da autenticação de hooks/Gateway como uma constatação crítica, incluindo a autenticação por senha do Gateway fornecida apenas no momento da auditoria (--auth password --password <password>). Execute openclaw doctor --fix para trocar um hooks.token reutilizado e persistido; depois, atualize os emissores externos de hooks para usarem o novo token de hook.
• hooks.path não pode ser /; use um subcaminho dedicado, como /hooks.
• Se hooks.allowRequestSessionKey=true, restrinja hooks.allowedSessionKeyPrefixes (por exemplo, ["hook:"]).
• Se um mapeamento ou predefinição usar um sessionKey baseado em modelo, defina hooks.allowedSessionKeyPrefixes e hooks.allowRequestSessionKey=true. Chaves de mapeamento estáticas não exigem essa habilitação explícita.

Endpoints:

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • O sessionKey da carga da solicitação só é aceito quando hooks.allowRequestSessionKey=true (padrão: false).
• POST /hooks/<name> → resolvido por meio de hooks.mappings
  • Valores de sessionKey de mapeamentos renderizados a partir de modelos são tratados como fornecidos externamente e também exigem hooks.allowRequestSessionKey=true.

Integração com o Gmail

• A predefinição integrada do Gmail usa sessionKey: "hook:gmail:{{messages[0].id}}".
• Se você mantiver esse encaminhamento por mensagem, defina hooks.allowRequestSessionKey: true e restrinja hooks.allowedSessionKeyPrefixes para corresponder ao namespace do Gmail, por exemplo, ["hook:", "hook:gmail:"].
• Se você precisar de hooks.allowRequestSessionKey: false, substitua a predefinição por um sessionKey estático, em vez do padrão baseado em modelo.

{  hooks: {    gmail: {      account: "openclaw@gmail.com",      topic: "projects/<project-id>/topics/gog-gmail-watch",      subscription: "gog-gmail-watch-push",      pushToken: "shared-push-token",      hookUrl: "http://127.0.0.1:18789/hooks/gmail",      includeBody: true,      maxBytes: 20000,      renewEveryMinutes: 720,      serve: { bind: "127.0.0.1", port: 8788, path: "/" },      tailscale: { mode: "funnel", path: "/gmail-pubsub" },      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",      thinking: "off",    },  },}

• O Gateway inicia automaticamente gog gmail watch serve na inicialização quando configurado. Defina OPENCLAW_SKIP_GMAIL_WATCHER=1 para desabilitar.
• Não execute uma instância separada de gog gmail watch serve junto com o Gateway.

Host do plugin Canvas

{  plugins: {    entries: {      canvas: {        config: {          host: {            root: "~/.openclaw/workspace/canvas",            liveReload: true,            // enabled: false, // ou OPENCLAW_SKIP_CANVAS_HOST=1          },        },      },    },  },}

• Disponibiliza HTML/CSS/JS editáveis pelo agente e A2UI via HTTP na porta do Gateway:
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Somente local: mantenha gateway.bind: "loopback" (padrão).
• Vinculações que não sejam de loopback: as rotas do Canvas exigem autenticação do Gateway (token/senha/proxy confiável), assim como outras superfícies HTTP do Gateway.
• WebViews de Node normalmente não enviam cabeçalhos de autenticação; depois que um Node é pareado e conectado, o Gateway anuncia URLs de capacidade com escopo de Node para acesso ao Canvas/A2UI.
• As URLs de capacidade são vinculadas à sessão WS ativa do Node e expiram rapidamente. Não é usada uma alternativa baseada em IP.
• Injeta o cliente de recarregamento ao vivo no HTML disponibilizado.
• Cria automaticamente um index.html inicial quando o diretório está vazio.
• Também disponibiliza A2UI em /__openclaw__/a2ui/.
• As alterações exigem a reinicialização do Gateway.
• Desabilite o recarregamento ao vivo para diretórios grandes ou erros EMFILE.

Descoberta

mDNS (Bonjour)

{  discovery: {    mdns: {      mode: "minimal", // minimal | full | off    },  },}

• minimal (padrão): omite cliPath + sshPort dos registros TXT.
• full: inclui cliPath + sshPort; a divulgação por multicast na LAN ainda exige que o plugin bonjour integrado esteja habilitado.
• off: suprime a divulgação por multicast na LAN sem alterar a habilitação do plugin.
• O plugin bonjour integrado é iniciado automaticamente em hosts macOS e requer habilitação explícita em implantações do Gateway no Linux, Windows e em contêineres.
• O nome do host usa por padrão o nome de host do sistema quando ele é um rótulo DNS válido e, caso contrário, usa openclaw. Substitua-o com OPENCLAW_MDNS_HOSTNAME.
• OPENCLAW_DISABLE_BONJOUR=1 desabilita totalmente a divulgação mDNS, substituindo discovery.mdns.mode.

Área ampla (DNS-SD)

{  discovery: {    wideArea: { enabled: true },  },}

Grava uma zona DNS-SD unicast em ~/.openclaw/dns/. Para descoberta entre redes, combine com um servidor DNS (CoreDNS recomendado) + DNS dividido do Tailscale.

Configuração: openclaw dns setup --apply.

Ambiente

env (variáveis de ambiente embutidas)

{  env: {    OPENROUTER_API_KEY: "sk-or-...",    vars: {      GROQ_API_KEY: "gsk-...",    },    shellEnv: {      enabled: true,      timeoutMs: 15000,    },  },}

• As variáveis de ambiente embutidas só são aplicadas se a variável estiver ausente no ambiente do processo.
• Arquivos .env: .env do CWD + ~/.openclaw/.env (nenhum deles substitui variáveis existentes).
• shellEnv: importa do perfil do shell de login as chaves esperadas que estiverem ausentes.
• Consulte Ambiente para ver a precedência completa.

Substituição de variáveis de ambiente

Referencie variáveis de ambiente em qualquer string de configuração com ${VAR_NAME}:

{  gateway: {    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },  },}

• Somente nomes em maiúsculas são correspondidos: [A-Z_][A-Z0-9_]*.
• Variáveis ausentes/vazias causam um erro ao carregar a configuração.
• Use $${VAR} como escape para um ${VAR} literal.
• Funciona com $include.

Segredos

As referências a segredos são aditivas: valores em texto simples continuam funcionando.

SecretRef

Use um destes formatos de objeto:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Validação:

• Padrão de provider: ^[a-z][a-z0-9_-]{0,63}$
• Padrão de ID para source: "env": ^[A-Z][A-Z0-9_]{0,127}$
• ID para source: "file": ponteiro JSON absoluto (por exemplo, "/providers/openai/apiKey")
• Padrão de ID para source: "exec": ^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$ (oferece suporte a seletores no estilo da AWS, como secret#json_key)
• IDs de source: "exec" não podem conter segmentos de caminho delimitados por barras . ou .. (por exemplo, a/../b é rejeitado)

Superfície de credenciais compatível

• Matriz canônica: Superfície de credenciais do SecretRef
• secrets apply usa como destino os caminhos de credenciais compatíveis do openclaw.json.
• As referências de auth-profiles.json são incluídas na resolução em tempo de execução e na cobertura da auditoria.

Configuração dos provedores de segredos

{  secrets: {    providers: {      default: { source: "env" }, // provedor de ambiente explícito opcional      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json",        timeoutMs: 5000,      },      vault: {        source: "exec",        command: "/usr/local/bin/openclaw-vault-resolver",        passEnv: ["PATH", "VAULT_ADDR"],      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },  },}

Observações:

• O provedor file aceita mode: "json" e mode: "singleValue" (id deve ser "value" no modo singleValue).
• Os caminhos dos provedores file e exec falham de forma fechada quando a verificação de ACLs do Windows não está disponível. Defina allowInsecurePath: true somente para caminhos confiáveis que não possam ser verificados.
• O provedor exec exige um caminho command absoluto e usa cargas de protocolo em stdin/stdout.
• Por padrão, caminhos de comando que sejam links simbólicos são rejeitados. Defina allowSymlinkCommand: true para permitir caminhos de links simbólicos enquanto valida o caminho de destino resolvido.
• Se trustedDirs estiver configurado, a verificação de diretório confiável será aplicada ao caminho de destino resolvido.
• Por padrão, o ambiente do processo filho de exec é mínimo; passe explicitamente as variáveis necessárias com passEnv.
• As referências a segredos são resolvidas no momento da ativação para um snapshot em memória; depois, os caminhos de solicitação leem somente esse snapshot.
• A filtragem de superfícies ativas é aplicada durante a ativação: referências não resolvidas em superfícies habilitadas fazem a inicialização/recarga falhar, enquanto superfícies inativas são ignoradas com diagnósticos.

Armazenamento de autenticação

{  auth: {    profiles: {      "anthropic:default": { provider: "anthropic", mode: "api_key" },      "anthropic:work": { provider: "anthropic", mode: "api_key" },      "openai:personal": { provider: "openai", mode: "oauth" },    },    order: {      anthropic: ["anthropic:default", "anthropic:work"],      openai: ["openai:personal"],    },  },}

• Os perfis por agente são armazenados em <agentDir>/auth-profiles.json.
• auth-profiles.json aceita referências no nível do valor (keyRef para api_key, tokenRef para token) em modos de credencial estática.
• Mapas planos legados de auth-profiles.json, como { "provider": { "apiKey": "..." } }, não são um formato de tempo de execução; openclaw doctor --fix os reescreve como perfis canônicos de chave de API provider:default, com um backup .legacy-flat.*.bak.
• Perfis no modo OAuth (auth.profiles.<id>.mode = "oauth") não aceitam credenciais de perfil de autenticação baseadas em SecretRef.
• As credenciais estáticas de tempo de execução vêm de snapshots resolvidos em memória; entradas estáticas legadas de auth.json são removidas quando detectadas.
• As importações legadas de OAuth vêm de ~/.openclaw/credentials/oauth.json.
• Consulte OAuth.
• Comportamento de segredos em tempo de execução e ferramentas audit/configure/apply: Gerenciamento de segredos.

auth.cooldowns

{  auth: {    cooldowns: {      billingBackoffHours: 5,      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },      billingMaxHours: 24,      authPermanentBackoffMinutes: 10,      authPermanentMaxMinutes: 60,      failureWindowHours: 24,      overloadedProfileRotations: 1,      overloadedBackoffMs: 0,      rateLimitedProfileRotations: 1,    },  },}

• billingBackoffHours: recuo base em horas quando um perfil falha devido a erros reais de cobrança/crédito insuficiente (padrão: 5). Texto explícito de cobrança ainda pode chegar aqui mesmo em respostas 401/403, mas os padrões de correspondência de texto específicos do provedor permanecem restritos ao provedor que os possui (por exemplo, Key limit exceeded do OpenRouter). Mensagens HTTP 402 recuperáveis sobre janela de uso ou limite de gastos da organização/do espaço de trabalho permanecem no fluxo rate_limit.
• billingBackoffHoursByProvider: substituições opcionais por provedor para as horas de recuo de cobrança.
• billingMaxHours: limite em horas para o crescimento exponencial do recuo de cobrança (padrão: 24).
• authPermanentBackoffMinutes: recuo base em minutos para falhas auth_permanent de alta confiança (padrão: 10).
• authPermanentMaxMinutes: limite em minutos para o crescimento do recuo de auth_permanent (padrão: 60).
• failureWindowHours: janela móvel em horas usada para contadores de recuo (padrão: 24).
• overloadedProfileRotations: número máximo de alternâncias de perfil de autenticação do mesmo provedor para erros de sobrecarga antes de mudar para o fallback de modelo (padrão: 1). Formatos de provedor ocupado, como ModelNotReadyException, chegam aqui.
• overloadedBackoffMs: atraso fixo antes de tentar novamente uma alternância de provedor/perfil sobrecarregado (padrão: 0).
• rateLimitedProfileRotations: número máximo de alternâncias de perfil de autenticação do mesmo provedor para erros de limite de taxa antes de mudar para o fallback de modelo (padrão: 1). Esse grupo de limite de taxa inclui textos formatados pelo provedor, como Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded e resource exhausted.

Auditoria

{  audit: {    enabled: true,    messages: "off", // desativado | direto | todos  },}

O Gateway registra eventos de auditoria somente de metadados para execuções de agentes e ações de ferramentas no banco de dados de estado compartilhado. Os metadados do ciclo de vida das mensagens são uma opção separada. O registro armazena identidade, temporização, nomes de ferramentas e resultados normalizados, mas nunca prompts, corpos de mensagens, argumentos de ferramentas, resultados ou texto bruto de erros. As linhas de mensagens não armazenam IDs brutos de conta da plataforma, conversa, mensagem e destino. As chaves de sessão de execução/ferramenta permanecem disponíveis para correlação e podem conter IDs de conta da plataforma ou de pares. Os registros expiram após 30 dias, e o registro é limitado a 100.000 linhas. Consulte-os com openclaw audit ou com a RPC do Gateway audit.activity.list. Consulte Histórico de auditoria para ver o modelo de dados completo, a semântica de privacidade e os limites de cobertura.

• enabled: registra novos eventos de auditoria (padrão: true). O registro fica ativado por padrão porque uma trilha de auditoria ativada somente após um incidente não pode explicar o incidente. Definir como false interrompe a inserção de novos eventos após a reinicialização do Gateway; os registros existentes permanecem legíveis até expirarem. Reativá-lo retoma o registro a partir desse ponto — a lacuna não é preenchida retroativamente.
• messages: escopo dos metadados de mensagens (padrão: "off"). "direct" registra somente conversas diretas conhecidas. "all" também registra grupos, canais e tipos de conversa desconhecidos. Ambos os modos permanecem sem conteúdo e substituem identificadores brutos por pseudônimos com chave locais da instalação quando há correlação disponível. Eles são auxiliares de correlação, não uma forma de anonimização; o banco de dados de estado armazena a chave de derivação, mas as exportações por RPC e CLI não.

O Gateway em execução captura audit.enabled e audit.messages na inicialização; reinicie-o após alterar qualquer uma das configurações. Atualmente, a cobertura de mensagens inclui mensagens de entrada aceitas que chegam ao despacho do núcleo e uma linha terminal por payload lógico original de resposta de saída que chega à entrega durável compartilhada. Caminhos locais de Plugin e de envio direto que ignoram esses limites compartilhados ainda não são cobertos. O gravador em segundo plano com capacidade limitada opera em regime de melhor esforço, não como um arquivo de conformidade sem perdas.

Registro em log

{  logging: {    level: "info",    file: "/tmp/openclaw/openclaw.log",    consoleLevel: "info",    consoleStyle: "pretty", // bonito | compacto | json    redactSensitive: "tools", // desativado | ferramentas    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],  },}

• Arquivo de log padrão: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
• Defina logging.file para usar um caminho estável.
• consoleLevel muda para debug quando --verbose é usado.
• maxFileBytes: tamanho máximo do arquivo de log ativo em bytes antes da rotação (inteiro positivo; padrão: 104857600 = 100 MB). O OpenClaw mantém até cinco arquivos numerados ao lado do arquivo ativo.
• redactSensitive / redactPatterns: mascaramento de melhor esforço para a saída do console, logs de arquivo, registros de log OTLP e texto persistido da transcrição da sessão. redactSensitive: "off" desativa somente essa política geral de logs/transcrições; superfícies de segurança da interface, das ferramentas e de diagnóstico ainda ocultam segredos antes da emissão.

Diagnósticos

{  diagnostics: {    enabled: true,    flags: ["telegram.*"],    stuckSessionWarnMs: 30000,    stuckSessionAbortMs: 300000,    memoryPressureSnapshot: false,     otel: {      enabled: false,      endpoint: "https://otel-collector.example.com:4318",      tracesEndpoint: "https://traces.example.com/v1/traces",      metricsEndpoint: "https://metrics.example.com/v1/metrics",      logsEndpoint: "https://logs.example.com/v1/logs",      protocol: "http/protobuf", // http/protobuf | grpc      headers: { "x-tenant-id": "my-org" },      serviceName: "openclaw-gateway",      traces: true,      metrics: true,      logs: false,      logsExporter: "otlp",      sampleRate: 1.0,      flushIntervalMs: 5000,      captureContent: {        enabled: false,        inputMessages: false,        outputMessages: false,        toolInputs: false,        toolOutputs: false,        systemPrompt: false,        toolDefinitions: false,      },    },     cacheTrace: {      enabled: false,      filePath: "~/.openclaw/logs/cache-trace.jsonl",      includeMessages: true,      includePrompt: true,      includeSystem: true,    },  },}

• enabled: controle mestre da saída de instrumentação (padrão: true).
• flags: matriz de strings de sinalizadores que ativam a saída de logs direcionada (aceita curingas como "telegram.*" ou "*").
• stuckSessionWarnMs: limite de tempo sem progresso, em ms, para classificar sessões de processamento de longa duração como session.long_running, session.stalled ou session.stuck (padrão: 120000). Progresso de resposta, ferramenta, status, bloco e ACP reinicia o temporizador; diagnósticos session.stuck repetidos aumentam o intervalo enquanto não houver alterações.
• stuckSessionAbortMs: limite de tempo sem progresso, em ms, antes que trabalhos ativos paralisados elegíveis possam ser encerrados e drenados para recuperação. Quando não definido, o OpenClaw usa a janela estendida mais segura de execução incorporada de pelo menos 5 minutos e 3x stuckSessionWarnMs.
• memoryPressureSnapshot: captura um snapshot de estabilidade ocultado anterior à falta de memória quando a pressão de memória atinge critical (padrão: false). Defina como true para adicionar a varredura/gravação do arquivo do pacote de estabilidade, mantendo os eventos normais de pressão de memória.
• otel.enabled: ativa o pipeline de exportação do OpenTelemetry (padrão: false). Para ver a configuração completa, o catálogo de sinais e o modelo de privacidade, consulte Exportação do OpenTelemetry.
• otel.endpoint: URL do coletor para exportação OTel.
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: endpoints OTLP opcionais específicos por sinal. Quando definidos, substituem otel.endpoint somente para esse sinal.
• otel.protocol: "http/protobuf" (padrão) ou "grpc".
• otel.headers: cabeçalhos adicionais de metadados HTTP/gRPC enviados com as solicitações de exportação OTel.
• otel.serviceName: nome do serviço para atributos de recurso.
• otel.traces / otel.metrics / otel.logs: ativa a exportação de rastreamentos, métricas ou logs.
• otel.logsExporter: destino da exportação de logs: "otlp" (padrão), "stdout" para um objeto JSON por linha da saída padrão ou "both".
• otel.sampleRate: taxa de amostragem de rastreamentos de 0 a 1.
• otel.flushIntervalMs: intervalo periódico de liberação da telemetria em ms.
• otel.captureContent: captura opcional de conteúdo bruto para atributos de spans OTEL. Fica desativada por padrão. O booleano true captura conteúdo de mensagens/ferramentas que não seja do sistema; o formato de objeto permite ativar explicitamente inputMessages, outputMessages, toolInputs, toolOutputs, systemPrompt e toolDefinitions.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: controle de ambiente para o formato experimental mais recente de spans de inferência GenAI, incluindo nomes de spans {gen_ai.operation.name} {gen_ai.request.model}, tipo de span CLIENT e gen_ai.provider.name em vez do gen_ai.system legado. Por padrão, os spans mantêm openclaw.model.call e gen_ai.system para compatibilidade; as métricas GenAI usam atributos semânticos limitados.
• OPENCLAW_OTEL_PRELOADED=1: controle de ambiente para hosts que já registraram um SDK OpenTelemetry global. O OpenClaw então ignora a inicialização/desligamento do SDK pertencente ao Plugin, mantendo os listeners de diagnóstico ativos.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT e OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: variáveis de ambiente de endpoint específicas por sinal usadas quando a chave de configuração correspondente não está definida.
• cacheTrace.enabled: registra snapshots de rastreamento de cache para execuções incorporadas (padrão: false).
• cacheTrace.filePath: caminho de saída do rastreamento de cache em JSONL (padrão: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: controla o que é incluído na saída de rastreamento de cache (todos com padrão: true).

Atualização

{  update: {    channel: "stable", // estável | estável estendido | beta | desenvolvimento    checkOnStart: true,     auto: {      enabled: false,      stableDelayHours: 6,      stableJitterHours: 12,      betaCheckIntervalHours: 1,    },  },}

• channel: canal de lançamento — "stable", "extended-stable", "beta" ou "dev". O canal estável estendido é exclusivo do pacote: comandos em primeiro plano controlam a instalação, enquanto o Gateway pode emitir dicas de atualização somente leitura.
• checkOnStart: verifica atualizações do npm quando o Gateway é iniciado (padrão: true). Seleções armazenadas do canal estável estendido usam a mesma dica somente leitura e a programação de dicas de 24 horas.
• auto.enabled: ativa a atualização automática em segundo plano para instalações de pacotes dos canais estável e beta (padrão: false). O canal estável estendido nunca é aplicado automaticamente.
• auto.stableDelayHours: atraso mínimo em horas antes da aplicação automática do canal estável (padrão: 6; máximo: 168).
• auto.stableJitterHours: janela adicional de distribuição gradual do canal estável em horas (padrão: 12; máximo: 168).
• auto.betaCheckIntervalHours: frequência em horas das verificações do canal beta (padrão: 1; máximo: 24). As configurações de atraso/distribuição do canal estável e de consulta do beta não se aplicam ao canal estável estendido.

ACP

{  acp: {    enabled: true,    dispatch: { enabled: true },    backend: "acpx",    fallbacks: ["acpx-secondary"],    defaultAgent: "main",    allowedAgents: ["main", "ops"],    maxConcurrentSessions: 10,     stream: {      coalesceIdleMs: 50,      maxChunkChars: 1000,      repeatSuppression: true,      deliveryMode: "live", // ao vivo | somente final      hiddenBoundarySeparator: "paragraph", // nenhum | espaço | nova linha | parágrafo      maxOutputChars: 50000,      maxSessionUpdateChars: 500,    },     runtime: {      ttlMinutes: 30,    },  },}

• enabled: controle global do recurso ACP (padrão: true; defina como false para ocultar os recursos de encaminhamento e criação do ACP).
• dispatch.enabled: controle independente para o encaminhamento de turnos de sessões ACP (padrão: true). Defina como false para manter os comandos ACP disponíveis enquanto bloqueia a execução.
• backend: id padrão do backend de runtime ACP (deve corresponder a um plugin de runtime ACP registrado). Instale primeiro o plugin de backend e, se plugins.allow estiver definido, inclua o id do plugin de backend (por exemplo, acpx), caso contrário o backend ACP não será carregado.
• fallbacks: lista ordenada de ids de backends ACP alternativos testados quando o backend principal falha antecipadamente, antes de produzir qualquer saída, com um erro aparentemente transitório (indisponível, com limitação de taxa, cota esgotada ou sobrecarregado). Cada entrada deve corresponder ao backend de um plugin de runtime ACP registrado.
• defaultAgent: id do agente ACP de destino alternativo quando as criações não especificam um destino explícito.
• allowedAgents: lista de permissões de ids de agentes permitidos para sessões de runtime ACP; vazia significa nenhuma restrição adicional.
• maxConcurrentSessions: número máximo de sessões ACP ativas simultaneamente.
• stream.coalesceIdleMs: janela de liberação por inatividade, em ms, para texto transmitido.
• stream.maxChunkChars: tamanho máximo do bloco antes de dividir a projeção de blocos transmitidos.
• stream.repeatSuppression: suprime linhas repetidas de status/ferramenta por turno (padrão: true).
• stream.deliveryMode: "live" transmite incrementalmente; "final_only" mantém em buffer até os eventos terminais do turno.
• stream.hiddenBoundarySeparator: separador antes do texto visível após eventos de ferramenta ocultos (padrão: "paragraph").
• stream.maxOutputChars: número máximo de caracteres da saída do assistente projetada por turno ACP.
• stream.maxSessionUpdateChars: número máximo de caracteres para linhas projetadas de status/atualização do ACP.
• stream.tagVisibility: registro de nomes de tags para substituições booleanas de visibilidade de eventos transmitidos.
• runtime.ttlMinutes: TTL de inatividade, em minutos, para workers de sessões ACP antes que possam ser limpos.
• runtime.installCommand: comando de instalação opcional a ser executado ao inicializar um ambiente de runtime ACP.

CLI

{  cli: {    banner: {      taglineMode: "off", // random | default | off    },  },}

• cli.banner.taglineMode controla o estilo do slogan do banner:
  • "random" (padrão): slogans divertidos/sazonais alternados.
  • "default": slogan neutro fixo (All your chats, one OpenClaw.).
  • "off": sem texto de slogan (o título/a versão do banner ainda são exibidos).
• Para ocultar o banner inteiro (não apenas os slogans), defina a variável de ambiente OPENCLAW_HIDE_BANNER=1.

Assistente

Metadados gravados pelos fluxos de configuração guiada da CLI (onboard, configure, doctor):

{  wizard: {    lastRunAt: "2026-01-01T00:00:00.000Z",    lastRunVersion: "2026.1.4",    lastRunCommit: "abc1234",    lastRunCommand: "configure",    lastRunMode: "local",    securityAcknowledgedAt: "2026-01-01T00:00:00.000Z",  },}

Identidade

Consulte os campos de identidade de agents.list em Padrões dos agentes.

Ponte (legada, removida)

As versões atuais não incluem mais a ponte TCP. Os Nodes se conectam pelo WebSocket do Gateway. As chaves bridge.* não fazem mais parte do esquema de configuração (a validação falha até que sejam removidas; openclaw doctor --fix pode eliminar chaves desconhecidas).

{"bridge": {  "enabled": true,  "port": 18790,  "bind": "tailnet",  "tls": {    "enabled": true,    "autoGenerate": true  }}}

Cron

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // padrão; despacho do cron + execução isolada do turno do agente de cron    webhook: "https://example.invalid/legacy", // fallback obsoleto para tarefas armazenadas com notify:true    webhookToken: "replace-with-dedicated-token", // token bearer opcional para autenticação de Webhooks de saída    sessionRetention: "24h", // string de duração ou false    runLog: {      maxBytes: "2mb", // padrão de 2_000_000 bytes      keepLines: 2000, // padrão de 2000    },  },}

• sessionRetention: por quanto tempo manter as sessões concluídas de execuções isoladas do cron antes de remover as linhas de sessão do SQLite. Também controla a limpeza de transcrições arquivadas de cron excluídas. Padrão: 24h; defina como false para desativar.
• runLog.maxBytes: aceito para compatibilidade com logs de execução de cron mais antigos baseados em arquivos. Padrão: 2_000_000 bytes.
• runLog.keepLines: linhas mais recentes do histórico de execuções do SQLite mantidas por tarefa. Padrão: 2000.
• webhookToken: token bearer usado para entrega POST de Webhooks do cron (delivery.mode = "webhook"); se omitido, nenhum cabeçalho de autenticação é enviado.
• webhook: URL de Webhook legada e obsoleta (http/https), usada por openclaw doctor --fix para migrar tarefas armazenadas que ainda têm notify: true; a entrega em tempo de execução usa delivery.mode="webhook" por tarefa mais delivery.to, ou delivery.completionDestination ao preservar a entrega de anúncio.

cron.retry

{  cron: {    retry: {      maxAttempts: 3,      backoffMs: [30000, 60000, 300000],      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],    },  },}

• maxAttempts: número máximo de novas tentativas para tarefas Cron em caso de erros transitórios (padrão: 3; intervalo: 0-10).
• backoffMs: matriz de atrasos de espera em ms para cada nova tentativa (padrão: [30000, 60000, 300000]; 1-10 entradas).
• retryOn: tipos de erro que acionam novas tentativas — "rate_limit", "overloaded", "network", "timeout", "server_error". Omita para tentar novamente em todos os tipos transitórios.

As tarefas de execução única permanecem habilitadas até que as tentativas se esgotem; em seguida, são desabilitadas, mantendo o estado de erro final. As tarefas recorrentes usam a mesma política de novas tentativas para erros transitórios e são executadas novamente após o tempo de espera, antes do próximo horário agendado; erros permanentes ou o esgotamento das tentativas para erros transitórios fazem com que a tarefa retorne à programação recorrente normal, com espera após erros.

cron.failureAlert

{  cron: {    failureAlert: {      enabled: false,      after: 3,      cooldownMs: 3600000,      includeSkipped: false,      mode: "announce",      accountId: "main",    },  },}

• enabled: habilita alertas de falha para tarefas Cron (padrão: false).
• after: número de falhas consecutivas antes do acionamento de um alerta (inteiro positivo, mín.: 1).
• cooldownMs: número mínimo de milissegundos entre alertas repetidos para a mesma tarefa (inteiro não negativo).
• includeSkipped: contabiliza execuções consecutivas ignoradas para o limite do alerta (padrão: false). As execuções ignoradas são monitoradas separadamente e não afetam a espera após erros de execução.
• mode: modo de entrega — "announce" envia por meio de uma mensagem de canal; "webhook" publica no Webhook configurado.
• accountId: ID opcional da conta ou do canal para delimitar a entrega de alertas.

cron.failureDestination

{  cron: {    failureDestination: {      mode: "announce",      channel: "last",      to: "channel:C1234567890",      accountId: "main",    },  },}

• Destino padrão das notificações de falha do Cron para todas as tarefas.
• mode: "announce" ou "webhook"; o padrão é "announce" quando há dados de destino suficientes.
• channel: substituição do canal para entrega por anúncio. "last" reutiliza o último canal de entrega conhecido.
• to: destino explícito do anúncio ou URL do Webhook. Obrigatório para o modo Webhook.
• accountId: substituição opcional da conta para entrega.
• O delivery.failureDestination de cada tarefa substitui este padrão global.
• Quando nenhum destino de falha global nem específico da tarefa está definido, as tarefas que já realizam entregas por announce usam esse destino principal de anúncio como alternativa em caso de falha.
• delivery.failureDestination é compatível apenas com tarefas sessionTarget="isolated", a menos que o delivery.mode principal da tarefa seja "webhook".

Consulte Tarefas Cron. As execuções isoladas do Cron são monitoradas como tarefas em segundo plano.

Variáveis de modelo para modelos de mídia

Espaços reservados de modelo expandidos em tools.media.models[].args:

Inclusões de configuração ($include)

Divida a configuração em vários arquivos:

// ~/.openclaw/openclaw.json{  gateway: { port: 18789 },  agents: { $include: "./agents.json5" },  broadcast: {    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],  },}

Comportamento da mesclagem:

• Arquivo único: substitui o objeto que o contém.
• Matriz de arquivos: mesclada profundamente na ordem indicada (os posteriores substituem os anteriores).
• Chaves irmãs: mescladas após as inclusões (substituem os valores incluídos).
• Inclusões aninhadas: até 10 níveis de profundidade.
• Caminhos: resolvidos em relação ao arquivo que realiza a inclusão, mas devem permanecer dentro do diretório de configuração de nível superior (dirname de openclaw.json). Formas absolutas/com ../ são permitidas somente quando ainda são resolvidas dentro desse limite. Defina OPENCLAW_INCLUDE_ROOTS (caminhos absolutos) para permitir raízes adicionais fora do diretório de configuração.
• Limites: os caminhos não devem conter bytes nulos e devem ter estritamente menos de 4096 caracteres antes e depois da resolução; cada arquivo incluído é limitado a 2 MB.
• As gravações pertencentes ao OpenClaw que alteram apenas uma seção de nível superior respaldada por uma inclusão de arquivo único são encaminhadas para esse arquivo incluído. Por exemplo, plugins install atualiza plugins: { $include: "./plugins.json5" } em plugins.json5 e mantém openclaw.json intacto.
• Inclusões na raiz, matrizes de inclusões e inclusões com substituições por chaves irmãs são somente leitura para gravações pertencentes ao OpenClaw; essas gravações falham de forma segura em vez de achatar a configuração.
• Erros: mensagens claras para arquivos ausentes, erros de análise, inclusões circulares, formato de caminho inválido e comprimento excessivo.

Relacionados

• Configuração
• Exemplos de configuração
• Doctor