Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Ejecuta varios agentes aislados — cada uno con su propio espacio de trabajo, directorio de estado (agentDir) e historial de sesiones — además de varias cuentas de canal (por ejemplo, dos WhatsApp) en un único Gateway en ejecución. Los mensajes entrantes se enrutan al agente correcto mediante vinculaciones. Un agente aquí es el ámbito completo por persona: 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 contiene esta configuración por agente en ~/.openclaw/agents/<agentId>/. Una vinculación asigna una cuenta de canal (por ejemplo, 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 completamente acotado con su propio:
  • Espacio de trabajo (archivos, AGENTS.md/SOUL.md/USER.md, notas locales, reglas de persona).
  • 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) en ~/.openclaw/agents/<agentId>/sessions.
Los perfiles de autenticación son por agente. Cada agente lee desde su propio: 
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
sessions_history también es aquí la ruta más segura de recuperación entre sesiones: devuelve una vista acotada y saneada, no un volcado bruto de la transcripción. La recuperación del asistente elimina etiquetas de pensamiento, andamiaje <relevant-memories>, cargas XML de llamadas a herramientas en texto plano (incluidos <tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls> y bloques truncados de llamadas a herramientas), andamiaje degradado de llamadas a herramientas, tokens filtrados de control de modelo ASCII/de ancho completo y XML de llamadas a herramientas de MiniMax mal formado antes de la redacción/truncamiento.
Nunca reutilices agentDir entre agentes (causa colisiones de autenticación/sesión). Los agentes pueden leer los perfiles de autenticación del agente predeterminado/principal cuando no tienen un perfil local, pero OpenClaw no clona tokens de actualización OAuth en el almacén del agente secundario. Si quieres una cuenta OAuth independiente, inicia sesión desde ese agente; si copias credenciales manualmente, copia solo perfiles estáticos portátiles api_key o token.
Skills se cargan desde cada espacio de trabajo de agente más raíces compartidas como ~/.openclaw/skills, y luego se filtran por la lista efectiva de Skills permitidas del agente cuando está configurada. Usa agents.defaults.skills para una línea base compartida y agents.list[].skills para reemplazo por agente. Consulta Skills: por agente frente a compartidas y Skills: listas de Skills permitidas por agente. El Gateway puede alojar un agente (predeterminado) o muchos agentes en paralelo.
Nota sobre el espacio de trabajo: el espacio de trabajo de cada agente es el cwd predeterminado, no un sandbox estricto. Las rutas relativas se resuelven dentro del espacio de trabajo, pero las rutas absolutas pueden alcanzar otras ubicaciones del host salvo que el sandboxing esté habilitado. Consulta Sandboxing.

​
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 usa main de forma predeterminada.
  • Las sesiones se identifican como agent:main:<mainKey>.
  • El espacio de trabajo usa ~/.openclaw/workspace de forma predeterminada (o ~/.openclaw/workspace-<profile> cuando OPENCLAW_PROFILE está configurado).
  • El estado usa ~/.openclaw/agents/main/agent de forma predeterminada.

​
Ayudante de agentes

Usa el asistente de agentes para añadir un nuevo agente aislado: 
openclaw agents add work
Luego añade bindings (o deja que el asistente lo haga) para enrutar los mensajes entrantes. Verifica con: 
openclaw agents list --bindings

​
Inicio rápido

1

Crear cada espacio de trabajo de agente

Usa el asistente o crea espacios de trabajo manualmente:
openclaw agents add coding
openclaw agents add social
Cada agente obtiene su propio espacio de trabajo con SOUL.md, AGENTS.md y USER.md opcional, además de un agentDir dedicado y un almacén de sesiones en ~/.openclaw/agents/<agentId>.
2

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 mediante BotFather, copia cada token.
  • WhatsApp: vincula cada número de teléfono por cuenta.
openclaw channels login --channel whatsapp --account work
Consulta las guías de canales: Discord, Telegram, WhatsApp.
3

Añadir agentes, cuentas y vinculaciones

Añade agentes en agents.list, cuentas de canal en channels.<channel>.accounts y conéctalos con bindings (ejemplos más abajo).
4

Reiniciar y verificar

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

​
Varios agentes = varias personas, varias personalidades

Con varios agentes, cada agentId se convierte en una persona completamente aislada:
  • Números de teléfono/cuentas diferentes (por canal accountId).
  • Personalidades diferentes (archivos de espacio de trabajo por agente como AGENTS.md y SOUL.md).
  • Autenticación + sesiones separadas (sin comunicación cruzada salvo que se habilite explícitamente).
Esto permite que varias personas compartan un servidor Gateway mientras mantienen aislados sus “cerebros” de IA y sus datos.

​
Búsqueda de memoria QMD entre agentes

Si un agente debe buscar en las transcripciones de sesiones QMD de otro agente, añade colecciones adicionales en agents.list[].memorySearch.qmd.extraCollections. Usa agents.defaults.memorySearch.qmd.extraCollections solo cuando todos los agentes deban heredar las mismas colecciones compartidas de transcripciones. 
{
  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 la colección adicional puede compartirse entre agentes, pero el nombre de la colección sigue siendo explícito cuando la ruta está fuera del espacio de trabajo del agente. Las rutas dentro del espacio de trabajo permanecen acotadas al agente para que cada agente conserve su propio conjunto de búsqueda de transcripciones.

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

Puedes enrutar distintos DM de WhatsApp a agentes diferentes mientras permaneces en una sola cuenta de WhatsApp. Coincide por remitente E.164 (como +15551234567) con peer.kind: "direct". Las respuestas siguen saliendo del mismo número de WhatsApp (sin identidad de remitente por agente).
Los chats directos se colapsan en la clave de sesión principal del agente, por lo que el aislamiento real requiere un agente por persona.
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 DM es global por cuenta de WhatsApp (emparejamiento/lista de permitidos), no por agente.
  • Para grupos compartidos, vincula el grupo a un agente o usa Grupos de difusión.

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

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

coincidencia de peer

ID exacto de DM/grupo/canal.
2

coincidencia de parentPeer

Herencia de hilo.
3

guildId + roles

Enrutamiento por rol de Discord.
4

guildId

Discord.
5

teamId

Slack.
6

coincidencia de accountId para un canal

Respaldo por cuenta.
7

Coincidencia a nivel de canal

accountId: "*".
8

Agente predeterminado

Respaldo a agents.list[].default; si no existe, primera entrada de la lista; predeterminado: main.
  • Si varias vinculaciones coinciden en el mismo nivel, gana la primera en el orden de configuración.
  • Si una vinculación define varios campos de coincidencia (por ejemplo peer + guildId), todos los campos especificados son obligatorios (semántica AND).
  • Una vinculación que omite accountId coincide solo con la cuenta predeterminada.
  • Usa accountId: "*" para un respaldo de todo el canal en todas las cuentas.
  • Si más adelante añades la misma vinculación para el mismo agente con un ID de cuenta explícito, OpenClaw actualiza la vinculación existente de solo canal a ámbito de cuenta 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 puede enrutarse a un agente diferente, por lo que un servidor puede alojar varios números de teléfono sin mezclar sesiones. Si quieres una cuenta predeterminada para todo el canal cuando se omite accountId, configura channels.<channel>.defaultAccount (opcional). Cuando no está configurado, OpenClaw recurre a default si está presente; de lo contrario, al primer ID de cuenta configurado (ordenado). Los canales comunes que admiten 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, almacén de sesiones por agente).
  • accountId: una instancia de cuenta de canal (por ejemplo, cuenta de WhatsApp "personal" frente a "biz").
  • binding: enruta mensajes entrantes a un agentId por (channel, accountId, peer) y opcionalmente IDs de guild/equipo.
  • Los chats directos se colapsan en agent:<agentId>:<mainKey> (“main” por agente; session.mainKey).

​
Ejemplos de plataforma

Cada cuenta de bot de Discord se asigna a un accountId único. Vincula cada cuenta a un agente y mantén 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 },
              },
            },
          },
        },
      },
    },
  },
}
  • Invita a cada bot al servidor y habilita Message Content Intent.
  • Los tokens viven en channels.discord.accounts.<id>.token (la cuenta predeterminada puede usar DISCORD_BOT_TOKEN).
{
  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"],
        },
      },
    },
  },
}
  • Crea un bot por agente con BotFather y copia cada token.
  • Los tokens viven en channels.telegram.accounts.<id>.botToken (la cuenta predeterminada puede usar TELEGRAM_BOT_TOKEN).
Vincula cada cuenta antes de iniciar el Gateway:
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: "1203630...@g.us" },
      },
    },
  ],

  // 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

Divide por canal: enruta WhatsApp a un agente rápido de uso diario 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 mientras mantienes el resto en chat, añade un enlace match.peer para ese par; las coincidencias de pares siempre prevalecen sobre las reglas de todo 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
        },
      },
    ],
  },
}
setupCommand vive bajo sandbox.docker y se ejecuta una vez al crear el contenedor. Las anulaciones sandbox.docker.* por agente se ignoran cuando el ámbito resuelto es "shared".
Beneficios:
  • Aislamiento de seguridad: restringe herramientas para agentes no confiables.
  • Control de recursos: ejecuta agentes específicos en sandbox mientras mantienes otros en el host.
  • Políticas flexibles: permisos diferentes por agente.
tools.elevated es global y se basa en el remitente; no es configurable por agente. Si necesitas límites por agente, usa agents.list[].tools para denegar exec. Para dirigir grupos, usa agents.list[].groupChat.mentionPatterns para que las @menciones se asignen claramente al agente previsto.
Consulta Sandbox y herramientas multiagente para ver ejemplos detallados.

​
Relacionado

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