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

Запускайте кілька ізольованих агентів — кожен із власним робочим простором, каталогом стану (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, після чого фільтруються за ефективним списком дозволених Skills агента, якщо його налаштовано. Використовуйте agents.defaults.skills для спільної бази та agents.list[].skills для заміни на рівні окремого агента. Див. Skills: для окремого агента чи спільні і Skills: списки дозволених 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 coding
openclaw agents add social

openclaw channels login --channel whatsapp --account work

openclaw gateway restart
openclaw agents list --bindings
openclaw 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)

Ви можете маршрутизувати різні WhatsApp DM до різних агентів, залишаючись в одному обліковому записі 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 (спарювання/список дозволених), а не окремим для кожного агента.
• Для спільних груп прив’яжіть групу до одного агента або використовуйте Групи трансляції.

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

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

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

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

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

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

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

# Поняття

• agentId: один «мозок» (робочий простір, автентифікація окремого агента, сховище сеансів окремого агента).
• accountId: один екземпляр облікового запису каналу (наприклад, обліковий запис WhatsApp "personal" проти "biz").
• binding: маршрутизує вхідні повідомлення до agentId за (channel, accountId, peer) і, за потреби, id гільдії/команди.
• Прямі чати згортаються до agent:<agentId>:<mainKey> («головний» для окремого агента; 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 personal
openclaw 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 — запуск зовнішніх середовищ для кодування
• Маршрутизація каналів — як повідомлення маршрутизуються до агентів
• Присутність — присутність і доступність агента
• Сесія — ізоляція та маршрутизація сесій
• Субагенти — запуск фонових виконань агентів