Referência de configuração

Referência da configuração principal para ~/.openclaw/openclaw.json. Para uma visão geral orientada a tarefas, consulte Configuração.

Abrange as principais superfícies de configuração do OpenClaw e aponta para outras referências quando um subsistema tem sua própria documentação mais aprofundada. Catálogos de comandos pertencentes a canais e plugins, bem como ajustes avançados de memória/QMD, ficam em suas próprias páginas em vez desta.

Fonte de verdade no código:

• openclaw config schema imprime o JSON Schema ativo usado para validação e Control UI, com metadados de pacotes integrados/plugins/canais mesclados quando disponíveis
• config.schema.lookup retorna um nó de esquema com escopo por caminho para ferramentas de detalhamento
• pnpm config:docs:check / pnpm config:docs:gen validam o hash de linha de base da documentação de configuração em relação à superfície atual do esquema

Caminho de consulta do agente: use a ação de ferramenta config.schema.lookup do gateway para obter documentação e restrições exatas em nível de campo antes das edições. Use Configuração para orientação orientada a tarefas e esta página para o mapa mais amplo de campos, padrões e links para referências de subsistemas.

Referências aprofundadas dedicadas:

• Referência de configuração de memória para agents.defaults.memorySearch.*, memory.qmd.*, memory.citations e configuração de Dreaming em plugins.entries.memory-core.config.dreaming
• Comandos slash para o catálogo atual de comandos integrados + empacotados
• páginas dos canais/plugins proprietários para superfícies de comando específicas de canais

O formato de configuração é JSON5 (comentários + vírgulas finais permitidos). Todos os campos são opcionais - o OpenClaw usa padrões seguros quando omitidos.

# Canais

As chaves de configuração por canal foram movidas para uma página dedicada - consulte Configuração - canais para channels.*, incluindo Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e outros canais empacotados (autenticação, controle de acesso, múltiplas contas, bloqueio por menção).

# Padrões de agente, multiagente, sessões e mensagens

Movido para uma página dedicada - consulte Configuração - agentes para:

• agents.defaults.* (espaço de trabalho, modelo, raciocínio, Heartbeat, memória, mídia, Skills, sandbox)
• multiAgent.* (roteamento e associações multiagente)
• session.* (ciclo de vida da sessão, Compaction, poda)
• messages.* (entrega de mensagens, TTS, renderização de markdown)
• talk.* (modo Talk)
  • talk.speechLocale: id de localidade BCP 47 opcional para 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)

# Ferramentas e provedores personalizados

Política de ferramentas, alternâncias experimentais, configuração de ferramentas apoiada por provedores e configuração de provedor personalizado / URL base foram movidas para uma página dedicada - consulte Configuração - ferramentas e provedores personalizados.

# Modelos

Definições de provedores, listas de modelos permitidos e 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: {
    // Optional. Default: true. Requires a Gateway restart when changed.
    pricing: { enabled: false },
  },
}

• models.mode: comportamento do catálogo de provedores (merge ou replace).
• models.providers: mapa de provedores personalizados indexado por id do provedor.
• models.pricing.enabled: controla a inicialização em segundo plano de preços que começa depois que os sidecars e canais alcançam o caminho de prontidão do Gateway. Quando false, o Gateway ignora buscas de catálogos de preços do OpenRouter e LiteLLM; valores configurados em models.providers.*.models[].cost ainda funcionam para estimativas de custo locais.

# MCP

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

{
  mcp: {
    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
    sessionIdleTtlMs: 600000,
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
      },
    },
  },
}

• mcp.servers: definições nomeadas de servidores MCP stdio ou remotos para runtimes que expõem ferramentas MCP configuradas. 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.sessionIdleTtlMs: TTL de inatividade para runtimes MCP empacotados com escopo de sessão. Execuções embarcadas de uso único solicitam limpeza ao final da execução; este TTL é o mecanismo de segurança para sessões de longa duração e futuros chamadores.
• Alterações em mcp.* são aplicadas a quente descartando runtimes MCP de sessão em cache. A próxima descoberta/uso de ferramenta os recria a partir da nova configuração, então entradas removidas de mcp.servers são coletadas imediatamente em vez de esperar pelo TTL de inatividade.

Consulte MCP e backends de CLI para o comportamento de runtime.

# Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• allowBundled: lista de permissão opcional apenas para Skills empacotadas (Skills gerenciadas/do espaço de trabalho não são afetadas).
• load.extraDirs: raízes extras de Skills compartilhadas (menor precedência).
• install.preferBrew: quando verdadeiro, prefere instaladores Homebrew quando brew está disponível antes de recorrer a outros tipos de instalador.
• install.nodeManager: preferência de instalador Node para especificações metadata.openclaw.install (npm | pnpm | yarn | bun).
• entries.<skillKey>.enabled: false desativa uma Skill mesmo que ela esteja empacotada/instalada.
• entries.<skillKey>.apiKey: conveniência para Skills que declaram uma variável de ambiente primária (string em texto simples ou objeto SecretRef).

# Plugins

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

• Carregado de ~/.openclaw/extensions, <workspace>/.openclaw/extensions, mais plugins.load.paths.
• A descoberta aceita plugins nativos do OpenClaw, além de pacotes compatíveis do Codex e pacotes do Claude, incluindo pacotes de layout padrão do Claude sem manifesto.
• Alterações de configuração exigem reinicialização do Gateway.
• allow: lista de permissão opcional (somente plugins listados são carregados). deny prevalece.
• bundledDiscovery: o padrão é "allowlist" para novas configurações, então um plugins.allow não vazio também restringe plugins de provedores empacotados, incluindo provedores de runtime de busca na web. O Doctor escreve "compat" para configurações de listas de permissão legadas migradas a fim de preservar o comportamento existente de provedores empacotados até você optar pelo novo modo.
• plugins.entries.<id>.apiKey: campo de conveniência de chave de API em nível de plugin (quando suportado pelo plugin).
• plugins.entries.<id>.env: mapa de variáveis de ambiente com escopo de plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: quando false, o núcleo bloqueia before_prompt_build e ignora campos que alteram prompt vindos do before_agent_start legado, preservando modelOverride e providerOverride legados. Aplica-se a hooks de plugins nativos e diretórios de hooks fornecidos por pacotes compatíveis.
• plugins.entries.<id>.hooks.allowConversationAccess: quando true, plugins confiáveis não empacotados podem ler conteúdo bruto da conversa a partir de 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 para execuções de subagentes em segundo plano.
• plugins.entries.<id>.subagent.allowedModels: lista de permissão opcional de destinos canônicos provider/model para substituições confiáveis de subagentes. Use "*" somente quando você quiser intencionalmente permitir qualquer modelo.
• plugins.entries.<id>.config: objeto de configuração definido pelo plugin (validado pelo esquema de plugin nativo do OpenClaw quando disponível).
• Configurações de conta/runtime de plugins 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.
• plugins.entries.firecrawl.config.webFetch: configurações do provedor de web-fetch Firecrawl.
  • apiKey: chave de API do Firecrawl (aceita SecretRef). Recai para plugins.entries.firecrawl.config.webSearch.apiKey, tools.web.fetch.firecrawl.apiKey legado ou variável de ambiente FIRECRAWL_API_KEY.
  • baseUrl: URL base da API Firecrawl (padrão: https://api.firecrawl.dev; substituições self-hosted devem apontar para endpoints privados/internos).
  • onlyMainContent: extrai somente o conteúdo principal das páginas (padrão: true).
  • maxAgeMs: idade máxima de cache em milissegundos (padrão: 172800000 / 2 dias).
  • timeoutSeconds: tempo limite da solicitação de scraping em segundos (padrão: 60).
• plugins.entries.xai.config.xSearch: configurações do xAI X Search (busca web do Grok).
  • enabled: habilita o provedor X Search.
  • model: modelo Grok a usar para busca (por exemplo, "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: configurações de Dreaming de memória. Consulte Dreaming para fases e limites.
  • enabled: alternância principal de Dreaming (padrão false).
  • frequency: cadência cron para cada varredura completa de Dreaming ("0 3 * * *" por padrão).
  • model: substituição opcional de modelo do subagente Dream Diary. Exige plugins.entries.memory-core.subagent.allowModelOverride: true; combine com allowedModels para restringir destinos. Erros de modelo indisponível tentam novamente uma vez com o modelo padrão da sessão; falhas de confiança ou lista de permissão não fazem fallback silenciosamente.
  • política de fases e limites são detalhes de implementação (não chaves de configuração voltadas ao usuário).
• A configuração completa de memória fica em Referência de configuração de memória:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• Plugins de pacote do Claude habilitados também podem contribuir padrões embarcados do Pi a partir de settings.json; o OpenClaw aplica esses valores como configurações saneadas de agente, não como patches brutos de configuração do OpenClaw.
• plugins.slots.memory: escolha o id do plugin de memória ativo, ou "none" para desativar plugins de memória.
• plugins.slots.contextEngine: escolha o id do plugin de mecanismo de contexto ativo; o padrão é "legacy" a menos que você instale e selecione outro mecanismo.

Consulte Plugins.

# Compromissos

commitments controla memória inferida de acompanhamento: o OpenClaw pode detectar check-ins em turnos de conversa e entregá-los por meio de execuções de Heartbeat.

• commitments.enabled: habilita extração oculta por LLM, armazenamento e entrega por Heartbeat para compromissos de acompanhamento inferidos. Padrão: false.
• commitments.maxPerDay: número máximo de compromissos de acompanhamento inferidos entregues por sessão de agente em um dia contínuo. Padrão: 3.

Consulte Compromissos inferidos.

# Navegador

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // 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 abas rastreadas do agente primário após tempo ocioso ou quando uma sessão excede seu limite. Defina idleMinutes: 0 ou maxTabsPerSession: 0 para desativar esses modos de limpeza individuais.
• ssrfPolicy.dangerouslyAllowPrivateNetwork fica desativado quando não definido, então a navegação do navegador permanece rigorosa por padrão.
• Defina ssrfPolicy.dangerouslyAllowPrivateNetwork: true somente quando você confiar intencionalmente na navegação do navegador em rede privada.
• No modo rigoroso, endpoints de perfil CDP remoto (profiles.*.cdpUrl) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de alcance/descoberta.
• ssrfPolicy.allowPrivateNetwork continua compatível como um alias legado.
• No modo rigoroso, use ssrfPolicy.hostnameAllowlist e ssrfPolicy.allowedHostnames para exceções explícitas.
• Perfis remotos são apenas para anexação (iniciar/parar/redefinir 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 direta de WebSocket do DevTools.
• remoteCdpTimeoutMs e remoteCdpHandshakeTimeoutMs se aplicam ao alcance CDP remoto e attachOnly, além de solicitações de abertura de abas. Perfis gerenciados de loopback mantêm os padrões CDP locais.
• Se um serviço CDP gerenciado externamente estiver acessível por loopback, defina attachOnly: true nesse perfil; caso contrário, o OpenClaw trata a porta de loopback como um perfil de navegador gerenciado local e pode relatar erros de propriedade de porta local.
• Perfis existing-session usam Chrome MCP em vez de CDP e podem se anexar no host selecionado ou por meio de um nó de navegador conectado.
• Perfis existing-session podem definir userDataDir para apontar para um perfil específico de navegador baseado em Chromium, como Brave ou Edge.
• Perfis existing-session mantêm os limites atuais de rota do Chrome MCP: ações orientadas por snapshot/ref em vez de seleção por seletor CSS, hooks de upload de um arquivo, sem substituições de timeout de diálogo, sem wait --load networkidle e sem responsebody, exportação de PDF, interceptação de download ou ações em lote.
• Perfis openclaw gerenciados locais atribuem automaticamente cdpPort e cdpUrl; apenas defina cdpUrl explicitamente para CDP remoto.
• Perfis gerenciados locais podem definir executablePath para substituir o browser.executablePath global nesse perfil. Use isso para executar um perfil no Chrome e outro no Brave.
• Perfis gerenciados locais usam browser.localLaunchTimeoutMs para descoberta HTTP do Chrome CDP após o início do processo e browser.localCdpReadyTimeoutMs para prontidão do websocket CDP pós-inicialização. Aumente-os em hosts mais lentos em que o Chrome inicia com sucesso, mas as verificações de prontidão disputam a inicialização. Ambos os valores devem ser inteiros positivos até 120000 ms; valores de configuração inválidos são rejeitados.
• Ordem de autodetecção: 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 SO antes da inicialização do Chromium. userDataDir por perfil em perfis existing-session também é expandido com til.
• Serviço de controle: apenas loopback (porta derivada de gateway.port, padrão 18791).
• extraArgs acrescenta flags extras de inicialização ao início local do Chromium (por exemplo --disable-gpu, dimensionamento de janela ou flags de depuração).

# UI

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

• seamColor: cor de destaque para o chrome da UI do app nativo (tom do balão do Talk Mode etc.).
• assistant: substituição da identidade da UI de controle. Usa a identidade do agente ativo como fallback.

# Gateway

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
      // chatMessageMaxWidth: "min(1280px, 82%)", // optional grouped chat message max-width
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    nodes: {
      pairing: {
        // Optional. Default unset/disabled.
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
      allowCommands: ["canvas.navigate"],
      denyCommands: ["system.run"],
    },
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

# Endpoints compatíveis com OpenAI

• Chat Completions: desativado por padrão. Habilite com gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Proteção de entrada por 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 por URL.
• Cabeçalho opcional de proteção de resposta:
  • gateway.http.securityHeaders.strictTransportSecurity (defina somente para origens HTTPS que você controla; consulte Autenticação por proxy confiável)

# Isolamento de múltiplas instâncias

Execute múltiplos 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 Múltiplos 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: habilita 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/dev.
• certPath: caminho no sistema de arquivos para o arquivo de certificado TLS.
• keyPath: caminho no sistema de arquivos para o arquivo de chave privada TLS; mantenha permissões restritas.
• caPath: caminho opcional para pacote de CA para verificação de cliente ou cadeias de confiança customizadas.

# gateway.reload

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

• mode: controla como edições de configuração são aplicadas em runtime.
  • "off": ignora edições ao vivo; alterações exigem uma reinicialização explícita.
  • "restart": sempre reinicia o processo do Gateway em mudança de configuração.
  • "hot": aplica alterações no processo sem reiniciar.
  • "hybrid" (padrão): tenta hot reload primeiro; recorre à reinicialização se necessário.
• debounceMs: janela de debounce em ms antes que alterações de configuração sejam aplicadas (inteiro não negativo).
• deferralTimeoutMs: tempo máximo opcional em ms para aguardar operações em andamento antes de forçar uma reinicialização ou hot reload de canal. Omita para usar a espera limitada padrão (300000); defina 0 para aguardar indefinidamente e registrar avisos periódicos de ainda pendente.

# Ganchos

{
  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: "From: {{messages[0].from}}\nSubject: {{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 em query string 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 de gateway.auth.token; reutilizar o token do Gateway é rejeitado.
• 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 preset usar um sessionKey com template, defina hooks.allowedSessionKeyPrefixes e hooks.allowRequestSessionKey=true. Chaves de mapeamento estáticas não exigem essa adesã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? }
  • sessionKey da carga da solicitação só é aceito quando hooks.allowRequestSessionKey=true (padrão: false).
• POST /hooks/<name> → resolvido via hooks.mappings
  • Valores de sessionKey de mapeamento renderizados por template são tratados como fornecidos externamente e também exigem hooks.allowRequestSessionKey=true.

# Integração com Gmail

• O preset integrado do Gmail usa sessionKey: "hook:gmail:{{messages[0].id}}".
• Se você mantiver esse roteamento por mensagem, defina hooks.allowRequestSessionKey: true e restrinja hooks.allowedSessionKeyPrefixes para corresponder ao namespace do Gmail, por exemplo ["hook:", "hook:gmail:"].
• Se precisar de hooks.allowRequestSessionKey: false, substitua o preset por um sessionKey estático em vez do padrão com template.

{
  hooks: {
    gmail: {
      account: "[email protected]",
      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 um gog gmail watch serve separado junto com o Gateway.

# Host do Plugin Canvas

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

• Serve HTML/CSS/JS editáveis por agentes e A2UI por 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).
• Vínculos sem loopback: rotas do canvas exigem autenticação do Gateway (token/senha/proxy confiável), igual a 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 a canvas/A2UI.
• URLs de capacidade são vinculadas à sessão WS ativa do Node e expiram rapidamente. Fallback baseado em IP não é usado.
• Injeta cliente de recarregamento ao vivo no HTML servido.
• Cria automaticamente um index.html inicial quando vazio.
• Também serve A2UI em /__openclaw__/a2ui/.
• Alterações exigem 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 quando o plugin integrado bonjour está habilitado): omite cliPath + sshPort dos registros TXT.
• full: inclui cliPath + sshPort; a publicidade multicast em LAN ainda exige que o plugin integrado bonjour esteja habilitado.
• off: suprime a publicidade multicast em LAN sem alterar a habilitação do plugin.
• O plugin integrado bonjour inicia automaticamente em hosts macOS e é opcional em Linux, Windows e implantações de Gateway conteinerizadas.
• O hostname usa como padrão o hostname do sistema quando ele é um rótulo DNS válido, usando openclaw como fallback. Substitua com OPENCLAW_MDNS_HOSTNAME.

# Á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 inline)

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

• Variáveis de ambiente inline são aplicadas apenas se o ambiente do processo não tiver a chave.
• Arquivos .env: .env do CWD + ~/.openclaw/.env (nenhum substitui variáveis existentes).
• shellEnv: importa chaves esperadas ausentes do perfil do seu shell de login.
• 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}" },
  },
}

• Apenas nomes em maiúsculas correspondem: [A-Z_][A-Z0-9_]*.
• Variáveis ausentes/vazias geram um erro no carregamento da configuração.
• Escape com $${VAR} para um ${VAR} literal.
• Funciona com $include.

# Segredos

Referências de segredo são aditivas: valores em texto simples ainda funcionam.

# SecretRef

Use um formato 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 de source: "env": ^[A-Z][A-Z0-9_]{0,127}$
• Id de source: "file": ponteiro JSON absoluto (por exemplo "/providers/openai/apiKey")
• Padrão de id de source: "exec": ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• 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 SecretRef
• secrets apply tem como alvo caminhos de credenciais compatíveis em openclaw.json.
• Referências de auth-profiles.json são incluídas na resolução em tempo de execução e na cobertura de auditoria.

# Configuração de provedores de segredos

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      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 oferece suporte a mode: "json" e mode: "singleValue" (id deve ser "value" no modo singleValue).
• Caminhos de provedores file e exec falham de forma fechada quando a verificação de ACL do Windows não está disponível. Defina allowInsecurePath: true apenas para caminhos confiáveis que não possam ser verificados.
• O provedor exec exige um caminho absoluto de command e usa cargas de protocolo em stdin/stdout.
• Por padrão, caminhos de comando por symlink são rejeitados. Defina allowSymlinkCommand: true para permitir caminhos de symlink enquanto valida o caminho de destino resolvido.
• Se trustedDirs estiver configurado, a verificação de diretório confiável se aplica ao caminho de destino resolvido.
• O ambiente filho de exec é mínimo por padrão; passe variáveis necessárias explicitamente com passEnv.
• Referências de segredo são resolvidas no momento da ativação em um snapshot em memória; depois, os caminhos de solicitação leem apenas o snapshot.
• A filtragem de superfície ativa se aplica 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-codex:personal": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      "openai-codex": ["openai-codex:personal"],
    },
  },
}

• Perfis por agente são armazenados em <agentDir>/auth-profiles.json.
• auth-profiles.json oferece suporte a referências no nível do valor (keyRef para api_key, tokenRef para token) para modos de credencial estática.
• Mapas planos legados de auth-profiles.json, como { "provider": { "apiKey": "..." } }, não são um formato em tempo de execução; openclaw doctor --fix os reescreve para perfis canônicos de chave de API provider:default com um backup .legacy-flat.*.bak.
• Perfis em modo OAuth (auth.profiles.<id>.mode = "oauth") não oferecem suporte a credenciais de perfil de autenticação apoiadas por SecretRef.
• Credenciais estáticas em tempo de execução vêm de snapshots resolvidos em memória; entradas estáticas legadas de auth.json são limpas quando descobertas.
• 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 cair aqui mesmo em respostas 401/403, mas os correspondedores de texto específicos do provedor continuam limitados ao provedor ao qual pertencem (por exemplo, OpenRouter Key limit exceeded). Mensagens HTTP 402 retentáveis de janela de uso ou limite de gastos de organização/workspace permanecem no caminho rate_limit em vez disso.
• billingBackoffHoursByProvider: substituições opcionais por provedor para 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 rotações de perfis de autenticação do mesmo provedor para erros de sobrecarga antes de alternar para o fallback de modelo (padrão: 1). Formatos de provedor ocupado, como ModelNotReadyException, caem aqui.
• overloadedBackoffMs: atraso fixo antes de tentar novamente uma rotação de provedor/perfil sobrecarregado (padrão: 0).
• rateLimitedProfileRotations: número máximo de rotações de perfis de autenticação do mesmo provedor para erros de limite de taxa antes de alternar para o fallback de modelo (padrão: 1). Esse bucket de limite de taxa inclui textos com formato de provedor, como Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded e resource exhausted.

# Registro de logs

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

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

# Diagnóstico

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,
    stuckSessionAbortMs: 600000,

    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,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },

    cacheTrace: {
      enabled: false,
      filePath: "~/.openclaw/logs/cache-trace.jsonl",
      includeMessages: true,
      includePrompt: true,
      includeSystem: true,
    },
  },
}

• enabled: alternância principal para saída de instrumentação (padrão: true).
• flags: array de strings de sinalizadores que habilitam saída de log direcionada (aceita curingas como "telegram.*" ou "*").
• stuckSessionWarnMs: limite de idade sem progresso em ms para classificar sessões de processamento de longa duração como session.long_running, session.stalled ou session.stuck. Resposta, ferramenta, status, bloco e progresso ACP reiniciam o temporizador; diagnósticos session.stuck repetidos fazem recuo enquanto não houver mudanças.
• stuckSessionAbortMs: limite de idade sem progresso em ms antes que trabalho ativo travado elegível possa ser drenado por abortamento para recuperação. Quando não definido, OpenClaw usa a janela estendida mais segura de execução embarcada de pelo menos 10 minutos e 5x stuckSessionWarnMs.
• otel.enabled: habilita o pipeline de exportação OpenTelemetry (padrão: false). Para a configuração completa, catálogo de sinais e modelo de privacidade, consulte exportação 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 apenas para esse sinal.
• otel.protocol: "http/protobuf" (padrão) ou "grpc".
• otel.headers: cabeçalhos extras de metadados HTTP/gRPC enviados com solicitações de exportação OTel.
• otel.serviceName: nome do serviço para atributos de recurso.
• otel.traces / otel.metrics / otel.logs: habilita exportação de rastreamentos, métricas ou logs.
• otel.sampleRate: taxa de amostragem de rastreamento de 0 a 1.
• otel.flushIntervalMs: intervalo periódico de envio de telemetria em ms.
• otel.captureContent: captura opcional de conteúdo bruto para atributos de spans OTEL. Desativado por padrão. Booleano true captura conteúdo não sistêmico de mensagens/ferramentas; a forma de objeto permite habilitar inputMessages, outputMessages, toolInputs, toolOutputs e systemPrompt explicitamente.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: alternância de ambiente para os atributos experimentais mais recentes de provedor de spans GenAI. Por padrão, spans mantêm o atributo legado gen_ai.system para compatibilidade; métricas GenAI usam atributos semânticos delimitados.
• OPENCLAW_OTEL_PRELOADED=1: alternância de ambiente para hosts que já registraram um SDK OpenTelemetry global. 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 embarcadas (padrão: false).
• cacheTrace.filePath: caminho de saída para JSONL de rastreamento de cache (padrão: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: controlam o que é incluído na saída de rastreamento de cache (todos padrão: true).

# Atualização

{
  update: {
    channel: "stable", // stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

• channel: canal de lançamento para instalações npm/git - "stable", "beta" ou "dev".
• checkOnStart: verifica atualizações do npm quando o Gateway inicia (padrão: true).
• auto.enabled: habilita atualização automática em segundo plano para instalações de pacotes (padrão: false).
• auto.stableDelayHours: atraso mínimo em horas antes da aplicação automática no 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, com que verificações do canal beta são executadas (padrão: 1; máximo: 24).

# ACP

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    maxConcurrentSessions: 10,

    stream: {
      coalesceIdleMs: 50,
      maxChunkChars: 1000,
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
      maxOutputChars: 50000,
      maxSessionUpdateChars: 500,
    },

    runtime: {
      ttlMinutes: 30,
    },
  },
}

• enabled: gate global do recurso ACP (padrão: true; defina como false para ocultar despacho ACP e opções de spawn).
• dispatch.enabled: gate independente para despacho de turnos de sessão ACP (padrão: true). Defina como false para manter comandos ACP disponíveis enquanto bloqueia a execução.
• backend: id padrão do backend de runtime ACP (deve corresponder a um Plugin registrado de runtime ACP). Instale primeiro o Plugin de backend e, se plugins.allow estiver definido, inclua o id do Plugin de backend (por exemplo, acpx) ou o backend ACP não será carregado.
• defaultAgent: id do agente ACP de fallback quando spawns não especificam um alvo explícito.
• allowedAgents: lista de permissão de ids de agentes permitidos para sessões de runtime ACP; vazia significa sem restrição adicional.
• maxConcurrentSessions: número máximo de sessões ACP ativas simultaneamente.
• stream.coalesceIdleMs: janela de flush ocioso em ms para texto transmitido.
• stream.maxChunkChars: tamanho máximo de chunk antes de dividir a projeção de bloco transmitido.
• stream.repeatSuppression: suprime linhas repetidas de status/ferramenta por turno (padrão: true).
• stream.deliveryMode: "live" transmite incrementalmente; "final_only" armazena em buffer até eventos terminais do turno.
• stream.hiddenBoundarySeparator: separador antes de texto visível após eventos de ferramenta ocultos (padrão: "paragraph").
• stream.maxOutputChars: número máximo de caracteres de saída do assistente projetados por turno ACP.
• stream.maxSessionUpdateChars: número máximo de caracteres para linhas projetadas de status/atualização ACP.
• stream.tagVisibility: registro de nomes de tags para substituições booleanas de visibilidade em eventos transmitidos.
• runtime.ttlMinutes: TTL ocioso em minutos para workers de sessão ACP antes de ficarem elegíveis para limpeza.
• runtime.installCommand: comando de instalação opcional a executar 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 engraçados/sazonais em rotação.
  • "default": slogan neutro fixo (All your chats, one OpenClaw.).
  • "off": nenhum texto de slogan (título/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 por fluxos guiados de configuração da CLI (onboard, configure, doctor):

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

# Identidade

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

# Ponte (legado, removido)

As builds atuais não incluem mais a ponte TCP. 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 remover chaves desconhecidas).

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

# Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}

• sessionRetention: por quanto tempo manter sessões concluídas de execuções Cron isoladas antes da remoção de sessions.json. Também controla a limpeza de transcrições Cron excluídas arquivadas. Padrão: 24h; defina como false para desativar.
• runLog.maxBytes: tamanho máximo por arquivo de log de execução (cron/runs/<jobId>.jsonl) antes da remoção. Padrão: 2_000_000 bytes.
• runLog.keepLines: linhas mais recentes mantidas quando a remoção do log de execução é acionada. Padrão: 2000.
• webhookToken: token bearer usado para entrega POST do Webhook Cron (delivery.mode = "webhook"); se omitido, nenhum cabeçalho de autenticação é enviado.
• webhook: URL de Webhook legada de fallback obsoleta (http/https), usada apenas para trabalhos armazenados que ainda têm notify: true.

# cron.retry

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

• maxAttempts: máximo de novas tentativas para trabalhos de execução única em erros transitórios (padrão: 3; intervalo: 0-10).
• backoffMs: array de atrasos de backoff em ms para cada 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.

Aplica-se apenas a trabalhos Cron de execução única. Trabalhos recorrentes usam tratamento de falhas separado.

# cron.failureAlert

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

• enabled: ativa alertas de falha para trabalhos Cron (padrão: false).
• after: falhas consecutivas antes de um alerta ser disparado (inteiro positivo, mín.: 1).
• cooldownMs: mínimo de milissegundos entre alertas repetidos para o mesmo trabalho (inteiro não negativo).
• includeSkipped: conta execuções ignoradas consecutivas para o limite do alerta (padrão: false). Execuções ignoradas são rastreadas separadamente e não afetam o backoff de erros de execução.
• mode: modo de entrega - "announce" envia por meio de uma mensagem de canal; "webhook" publica no Webhook configurado.
• accountId: conta ou id de canal opcional para limitar o escopo da entrega de alertas.

# cron.failureDestination

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

• Destino padrão para notificações de falha de Cron em todos os trabalhos.
• mode: "announce" ou "webhook"; usa "announce" por padrão quando há dados de destino suficientes.
• channel: substituição de canal para entrega de anúncio. "last" reutiliza o último canal de entrega conhecido.
• to: destino de anúncio explícito ou URL de Webhook. Obrigatório para o modo Webhook.
• accountId: substituição opcional de conta para entrega.
• delivery.failureDestination substitui este padrão global por trabalho.
• Quando nenhum destino de falha global nem por trabalho está definido, trabalhos que já fazem entrega via announce usam esse destino principal de anúncio como fallback em caso de falha.
• delivery.failureDestination só é compatível com trabalhos sessionTarget="isolated", a menos que o delivery.mode principal do trabalho seja "webhook".

Veja Trabalhos Cron. Execuções Cron isoladas são rastreadas como tarefas em segundo plano.

# Variáveis de modelo de mídia

Placeholders de template expandidos em tools.media.models[].args:

# Includes 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 de mesclagem:

• Arquivo único: substitui o objeto contêiner.
• Array de arquivos: mesclados profundamente em ordem (os posteriores substituem os anteriores).
• Chaves irmãs: mescladas após os includes (substituem valores incluídos).
• Includes aninhados: até 10 níveis de profundidade.
• Caminhos: resolvidos em relação ao arquivo que inclui, mas devem permanecer dentro do diretório de configuração de nível superior (dirname de openclaw.json). Formas absolutas/../ são permitidas apenas quando ainda resolvem dentro desse limite.
• Gravações de propriedade do OpenClaw que alteram apenas uma seção de nível superior apoiada por um include de arquivo único são gravadas nesse arquivo incluído. Por exemplo, plugins install atualiza plugins: { $include: "./plugins.json5" } em plugins.json5 e deixa openclaw.json intacto.
• Includes raiz, arrays de includes e includes com substituições irmãs são somente leitura para gravações de propriedade do OpenClaw; essas gravações falham de forma fechada em vez de achatar a configuração.
• Erros: mensagens claras para arquivos ausentes, erros de análise e includes circulares.

Relacionado: Configuração · Exemplos de configuração · Doctor

# Relacionado

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