Configuração

Cada canal tem sua própria seção de configuração em channels.<provider>. Consulte a página dedicada do canal para ver 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 principal 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.
• 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 a redução de escala de imagens de transcrição/ferramenta (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/auto-hospedados, 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 único para aprovação
• "allowlist": somente remetentes em allowFrom (ou no armazenamento de permissões pareado)
• "open": permite todas as DMs recebidas (requer allowFrom: ["*"])
• "disabled": ignora todas as DMs

Para grupos, use groupPolicy + groupAllowFrom ou listas de permissão 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 salas no caminho padrão da ferramenta de mensagens, 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 (toque para mencionar no WhatsApp, @bot no Telegram etc.)
• Padrões de texto: padrões regex seguros em mentionPatterns
• Respostas visíveis: messages.visibleReplies pode exigir envios pela ferramenta de mensagens 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 chat consigo mesmo.

Use agents.defaults.skills para uma 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 Skills.
• Consulte Skills, Configuração de Skills e a Referência de Configuração.

Controle a agressividade com que 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 desabilitar globalmente reinicializações pelo monitoramento de integridade.
• channelStaleEventThresholdMinutes deve ser maior que ou igual ao intervalo de verificação.
• Use channels.<provider>.healthMonitor.enabled ou channels.<provider>.accounts.<id>.healthMonitor.enabled para desabilitar reinicializações automáticas de um canal ou conta sem desabilitar o monitor global.
• Consulte Verificações de Integridade para depuração operacional e a referência completa para todos os campos.

Dê a clientes locais mais tempo para concluir o handshake WebSocket de 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 travamentos de inicialização/loop de eventos primeiro; este ajuste é para hosts que estão saudáveis, mas lentos durante o aquecimento.

Sessões controlam a continuidade e o isolamento da conversa:

{
  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ão vinculado a thread (Discord oferece suporte a /focus, /unfocus, /agents, /session idle e /session max-age).
• Consulte Gerenciamento de Sessões para escopo, links 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 npm, veja o comando docker build inline em Sandboxing § Imagens e configuração.

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

O push com suporte de 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, sinais de ativação e ativações 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 com suporte de relay à identidade do Gateway com a qual o app iOS foi pareado, para que outro Gateway não consiga reutilizar o registro armazenado.
• Mantém builds locais/manuais do iOS em APNs diretos. Envios com suporte de relay se aplicam apenas a builds oficiais distribuídos que se registraram pelo relay.
• Deve corresponder à URL base do relay incorporada ao build oficial/TestFlight do iOS, para que o tráfego de registro e envio chegue à 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 deixe as sessões de node e operador se conectarem.
4. O app iOS busca a identidade do Gateway, registra-se no relay usando App Attest mais o recibo do app e, em seguida, publica o payload push.apns.register com suporte de relay no Gateway pareado.
5. O Gateway armazena o identificador do relay e a concessão de envio e depois os usa para push.test, sinais de ativação e ativações 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ê publicar um novo build do 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 por env.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true continua sendo uma rota de escape de desenvolvimento apenas para 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 desativar.
• 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: remove sessões isoladas de execuções concluídas de sessions.json (padrão 24h; defina false para desativar).
• runLog: reduz cron/runs/<jobId>.jsonl por tamanho e linhas retidas.
• Consulte trabalhos Cron para a visão geral do recurso e exemplos de 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,
      },
    ],
  },
}

Observação de segurança:

• Trate todo o conteúdo de payload 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 usa apenas 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 as flags de bypass de conteúdo inseguro desativadas (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), exceto ao fazer depuração com escopo estrito.
• Se você ativar hooks.allowRequestSessionKey, também defina hooks.allowedSessionKeyPrefixes para delimitar chaves de sessão escolhidas pelo chamador.
• Para agentes acionados por hook, prefira camadas de modelo modernas e fortes e uma política de ferramentas estrita (por exemplo, apenas mensagens mais sandboxing quando possível).

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

Execute vários 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 Multiagente 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 contêiner
• Array de arquivos: mesclados profundamente em ordem (o posterior vence)
• Chaves irmãs: mescladas após includes (sobrescrevem valores incluídos)
• Includes aninhados: compatíveis com até 10 níveis de profundidade
• Caminhos relativos: resolvidos em relação ao arquivo que faz a inclusão
• Gravações pertencentes ao OpenClaw: quando uma gravação altera apenas uma seção de nível superior apoiada 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 sem suporte: includes na raiz, arrays de includes e includes com sobrescritas irmãs falham de modo fechado para gravações pertencentes ao OpenClaw, em vez de achatar a configuração
• Confinamento: caminhos $include devem resolver sob o 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, portanto 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