Configuração

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

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

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

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // only for allowlist/open    },  },}

Defina o modelo primário e 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 allowlist para /model; entradas provider/* filtram /model, /models e seletores de modelo para provedores selecionados, ainda usando descoberta dinâmica de modelos.
• Use openclaw config set agents.defaults.models '<json>' --strict-json --merge para adicionar entradas à allowlist sem remover modelos existentes. Substituições simples que removeriam entradas são rejeitadas, a menos que você passe --replace.
• Referências de modelo usam o formato provider/model (por exemplo, anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx controla o redimensionamento de imagens de transcrição/ferramentas (padrão 1200); valores menores geralmente reduzem o uso de tokens de visão em execuções com muitas capturas de tela.
• Consulte CLI de modelos para alternar modelos no chat e Failover de modelo para rotação de autenticação e comportamento de fallback.
• Para provedores personalizados/hospedados pelo próprio usuário, consulte Provedores personalizados na referência.

O acesso por DM é controlado por canal via dmPolicy:

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

Para grupos, use groupPolicy + groupAllowFrom ou allowlists específicas do canal.

Consulte a referência completa para detalhes por canal.

Mensagens de grupo, por padrão, exigem menção. Configure padrões de acionamento por agente e mantenha respostas visíveis em sala no caminho padrão de ferramenta de mensagem, a menos que você queira intencionalmente respostas finais automáticas legadas:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Menções de metadados: @-menções nativas (menção por toque do WhatsApp, @bot do Telegram etc.)
• Padrões de texto: padrões regex seguros em mentionPatterns
• Respostas visíveis: messages.visibleReplies pode exigir envios por ferramenta de mensagem globalmente; messages.groupChat.visibleReplies substitui isso para grupos/canais.
• Consulte a referência completa para modos de resposta visível, substituições por canal e modo de autochat.

Use agents.defaults.skills para uma linha de base compartilhada e, em seguida, substitua agentes específicos com agents.list[].skills:

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

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

Controle com que agressividade o gateway reinicia canais que parecem obsoletos:

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

• Defina gateway.channelHealthCheckMinutes: 0 para desativar reinicializações por monitoramento de integridade globalmente.
• 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 reinicializações automáticas para um canal ou conta sem desativar o monitor global.
• Consulte Verificações de integridade para depuração operacional e a referência completa para todos os campos.

Dê mais tempo para clientes locais concluírem o handshake WebSocket pré-autenticação em hosts carregados ou de baixa potência:

{  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 travamentos de inicialização/event loop; este controle é para hosts que estão saudáveis, mas lentos durante o aquecimento.

Sessões controlam continuidade e isolamento de conversas:

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    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 roteamento de sessões vinculadas a threads (Discord oferece suporte a /focus, /unfocus, /agents, /session idle e /session max-age).
• Consulte Gerenciamento de sessões para escopo, vínculos de identidade e política de envio.
• Consulte a referência completa para 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      },    },  },}

Crie a imagem primeiro: a partir de um checkout do código-fonte, execute scripts/sandbox-setup.sh; ou, a partir de uma instalação via npm, veja o comando docker build embutido em Sandboxing § Images and setup.

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

Push apoiado por relay é configurado em openclaw.json.

Defina isto na configuração do Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 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, toques de despertar e despertares de reconexão pelo relay externo.
• Usa uma concessão de envio com escopo de registro encaminhada pelo app iOS pareado. O Gateway não precisa de um token de relay para toda a implantação.
• Vincula cada registro apoiado por relay à identidade do Gateway com a qual o app iOS foi pareado, para que outro Gateway não possa reutilizar o registro armazenado.
• Mantém builds iOS locais/manuais em APNs direto. Envios apoiados por relay se aplicam apenas a builds oficiais distribuídos que se registraram pelo relay.
• Deve corresponder à URL base do relay embutida no build oficial/TestFlight do iOS, para que o tráfego de registro e envio alcance a mesma implantação de relay.

Fluxo de ponta a ponta:

1. Instale um build oficial/TestFlight do iOS que foi compilado com a mesma URL base do relay.
2. Configure gateway.push.apns.relay.baseUrl no Gateway.
3. Pareie o app iOS com o Gateway e permita que tanto as sessões de Node quanto as de operador se conectem.
4. O app iOS busca a identidade do Gateway, registra-se no relay usando App Attest mais o recibo do app e então publica a carga push.apns.register apoiada por relay no Gateway pareado.
5. O Gateway armazena o identificador do relay e a concessão de envio, depois os usa para push.test, toques de despertar e despertares de reconexão.

Observações operacionais:

• Se você alternar o app iOS para um Gateway diferente, reconecte o app para que ele possa publicar um novo registro de relay vinculado a esse Gateway.
• Se você distribuir um novo build iOS que aponta para uma implantação de relay diferente, o app atualiza seu registro de relay em cache em vez de reutilizar a origem de relay antiga.

Observação de compatibilidade:

• OPENCLAW_APNS_RELAY_BASE_URL e OPENCLAW_APNS_RELAY_TIMEOUT_MS ainda funcionam como substituições temporárias de ambiente.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true continua sendo uma saída de desenvolvimento somente para local loopback; não persista URLs de relay HTTP na configuração.

Consulte App iOS para o fluxo de ponta a ponta e Fluxo de autenticação e confiança para o modelo de segurança do relay.

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

• every: string de duração (30m, 2h). Defina 0m para desabilitar.
• 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 o guia completo.

{  cron: {    enabled: true,    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: remova sessões de execução isoladas concluídas de sessions.json (padrão 24h; defina false para desabilitar).
• runLog: remova cron/runs/<jobId>.jsonl por tamanho e linhas retidas.
• Consulte tarefas Cron para a visão geral do recurso e exemplos de CLI.

Habilite endpoints de Webhook HTTP 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,      },    ],  },}

Observação de segurança:

• Trate todo conteúdo de carga de hook/Webhook como entrada não confiável.
• Use um hooks.token dedicado; não reutilize o token compartilhado do Gateway.
• A autenticação de hook é somente por cabeçalho (Authorization: Bearer ... ou x-openclaw-token); tokens em query string são rejeitados.
• hooks.path não pode ser /; mantenha a entrada de Webhook em um subcaminho dedicado, como /hooks.
• Mantenha flags de bypass de conteúdo inseguro desabilitadas (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), exceto para depuração com escopo bem restrito.
• Se você habilitar hooks.allowRequestSessionKey, também defina hooks.allowedSessionKeyPrefixes para limitar chaves de sessão selecionadas pelo chamador.
• Para agentes acionados por hooks, prefira níveis de modelo modernos e fortes e política de ferramentas estrita (por exemplo, somente mensagens mais sandboxing quando possível).

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

Execute múltiplos agentes isolados com workspaces 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 Multi-Agent e a referência completa para regras de vinculação e 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
• Array de arquivos: mesclado profundamente em ordem (o posterior prevalece)
• Chaves irmãs: mescladas após includes (substituem valores incluídos)
• Includes aninhados: compatíveis até 10 níveis de profundidade
• Caminhos relativos: resolvidos em relação ao arquivo que inclui
• Escritas pertencentes ao OpenClaw: quando uma escrita altera apenas uma seção de nível superior respaldada por um include de arquivo único, como plugins: { $include: "./plugins.json5" }, o OpenClaw atualiza esse arquivo incluído e deixa openclaw.json intacto
• Write-through não compatível: includes raiz, arrays de include e includes com substituições irmãs falham de modo fechado para escritas pertencentes ao OpenClaw em vez de achatar a configuração
• Confinamento: caminhos $include devem resolver 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 includes podem referenciar. Symlinks são resolvidos e verificados novamente, então um caminho que lexicalmente fica em um diretório de configuração, mas cujo destino real escapa de toda raiz permitida, ainda é rejeitado.
• Tratamento de erros: erros claros para arquivos ausentes, erros de análise e includes circulares