Enrutamiento multiagente

Ejecuta múltiples agentes aislados — cada uno con su propio espacio de trabajo, directorio de estado (agentDir) e historial de sesión — además de múltiples cuentas de canal (ej. dos WhatsApps) en una sola Gateway en ejecución. Los mensajes entrantes se enrutan al agente correcto a través de enlaces.

Un agente aquí es el alcance completo por personalidad: archivos del espacio de trabajo, perfiles de autenticación, registro de modelos y almacén de sesiones. agentDir es el directorio de estado en disco que mantiene esta configuración por agente en ~/.openclaw/agents/<agentId>/. Un enlace asigna una cuenta de canal (ej. un espacio de trabajo de Slack o un número de WhatsApp) a uno de esos agentes.

¿Qué es “un agente”?

Un agente es un cerebro con alcance completo con su propio:

Espacio de trabajo (archivos, AGENTS.md/SOUL.md/USER.md, notas locales, reglas de personalidad).
Directorio de estado (agentDir) para perfiles de autenticación, registro de modelos y configuración por agente.
Almacén de sesiones (historial de chat + estado de enrutamiento) bajo ~/.openclaw/agents/<agentId>/sessions.

Los perfiles de autenticación son por agente. Cada agente lee de su propio:

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

Las habilidades se cargan desde el espacio de trabajo de cada agente más las raíces compartidas como ~/.openclaw/skills, y luego se filtran por la lista de permitidos de habilidades del agente efectivo cuando está configurado. Usa agents.defaults.skills para una base compartida y agents.list[].skills para el reemplazo por agente. Consulta Skills: per-agent vs shared y Skills: agent skill allowlists.

El Gateway puede alojar un agente (predeterminado) o muchos agentes simultáneamente.

Rutas (mapa rápido)

Configuración: ~/.openclaw/openclaw.json (o OPENCLAW_CONFIG_PATH)
Directorio de estado: ~/.openclaw (o OPENCLAW_STATE_DIR)
Espacio de trabajo: ~/.openclaw/workspace (o ~/.openclaw/workspace-<agentId>)
Directorio del agente: ~/.openclaw/agents/<agentId>/agent (o agents.list[].agentDir)
Sesiones: ~/.openclaw/agents/<agentId>/sessions

Modo de agente único (predeterminado)

Si no haces nada, OpenClaw ejecuta un solo agente:

agentId por defecto es main.
Las sesiones se clavean como agent:main:<mainKey>.
El espacio de trabajo por defecto es ~/.openclaw/workspace (o ~/.openclaw/workspace-<profile> cuando se establece OPENCLAW_PROFILE).
El estado por defecto es ~/.openclaw/agents/main/agent.

Asistente de agente

Usa el asistente de agente para agregar un nuevo agente aislado:

openclaw agents add work

Luego agrega bindings (o deja que el asistente lo haga) para enrutar los mensajes entrantes.

Verifica con:

openclaw agents list --bindings

Inicio rápido

Crear cada espacio de trabajo del agente
Use el asistente o cree los espacios de trabajo manualmente:
Ventana de terminal
```
openclaw agents add coding
openclaw agents add social
```
Cada agente obtiene su propio espacio de trabajo con SOUL.md, AGENTS.md y USER.md opcionales, además de un agentDir dedicado y un almacén de sesiones bajo `~/.openclaw/agents/
`.
Crear cuentas de canal
Crea una cuenta por agente en tus canales preferidos:
- Discord: un bot por agente, habilita Message Content Intent, copia cada token.
- Telegram: un bot por agente a través de BotFather, copia cada token.
- WhatsApp: vincula cada número de teléfono por cuenta.
Ventana de terminal
```
openclaw channels login --channel whatsapp --account work
```
Consulta las guías de canales: Discord, Telegram, WhatsApp.
Añadir agentes, cuentas y enlaces
Añada agentes en agents.list, cuentas de canal en `channels.
.accountsy conéctelos conbindings` (ejemplos a continuación).

Reiniciar y verificar

openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

Múltiples agentes = múltiples personas, múltiples personalidades

Con múltiples agentes, cada agentId se convierte en una personalidad totalmente aislada:

Diferentes números de teléfono/cuentas (por accountId de canal).
Diferentes personalidades (archivos de espacio de trabajo por agente como AGENTS.md y SOUL.md).
Autenticación y sesiones separadas (sin interferencias a menos que se habiliten explícitamente).

Esto permite que múltiples personas compartan un servidor Gateway mientras mantienen sus “cerebros” de IA y datos aislados.

Búsqueda de memoria QMD entre agentes

Si un agente debe buscar las transcripciones de sesión QMD de otro agente, añada colecciones adicionales bajo agents.list[].memorySearch.qmd.extraCollections. Use agents.defaults.memorySearch.qmd.extraCollections solo cuando cada agente deba heredar las mismas colecciones de transcripciones compartidas.

{
  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" }], // resolves inside workspace -> collection named "notes-main"
          },
        },
      },
      { id: "family", workspace: "~/workspaces/family" },
    ],
  },
  memory: {
    backend: "qmd",
    qmd: { includeDefaultMemory: false },
  },
}

La ruta de colección adicional se puede compartir entre agentes, pero el nombre de la colección se mantiene explícito cuando la ruta está fuera del espacio de trabajo del agente. Las rutas dentro del espacio de trabajo permanecen con ámbito de agente para que cada agente mantenga su propio conjunto de búsqueda de transcripciones.

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

Puede enrutar diferentes MD de WhatsApp a diferentes agentes mientras permanece en una cuenta de WhatsApp. Coincida con el E.164 del remitente (como +15551234567) con peer.kind: "direct". Las respuestas aún provienen del mismo número de WhatsApp (sin identidad de remitente por agente).

Ejemplo:

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

Notas:

El control de acceso de MD es global por cuenta de WhatsApp (vinculación/lista de permitidos), no por agente.
Para grupos compartidos, vincula el grupo a un agente o usa Broadcast groups.

Reglas de enrutamiento (cómo los mensajes eligen un agente)

Las vinculaciones son deterministas y gana la más específica:

peer match
Id. de MD/grupo/canal exacto.
parentPeer match
Herencia de hilos.
guildId + roles
Enrutamiento por roles de Discord.
guildId
Discord.
teamId
Slack.
accountId match for a channel
Reserva por cuenta.
Channel-level match
accountId: "*".
Default agent
Reserva a agents.list[].default, si no, la primera entrada de la lista, por defecto: main.

Desempate y semántica AND

Si varias vinculaciones coinciden en el mismo nivel, gana la primera en el orden de configuración.
Si una vinculación establece varios campos de coincidencia (por ejemplo peer + guildId), se requieren todos los campos especificados (semántica AND).

Account-scope detail

Un enlace que omite accountId coincide solo con la cuenta predeterminada.
Use accountId: "*" para un respaldo en todo el canal a través de todas las cuentas.
Si más tarde agrega el mismo enlace para el mismo agente con una identificación de cuenta explícita, OpenClaw actualiza el enlace existente de solo canal a nivel de cuenta en lugar de duplicarlo.

Múltiples cuentas / números de teléfono

Los canales que soportan múltiples cuentas (por ejemplo, WhatsApp) usan accountId para identificar cada inicio de sesión. Cada accountId puede ser enrutado a un agente diferente, por lo que un servidor puede alojar múltiples números de teléfono sin mezclar sesiones.

Si desea una cuenta predeterminada para todo el canal cuando se omite accountId, establezca channels.<channel>.defaultAccount (opcional). Cuando no está configurado, OpenClaw recurre a default si está presente; de lo contrario, a la primera identificación de cuenta configurada (ordenada).

Los canales comunes que soportan este patrón incluyen:

whatsapp, telegram, discord, slack, signal, imessage
irc, line, googlechat, mattermost, matrix, nextcloud-talk
zalo, zalouser, nostr, feishu

Conceptos

agentId: un “cerebro” (espacio de trabajo, autenticación por agente, almacenamiento de sesión por agente).
accountId: una instancia de cuenta de canal (p. ej., cuenta de WhatsApp "personal" vs "biz").
binding: enruta los mensajes entrantes a un agentId por (channel, accountId, peer) e opcionalmente identificaciones de gremio/equipo.
Los chats directos se colapsan en agent:<agentId>:<mainKey> (“principal” por agente; session.mainKey).

Ejemplos de plataformas

Discord bots per agent

Cada cuenta de bot de Discord se asigna a un accountId único. Vincule cada cuenta a un agente y mantenga listas de permitidos por bot.

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

Invite cada bot al gremio y habilite la intención de contenido de mensaje (Message Content Intent).
Los tokens viven en `channels.discord.accounts.

.token(la cuenta predeterminada puede usarDISCORD_BOT_TOKEN`).

Telegram bots per agent

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

Cree un bot por agente con BotFather y copie cada token.
Los tokens viven en `channels.telegram.accounts.

.botToken(la cuenta predeterminada puede usarTELEGRAM_BOT_TOKEN`).

WhatsApp numbers per agent

Vincule cada cuenta antes de iniciar la puerta de enlace:

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

~/.openclaw/openclaw.json (JSON5):

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

  // Deterministic routing: first match wins (most-specific first).
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

    // Optional per-peer override (example: send a specific group to work agent).
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "[email protected]" },
      },
    },
  ],

  // Off by default: agent-to-agent messaging must be explicitly enabled + allowlisted.
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // Optional override. Default: ~/.openclaw/credentials/whatsapp/personal
          // authDir: "~/.openclaw/credentials/whatsapp/personal",
        },
        biz: {
          // Optional override. Default: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

Patrones comunes

Dividir por canal: enruta WhatsApp a un agente rápido para el día a día y Telegram a un agente Opus.

{
  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" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

Notas:

Si tienes varias cuentas para un canal, añade accountId al enlace (por ejemplo { channel: "whatsapp", accountId: "personal" }).
Para enrutar un solo DM/grupo a Opus manteniendo el resto en el chat, añade un enlace match.peer para ese par; las coincidencias de pares siempre tienen prioridad sobre las reglas de todo el canal.

Mantén WhatsApp en el agente rápido, pero enruta un MD a Opus:

{
  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", peer: { kind: "direct", id: "+15551234567" } },
    },
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}

Las vinculaciones de pares (peer) siempre ganan, así que manténelas por encima de la regla de todo el canal.

Vincula un agente familiar dedicado a un solo grupo de WhatsApp, con filtrado de menciones y una política de herramientas más estricta:

{
  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: "[email protected]" },
      },
    },
  ],
}

Notas:

Las listas de permitidos/denegados de herramientas son herramientas, no habilidades. Si una habilidad necesita ejecutar un binario, asegúrate de que exec esté permitido y de que el binario exista en el sandbox.
Para un filtrado más estricto, establece agents.list[].groupChat.mentionPatterns y mantén las listas de permitidos de grupos habilitadas para el canal.

Configuración de sandbox y herramientas por agente

Cada agente puede tener su propio sandbox y restricciones de herramientas:

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // Always sandboxed
          scope: "agent",  // One container per agent
          docker: {
            // Optional one-time setup after container creation
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // Only read tool
          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
        },
      },
    ],
  },
}

Beneficios:

Aislamiento de seguridad: restringir herramientas para agentes no confiables.
Control de recursos: sandbox para agentes específicos mientras se mantienen otros en el host.
Políticas flexibles: diferentes permisos por agente.

Consulta Sandbox y herramientas multiagente para ver ejemplos detallados.

Relacionado

Agentes ACP — ejecutando arneses de codificación externos
Enrutamiento de canales — cómo los mensajes se enrutan a los agentes
Presencia — presencia y disponibilidad del agente
Sesión — aislamiento y enrutamiento de sesiones
Sub-agentes — generando ejecuciones de agentes en segundo plano