Skip to content

Colaboración multiagent: un Gateway ejecuta varios expertos ​

La arquitectura multiagent de OpenClaw permite ejecutar varios agents mutuamente aislados en un solo proceso de Gateway: cada agent tiene su propio espacio de trabajo, directorio de estado (agentDir) e historial de sesiones basado en SQLite, y además puede tener varias cuentas de canal conectadas a la vez (por ejemplo, dos números de WhatsApp). Los mensajes entrantes se enrutan al agent correcto mediante binding.

Escenarios de uso ​

  • Quieres un «Claw de trabajo» y un «Claw personal», con persona, memoria y credenciales que no interfieran entre sí.
  • Tienes varias cuentas del mismo tipo de canal — dos números de WhatsApp, dos workspaces de Slack — y quieres conectar cada una a un experto.
  • Un equipo comparte un mismo despliegue y cada miembro o línea de negocio tiene su propio agent dedicado.

Primero distingue los conceptos: esta página trata sobre multiagent con enrutamiento por cuenta de canal. El repositorio también tiene documentación de subagents y de la herramienta agent-send, que corresponden a otra forma de colaboración entre agents.

Preparación ​

  • Has leído Escenarios prácticos: elige tu ruta y has confirmado que multiagent es la ruta que quieres.
  • Tienes un Gateway ya en ejecución: multiagent no necesita un segundo proceso.
  • Ten claro el reparto: qué cuenta de canal va con qué agent, y escribe las reglas de persona de cada experto en su propio AGENTS.md/SOUL.md.

Hazlo conmigo: tres pasos para poner en marcha varios expertos ​

Paso 1: crea varios agents expertos con openclaw agents add ​

¿Por qué crear un agent separado para cada experto? Porque un agent es un ámbito de persona completo, que incluye tres cosas:

  • Espacio de trabajo: archivos, AGENTS.md/SOUL.md/USER.md, notas locales, reglas de persona.
  • Directorio de estado agentDir: perfiles de auth, registro de modelos, configuración por agent; por defecto en ~/.openclaw/agents/<agentId>/agent.
  • Base de datos de sesiones: historial de chat y estado de enrutamiento, almacenados en <agentDir>/openclaw-agent.sqlite; con la disposición predeterminada, es ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.

Ejecuta una vez agents add para cada experto; el ejemplo crea un «Claw personal» y un «Claw de trabajo»:

bash
openclaw agents add home
openclaw agents add work

Flags habituales: --role <role> (aplica una plantilla de rol), --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (repetible; crea el binding de paso al crear); --non-interactive debe combinarse con --workspace, salvo que se especifique --role.

Deberías ver: cada agent obtiene su propio espacio de trabajo (incluye SOUL.md, AGENTS.md y, opcionalmente, USER.md), su agentDir y su base de datos de sesiones independientes, y los archivos del agent quedan por defecto en ~/.openclaw/agents/<agentId>. El asistente de creación también te preguntará si quieres añadir un binding ahora; puedes omitirlo y escribirlo a mano en el siguiente paso.

Paso 2: conecta las cuentas de canales al agent correspondiente con binding ​

El binding solo decide «a qué agent pertenece este mensaje»: no crea cuentas de canal ni concede acceso, así que primero configura la cuenta y luego enlázala. Un Gateway puede tener varias cuentas conectadas; por ejemplo, dos números de WhatsApp enlazados respectivamente a dos expertos.

Primero prepara una cuenta de canal para cada agent:

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

Luego, en ~/.openclaw/openclaw.json (JSON5), conecta el agent con la cuenta: agents.entries enumera los agents y bindings declara el enrutamiento.

json5
{
  agents: {
    entries: {
      home: {
        workspace: "~/.openclaw/workspace-home",
        agentDir: "~/.openclaw/agents/home/agent",
      },
      work: {
        workspace: "~/.openclaw/workspace-work",
        agentDir: "~/.openclaw/agents/work/agent",
      },
    },
  },
  // 固定路由顺序:先匹配的赢,窄规则写在宽规则前面。
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

Diferencias entre binding a nivel de cuenta y a nivel de sesión; elige según lo que necesites:

  • A nivel de cuenta: solo se escribe channel + accountId, y todos los mensajes de la cuenta van a ese agent. accountId: "*" es el comodín a nivel de canal; si se omite accountId, solo coincide con la cuenta predeterminada de ese canal.
  • A nivel de sesión: se añade match.peer (kind toma direct/group/channel, usando el peer ID estable del canal, no el nombre visible) para enrutar solo una conversación concreta al experto.
  • Prioridad: las coincidencias de sesión o grupo concretas ganan sobre el nivel de cuenta y el comodín de canal; dentro de un mismo nivel, se aplica por orden de configuración, primero en llegar.

Deberías ver: los cambios válidos de binding surten efecto automáticamente en el modo predeterminado de recarga en caliente hybrid; si gateway.reload.mode es off, hay que reiniciar el Gateway para que surtan efecto. Un binding que apunte a una cuenta que el canal nunca acepta no funcionará.

Paso 3: envía mensajes para verificar el enrutamiento y el aislamiento ​

Que la configuración esté escrita no significa que el enrutamiento sea correcto: primero verifica el roster y los enlaces con comandos, y luego comprueba cada caso con mensajes reales:

bash
openclaw agents list --bindings
openclaw channels status --probe

Después, envía un mensaje desde cada cuenta enlazada y confirma tres cosas: que el mensaje llegó al agent correcto; que los historiales de sesión de cada uno son independientes; y que las reglas de persona se aplican por separado.

Deberías ver: agents list --bindings enumera el roster de agents y los enlaces «cuenta de canal → agent», y channels status --probe muestra qué cuentas están en línea. Si ningún binding coincide y no hay una asignación predeterminada disponible, el enrutamiento devuelve AGENT_SELECTION_REQUIRED y te pide añadir un binding. Cuando las tres cosas pasan, tus múltiples expertos quedan cada uno en su sitio dentro del mismo Gateway.

Puntos de control ​

  • Nunca reutilices agentDir. Si dos agents apuntan al mismo directorio, se producen conflictos de estado de auth y de sesión.
  • OAuth tiene comportamiento heredado: cuando las credenciales OAuth locales de un agent secundario caducan o falla su refresco, OpenClaw lee las credenciales del mismo perfil del principal heredado, adopta el token más actualizado y no copia el refresh token al almacenamiento del agent secundario. Para tener cuentas OAuth totalmente independientes, inicia sesión una vez desde ese propio agent.
  • Copiar credenciales manualmente solo copia elementos estáticos: los perfiles tipo api_key/token se pueden copiar; el material de refresco de OAuth no es portátil por defecto, salvo que se incluya explícitamente con copyToAgents.
  • Carga de Skills por doble vía: cada agent carga Skills desde su propio espacio de trabajo y también lee la raíz compartida (por ejemplo, ~/.openclaw/skills).

Límites ​

  • Los múltiples agent siguen dentro del mismo proceso Gateway, por lo que el límite de confianza no cambia; tanto el modelo como el agent harness son complementos intercambiables.
  • Las capacidades del canal dependen del complemento: el complemento de WeChat solo admite chat privado, no chat de grupo, así que no cuentes «vincular un grupo de WeChat» como parte del plan.
  • El historial de conversaciones ofrece una recuperación entre sesiones acotada, no una memoria ilimitada.

Siguiente paso ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.