Configuration

Roteamento de canais

Canais e roteamento

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

Termos principais

Canal: um plugin de canal incluído, como discord, googlechat, imessage, irc, line, signal, slack, telegram ou whatsapp, além dos canais de plugins instalados. webchat é o canal interno da interface WebChat e não é um canal de saída configurável.
AccountId: instância de conta por canal (quando houver suporte).
Conta padrão opcional do canal: channels.<channel>.defaultAccount escolhe qual conta será usada quando um caminho de saída não especificar accountId.
- Em configurações com várias contas, defina explicitamente uma conta padrão (defaultAccount ou uma conta chamada default) quando houver duas ou mais contas configuradas. Sem isso, o roteamento de fallback poderá escolher o primeiro ID de conta normalizado.
AgentId: um espaço de trabalho isolado + armazenamento de sessões ("cérebro").
SessionKey: a chave do agrupador usada para armazenar contexto e controlar a concorrência.

Prefixos de destino de saída

Destinos de saída explícitos podem incluir um prefixo de provedor, como telegram:123 ou tg:123. O núcleo trata esse prefixo como uma indicação de seleção de canal apenas quando o canal selecionado é last ou ainda não foi resolvido, e somente quando o plugin carregado anuncia esse prefixo. Se o chamador já tiver selecionado um canal explícito, o prefixo do provedor deverá corresponder a esse canal; combinações entre canais, como entregar pelo WhatsApp para telegram:123, falham antes da normalização de destino específica do plugin.

Prefixos de tipo de destino e de serviço, como channel:<id>, user:<id>, room:<id>, thread:<id>, imessage:<handle> e sms:<number>, permanecem dentro da gramática do canal selecionado. Eles não selecionam o provedor por conta própria.

Formatos de chave de sessão (exemplos)

Por padrão, as mensagens diretas são consolidadas na sessão principal do agente:

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

session.dmScope controla a consolidação das MDs: main (padrão) compartilha uma única sessão principal, enquanto per-peer, per-channel-peer e per-account-channel-peer mantêm as MDs em sessões separadas. Uma vinculação de rota pode substituir o escopo para os pares correspondentes por meio de bindings[].session.dmScope.

Mesmo quando o histórico de conversas por mensagens diretas é compartilhado com a sessão principal, as políticas de sandbox e de ferramentas usam uma chave de runtime de conversa direta por conta derivada para MDs externas, para que mensagens originadas em canais não sejam tratadas como execuções locais da sessão principal.

Grupos e canais permanecem isolados por canal:

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

Tópicos:

Tópicos do Slack/Discord acrescentam :thread:<threadId> à chave base.
Tópicos de fórum do Telegram incorporam :topic:<topicId> à chave do grupo.

Exemplos:

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

Fixação da rota de MD principal

Quando session.dmScope é main, as mensagens diretas podem compartilhar uma única sessão principal. Para impedir que o lastRoute da sessão seja sobrescrito por MDs de usuários que não sejam o proprietário, o OpenClaw infere um proprietário fixado a partir de allowFrom quando todas estas condições são verdadeiras:

allowFrom contém exatamente uma entrada que não seja curinga.
A entrada pode ser normalizada para um ID de remetente concreto desse canal.
O remetente da MD recebida não corresponde ao proprietário fixado.

Nesse caso de incompatibilidade, o OpenClaw ainda registra os metadados da sessão recebida, mas não atualiza o lastRoute da sessão principal.

Registro protegido de mensagens recebidas

Plugins de canal podem marcar um registro de sessão recebida como createIfMissing: false quando um caminho protegido não deve criar uma nova sessão do OpenClaw. Nesse modo, o OpenClaw pode atualizar os metadados e o lastRoute de uma sessão existente, mas não cria uma entrada de sessão apenas para a rota simplesmente porque uma mensagem foi observada.

Regras de roteamento (como um agente é escolhido)

O roteamento seleciona um agente para cada mensagem recebida:

Correspondência exata de peer (bindings com peer.kind + peer.id).
Correspondência de peer pai (herança de thread).
Correspondência curinga de peer (peer.id: "*" para um tipo de peer).
Correspondência de guilda + funções (Discord) por meio de guildId + roles.
Correspondência de guilda (Discord) por meio de guildId.
Correspondência de equipe (Slack) por meio de teamId.
Correspondência de conta (accountId no canal).
Correspondência de canal (qualquer conta nesse canal, accountId: "*").
Agente padrão (agents.list[].default; caso contrário, a primeira entrada da lista, com fallback para main).

Quando uma vinculação inclui vários campos de correspondência (peer, guildId, teamId, roles), todos os campos fornecidos devem corresponder para que essa vinculação seja aplicada.

O agente correspondente determina quais workspace e armazenamento de sessões são usados.

Grupos de transmissão (executar vários agentes)

Os grupos de transmissão permitem executar vários agentes para o mesmo peer quando o OpenClaw normalmente responderia (por exemplo: em grupos do WhatsApp, após a verificação de menção/ativação).

Configuração:

json5

{  broadcast: {    strategy: "parallel",    "120363403215116621@g.us": ["alfred", "baerbel"],    "+15555550123": ["support", "logger"],  },}

Consulte: Grupos de transmissão.

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:

json5

{  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ões

As linhas de sessão em tempo de execução ficam no banco de dados SQLite de cada agente, no diretório de estado (padrão ~/.openclaw):

~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite

Instalações mais antigas podem ter arquivos JSONL legados de transcrições e um armazenamento de linhas sessions.json em ~/.openclaw/agents/<agentId>/sessions/. A inicialização do Gateway e openclaw doctor --fix importam automaticamente para o SQLite as linhas e o histórico legados em uso. Use openclaw doctor --session-sqlite inspect --session-sqlite-all-agents e a sequência de validação do Doctor quando precisar de evidências explícitas da migração. Ainda é possível selecionar um caminho de armazenamento legado por meio de session.store e da modelagem {agentId} para fluxos de trabalho de migração e manutenção offline.

A descoberta de sessões do Gateway e do ACP também verifica os armazenamentos de agentes em disco na raiz padrão agents/ e nas raízes modeladas de session.store. Os armazenamentos descobertos devem permanecer dentro dessa raiz de agente resolvida e usar um arquivo legado regular sessions.json. Links simbólicos e caminhos fora da raiz são ignorados.

Comportamento do WebChat

O WebChat se conecta ao agente selecionado e usa como padrão a sessão principal do agente. Por isso, o WebChat permite que você veja em um só lugar o contexto entre canais desse agente.

Contexto da resposta

As respostas recebidas incluem:

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

Isso é consistente em todos os canais.

Relacionado

Was this useful?