Instradamento multi-agente

Esegui più agenti isolati in un unico processo Gateway, ciascuno con il proprio workspace, la propria directory di stato (agentDir) e la cronologia delle sessioni basata su SQLite, oltre a più account di canale (ad esempio, due numeri WhatsApp). I messaggi in entrata vengono instradati all'agente corretto tramite binding.

Un agente rappresenta l'intero ambito di ciascuna persona: file del workspace, profili di autenticazione, registro dei modelli e archivio delle sessioni. Un binding associa un account di canale (un workspace Slack, un numero WhatsApp e così via) a uno di questi agenti.

Che cos'è un agente

Ogni agente dispone dei propri:

• Workspace: file, AGENTS.md/SOUL.md/USER.md, note locali, regole della persona.
• Directory di stato (agentDir): profili di autenticazione, registro dei modelli, configurazione specifica dell'agente.
• Archivio delle sessioni: cronologia delle chat e stato di instradamento in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.

I profili di autenticazione sono specifici dell'agente e vengono letti da:

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

Le Skills vengono caricate dal workspace di ciascun agente e da radici condivise come ~/.openclaw/skills, quindi filtrate in base all'elenco di Skills consentite effettivo dell'agente. Usare agents.defaults.skills per una base condivisa e agents.list[].skills per una sostituzione specifica dell'agente (le voci esplicite sostituiscono quelle predefinite, non vengono unite). Consultare Skills: specifiche dell'agente e condivise e Skills: elenchi consentiti degli agenti.

L'archiviazione gestita da un Plugin segue la configurazione di tale Plugin; l'aggiunta di un secondo agente non suddivide automaticamente ogni archivio globale dei Plugin. Ad esempio, configurare i vault di Memory Wiki specifici dell'agente quando le persone non devono condividere le conoscenze wiki compilate.

Percorsi

Modalità con agente singolo (predefinita)

Se non viene configurato nulla, OpenClaw esegue un solo agente:

• agentId usa come valore predefinito main.
• Le sessioni usano la chiave agent:main:<mainKey> (il valore predefinito mainKey è main).
• Il workspace usa come valore predefinito ~/.openclaw/workspace (o workspace-<profile> quando OPENCLAW_PROFILE è impostato su un valore diverso da default).
• Lo stato usa come valore predefinito ~/.openclaw/agents/main/agent.

Assistente per gli agenti

Aggiungere un nuovo agente isolato:

openclaw agents add work

Opzioni: --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (ripetibile), --non-interactive (richiede --workspace).

Aggiungere bindings per instradare i messaggi in entrata (la procedura guidata propone di farlo automaticamente), quindi verificare:

openclaw agents list --bindings

Avvio rapido

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

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

Più agenti, più persone

Ogni agentId configurato costituisce un confine distinto della persona per lo stato principale dell'agente:

• Account diversi per canale (per accountId).
• Personalità diverse (tramite AGENTS.md/SOUL.md specifici dell'agente).
• Autenticazione e sessioni separate, con accesso tra agenti abilitato solo tramite funzionalità esplicite o la configurazione dei Plugin.

Ciò consente a più persone di condividere un unico Gateway mantenendo separato lo stato principale degli agenti.

Vault di Memory Wiki specifici dell'agente

Per impostazione predefinita, Memory Wiki utilizza un unico vault globale. Per mantenere le conoscenze compilate di un agente di supporto separate da quelle di un agente di marketing, impostare plugins.entries.memory-wiki.config.vault.scope su agent:

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

Il percorso configurato è la directory principale. OpenClaw aggiunge l'ID normalizzato dell'agente, producendo percorsi come ~/.openclaw/wiki/support e ~/.openclaw/wiki/marketing. Le operazioni CLI e Gateway con ambito agente richiedono un agente esplicito quando sono configurati più agenti. Consultare i vault di Memory Wiki specifici dell'agente per i dettagli su filtraggio del bridge, migrazione e confini di attendibilità.

Ricerca QMD nella memoria tra agenti

Per consentire a un agente di cercare nelle trascrizioni delle sessioni QMD di un altro agente, aggiungere raccolte supplementari in agents.list[].memorySearch.qmd.extraCollections. Usare agents.defaults.memorySearch.qmd.extraCollections quando tutti gli agenti devono condividere le stesse raccolte.

{  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" }], // viene risolto nel workspace -> raccolta denominata "notes-main"          },        },      },      { id: "family", workspace: "~/workspaces/family" },    ],  },  memory: {    backend: "qmd",    qmd: { includeDefaultMemory: false },  },}

Un percorso di una raccolta supplementare può essere condiviso tra gli agenti, ma il relativo name rimane esplicito quando il percorso si trova all'esterno del workspace dell'agente. I percorsi all'interno del workspace rimangono specifici dell'agente, in modo che ciascun agente mantenga il proprio insieme di ricerca delle trascrizioni.

Un numero WhatsApp, più persone (suddivisione dei messaggi diretti)

Instradare messaggi diretti WhatsApp diversi ad agenti diversi su un solo account WhatsApp associando il mittente E.164 (+15551234567) con peer.kind: "direct". Le risposte continuano a provenire dallo stesso numero WhatsApp: non esiste un'identità del mittente specifica dell'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"],    },  },}

Il controllo dell'accesso ai messaggi diretti (associazione/elenco consentito) è globale per ciascun account WhatsApp, non specifico dell'agente. Per i gruppi condivisi, associare il gruppo a un agente oppure usare i gruppi di trasmissione.

Regole di instradamento

I binding sono deterministici e prevale quello più specifico. Consultare Instradamento dei canali per l'ordine completo dei livelli (peer esatto, peer principale, carattere jolly del peer, gilda+ruoli, gilda, team, account, canale, agente predefinito). Alcune regole da evidenziare:

• Se più binding corrispondono nello stesso livello, prevale il primo nell'ordine di configurazione.
• Se un binding imposta più campi di corrispondenza (ad esempio peer + guildId), tutti i campi specificati devono corrispondere (semantica AND).
• Un binding che omette accountId corrisponde solo all'account predefinito, non a tutti gli account. Usare accountId: "*" come fallback per l'intero canale oppure accountId: "<name>" per un singolo account. Se si aggiunge nuovamente lo stesso binding con un ID account esplicito, il binding esistente relativo al solo canale viene aggiornato anziché duplicato.

Più account/numeri di telefono

I canali che supportano più account (ad esempio WhatsApp) usano accountId per identificare ciascun accesso. Ogni accountId viene instradato al proprio agente, consentendo a un unico server di ospitare più numeri di telefono senza mescolare le sessioni.

Impostare channels.<channel>.defaultAccount per scegliere l'account utilizzato quando accountId viene omesso. Se non è impostato, OpenClaw usa default se presente, altrimenti il primo ID account configurato (in ordine alfabetico).

Canali che supportano più account: discord, feishu, googlechat, imessage, irc, line, mattermost, matrix, nextcloud-talk, nostr, signal, slack, telegram, whatsapp, zalo, zalouser.

Concetti

• agentId: un "cervello" (spazio di lavoro, autenticazione per agente, archivio delle sessioni per agente).
• accountId: un'istanza di account del canale (ad esempio, account WhatsApp personal rispetto a biz).
• binding: instrada i messaggi in entrata a un agentId in base a (channel, accountId, peer) e, facoltativamente, agli ID di gilda/team.
• Le chat dirette vengono ricondotte a agent:<agentId>:<mainKey> (il valore "main" per agente; vedere session.mainKey).

Esempi per piattaforma

{  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",      },    ],  },   // Instradamento deterministico: prevale la prima corrispondenza (prima la più specifica).  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },     // Sostituzione facoltativa per interlocutore (esempio: inviare un gruppo specifico all'agente di lavoro).    {      agentId: "work",      match: {        channel: "whatsapp",        accountId: "personal",        peer: { kind: "group", id: "1203630...@g.us" },      },    },  ],   // Disattivata per impostazione predefinita: la messaggistica tra agenti deve essere abilitata esplicitamente e inserita nell'elenco degli elementi consentiti.  tools: {    agentToAgent: {      enabled: false,      allow: ["home", "work"],    },  },   channels: {    whatsapp: {      accounts: {        personal: {          // Sostituzione facoltativa. Valore predefinito: ~/.openclaw/credentials/whatsapp/personal          // authDir: "~/.openclaw/credentials/whatsapp/personal",        },        biz: {          // Sostituzione facoltativa. Valore predefinito: ~/.openclaw/credentials/whatsapp/biz          // authDir: "~/.openclaw/credentials/whatsapp/biz",        },      },    },  },}

Schemi comuni

{  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" },      },    },  ],}

Configurazione della sandbox e degli strumenti per agente

Ogni agente può avere restrizioni proprie per la sandbox e gli strumenti:

{  agents: {    list: [      {        id: "personal",        workspace: "~/.openclaw/workspace-personal",        sandbox: {          mode: "off",  // Nessuna sandbox per l'agente personale        },        // Nessuna restrizione degli strumenti: tutti gli strumenti sono disponibili      },      {        id: "family",        workspace: "~/.openclaw/workspace-family",        sandbox: {          mode: "all",     // Sempre in sandbox          scope: "agent",  // Un container per agente          docker: {            // Configurazione iniziale facoltativa eseguita una sola volta dopo la creazione del container            setupCommand: "apt-get update && apt-get install -y git curl",          },        },        tools: {          allow: ["read"],                    // Solo lo strumento di lettura          deny: ["exec", "write", "edit", "apply_patch"],    // Nega gli altri        },      },    ],  },}

Ciò offre:

• Isolamento di sicurezza: limita gli strumenti per gli agenti non attendibili.
• Controllo delle risorse: esegue in sandbox agenti specifici mantenendo gli altri sull'host.
• Criteri flessibili: autorizzazioni diverse per ciascun agente.

Per esempi dettagliati, vedere Sandbox e strumenti multi-agente.

Contenuti correlati

• Agenti ACP — esecuzione di harness di programmazione esterni
• Instradamento dei canali — modalità di instradamento dei messaggi agli agenti
• Presenza — presenza e disponibilità degli agenti
• Sessione — isolamento e instradamento delle sessioni
• Sottoagenti — avvio di esecuzioni di agenti in background