Enrutamiento multiagente

Ejecute varios agentes aislados en un único 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.entries.*.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 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 agente único (predeterminado)

Si no configura nada, OpenClaw ejecuta un agente:

• agentId tiene como valor predeterminado main.
• Las sesiones usan como clave agent:main:<mainKey> (el valor predeterminado de mainKey es main).
• El espacio de trabajo tiene como valor predeterminado ~/.openclaw/workspace (o workspace-<profile> cuando OPENCLAW_PROFILE se establece en un valor distinto de default).
• El estado tiene como valor predeterminado ~/.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]> (repetible), --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 constituye un límite de persona distinto para el estado principal del agente:

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

Esto permite que varias personas compartan un Gateway mientras mantienen separado el estado principal de cada agente.

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 superior. OpenClaw añade el identificador 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 un agente explícito cuando hay varios agentes configurados. Consulte Bóvedas de Memory Wiki por agente para obtener información 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.entries.*.memory.search.qmd.extraCollections. Use memory.search.qmd.extraCollections cuando todos los agentes deban compartir las mismas colecciones.

{  agents: {    defaults: {      workspace: "~/workspaces/main",    },    entries: {      main: {        workspace: "~/workspaces/main",        memory: {          search: {            qmd: {              extraCollections: [{ path: "notes" }], // se resuelve dentro del espacio de trabajo -> colección denominada "notes-main"            },          },        },      },      family: { workspace: "~/workspaces/family" },    },  },  memory: {    backend: "qmd",    search: {      qmd: {        extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],      },    },    qmd: { includeDefaultMemory: false },  },}

Una ruta de colección adicional puede compartirse 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 mantienen el ámbito del agente para que cada uno conserve su propio conjunto de búsqueda de transcripciones.

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

Enrute distintos mensajes directos de WhatsApp a distintos agentes en una cuenta de WhatsApp mediante la coincidencia del remitente E.164 (+15551234567) con peer.kind: "direct". Las respuestas siguen 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 mensajes directos (emparejamiento/lista permitida) es global para cada cuenta de WhatsApp, no para cada agente. Para 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 ver el orden completo de niveles (par exacto, par superior, comodín de par, servidor+roles, servidor, equipo, cuenta, canal, agente predeterminado). Conviene destacar aquí 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 de AND).
• Una vinculación que omite accountId coincide únicamente con la cuenta predeterminada, no con todas las cuentas. Use accountId: "*" como alternativa para todo el canal o accountId: "<name>" para una cuenta. Añadir de nuevo la misma vinculación con un identificador de cuenta explícito actualiza la vinculación existente exclusiva del 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 utilizada cuando se omite accountId. Si no se establece, OpenClaw recurre a 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 y 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 id. del gremio/equipo.
• Los chats directos se agrupan en agent:<agentId>:<mainKey> (la sesión «principal» por 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: prevalece la primera coincidencia (primero la más específica).  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },     // Reemplazo 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: {          // Reemplazo opcional. Valor predeterminado: ~/.openclaw/credentials/whatsapp/personal          // authDir: "~/.openclaw/credentials/whatsapp/personal",        },        biz: {          // Reemplazo 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 de 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 para 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: distintos permisos para cada agente.

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

Contenido relacionado

• Agentes ACP — ejecución de entornos externos de programación
• Enrutamiento de canales — cómo se enrutan 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