Мульти-агент

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

Цель: несколько изолированных агентов (отдельное рабочее пространство + 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/ каждого рабочего пространства, при этом общие навыки доступны из ~/.openclaw/skills. См. Навыки: на агента vs общие. Gateway может размещать одного агента (по умолчанию) или многих агентов параллельно. Примечание о рабочем пространстве: рабочее пространство каждого агента — это текущая рабочая директория по умолчанию, а не жёсткая песочница. Относительные пути разрешаются внутри рабочего пространства, но абсолютные пути могут достигать других мест на хосте, если не включена песочница. См. Песочница.

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

  • Конфиг: ~/.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

Быстрый старт

Шаг 1: Создайте рабочее пространство для каждого агента

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

openclaw agents add coding
openclaw agents add social

Каждый агент получает своё рабочее пространство с SOUL.md, AGENTS.md и опционально USER.md, а также выделенный agentDir и хранилище сессий в ~/.openclaw/agents/<agentId>.

Шаг 2: Создайте учётные записи каналов

Создайте по одной учётной записи на каждого агента на предпочитаемых каналах:

  • Discord: один бот на агента, включите Message Content Intent, скопируйте каждый токен.
  • Telegram: один бот на агента через BotFather, скопируйте каждый токен.
  • WhatsApp: привяжите каждый номер телефона к каждой учётной записи.
openclaw channels login --channel whatsapp --account work

См. руководства по каналам: Discord, Telegram, WhatsApp.

Шаг 3: Добавьте агентов, учётные записи и привязки

Добавьте агентов в agents.list, учётные записи каналов в channels.<channel>.accounts и свяжите их с помощью bindings (примеры ниже).

Шаг 4: Перезапустите и проверьте

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

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

При использовании нескольких агентов каждый 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 (спаривание/белый список), а не на агента.
  • Для общих групп привяжите группу к одному агенту или используйте Группы трансляции.

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

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

  1. Совпадение peer (точный id ЛС/группы/канала)
  2. Совпадение parentPeer (наследование ветки)
  3. guildId + roles (маршрутизация по ролям Discord)
  4. guildId (Discord)
  5. teamId (Slack)
  6. Совпадение accountId для канала
  7. Совпадение на уровне канала (accountId: "*")
  8. Возврат к агенту по умолчанию (agents.list[].default, иначе первая запись в списке, по умолчанию: main)

Если несколько привязок совпадают на одном уровне, побеждает первая в порядке конфигурации. Если привязка задаёт несколько полей совпадения (например, peer + guildId), все указанные поля обязательны (семантика И). Важная деталь области действия учётной записи:

  • Привязка, опускающая accountId, соответствует только учётной записи по умолчанию.
  • Используйте accountId: "*" для глобального возврата на канале для всех учётных записей.
  • Если позже вы добавите ту же привязку для того же агента с явным id учётной записи, OpenClaw обновит существующую привязку только для канала до области действия учётной записи вместо её дублирования.

Несколько учётных записей / номеров телефона

Каналы, поддерживающие несколько учётных записей (например, WhatsApp), используют accountId для идентификации каждого входа. Каждый accountId может быть направлен к разному агенту, поэтому один сервер может размещать несколько номеров телефона без смешивания сессий. Если вы хотите, чтобы учётная запись по умолчанию на канале использовалась, когда accountId опущен, установите channels.<channel>.defaultAccount (опционально). Если не установлено, OpenClaw возвращается к default, если он присутствует, иначе к первой настроенной учётной записи (отсортированной). Распространённые каналы, поддерживающие эту схему, включают:

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

Концепции

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

Примеры для платформ

Боты Discord на агента

Каждая учётная запись бота Discord соответствует уникальному accountId. Привяжите каждую учётную запись к агенту и поддерживайте белые списки на бота.

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

Примечания:

  • Пригласите каждого бота на сервер и включите Message Content Intent.
  • Токены находятся в channels.discord.accounts.<id>.token (учётная запись по умолчанию может использовать DISCORD_BOT_TOKEN).

Боты Telegram на агента

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

Примечания:

  • Создайте по одному боту на агента через BotFather и скопируйте каждый токен.
  • Токены находятся в channels.telegram.accounts.<id>.botToken (учётная запись по умолчанию может использовать TELEGRAM_BOT_TOKEN).

Номера WhatsApp на агента

Привяжите каждую учётную запись перед запуском шлюза:

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

  // Детерминированная маршрутизация: побеждает первое совпадение (самое специфичное первым).
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

    // Опциональное переопределение на конкретного собеседника (пример: отправить конкретную группу агенту work).
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "1203630...@g.us" },
      },
    },
  ],

  // Выключено по умолчанию: обмен сообщениями между агентами должен быть явно включён + добавлен в белый список.
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // Опциональное переопределение. По умолчанию: ~/.openclaw/credentials/whatsapp/personal
          // authDir: "~/.openclaw/credentials/whatsapp/personal",
        },
        biz: {
          // Опциональное переопределение. По умолчанию: ~/.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" }).
  • Чтобы направить одно ЛС/группу к Opus, оставив остальное на chat, добавьте привязку match.peer для этого собеседника; совпадения по собеседнику всегда побеждают над правилами на весь канал.

Пример: тот же канал, один собеседник к Opus

Оставьте WhatsApp на быстром агенте, но направьте одно ЛС к 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: "120363999999999999@g.us" },
      },
    },
  ],
}

Примечания:

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

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

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

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // Без песочницы для личного агента
        },
        // Без ограничений инструментов - все инструменты доступны
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // Всегда в песочнице
          scope: "agent",  // Один контейнер на агента
          docker: {
            // Опциональная однократная настройка после создания контейнера
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // Только инструмент read
          deny: ["exec", "write", "edit", "apply_patch"],    // Запретить другие
        },
      },
    ],
  },
}

Примечание: setupCommand находится в sandbox.docker и запускается один раз при создании контейнера. Переопределения sandbox.docker.* на агента игнорируются, когда разрешённая область — "shared". Преимущества:

  • Изоляция безопасности: Ограничьте инструменты для ненадёжных агентов
  • Контроль ресурсов: Песочница для конкретных агентов, оставляя других на хосте
  • Гибкие политики: Разные разрешения на агента

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

КомпактизацияПрисутствие