Configuração — canais

​

Canais

​

Acesso a DMs e grupos

​

Substituições de modelo por canal

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-5.5",
        "user:U12345": "openai/gpt-5.4-mini",
      },
      telegram: {
        "-1001234567890": "openai/gpt-5.4-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
        "123456789": "openai/gpt-4.1",
      },
    },
  },
}

​

Padrões de canal e Heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: política de grupo de fallback quando um groupPolicy no nível do provedor não está definido.
• channels.defaults.contextVisibility: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: all (padrão, inclui todo o contexto de citações/threads/histórico), allowlist (inclui apenas contexto de remetentes na allowlist), allowlist_quote (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: inclui status de canais saudáveis na saída do Heartbeat.
• channels.defaults.heartbeat.showAlerts: inclui status degradados/com erro na saída do Heartbeat.
• channels.defaults.heartbeat.useIndicator: renderiza saída compacta do Heartbeat em estilo de indicador.

​

WhatsApp

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    whatsapp: {
      keepAliveIntervalMs: 25000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

• Entradas bindings[] de nível superior com type: "acp" configuram vinculações ACP persistentes para DMs e grupos do WhatsApp. Use um número direto E.164 ou JID de grupo do WhatsApp em match.peer.id. A semântica dos campos é compartilhada em Agentes ACP.

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: partial)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      apiRoot: "https://api.telegram.org",
      trustedLocalFileRoots: ["/srv/telegram-bot-api-data"],
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Token do bot: channels.telegram.botToken ou channels.telegram.tokenFile (somente arquivo regular; symlinks rejeitados), com TELEGRAM_BOT_TOKEN como fallback para a conta padrão.
• apiRoot é apenas a raiz da API de Bot do Telegram. Use https://api.telegram.org ou sua raiz auto-hospedada/proxy, não https://api.telegram.org/bot<TOKEN>; openclaw doctor --fix remove um sufixo /bot<TOKEN> final acidental.
• Para um servidor de API de Bot auto-hospedado no modo --local, trustedLocalFileRoots lista caminhos de host que o OpenClaw pode ler. Monte o volume de dados do servidor no host do OpenClaw e configure a raiz de dados dele ou o diretório por token; caminhos de contêiner em /var/lib/telegram-bot-api são mapeados para essas raízes. Outros caminhos absolutos continuam rejeitados.
• O channels.telegram.defaultAccount opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
• Em configurações com várias contas (2+ IDs de conta), defina um padrão explícito (channels.telegram.defaultAccount ou channels.telegram.accounts.default) para evitar roteamento de fallback; openclaw doctor avisa quando isso está ausente ou inválido.
• configWrites: false bloqueia gravações de configuração iniciadas pelo Telegram (migrações de ID de supergrupo, /config set|unset).
• Entradas bindings[] de nível superior com type: "acp" configuram vinculações ACP persistentes para tópicos de fórum (use chatId:topic:topicId canônico em match.peer.id). A semântica dos campos é compartilhada em Agentes ACP.
• Pré-visualizações de stream do Telegram usam sendMessage + editMessageText (funciona em chats diretos e de grupo).
• Política de nova tentativa: consulte Política de nova tentativa.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      suppressEmbeds: true,
      chunkMode: "length", // length | newline
      streaming: {
        mode: "progress", // off | partial | block | progress (Discord default: progress)
        progress: {
          label: "auto",
          maxLines: 8,
          maxLineChars: 120,
          toolProgress: true,
        },
      },
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, com DISCORD_BOT_TOKEN como fallback para a conta padrão.
• Chamadas diretas de saída que fornecem um token explícito do Discord usam esse token para a chamada; as configurações de nova tentativa/política da conta ainda vêm da conta selecionada no snapshot de runtime ativo.
• O channels.discord.defaultAccount opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
• Use user:<id> (DM) ou channel:<id> (canal de guilda) para destinos de entrega; IDs numéricos sem prefixo são rejeitados.
• Slugs de guilda ficam em minúsculas com espaços substituídos por -; chaves de canal usam o nome em formato de slug (sem #). Prefira IDs de guilda.
• Mensagens criadas por bots são ignoradas por padrão. allowBots: true as habilita; use allowBots: "mentions" para aceitar apenas mensagens de bots que mencionem o bot (mensagens próprias continuam filtradas).
• Canais que dão suporte a mensagens de entrada criadas por bots podem usar a proteção contra loop de bot compartilhada. Defina channels.defaults.botLoopProtection para orçamentos básicos de pares e substitua o canal ou a conta apenas quando uma superfície precisar de limites diferentes.
• channels.discord.guilds.<id>.ignoreOtherMentions (e substituições de canal) descarta mensagens que mencionam outro usuário ou função, mas não o bot (excluindo @everyone/@here).
• channels.discord.mentionAliases mapeia texto @handle de saída estável para IDs de usuário do Discord antes do envio, para que colegas conhecidos possam ser mencionados de forma determinística mesmo quando o cache de diretório transitório estiver vazio. Substituições por conta ficam em channels.discord.accounts.<accountId>.mentionAliases.
• maxLinesPerMessage (padrão 17) divide mensagens altas mesmo quando estão abaixo de 2000 caracteres.
• channels.discord.suppressEmbeds usa true por padrão, então URLs de saída não se expandem em prévias de links do Discord a menos que isso seja desabilitado. Payloads embeds explícitos ainda são enviados normalmente; chamadas de ferramenta por mensagem podem substituir com suppressEmbeds.
• channels.discord.threadBindings controla o roteamento vinculado a threads do Discord:
  • enabled: substituição do Discord para recursos de sessão vinculada a thread (/focus, /unfocus, /agents, /session idle, /session max-age e entrega/roteamento vinculados)
  • idleHours: substituição do Discord para auto-unfocus por inatividade em horas (0 desabilita)
  • maxAgeHours: substituição do Discord para idade máxima rígida em horas (0 desabilita)
  • spawnSessions: alternador para sessions_spawn({ thread: true }) e criação/vinculação automática de thread por spawn de thread ACP (padrão: true)
  • defaultSpawnContext: contexto nativo de subagente para spawns vinculados a thread ("fork" por padrão)
• Entradas bindings[] de nível superior com type: "acp" configuram vinculações ACP persistentes para canais e threads (use o id de canal/thread em match.peer.id). A semântica dos campos é compartilhada em Agentes ACP.
• channels.discord.ui.components.accentColor define a cor de destaque para contêineres de componentes v2 do Discord.
• channels.discord.agentComponents.ttlMs controla por quanto tempo callbacks de componentes do Discord enviados permanecem registrados. O padrão é 1800000 (30 minutos), o máximo é 86400000 (24 horas), e substituições por conta ficam em channels.discord.accounts.<accountId>.agentComponents.ttlMs. Valores maiores mantêm botões/seletores/formulários antigos utilizáveis por mais tempo, então prefira o TTL mais curto que se encaixe no fluxo de trabalho.
• channels.discord.voice habilita conversas em canais de voz do Discord e substituições opcionais de entrada automática + LLM + TTS. Configurações do Discord somente de texto deixam voz desativada por padrão; defina channels.discord.voice.enabled=true para aderir.
• channels.discord.voice.model substitui opcionalmente o modelo LLM usado para respostas em canais de voz do Discord.
• channels.discord.voice.daveEncryption e channels.discord.voice.decryptionFailureTolerance são repassados para as opções DAVE de @discordjs/voice (true e 24 por padrão).
• channels.discord.voice.connectTimeoutMs controla a espera inicial de Ready do @discordjs/voice para tentativas de /vc join e entrada automática (30000 por padrão).
• channels.discord.voice.reconnectGraceMs controla quanto tempo uma sessão de voz desconectada pode levar para entrar em sinalização de reconexão antes que o OpenClaw a destrua (15000 por padrão).
• A reprodução de voz do Discord não é interrompida pelo evento de início de fala de outro usuário. Para evitar loops de feedback, o OpenClaw ignora nova captura de voz enquanto o TTS está em reprodução.
• O OpenClaw também tenta recuperar o recebimento de voz saindo e entrando novamente em uma sessão de voz após falhas repetidas de descriptografia.
• channels.discord.streaming é a chave canônica do modo de stream. O Discord usa streaming.mode: "progress" por padrão para que o progresso de ferramentas/trabalho apareça em uma mensagem de prévia editada; defina streaming.mode: "off" para desabilitá-lo. Valores legados de streamMode e streaming booleano permanecem como aliases de runtime; execute openclaw doctor --fix para reescrever a configuração persistida.
• channels.discord.autoPresence mapeia disponibilidade de runtime para presença do bot (saudável => online, degradado => ocioso, esgotado => dnd) e permite substituições opcionais de texto de status.
• channels.discord.dangerouslyAllowNameMatching reabilita correspondência mutável de nome/tag (modo de compatibilidade de emergência).
• channels.discord.execApprovals: entrega de aprovação de exec nativa do Discord e autorização de aprovadores.
  • enabled: true, false ou "auto" (padrão). No modo automático, aprovações de exec são ativadas quando aprovadores podem ser resolvidos de approvers ou commands.ownerAllowFrom.
  • approvers: IDs de usuário do Discord autorizados a aprovar solicitações de exec. Usa commands.ownerAllowFrom como fallback quando omitido.
  • agentFilter: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
  • sessionFilter: padrões opcionais de chave de sessão (substring ou regex).
  • target: para onde enviar prompts de aprovação. "dm" (padrão) envia para DMs dos aprovadores, "channel" envia para o canal de origem, "both" envia para ambos. Quando o destino inclui "channel", os botões só podem ser usados por aprovadores resolvidos.
  • cleanupAfterResolve: quando true, exclui DMs de aprovação após aprovação, negação ou timeout.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• JSON da conta de serviço: embutido (serviceAccount) ou baseado em arquivo (serviceAccountFile).
• SecretRef da conta de serviço também é compatível (serviceAccountRef).
• Fallbacks de env: GOOGLE_CHAT_SERVICE_ACCOUNT ou GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Use spaces/<spaceId> ou users/<userId> para destinos de entrega.
• channels.googlechat.dangerouslyAllowNameMatching reabilita correspondência mutável de principal de e-mail (modo de compatibilidade de emergência).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      socketMode: {
        clientPingTimeout: 15000,
        serverPingTimeout: 30000,
        pingPongLoggingEnabled: false,
      },
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      unfurlLinks: false,
      unfurlMedia: false,
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // use Slack native streaming API when mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Modo Socket exige botToken e appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN para fallback de env da conta padrão).
• Modo HTTP exige botToken mais signingSecret (na raiz ou por conta).
• socketMode repassa o ajuste de transporte Socket Mode do Slack SDK para a API pública do receptor Bolt. Use-o apenas ao investigar timeout de ping/pong ou comportamento de websocket obsoleto. clientPingTimeout usa 15000 por padrão; serverPingTimeout e pingPongLoggingEnabled são repassados somente quando configurados.
• botToken, appToken, signingSecret e userToken aceitam strings de texto simples ou objetos SecretRef.
• Snapshots de conta do Slack expõem campos de origem/status por credencial, como botTokenSource, botTokenStatus, appTokenStatus e, no modo HTTP, signingSecretStatus. configured_unavailable significa que a conta está configurada por SecretRef, mas o caminho de comando/runtime atual não conseguiu resolver o valor do segredo.
• configWrites: false bloqueia gravações de configuração iniciadas pelo Slack.
• channels.slack.defaultAccount opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
• channels.slack.streaming.mode é a chave canônica do modo de stream do Slack. channels.slack.streaming.nativeTransport controla o transporte de streaming nativo do Slack. Valores legados streamMode, booleano streaming e nativeStreaming continuam como aliases de runtime; execute openclaw doctor --fix para reescrever a configuração persistida.
• unfurlLinks e unfurlMedia repassam os booleanos de expansão de links e mídia do chat.postMessage do Slack para respostas do bot. unfurlLinks usa false por padrão para que links de saída do bot não sejam expandidos inline, a menos que isso seja habilitado; unfurlMedia é omitido, a menos que seja configurado. Defina qualquer um dos valores em channels.slack.accounts.<accountId> para substituir o valor de nível superior de uma conta.
• Use user:<id> (DM) ou channel:<id> para destinos de entrega.

• O streaming nativo do Slack mais o status de thread “is typing…” no estilo assistente do Slack exigem um destino de thread de resposta. DMs de nível superior permanecem fora de thread por padrão, então ainda podem fazer stream por meio de prévias de rascunho publicar-e-editar do Slack, em vez de mostrar a prévia nativa de stream/status no estilo thread.
• typingReaction adiciona uma reação temporária à mensagem de entrada do Slack enquanto uma resposta está em execução, depois a remove na conclusão. Use um shortcode de emoji do Slack, como "hourglass_flowing_sand".
• channels.slack.execApprovals: entrega de cliente de aprovação nativa do Slack e autorização de aprovador de exec. Mesmo esquema do Discord: enabled (true/false/"auto"), approvers (IDs de usuário do Slack), agentFilter, sessionFilter e target ("dm", "channel" ou "both"). Aprovações de Plugin podem usar este caminho de cliente nativo para solicitações originadas no Slack quando os aprovadores do Plugin do Slack forem resolvidos; a entrega de aprovação de Plugin nativa do Slack também pode ser habilitada por meio de approvals.plugin para sessões originadas no Slack ou destinos Slack. Aprovações de Plugin usam aprovadores do Plugin do Slack de allowFrom e roteamento padrão, não aprovadores de exec.

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath deve ser um caminho (por exemplo, /api/channels/mattermost/command), não uma URL completa.
• commands.callbackUrl deve resolver para o endpoint do Gateway do OpenClaw e ser acessível a partir do servidor Mattermost.
• Callbacks slash nativos são autenticados com os tokens por comando retornados pelo Mattermost durante o registro de comando slash. Se o registro falhar ou nenhum comando for ativado, o OpenClaw rejeita callbacks com Unauthorized: invalid command token.
• Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que ServiceSettings.AllowedUntrustedInternalConnections inclua o host/domínio de callback. Use valores de host/domínio, não URLs completas.
• channels.mattermost.configWrites: permite ou nega gravações de configuração iniciadas pelo Mattermost.
• channels.mattermost.requireMention: exige @mention antes de responder em canais.
• channels.mattermost.groups.<channelId>.requireMention: substituição por canal do gate por menção ("*" para o padrão).
• channels.mattermost.defaultAccount opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account: fixa a inicialização do canal em uma identidade de conta específica do Signal.
• channels.signal.configWrites: permite ou nega gravações de configuração iniciadas pelo Signal.
• channels.signal.defaultAccount opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      sendTransport: "auto",
      region: "US",
      actions: {
        reactions: true,
        edit: true,
        unsend: true,
        reply: true,
        sendWithEffect: true,
        sendAttachment: true,
      },
    },
  },
}

• channels.imessage.defaultAccount opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
• Exige Acesso Total ao Disco ao DB do Mensagens.
• Prefira destinos chat_id:<id>. Use imsg chats --limit 20 para listar chats.
• cliPath pode apontar para um wrapper SSH; defina remoteHost (host ou user@host) para buscar anexos por SCP.
• attachmentRoots e remoteAttachmentRoots restringem caminhos de anexos de entrada (padrão: /Users/*/Library/Messages/Attachments).
• SCP usa verificação estrita de chave de host, então garanta que a chave do host de relay já exista em ~/.ssh/known_hosts.
• channels.imessage.configWrites: permite ou nega gravações de configuração iniciadas pelo iMessage.
• channels.imessage.sendTransport: transporte preferencial de envio RPC do imsg para respostas normais de saída. auto (padrão) usa a ponte IMCore para chats existentes quando ela está em execução, depois faz fallback para AppleScript; bridge exige entrega por API privada; applescript força o caminho público de automação do Mensagens.
• channels.imessage.actions.*: habilita ações de API privada que também são controladas por gate por imsg status / openclaw channels status --probe.
• channels.imessage.includeAttachments fica desativado por padrão; defina como true antes de esperar mídia de entrada em turnos de agente.
• A recuperação de entrada após uma reinicialização de ponte/gateway é automática (dedupe por GUID mais uma cerca de idade de backlog obsoleto). Configurações channels.imessage.catchup.enabled: true existentes ainda são respeitadas como um perfil de compatibilidade obsoleto.
• channels.imessage.groups: registro de grupos e configurações por grupo. Com groupPolicy: "allowlist", configure chaves chat_id explícitas ou uma entrada curinga "*" para que mensagens de grupo possam passar pelo gate do registro.
• Entradas bindings[] de nível superior com type: "acp" podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou destino de chat explícito (chat_id:*, chat_guid:*, chat_identifier:*) em match.peer.id. Semântica de campos compartilhados: Agentes ACP.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• A autenticação por token usa accessToken; a autenticação por senha usa userId + password.
• channels.matrix.proxy roteia o tráfego HTTP do Matrix por um proxy HTTP(S) explícito. Contas nomeadas podem sobrescrevê-lo com channels.matrix.accounts.<id>.proxy.
• channels.matrix.network.dangerouslyAllowPrivateNetwork permite homeservers privados/internos. proxy e essa adesão de rede são controles independentes.
• channels.matrix.defaultAccount seleciona a conta preferencial em configurações com várias contas.
• channels.matrix.autoJoin usa off por padrão, então salas convidadas e novos convites no estilo DM são ignorados até você definir autoJoin: "allowlist" com autoJoinAllowlist ou autoJoin: "always".
• channels.matrix.execApprovals: entrega de aprovações de exec nativa do Matrix e autorização de aprovadores.
  • enabled: true, false ou "auto" (padrão). No modo automático, aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de approvers ou commands.ownerAllowFrom.
  • approvers: IDs de usuário do Matrix (por exemplo, @owner:example.org) autorizados a aprovar solicitações de exec.
  • agentFilter: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
  • sessionFilter: padrões opcionais de chave de sessão (substring ou regex).
  • target: para onde enviar prompts de aprovação. "dm" (padrão), "channel" (sala de origem) ou "both".
  • Sobrescritas por conta: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope controla como DMs do Matrix são agrupadas em sessões: per-user (padrão) compartilha por par roteado, enquanto per-room isola cada sala de DM.
• Sondagens de status do Matrix e consultas de diretório ao vivo usam a mesma política de proxy do tráfego em tempo de execução.
• A configuração completa do Matrix, as regras de direcionamento e os exemplos de configuração estão documentados em Matrix.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, políticas de equipe/canal:
      // veja /channels/msteams
    },
  },
}

• Caminhos de chave principais cobertos aqui: channels.msteams, channels.msteams.configWrites.
• A configuração completa do Teams (credenciais, Webhook, política de DM/grupo, sobrescritas por equipe/por canal) está documentada em Microsoft Teams.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• Caminhos de chave principais cobertos aqui: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• channels.irc.defaultAccount opcional sobrescreve a seleção da conta padrão quando corresponde a um ID de conta configurado.
• A configuração completa do canal IRC (host/porta/TLS/canais/allowlists/bloqueio por menção) está documentada em IRC.

​

Várias contas (todos os canais)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Bot principal",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Bot de alertas",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default é usado quando accountId é omitido (CLI + roteamento).
• Tokens de env se aplicam apenas à conta padrão.
• As configurações base do canal se aplicam a todas as contas, a menos que sejam sobrescritas por conta.
• Use bindings[].match.accountId para rotear cada conta para um agente diferente.
• Se você adicionar uma conta não padrão via openclaw channels add (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de nível superior com conta única, o OpenClaw primeiro promove valores de conta única de nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para channels.<channel>.accounts.default; o Matrix pode preservar um destino nomeado/padrão correspondente existente.
• Bindings existentes somente de canal (sem accountId) continuam correspondendo à conta padrão; bindings com escopo de conta continuam opcionais.
• openclaw doctor --fix também repara formatos mistos movendo valores de conta única de nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa accounts.default; o Matrix pode preservar um destino nomeado/padrão correspondente existente.

​

Outros canais de Plugin

​

Bloqueio por menção em chats em grupo

• Menções de metadados: @menções nativas da plataforma. Ignoradas no modo de autochat do WhatsApp.
• Padrões de texto: padrões regex seguros em agents.list[].groupChat.mentionPatterns. Padrões inválidos e repetição aninhada insegura são ignorados.
• O bloqueio por menção é aplicado somente quando a detecção é possível (menções nativas ou pelo menos um padrão).

{
  messages: {
    visibleReplies: "automatic", // força respostas finais automáticas antigas para chats diretos/de origem
    groupChat: {
      historyLimit: 50,
      unmentionedInbound: "room_event", // conversa de sala sem menção e sempre ativa vira contexto silencioso
      visibleReplies: "message_tool", // opt-in; exige message(action=send) para respostas visíveis na sala
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

Limites de histórico de DM

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

Modo de autochat

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["responde", "@openclaw"] },
      },
    ],
  },
}

​

Comandos (tratamento de comandos de chat)

{
  commands: {
    native: "auto", // registra comandos nativos quando compatível
    nativeSkills: "auto", // registra comandos nativos de skill quando compatível
    text: true, // analisa /commands em mensagens de chat
    bash: false, // permite ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // permite /config
    mcp: false, // permite /mcp
    plugins: false, // permite /plugins
    debug: false, // permite /debug
    restart: true, // permite /restart + ferramenta de reinício do gateway
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

Relacionado

• Referência de configuração — chaves de nível superior
• Configuração — agentes
• Visão geral dos canais