Roteamento multiagente

Execute vários agentes isolados em um único processo do Gateway, cada um com seu próprio workspace, diretório de estado (agentDir) e histórico de sessões armazenado em SQLite, além de várias contas de canal (por exemplo, dois números do WhatsApp). As mensagens recebidas são encaminhadas ao agente correto por meio de vinculações.

Um agente é o escopo completo por persona: arquivos do workspace, perfis de autenticação, registro de modelos e armazenamento de sessões. Uma vinculação mapeia uma conta de canal (um workspace do Slack, um número do WhatsApp etc.) para um desses agentes.

O que é um agente

Cada agente tem seu próprio:

• Workspace: arquivos, AGENTS.md/SOUL.md/USER.md, notas locais e regras da persona.
• Diretório de estado (agentDir): perfis de autenticação, registro de modelos e configuração por agente.
• Armazenamento de sessões: histórico de conversas e estado de roteamento em ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.

Os perfis de autenticação são específicos de cada agente e são lidos de:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

As Skills são carregadas do workspace de cada agente e de raízes compartilhadas, como ~/.openclaw/skills, e depois filtradas pela lista de permissões de Skills efetiva do agente. Use agents.defaults.skills para uma base compartilhada e agents.list[].skills para uma substituição por agente (entradas explícitas substituem o padrão; elas não são mescladas). Consulte Skills: por agente vs. compartilhadas e Skills: listas de permissões de agentes.

O armazenamento pertencente a um Plugin segue a configuração desse Plugin; adicionar um segundo agente não divide automaticamente todos os armazenamentos globais de Plugins. Por exemplo, configure cofres do Memory Wiki por agente quando as personas não puderem compartilhar o conhecimento compilado da wiki.

Caminhos

Modo de agente único (padrão)

Se você não configurar nada, o OpenClaw executará um agente:

• O padrão de agentId é main.
• As chaves das sessões seguem o formato agent:main:<mainKey> (o mainKey padrão é main).
• O workspace padrão é ~/.openclaw/workspace (ou workspace-<profile> quando OPENCLAW_PROFILE é definido como algo diferente de default).
• O estado padrão é ~/.openclaw/agents/main/agent.

Assistente de agentes

Adicione um novo agente isolado:

openclaw agents add work

Flags: --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (repetível), --non-interactive (requer --workspace).

Adicione bindings para encaminhar mensagens recebidas (o assistente oferece a opção de fazer isso por você) e depois verifique:

openclaw agents list --bindings

Início rápido

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

openclaw gateway restartopenclaw agents list --bindingsopenclaw channels status --probe

Vários agentes, várias personas

Cada agentId configurado é um limite de persona distinto para o estado principal do agente:

• Contas diferentes por canal (por accountId).
• Personalidades diferentes (AGENTS.md/SOUL.md por agente).
• Autenticação e sessões separadas, com acesso entre agentes habilitado apenas por meio de recursos explícitos ou da configuração de Plugins.

Isso permite que várias pessoas compartilhem um Gateway enquanto mantêm separado o estado principal dos agentes.

Cofres do Memory Wiki por agente

Por padrão, o Memory Wiki usa um único cofre global. Para manter o conhecimento compilado de um agente de suporte separado do conhecimento de um agente de marketing, defina plugins.entries.memory-wiki.config.vault.scope como agent:

{  plugins: {    entries: {      "memory-wiki": {        enabled: true,        config: {          vault: {            scope: "agent",            path: "~/.openclaw/wiki",          },        },      },    },  },}

O caminho configurado é o diretório pai. O OpenClaw acrescenta o id normalizado do agente, produzindo caminhos como ~/.openclaw/wiki/support e ~/.openclaw/wiki/marketing. Operações da CLI e do Gateway com escopo de agente exigem um agente explícito quando vários agentes estão configurados. Consulte cofres do Memory Wiki por agente para obter detalhes sobre filtragem da ponte, migração e limites de confiança.

Pesquisa de memória QMD entre agentes

Para permitir que um agente pesquise as transcrições de sessões QMD de outro agente, adicione coleções extras em agents.list[].memorySearch.qmd.extraCollections. Use agents.defaults.memorySearch.qmd.extraCollections quando todos os agentes precisarem compartilhar as mesmas coleções.

{  agents: {    defaults: {      workspace: "~/workspaces/main",      memorySearch: {        qmd: {          extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],        },      },    },    list: [      {        id: "main",        workspace: "~/workspaces/main",        memorySearch: {          qmd: {            extraCollections: [{ path: "notes" }], // resolvido dentro do workspace -> coleção chamada "notes-main"          },        },      },      { id: "family", workspace: "~/workspaces/family" },    ],  },  memory: {    backend: "qmd",    qmd: { includeDefaultMemory: false },  },}

Um caminho de coleção extra pode ser compartilhado entre agentes, mas seu name permanece explícito quando o caminho está fora do workspace do agente. Caminhos dentro do workspace permanecem com escopo de agente, para que cada agente mantenha seu próprio conjunto de pesquisa de transcrições.

Um número do WhatsApp, várias pessoas (divisão de MDs)

Encaminhe diferentes MDs do WhatsApp para diferentes agentes em uma única conta do WhatsApp, fazendo a correspondência do remetente E.164 (+15551234567) com peer.kind: "direct". As respostas ainda são enviadas pelo mesmo número do WhatsApp — não há uma identidade de remetente por agente.

{  agents: {    list: [      { id: "alex", workspace: "~/.openclaw/workspace-alex" },      { id: "mia", workspace: "~/.openclaw/workspace-mia" },    ],  },  bindings: [    {      agentId: "alex",      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } },    },    {      agentId: "mia",      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } },    },  ],  channels: {    whatsapp: {      dmPolicy: "allowlist",      allowFrom: ["+15551230001", "+15551230002"],    },  },}

O controle de acesso a MDs (pareamento/lista de permissões) é global por conta do WhatsApp, não por agente. Para grupos compartilhados, vincule o grupo a um agente ou use Grupos de transmissão.

Regras de roteamento

As vinculações são determinísticas, e a mais específica prevalece. Consulte Roteamento de canais para ver a ordem completa das camadas (par exato, par pai, curinga de par, guilda+funções, guilda, equipe, conta, canal, agente padrão). Algumas regras que merecem destaque:

• Se várias vinculações corresponderem na mesma camada, a primeira na ordem da configuração prevalecerá.
• Se uma vinculação definir vários campos de correspondência (por exemplo, peer + guildId), todos os campos especificados deverão corresponder (semântica AND).
• Uma vinculação que omite accountId corresponde apenas à conta padrão, não a todas as contas. Use accountId: "*" como fallback para todo o canal ou accountId: "<name>" para uma conta. Adicionar novamente a mesma vinculação com um id de conta explícito atualiza a vinculação existente exclusiva do canal, em vez de duplicá-la.

Várias contas/números de telefone

Os canais compatíveis com várias contas (por exemplo, WhatsApp) usam accountId para identificar cada login. Cada accountId é encaminhado ao seu próprio agente, permitindo que um servidor hospede vários números de telefone sem misturar sessões.

Defina channels.<channel>.defaultAccount para escolher a conta usada quando accountId for omitido. Quando essa opção não estiver definida, o OpenClaw usará default, se existir; caso contrário, usará o primeiro id de conta configurado (em ordem alfabética).

Canais compatíveis com várias contas: discord, feishu, googlechat, imessage, irc, line, mattermost, matrix, nextcloud-talk, nostr, signal, slack, telegram, whatsapp, zalo, zalouser.

Conceitos

• agentId: um "cérebro" (workspace, autenticação por agente, armazenamento de sessões por agente).
• accountId: uma instância de conta de canal (por exemplo, conta do WhatsApp personal versus biz).
• binding: encaminha mensagens recebidas para um agentId por (channel, accountId, peer) e, opcionalmente, por IDs de guilda/equipe.
• Conversas diretas são consolidadas em agent:<agentId>:<mainKey> (a sessão "principal" por agente; consulte session.mainKey).

Exemplos de plataformas

{  agents: {    list: [      { id: "main", workspace: "~/.openclaw/workspace-main" },      { id: "coding", workspace: "~/.openclaw/workspace-coding" },    ],  },  bindings: [    { agentId: "main", match: { channel: "discord", accountId: "default" } },    { agentId: "coding", match: { channel: "discord", accountId: "coding" } },  ],  channels: {    discord: {      groupPolicy: "allowlist",      accounts: {        default: {          token: "DISCORD_BOT_TOKEN_MAIN",          guilds: {            "123456789012345678": {              channels: {                "222222222222222222": { allow: true, requireMention: false },              },            },          },        },        coding: {          token: "DISCORD_BOT_TOKEN_CODING",          guilds: {            "123456789012345678": {              channels: {                "333333333333333333": { allow: true, requireMention: false },              },            },          },        },      },    },  },}

{  agents: {    list: [      { id: "main", workspace: "~/.openclaw/workspace-main" },      { id: "alerts", workspace: "~/.openclaw/workspace-alerts" },    ],  },  bindings: [    { agentId: "main", match: { channel: "telegram", accountId: "default" } },    { agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },  ],  channels: {    telegram: {      accounts: {        default: {          botToken: "123456:ABC...",          dmPolicy: "pairing",        },        alerts: {          botToken: "987654:XYZ...",          dmPolicy: "allowlist",          allowFrom: ["tg:123456789"],        },      },    },  },}

openclaw channels login --channel whatsapp --account personalopenclaw channels login --channel whatsapp --account biz

{  agents: {    list: [      {        id: "home",        default: true,        name: "Home",        workspace: "~/.openclaw/workspace-home",        agentDir: "~/.openclaw/agents/home/agent",      },      {        id: "work",        name: "Work",        workspace: "~/.openclaw/workspace-work",        agentDir: "~/.openclaw/agents/work/agent",      },    ],  },   // Encaminhamento determinístico: a primeira correspondência vence (a mais específica primeiro).  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },     // Substituição opcional por peer (exemplo: enviar um grupo específico ao agente de trabalho).    {      agentId: "work",      match: {        channel: "whatsapp",        accountId: "personal",        peer: { kind: "group", id: "1203630...@g.us" },      },    },  ],   // Desativado por padrão: as mensagens entre agentes devem ser habilitadas explicitamente e incluídas na lista de permissões.  tools: {    agentToAgent: {      enabled: false,      allow: ["home", "work"],    },  },   channels: {    whatsapp: {      accounts: {        personal: {          // Substituição opcional. Padrão: ~/.openclaw/credentials/whatsapp/personal          // authDir: "~/.openclaw/credentials/whatsapp/personal",        },        biz: {          // Substituição opcional. Padrão: ~/.openclaw/credentials/whatsapp/biz          // authDir: "~/.openclaw/credentials/whatsapp/biz",        },      },    },  },}

Padrões comuns

{  agents: {    list: [      {        id: "chat",        name: "Everyday",        workspace: "~/.openclaw/workspace-chat",        model: "anthropic/claude-sonnet-4-6",      },      {        id: "opus",        name: "Deep Work",        workspace: "~/.openclaw/workspace-opus",        model: "anthropic/claude-opus-4-6",      },    ],  },  bindings: [    { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } },    { agentId: "opus", match: { channel: "telegram", accountId: "*" } },  ],}

{  agents: {    list: [      {        id: "chat",        name: "Everyday",        workspace: "~/.openclaw/workspace-chat",        model: "anthropic/claude-sonnet-4-6",      },      {        id: "opus",        name: "Deep Work",        workspace: "~/.openclaw/workspace-opus",        model: "anthropic/claude-opus-4-6",      },    ],  },  bindings: [    {      agentId: "opus",      match: { channel: "whatsapp", accountId: "*", peer: { kind: "direct", id: "+15551234567" } },    },    { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } },  ],}

{  agents: {    list: [      {        id: "family",        name: "Family",        workspace: "~/.openclaw/workspace-family",        identity: { name: "Family Bot" },        groupChat: {          mentionPatterns: ["@family", "@familybot", "@Family Bot"],        },        sandbox: {          mode: "all",          scope: "agent",        },        tools: {          allow: [            "exec",            "read",            "sessions_list",            "sessions_history",            "sessions_send",            "sessions_spawn",            "session_status",          ],          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],        },      },    ],  },  bindings: [    {      agentId: "family",      match: {        channel: "whatsapp",        peer: { kind: "group", id: "120363999999999999@g.us" },      },    },  ],}

Configuração de sandbox e ferramentas por agente

Cada agente pode ter suas próprias restrições de sandbox e ferramentas:

{  agents: {    list: [      {        id: "personal",        workspace: "~/.openclaw/workspace-personal",        sandbox: {          mode: "off",  // Sem sandbox para o agente pessoal        },        // Sem restrições de ferramentas — todas as ferramentas estão disponíveis      },      {        id: "family",        workspace: "~/.openclaw/workspace-family",        sandbox: {          mode: "all",     // Sempre em sandbox          scope: "agent",  // Um contêiner por agente          docker: {            // Configuração inicial opcional, executada uma vez após a criação do contêiner            setupCommand: "apt-get update && apt-get install -y git curl",          },        },        tools: {          allow: ["read"],                    // Somente a ferramenta de leitura          deny: ["exec", "write", "edit", "apply_patch"],    // Bloqueia as demais        },      },    ],  },}

Isso oferece:

• Isolamento de segurança: restrinja ferramentas para agentes não confiáveis.
• Controle de recursos: execute agentes específicos em sandbox enquanto mantém os demais no host.
• Políticas flexíveis: permissões diferentes por agente.

Consulte Sandbox e ferramentas multiagente para ver exemplos detalhados.

Relacionados

• Agentes ACP — execução de ambientes externos de programação
• Encaminhamento de canais — como as mensagens são encaminhadas aos agentes
• Presença — presença e disponibilidade do agente
• Sessão — isolamento e encaminhamento de sessões
• Subagentes — criação de execuções de agentes em segundo plano