Маршрутизация с несколькими агентами

Цель: несколько изолированных агентов (отдельное рабочее пространство + agentDir + сеансы), а также несколько аккаунтов каналов (например, два WhatsApp) в одном запущенном Gateway (шлюзе). Входящие сообщения маршрутизируются к агенту через привязки.

Что такое «один агент»?

Агент — это полностью изолированный «мозг» со своим:

Рабочим пространством (файлы, AGENTS.md/SOUL.md/USER.md, локальные заметки, правила персоны).
Каталогом состояния (agentDir) для профилей аутентификации, реестра моделей и конфига на агента.
Хранилищем сеансов (история чатов + состояние маршрутизации) в ~/.openclaw/agents/<agentId>/sessions.

Профили аутентификации — для каждого агента. Каждый агент читает из своего:

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

Основные учетные данные агента не разделяются автоматически. Никогда не используйте повторно agentDir между агентами (это приводит к коллизиям аутентификации/сеансов). Если нужно разделить учетные данные, скопируйте auth-profiles.json в agentDir другого агента. Skills являются пер-агентными через папку skills/ каждого рабочего пространства, при этом общие skills доступны из ~/.openclaw/skills. Skills: per-agent vs shared. Gateway (шлюз) может размещать один агент (по умолчанию) или несколько агентов параллельно. Примечание о рабочем пространстве: рабочее пространство каждого агента является cwd по умолчанию, а не жёстким sandbox. Относительные пути разрешаются внутри рабочего пространства, но абсолютные пути могут достигать других расположений хоста, если sandboxing не включён. См. См. Sandboxing.

Пути (быстрая карта)

Конфигурация: ~/.openclaw/openclaw.json (или OPENCLAW_CONFIG_PATH)
Каталог состояния: ~/.openclaw (или OPENCLAW_STATE_DIR)
Рабочее пространство: ~/.openclaw/workspace (или ~/.openclaw/workspace-<agentId>)
Каталог агента: ~/.openclaw/agents/<agentId>/agent (или agents.list[].agentDir)
Сеансы: ~/.openclaw/agents/<agentId>/sessions

Режим одного агента (по умолчанию)

Если ничего не настраивать, OpenClaw запускается с одним агентом:

agentId по умолчанию равен main.
Сеансы имеют ключи вида agent:main:<mainKey>.
Рабочее пространство по умолчанию — ~/.openclaw/workspace (или ~/.openclaw/workspace-<profile>, когда установлен OPENCLAW_PROFILE).
Каталог состояния по умолчанию — ~/.openclaw/agents/main/agent.

Помощник агента

Используйте мастер агента, чтобы добавить новый изолированный агент:

openclaw agents add work

Затем добавьте bindings (или позвольте мастеру сделать это), чтобы маршрутизировать входящие сообщения. Проверьте с помощью:

openclaw agents list --bindings

Несколько агентов = несколько людей, несколько персоналий

При нескольких агентах каждый agentId становится полностью изолированной персоной:

Разные номера телефонов/аккаунты (для каждого канала accountId).
Разные личности (файлы рабочего пространства на агента, такие как AGENTS.md и SOUL.md).
Раздельная аутентификация и сеансы (без пересечений, если это явно не включено).

Это позволяет нескольким людям использовать один сервер Gateway, сохраняя их ИИ-«мозги» и данные изолированными.

Один номер WhatsApp, несколько людей (разделение личных сообщений)

Вы можете маршрутизировать разные личные сообщения WhatsApp к разным агентам, оставаясь в рамках одного аккаунта WhatsApp. Сопоставляйте по E.164 отправителя (например, +15551234567) с peer.kind: "direct". Ответы по‑прежнему приходят с одного и того же номера WhatsApp (нет идентификации отправителя на агента). Важная деталь: прямые чаты сворачиваются к основному ключу сеанса агента, поэтому для истинной изоляции требуется один агент на человека. Пример:

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

Примечания:

Контроль доступа к личным сообщениям — глобальный для аккаунта WhatsApp (сопряжение/список разрешённых), а не на агента.
Для общих групп привяжите группу к одному агенту или используйте Broadcast groups.

Правила маршрутизации (как сообщения выбирают агента)

Привязки являются детерминированными, и самое специфичное правило выигрывает:

Совпадение peer (точный DM/группа/id канала)
Совпадение parentPeer (наследование треда)
guildId + roles (маршрутизация ролей Discord)
guildId (Discord)
teamId (Slack)
Совпадение accountId для канала
Совпадение на уровне канала (accountId: "*")
Откат к агенту по умолчанию (agents.list[].default, иначе первый элемент списка, по умолчанию: main)

Если привязка задает несколько полей соответствия (например, peer + guildId), требуются все указанные поля (логика AND).

Несколько аккаунтов / номеров телефонов

Каналы, поддерживающие несколько аккаунтов (например, WhatsApp), используют accountId для идентификации каждого входа. Каждый accountId может быть направлен к разному агенту, поэтому один сервер может обслуживать несколько номеров телефонов без смешения сеансов.

Concepts

agentId: один «мозг» (рабочее пространство, аутентификация на агента, хранилище сеансов на агента).
accountId: один экземпляр аккаунта канала (например, аккаунт WhatsApp "personal" против "biz").
binding: маршрутизирует входящие сообщения к agentId по (channel, accountId, peer) и, при необходимости, идентификаторам гильдий/команд.
Прямые чаты сворачиваются к agent:<agentId>:<mainKey> (пер-агентный «основной»; session.mainKey).

Пример: два WhatsApp → два агента

~/.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",
        },
      },
    },
  },
}

Пример: ежедневный чат в WhatsApp + глубокая работа в Telegram

Разделение по каналу: направляйте WhatsApp к быстрому повседневному агенту, а Telegram — к агенту Opus.

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        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" } },
  ],
}

Примечания:

Если у вас несколько аккаунтов для канала, добавьте accountId в привязку (например, { channel: "whatsapp", accountId: "personal" }).
Чтобы направить один DM/группу к Opus, оставив остальное на чат‑агенте, добавьте привязку match.peer для этого пира; совпадения по пиру всегда выигрывают у правил уровня канала.

Пример: один канал, один пир — к Opus

Оставьте WhatsApp на быстром агенте, но направьте один DM к Opus:

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        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" } },
  ],
}

Привязки по пиру всегда выигрывают, поэтому держите их выше правила уровня канала.

Семейный агент, привязанный к группе WhatsApp

Привяжите выделенного семейного агента к одной группе WhatsApp с фильтрацией по упоминаниям и более строгой политикой инструментов:

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

Примечания:

Списки разрешений/запретов инструментов относятся к tools, а не к skills. Если skill должен запускать бинарник, убедитесь, что exec разрешён и бинарник существует в sandbox.
Для более строгой фильтрации установите agents.list[].groupChat.mentionPatterns и оставьте включёнными списки разрешённых групп для канала.

Sandbox и конфигурация инструментов на агента

Начиная с версии v2026.1.6, каждый агент может иметь собственный sandbox и ограничения инструментов:

{
  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 находится в sandbox.docker и выполняется один раз при создании контейнера. Переопределения sandbox.docker.* на агента игнорируются, когда итоговая область равна "shared". Преимущества:

Изоляция безопасности: ограничение инструментов для недоверенных агентов
Контроль ресурсов: изоляция sandbox для отдельных агентов при сохранении работы других на хосте
Гибкие политики: разные разрешения для разных агентов

Примечание: tools.elevated является глобальным и основанным на отправителе; его нельзя настраивать на агента. Если нужны границы на агента, используйте agents.list[].tools, чтобы запретить exec. Для таргетинга групп используйте agents.list[].groupChat.mentionPatterns, чтобы @упоминания корректно сопоставлялись с нужным агентом. Multi-Agent Sandbox & Tools для подробных примеров.

Основы

Bootstrapping

Сессии и память

Мультиагентный

Сообщения и доставка

Маршрутизация с несколькими агентами

Маршрутизация с несколькими агентами

Что такое «один агент»?

Пути (быстрая карта)

Режим одного агента (по умолчанию)

Помощник агента

Несколько агентов = несколько людей, несколько персоналий

Один номер WhatsApp, несколько людей (разделение личных сообщений)

Правила маршрутизации (как сообщения выбирают агента)

Несколько аккаунтов / номеров телефонов

Concepts

Пример: два WhatsApp → два агента

Пример: ежедневный чат в WhatsApp + глубокая работа в Telegram

Пример: один канал, один пир — к Opus

Семейный агент, привязанный к группе WhatsApp

Sandbox и конфигурация инструментов на агента

​Маршрутизация с несколькими агентами

​Что такое «один агент»?

​Пути (быстрая карта)

​Режим одного агента (по умолчанию)

​Помощник агента

​Несколько агентов = несколько людей, несколько персоналий

​Один номер WhatsApp, несколько людей (разделение личных сообщений)

​Правила маршрутизации (как сообщения выбирают агента)

​Несколько аккаунтов / номеров телефонов

​Concepts

​Пример: два WhatsApp → два агента

​Пример: ежедневный чат в WhatsApp + глубокая работа в Telegram

​Пример: один канал, один пир — к Opus

​Семейный агент, привязанный к группе WhatsApp

​Sandbox и конфигурация инструментов на агента

Маршрутизация с несколькими агентами

Что такое «один агент»?

Пути (быстрая карта)

Режим одного агента (по умолчанию)

Помощник агента

Несколько агентов = несколько людей, несколько персоналий

Один номер WhatsApp, несколько людей (разделение личных сообщений)

Правила маршрутизации (как сообщения выбирают агента)

Несколько аккаунтов / номеров телефонов

Concepts

Пример: два WhatsApp → два агента

Пример: ежедневный чат в WhatsApp + глубокая работа в Telegram

Пример: один канал, один пир — к Opus

Семейный агент, привязанный к группе WhatsApp

Sandbox и конфигурация инструментов на агента