Багатоагентна маршрутизація

Запускайте кілька ізольованих агентів — кожен із власним робочим простором, каталогом стану (agentDir) та історією сесій — а також кілька облікових записів каналів (наприклад, два WhatsApp) в одному запущеному Gateway. Вхідні повідомлення маршрутизуються до потрібного агента через прив’язки.

Агент тут — це повна область окремої персони: файли робочого простору, профілі автентифікації, реєстр моделей і сховище сесій. agentDir — це каталог стану на диску, який містить цю конфігурацію для кожного агента за шляхом ~/.openclaw/agents/<agentId>/. Прив’язка зіставляє обліковий запис каналу (наприклад, робочий простір Slack або номер WhatsApp) з одним із цих агентів.

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

Агент — це повністю ізольований «мозок» із власними:

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

Профілі автентифікації є окремими для кожного агента. Кожен агент читає зі свого власного:

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

Skills завантажуються з робочого простору кожного агента, а також зі спільних коренів, таких як ~/.openclaw/skills, а потім фільтруються за ефективним allowlist Skills агента, якщо його налаштовано. Використовуйте agents.defaults.skills для спільної бази та agents.list[].skills для заміни на рівні агента. Див. Skills: на рівні агента чи спільні і Skills: allowlist Skills агента.

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

Швидкий старт

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

openclaw gateway restartopenclaw agents list --bindingsopenclaw channels status --probe

Кілька агентів = кілька людей, кілька особистостей

З кількома агентами кожен agentId стає повністю ізольованою персоною:

• Різні номери телефонів/облікові записи (для кожного каналу accountId).
• Різні особистості (файли робочого простору для кожного агента, як-от AGENTS.md і SOUL.md).
• Окрема автентифікація + сесії (без перетину, якщо його явно не ввімкнено).

Це дає змогу кільком людям спільно використовувати один сервер Gateway, зберігаючи їхні AI-«мозки» та дані ізольованими.

Пошук QMD-пам’яті між агентами

Якщо один агент має шукати в стенограмах QMD-сесій іншого агента, додайте додаткові колекції в agents.list[].memorySearch.qmd.extraCollections. Використовуйте agents.defaults.memorySearch.qmd.extraCollections лише тоді, коли кожен агент має успадковувати ті самі спільні колекції стенограм.

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

Шлях додаткової колекції може бути спільним для агентів, але назва колекції залишається явною, коли шлях розташований поза робочим простором агента. Шляхи всередині робочого простору залишаються обмеженими агентом, тож кожен агент зберігає власний набір пошуку стенограм.

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

Ви можете маршрутизувати різні DM 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"],    },  },}

Нотатки:

• Контроль доступу DM є глобальним для облікового запису WhatsApp (сполучення/allowlist), а не для кожного агента.
• Для спільних груп прив’яжіть групу до одного агента або використовуйте групи розсилання.

Правила маршрутизації (як повідомлення вибирають агента)

Прив’язки є детермінованими, і найспецифічніша перемагає:

Кілька облікових записів / номерів телефонів

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

Якщо вам потрібен стандартний обліковий запис на рівні каналу, коли accountId пропущено, задайте channels.<channel>.defaultAccount (необов’язково). Якщо його не задано, OpenClaw повертається до default, якщо він є, інакше до першого налаштованого ідентифікатора облікового запису (відсортовано).

Поширені канали, що підтримують цей шаблон, включають:

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

Поняття

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

Приклади платформ

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

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

openclaw channels login --channel whatsapp --account personalopenclaw channels login --channel whatsapp --account biz

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

Поширені шаблони

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

{  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: "opus",      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } },    },    { agentId: "chat", match: { channel: "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]" },      },    },  ],}

Конфігурація пісочниці та інструментів для кожного агента

Кожен агент може мати власні обмеження пісочниці та інструментів:

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

Переваги:

• Ізоляція безпеки: обмежуйте інструменти для ненадійних агентів.
• Контроль ресурсів: запускайте певних агентів у пісочниці, залишаючи інших на хості.
• Гнучкі політики: різні дозволи для кожного агента.

Див. пісочниця та інструменти для кількох агентів для докладних прикладів.

Пов’язане

• Агенти ACP — запуск зовнішніх середовищ кодування
• Маршрутизація каналів — як повідомлення маршрутизуються до агентів
• Присутність — присутність і доступність агента
• Сесія — ізоляція та маршрутизація сесій
• Підагенті — запуск фонових виконань агентів