Enrutamiento multiagente

Ejecute varios agentes aislados en un proceso de Gateway, cada uno con su propio espacio de trabajo, directorio de estado (agentDir) e historial de sesiones respaldado por SQLite, además de varias cuentas de canales (por ejemplo, dos números de WhatsApp). Los mensajes entrantes se enrutan al agente correcto mediante vinculaciones.

Un agente es el ámbito completo de cada persona: archivos del espacio de trabajo, perfiles de autenticación, registro de modelos y almacén de sesiones. Una vinculación asigna una cuenta de canal (un espacio de trabajo de Slack, un número de WhatsApp, etc.) a uno de esos agentes.

Qué es un agente

Cada agente tiene sus propios elementos:

• Espacio de trabajo: archivos, AGENTS.md/SOUL.md/USER.md, notas locales y reglas de la persona.
• Directorio de estado (agentDir): perfiles de autenticación, registro de modelos y configuración por agente.
• Almacén de sesiones: historial de chat y estado de enrutamiento en ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.

Los perfiles de autenticación son específicos de cada agente y se leen desde:

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

Las Skills se cargan desde el espacio de trabajo de cada agente y desde raíces compartidas como ~/.openclaw/skills, y después se filtran mediante la lista efectiva de Skills permitidas para el agente. Use agents.defaults.skills como base compartida y agents.list[].skills como sustitución por agente (las entradas explícitas sustituyen el valor predeterminado; no se combinan). Consulte Skills: por agente frente a compartidas y Skills: listas permitidas de agentes.

El almacenamiento propiedad de un Plugin sigue la configuración de ese Plugin; añadir un segundo agente no divide automáticamente todos los almacenes globales de los Plugins. Por ejemplo, configure bóvedas de Memory Wiki por agente cuando las personas no deban compartir el conocimiento compilado de la wiki.

Rutas

Modo de un solo agente (predeterminado)

Si no configura nada, OpenClaw ejecuta un agente:

• El valor predeterminado de agentId es main.
• Las sesiones usan claves con el formato agent:main:<mainKey> (el valor predeterminado de mainKey es main).
• El espacio de trabajo predeterminado es ~/.openclaw/workspace (o workspace-<profile> cuando OPENCLAW_PROFILE se establece en un valor distinto de default).
• El estado predeterminado se encuentra en ~/.openclaw/agents/main/agent.

Asistente de agentes

Añada un nuevo agente aislado:

openclaw agents add work

Opciones: --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (se puede repetir), --non-interactive (requiere --workspace).

Añada bindings para enrutar los mensajes entrantes (el asistente ofrece hacerlo), y después verifique:

openclaw agents list --bindings

Inicio 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

Varios agentes, varias personas

Cada agentId configurado es un límite de persona distinto para el estado central del agente:

• Cuentas diferentes por canal (por accountId).
• Personalidades diferentes (AGENTS.md/SOUL.md por agente).
• Autenticación y sesiones independientes, con acceso entre agentes habilitado únicamente mediante funciones explícitas o la configuración de Plugins.

Esto permite que varias personas compartan un Gateway mientras se mantiene separado el estado central de los agentes.

Bóvedas de Memory Wiki por agente

Memory Wiki utiliza una bóveda global de forma predeterminada. Para mantener el conocimiento compilado de un agente de soporte separado del de un agente de marketing, establezca plugins.entries.memory-wiki.config.vault.scope en agent:

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

La ruta configurada es el directorio principal. OpenClaw añade el id normalizado del agente, lo que genera rutas como ~/.openclaw/wiki/support y ~/.openclaw/wiki/marketing. Las operaciones de la CLI y del Gateway con ámbito de agente requieren que se especifique un agente cuando hay varios agentes configurados. Consulte Bóvedas de Memory Wiki por agente para obtener detalles sobre el filtrado del puente, la migración y los límites de confianza.

Búsqueda de memoria QMD entre agentes

Para permitir que un agente busque en las transcripciones de sesiones QMD de otro agente, añada colecciones adicionales en agents.list[].memorySearch.qmd.extraCollections. Use agents.defaults.memorySearch.qmd.extraCollections cuando todos los agentes deban compartir las mismas colecciones.

{  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" }], // se resuelve dentro del espacio de trabajo -> colección denominada "notes-main"          },        },      },      { id: "family", workspace: "~/workspaces/family" },    ],  },  memory: {    backend: "qmd",    qmd: { includeDefaultMemory: false },  },}

Una ruta de colección adicional se puede compartir entre agentes, pero su name permanece explícito cuando la ruta está fuera del espacio de trabajo del agente. Las rutas dentro del espacio de trabajo conservan el ámbito del agente, de modo que cada agente mantiene su propio conjunto de búsqueda de transcripciones.

Un número de WhatsApp, varias personas (división de MD)

Enrute distintos MD de WhatsApp a distintos agentes en una cuenta de WhatsApp haciendo coincidir el remitente E.164 (+15551234567) con peer.kind: "direct". Las respuestas seguirán procediendo del mismo número de WhatsApp: no existe una identidad de remitente 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"],    },  },}

El control de acceso a los MD (emparejamiento/lista de permitidos) es global para cada cuenta de WhatsApp, no para cada agente. Para los grupos compartidos, vincule el grupo a un agente o use Grupos de difusión.

Reglas de enrutamiento

Las vinculaciones son deterministas y gana la más específica. Consulte Enrutamiento de canales para conocer el orden completo de niveles (par exacto, par principal, comodín de par, gremio+roles, gremio, equipo, cuenta, canal, agente predeterminado). Conviene destacar algunas reglas:

• Si varias vinculaciones coinciden dentro del mismo nivel, gana la primera según el orden de la configuración.
• Si una vinculación establece varios campos de coincidencia (por ejemplo, peer + guildId), todos los campos especificados deben coincidir (semántica AND).
• Una vinculación que omite accountId solo coincide con la cuenta predeterminada, no con todas las cuentas. Use accountId: "*" como alternativa para todo el canal o accountId: "<name>" para una cuenta. Si se vuelve a añadir la misma vinculación con un id de cuenta explícito, se actualiza la vinculación existente que solo especificaba el canal, en lugar de duplicarla.

Varias cuentas/números de teléfono

Los canales que admiten varias cuentas (por ejemplo, WhatsApp) usan accountId para identificar cada inicio de sesión. Cada accountId se enruta a su propio agente, por lo que un servidor puede alojar varios números de teléfono sin mezclar las sesiones.

Establezca channels.<channel>.defaultAccount para elegir la cuenta que se usa cuando se omite accountId. Si no se establece, OpenClaw utiliza default si está presente; de lo contrario, utiliza el primer id de cuenta configurado (ordenado).

Canales que admiten varias cuentas: discord, feishu, googlechat, imessage, irc, line, mattermost, matrix, nextcloud-talk, nostr, signal, slack, telegram, whatsapp, zalo, zalouser.

Conceptos

• agentId: un «cerebro» (espacio de trabajo, autenticación por agente, almacén de sesiones por agente).
• accountId: una instancia de cuenta de canal (p. ej., la cuenta de WhatsApp personal frente a biz).
• binding: dirige los mensajes entrantes a un agentId según (channel, accountId, peer) y, opcionalmente, los identificadores de servidor/equipo.
• Los chats directos se agrupan en agent:<agentId>:<mainKey> (la sesión «principal» de cada agente; consulte session.mainKey).

Ejemplos 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",      },    ],  },   // Enrutamiento determinista: gana la primera coincidencia (primero la más específica).  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },     // Sobrescritura opcional por interlocutor (ejemplo: enviar un grupo específico al agente de trabajo).    {      agentId: "work",      match: {        channel: "whatsapp",        accountId: "personal",        peer: { kind: "group", id: "1203630...@g.us" },      },    },  ],   // Desactivado de forma predeterminada: la mensajería entre agentes debe habilitarse explícitamente y añadirse a la lista de permitidos.  tools: {    agentToAgent: {      enabled: false,      allow: ["home", "work"],    },  },   channels: {    whatsapp: {      accounts: {        personal: {          // Sobrescritura opcional. Valor predeterminado: ~/.openclaw/credentials/whatsapp/personal          // authDir: "~/.openclaw/credentials/whatsapp/personal",        },        biz: {          // Sobrescritura opcional. Valor predeterminado: ~/.openclaw/credentials/whatsapp/biz          // authDir: "~/.openclaw/credentials/whatsapp/biz",        },      },    },  },}

Patrones habituales

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

Configuración del entorno aislado y las herramientas por agente

Cada agente puede tener sus propias restricciones de entorno aislado y herramientas:

{  agents: {    list: [      {        id: "personal",        workspace: "~/.openclaw/workspace-personal",        sandbox: {          mode: "off",  // Sin entorno aislado para el agente personal        },        // Sin restricciones de herramientas: todas las herramientas están disponibles      },      {        id: "family",        workspace: "~/.openclaw/workspace-family",        sandbox: {          mode: "all",     // Siempre en un entorno aislado          scope: "agent",  // Un contenedor por agente          docker: {            // Configuración inicial opcional tras crear el contenedor            setupCommand: "apt-get update && apt-get install -y git curl",          },        },        tools: {          allow: ["read"],                    // Solo la herramienta de lectura          deny: ["exec", "write", "edit", "apply_patch"],    // Denegar las demás        },      },    ],  },}

Esto proporciona:

• Aislamiento de seguridad: restrinja las herramientas de los agentes que no sean de confianza.
• Control de recursos: aísle agentes específicos mientras mantiene los demás en el host.
• Políticas flexibles: use permisos diferentes para cada agente.

Consulte Entorno aislado y herramientas para varios agentes para ver ejemplos detallados.

Temas relacionados

• Agentes ACP — ejecución de entornos externos de programación
• Enrutamiento de canales — cómo se dirigen los mensajes a los agentes
• Presencia — presencia y disponibilidad de los agentes
• Sesión — aislamiento y enrutamiento de sesiones
• Subagentes — inicio de ejecuciones de agentes en segundo plano