Canais e roteamento

O OpenClaw roteia respostas de volta ao canal de onde a mensagem veio. O modelo não escolhe um canal; o roteamento é determinístico e controlado pela configuração do host.

Termos-chave

• Canal: whatsapp, telegram, discord, slack, signal, imessage, webchat.
• AccountId: instância de conta por canal (quando suportado).
• Conta padrão opcional do canal: channels.<channel>.defaultAccount escolhe qual conta é usada quando um caminho de saída não especifica accountId.
  • Em configurações multi-conta, defina um padrão explícito (defaultAccount ou accounts.default) quando duas ou mais contas estiverem configuradas. Sem isso, o roteamento de fallback pode selecionar o primeiro ID de conta normalizado.
• AgentId: um workspace isolado + session store (“cérebro”).
• SessionKey: a chave de bucket usada para armazenar contexto e controlar concorrência.

Formatos de chave de sessão (exemplos)

Mensagens diretas se consolidam na sessão principal do agente:

• agent:<agentId>:<mainKey> (padrão: agent:main:main)

Grupos e canais permanecem isolados por canal:

• Grupos: agent:<agentId>:<channel>:group:<id>
• Canais/salas: agent:<agentId>:<channel>:channel:<id>

Threads:

• Threads de Slack/Discord adicionam :thread:<threadId> à chave base.
• Tópicos de fórum do Telegram embutem :topic:<topicId> na chave de grupo.

Exemplos:

• agent:main:telegram:group:-1001234567890:topic:42
• agent:main:discord:channel:123456:thread:987654

Fixação de rota de DM principal

Quando session.dmScope é main, mensagens diretas podem compartilhar uma sessão principal. Para evitar que o lastRoute da sessão seja sobrescrito por DMs de não-proprietários, o OpenClaw infere um proprietário fixo a partir de allowFrom quando todas estas condições são verdadeiras:

• allowFrom tem exatamente uma entrada não-curinga.
• A entrada pode ser normalizada para um ID concreto de remetente para aquele canal.
• O remetente da DM de entrada não corresponde àquele proprietário fixo.

Nesse caso de divergência, o OpenClaw ainda registra metadados de sessão de entrada, mas ignora a atualização do lastRoute da sessão principal.

Regras de roteamento (como um agente é escolhido)

O roteamento seleciona um agente para cada mensagem de entrada:

1. Correspondência exata de peer (bindings com peer.kind + peer.id).
2. Correspondência de peer pai (herança de thread).
3. Correspondência de guild + papéis (Discord) via guildId + roles.
4. Correspondência de guild (Discord) via guildId.
5. Correspondência de time (Slack) via teamId.
6. Correspondência de conta (accountId no canal).
7. Correspondência de canal (qualquer conta naquele canal, accountId: "*").
8. Agente padrão (agents.list[].default, senão primeira entrada da lista, fallback para main).

Quando um binding inclui múltiplos campos de correspondência (peer, guildId, teamId, roles), todos os campos fornecidos devem corresponder para que aquele binding se aplique.

O agente correspondido determina qual workspace e session store são usados.

Grupos de broadcast (executar múltiplos agentes)

Grupos de broadcast permitem executar múltiplos agentes para o mesmo peer quando o OpenClaw normalmente responderia (por exemplo: em grupos de WhatsApp, após gating de menção/ativação).

Configuração:

{
  broadcast: {
    strategy: "parallel",
    "[email protected]": ["alfred", "baerbel"],
    "+15555550123": ["support", "logger"],
  },
}

Veja: Grupos de Broadcast.

Visão geral da configuração

• agents.list: definições de agentes nomeados (workspace, modelo, etc.).
• bindings: mapeia canais/contas/peers de entrada para agentes.

Exemplo:

{
  agents: {
    list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
  },
  bindings: [
    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },
    { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
  ],
}

Armazenamento de sessão

Os session stores ficam no diretório de estado (padrão ~/.openclaw):

• ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Transcrições JSONL ficam ao lado do store

Você pode sobrescrever o caminho do store via session.store e template {agentId}.

A descoberta de sessão do gateway e ACP também examina stores de agente em disco sob a raiz padrão agents/ e sob raízes session.store com template. Stores descobertos devem permanecer dentro da raiz de agente resolvida e usar um arquivo regular sessions.json. Symlinks e caminhos fora da raiz são ignorados.

Comportamento do WebChat

O WebChat se conecta ao agente selecionado e aponta para a sessão principal do agente por padrão. Por isso, o WebChat permite ver o contexto entre canais daquele agente em um só lugar.

Contexto de resposta

Respostas de entrada incluem:

• ReplyToId, ReplyToBody e ReplyToSender quando disponíveis.
• O contexto citado é anexado ao Body como um bloco [Replying to ...].

Isso é consistente entre canais.