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

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

Что такое "один агент"?

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

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

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

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

Учетные данные основного агента не являются общими автоматически. Никогда не используйте повторно agentDir между агентами (это вызывает коллизии auth/сессий). Если вы хотите поделиться учетными данными, скопируйте auth-profiles.json в agentDir другого агента.

Навыки для каждого агента через папку skills/ каждого рабочего пространства, с общими навыками доступными из ~/.openclaw/skills. См. Skills: per-agent vs shared.

Gateway может размещать одного агента (по умолчанию) или много агентов рядом.

Примечание к рабочему пространству: рабочее пространство каждого агента является cwd по умолчанию, а не жесткой песочницей. Относительные пути разрешаются внутри рабочего пространства, но абсолютные пути могут достичь других местоположений хоста, если не включена песочница. См. 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).
  • Отдельные auth + сессии (без перекрестных разговоров, если явно не включено).

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

Один номер WhatsApp, несколько людей (разделение DM)

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

Важная деталь: прямые чаты сворачиваются в основной ключ сессии агента, поэтому истинная изоляция требует одного агента на человека.

Пример:

{
  agents: {
    list: [
      { id: "alex", workspace: "~/.openclaw/workspace-alex" },
      { id: "mia", workspace: "~/.openclaw/workspace-mia" }
    ]
  },
  bindings: [
    { agentId: "alex", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
    { agentId: "mia",  match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } }
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"]
    }
  }
}

Примечания:

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

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

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

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

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

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

Концепции

  • agentId: один "мозг" (рабочее пространство, auth для каждого агента, хранилище сессий для каждого агента).
  • accountId: один экземпляр аккаунта канала (например, аккаунт WhatsApp "personal" vs "biz").
  • binding: направляет входящие сообщения к agentId по (channel, accountId, peer) и дополнительно guild/team ids.
  • Прямые чаты сворачиваются в 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",
      },
    ],
  },

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

    // Необязательное переопределение для каждого peer (пример: отправить конкретную группу к рабочему агенту).
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "[email protected]" },
      },
    },
  ],

  // По умолчанию отключено: обмен сообщениями агент-агент должен быть явно включен + внесен в список разрешений.
  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-5"
      }
    ]
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } }
  ]
}

Примечания:

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

Пример: тот же канал, один 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-5" }
    ]
  },
  bindings: [
    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
    { agentId: "chat", match: { channel: "whatsapp" } }
  ]
}

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

Семейный агент, привязанный к группе 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", "session_status"],
          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"]
        }
      }
    ]
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "[email protected]" }
      }
    }
  ]
}

Примечания:

  • Списки разрешения/запрета инструментов - это инструменты, а не навыки. Если навыку нужно запустить бинарный файл, убедитесь, что 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, чтобы @упоминания четко отображались на предназначенного агента.

См. Multi-Agent Sandbox & Tools для подробных примеров.

← Назад к документации