Configuração

Cada canal tem sua própria seção de configuração em channels.<provider>. Consulte a página específica do canal para ver as etapas de configuração:

• Discord — channels.discord
• Feishu — channels.feishu
• Google Chat — channels.googlechat
• iMessage — channels.imessage
• Mattermost — channels.mattermost
• Microsoft Teams — channels.msteams
• Signal — channels.signal
• Slack — channels.slack
• Telegram — channels.telegram
• WhatsApp — channels.whatsapp

Todos os canais compartilham o mesmo padrão de política de mensagens diretas:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pareamento | lista de permissões | aberto | desativado      allowFrom: ["tg:123"], // somente para lista de permissões/aberto    },  },}

Defina o modelo principal e os fallbacks opcionais:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• agents.defaults.models define o catálogo de modelos e atua como a lista de permissões para /model; as entradas de provider/* filtram /model, /models e os seletores de modelos para os provedores selecionados, ainda usando a descoberta dinâmica de modelos.
• Use openclaw config set agents.defaults.models '<json>' --strict-json --merge para adicionar entradas à lista de permissões sem remover os modelos existentes. Substituições simples que removeriam entradas são rejeitadas, a menos que --replace seja fornecido.
• As referências de modelos usam o formato provider/model (por exemplo, anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx controla a redução de resolução de imagens de transcrições/ferramentas (padrão: 1200); valores menores geralmente reduzem o uso de tokens de visão em execuções com muitas capturas de tela.
• Consulte a CLI de modelos para alternar modelos no chat e Failover de modelos para saber mais sobre a rotação de autenticação e o comportamento de fallback.
• Para provedores personalizados/hospedados localmente, consulte Provedores personalizados na referência.

O acesso a mensagens diretas é controlado por canal por meio de dmPolicy (padrão: "pairing"):

• "pairing": remetentes desconhecidos recebem um código de pareamento de uso único para aprovação
• "allowlist": somente remetentes em allowFrom (ou no armazenamento de permissões pareadas)
• "open": permite todas as mensagens diretas recebidas (requer allowFrom: ["*"])
• "disabled": ignora todas as mensagens diretas

Para grupos, use groupPolicy ("allowlist" | "open" | "disabled") junto com groupAllowFrom ou listas de permissões específicas do canal.

Consulte a referência completa para ver os detalhes de cada canal.

Por padrão, mensagens em grupo exigem menção. Configure os padrões de acionamento por agente. Respostas normais de grupos/canais são publicadas automaticamente; ative o caminho da ferramenta de mensagens para salas compartilhadas nas quais o agente deve decidir quando falar:

{  messages: {    visibleReplies: "automatic", // defina como "message_tool" para exigir envios pela ferramenta de mensagens em todos os lugares    groupChat: {      visibleReplies: "message_tool", // opção habilitada; a saída visível exige message(action=send)      unmentionedInbound: "room_event", // conversas contínuas em grupo sem menção são um contexto silencioso    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Menções nos metadados: @menções nativas (tocar para mencionar no WhatsApp, @bot no Telegram etc.)
• Padrões de texto: padrões seguros de expressões regulares em mentionPatterns
• Respostas visíveis: messages.visibleReplies pode exigir envios pela ferramenta de mensagens globalmente; messages.groupChat.visibleReplies substitui essa configuração para grupos/canais.
• Consulte a referência completa para ver os modos de resposta visível, as substituições específicas por canal e o modo de conversa consigo mesmo.

Use agents.defaults.skills como uma linha de base compartilhada e depois substitua a configuração de agentes específicos com agents.list[].skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // herda github, weather      { id: "docs", skills: ["docs-search"] }, // substitui os padrões      { id: "locked-down", skills: [] }, // nenhuma skill    ],  },}

• Omita agents.defaults.skills para permitir Skills sem restrições por padrão.
• Omita agents.list[].skills para herdar os padrões.
• Defina agents.list[].skills: [] para não permitir nenhuma skill.
• Consulte Skills, Configuração de Skills e a Referência de configuração.

Controle com que agressividade o Gateway reinicia canais que parecem inativos:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Os valores exibidos são os padrões. Defina gateway.channelHealthCheckMinutes: 0 para desativar globalmente as reinicializações do monitor de integridade.
• channelStaleEventThresholdMinutes deve ser maior ou igual ao intervalo de verificação.
• Use channels.<provider>.healthMonitor.enabled ou channels.<provider>.accounts.<id>.healthMonitor.enabled para desativar as reinicializações automáticas de um canal ou uma conta sem desativar o monitor global.
• Consulte Verificações de integridade para depuração operacional e a referência completa para ver todos os campos.

Dê aos clientes locais mais tempo para concluir o handshake WebSocket anterior à autenticação em hosts sobrecarregados ou de baixo consumo:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• O padrão é 15000 milissegundos.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS ainda tem precedência para substituições pontuais de serviço ou shell.
• Prefira corrigir primeiro os bloqueios na inicialização/no loop de eventos; este ajuste destina-se a hosts que estão íntegros, mas lentos durante o aquecimento.

As sessões controlam a continuidade e o isolamento das conversas:

{  session: {    dmScope: "per-channel-peer",  // recomendado para vários usuários    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (compartilhado) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: padrões globais para o roteamento de sessões vinculadas a threads. /focus, /unfocus, /agents, /session idle e /session max-age vinculam, desvinculam, listam e ajustam isso por sessão (o Discord vincula threads; o Telegram vincula tópicos/conversas).
• Consulte Gerenciamento de sessões para saber mais sobre escopo, vínculos de identidade e política de envio.
• Consulte a referência completa para ver todos os campos.

Execute sessões de agente em runtimes de sandbox isolados:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

Primeiro, compile a imagem — em um checkout do código-fonte, execute scripts/sandbox-setup.sh; em uma instalação pelo npm, consulte o comando docker build embutido em Sandbox § Imagens e configuração.

Consulte Sandbox para ver o guia completo e a referência completa para conhecer todas as opções.

O push com suporte de relay para builds públicos da App Store usa o relay hospedado do OpenClaw: https://ios-push-relay.openclaw.ai.

Implantações de relay personalizadas exigem um caminho deliberadamente separado de build/implantação do iOS cuja URL de relay corresponda à URL de relay do Gateway. Se estiver usando um build com relay personalizado, defina isto na configuração do Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Opcional. Padrão: 10000          timeoutMs: 10000,        },      },    },  },}

Equivalente na CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

O que isso faz:

• Permite que o Gateway envie push.test, sinais de ativação e ativações de reconexão pelo relay externo.
• Usa uma concessão de envio limitada ao registro, encaminhada pelo aplicativo iOS emparelhado. O Gateway não precisa de um token de relay válido para toda a implantação.
• Vincula cada registro com suporte de relay à identidade do Gateway com o qual o aplicativo iOS foi emparelhado, impedindo que outro Gateway reutilize o registro armazenado.
• Mantém builds locais/manuais do iOS usando APNs diretamente. Os envios com suporte de relay aplicam-se somente a builds distribuídos oficiais registrados pelo relay.
• Deve corresponder à URL base do relay incorporada ao build do iOS, para que o tráfego de registro e envio chegue à mesma implantação do relay.

Fluxo completo:

1. Instale o aplicativo iOS oficial.
2. Opcional: configure gateway.push.apns.relay.baseUrl no Gateway somente ao usar um build de relay personalizado e deliberadamente separado.
3. Emparelhe o aplicativo iOS com o Gateway e permita que as sessões do Node e do operador se conectem.
4. O aplicativo iOS obtém a identidade do Gateway, registra-se no relay usando o App Attest e o recibo do aplicativo e, em seguida, publica o payload push.apns.register com suporte de relay no Gateway emparelhado.
5. O Gateway armazena o identificador do relay e a concessão de envio e depois os utiliza para push.test, sinais de ativação e ativações de reconexão.

Notas operacionais:

• Se você mudar o aplicativo iOS para outro Gateway, reconecte-o para que ele possa publicar um novo registro de relay vinculado a esse Gateway.
• Se você distribuir um novo build do iOS que aponte para uma implantação de relay diferente, o aplicativo atualizará o registro de relay em cache em vez de reutilizar a origem antiga do relay.

Nota de compatibilidade:

• OPENCLAW_APNS_RELAY_BASE_URL e OPENCLAW_APNS_RELAY_TIMEOUT_MS ainda funcionam como substituições temporárias por variáveis de ambiente.
• URLs de relay personalizadas do Gateway devem corresponder à URL base do relay incorporada ao build do iOS; o fluxo de lançamento público da App Store rejeita substituições personalizadas da URL de relay do iOS.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true continua sendo uma alternativa de desenvolvimento limitada ao loopback; não persista URLs HTTP de relay na configuração.

Consulte Aplicativo iOS para ver o fluxo completo e Fluxo de autenticação e confiança para conhecer o modelo de segurança do relay.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",      },    },  },}

• every: string de duração (30m, 2h). Defina como 0m para desativar. Padrão: 30m.
• target: last | none | <channel-id> (por exemplo, discord, matrix, telegram ou whatsapp)
• directPolicy: allow (padrão) ou block para destinos de Heartbeat no estilo DM
• Consulte Heartbeat para ver o guia completo.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // padrão; despacho do Cron + execução isolada do turno do agente Cron    sessionRetention: "24h",  },}

• sessionRetention: remove das linhas de sessão do SQLite as sessões concluídas de execuções isoladas (padrão: 24h; defina como false para desativar).
• O histórico de execuções mantém automaticamente as 2000 linhas terminais mais recentes por tarefa; as linhas perdidas mantêm sua janela de limpeza de 24 horas.
• Consulte Tarefas Cron para ver uma visão geral do recurso e exemplos da CLI.

Ative endpoints HTTP de Webhook no Gateway:

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

Nota de segurança:

• Trate todo o conteúdo dos payloads de hooks/Webhooks como entrada não confiável.
• Use um hooks.token dedicado; não reutilize segredos ativos de autenticação do Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN ou gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• A autenticação de hooks usa somente cabeçalhos (Authorization: Bearer ... ou x-openclaw-token); tokens na string de consulta são rejeitados.
• hooks.path não pode ser /; mantenha a entrada de Webhooks em um subcaminho dedicado, como /hooks.
• Mantenha desativadas as opções que ignoram a proteção contra conteúdo inseguro (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), exceto durante depurações com escopo rigorosamente limitado.
• Se ativar hooks.allowRequestSessionKey, defina também hooks.allowedSessionKeyPrefixes para limitar as chaves de sessão selecionadas pelo chamador.
• Para agentes acionados por hooks, prefira níveis de modelos modernos e robustos, além de uma política rigorosa de ferramentas (por exemplo, somente mensagens com isolamento em sandbox quando possível).

Consulte a referência completa para ver todas as opções de mapeamento e a integração com o Gmail.

Execute vários agentes isolados com espaços de trabalho e sessões separados:

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

Consulte Multiagente e a referência completa para conhecer as regras de vinculação e os perfis de acesso por agente.

Use $include para organizar configurações grandes:

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

• Arquivo único: substitui o objeto que o contém
• Matriz de arquivos: mesclada profundamente em ordem (o último prevalece), com até 10 níveis de aninhamento
• Chaves irmãs: mescladas após as inclusões (sobrescrevem os valores incluídos)
• Caminhos relativos: resolvidos em relação ao arquivo que realiza a inclusão
• Formato do caminho: os caminhos de inclusão não podem conter bytes nulos e devem ter estritamente menos de 4096 caracteres antes e depois da resolução
• Gravações realizadas pelo OpenClaw: quando uma gravação altera apenas uma seção de nível superior respaldada por uma inclusão de arquivo único, como plugins: { $include: "./plugins.json5" }, o OpenClaw atualiza esse arquivo incluído e mantém openclaw.json intacto
• Gravação propagada não compatível: inclusões na raiz, matrizes de inclusões e inclusões com substituições em chaves irmãs falham de forma segura nas gravações realizadas pelo OpenClaw, em vez de achatar a configuração
• Confinamento: os caminhos de $include devem ser resolvidos dentro do diretório que contém openclaw.json. Para compartilhar uma árvore entre máquinas ou usuários, defina OPENCLAW_INCLUDE_ROOTS como uma lista de caminhos (: no POSIX, ; no Windows) de diretórios adicionais que as inclusões podem referenciar. Links simbólicos são resolvidos e verificados novamente; portanto, um caminho que lexicalmente esteja em um diretório de configuração, mas cujo destino real saia de todas as raízes permitidas, ainda será rejeitado.
• Tratamento de erros: erros claros para arquivos ausentes, erros de análise, inclusões circulares, formato de caminho inválido e comprimento excessivo