Routing wieloagentowy

Uruchamiaj wielu izolowanych agentów — każdego z własnym obszarem roboczym, katalogiem stanu (agentDir) i historią sesji — oraz wiele kont kanałów (np. dwa konta WhatsApp) w jednym działającym Gateway. Wiadomości przychodzące są kierowane do właściwego agenta przez powiązania.

Agent oznacza tutaj pełny zakres dla danej persony: pliki obszaru roboczego, profile uwierzytelniania, rejestr modeli i magazyn sesji. agentDir to katalog stanu na dysku, który przechowuje tę konfigurację per agent w ~/.openclaw/agents/<agentId>/. Powiązanie mapuje konto kanału (np. obszar roboczy Slack lub numer WhatsApp) na jednego z tych agentów.

Czym jest „jeden agent”?

Agent to w pełni wydzielony mózg z własnymi:

• Obszarem roboczym (pliki, AGENTS.md/SOUL.md/USER.md, notatki lokalne, reguły persony).
• Katalogiem stanu (agentDir) dla profili uwierzytelniania, rejestru modeli i konfiguracji per agent.
• Magazynem sesji (historia czatu + stan routingu) w ~/.openclaw/agents/<agentId>/sessions.

Profile uwierzytelniania są per agent. Każdy agent czyta z własnego:

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

Skills są ładowane z obszaru roboczego każdego agenta oraz ze współdzielonych katalogów głównych, takich jak ~/.openclaw/skills, a następnie filtrowane według efektywnej listy dozwolonych Skills agenta, gdy jest skonfigurowana. Użyj agents.defaults.skills jako współdzielonej bazy i agents.list[].skills jako zastąpienia per agent. Zobacz Skills: per agent a współdzielone oraz Skills: listy dozwolonych Skills agenta.

Gateway może hostować jednego agenta (domyślnie) albo wielu agentów obok siebie.

Ścieżki (szybka mapa)

• Konfiguracja: ~/.openclaw/openclaw.json (lub OPENCLAW_CONFIG_PATH)
• Katalog stanu: ~/.openclaw (lub OPENCLAW_STATE_DIR)
• Obszar roboczy: ~/.openclaw/workspace (lub ~/.openclaw/workspace-<agentId>)
• Katalog agenta: ~/.openclaw/agents/<agentId>/agent (lub agents.list[].agentDir)
• Sesje: ~/.openclaw/agents/<agentId>/sessions

Tryb jednego agenta (domyślny)

Jeśli nic nie zrobisz, OpenClaw uruchamia pojedynczego agenta:

• agentId domyślnie ma wartość main.
• Sesje są kluczowane jako agent:main:<mainKey>.
• Obszar roboczy domyślnie to ~/.openclaw/workspace (lub ~/.openclaw/workspace-<profile>, gdy ustawiono OPENCLAW_PROFILE).
• Stan domyślnie to ~/.openclaw/agents/main/agent.

Pomocnik agentów

Użyj kreatora agentów, aby dodać nowego izolowanego agenta:

openclaw agents add work

Następnie dodaj bindings (albo pozwól zrobić to kreatorowi), aby kierować wiadomości przychodzące.

Zweryfikuj za pomocą:

openclaw agents list --bindings

Szybki start

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

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

Wielu agentów = wiele osób, wiele osobowości

Przy wielu agentach każdy agentId staje się w pełni odizolowaną personą:

• Różne numery telefonów/konta (dla każdego kanału accountId).
• Różne osobowości (pliki przestrzeni roboczej dla poszczególnych agentów, takie jak AGENTS.md i SOUL.md).
• Oddzielne uwierzytelnianie + sesje (bez przenikania rozmów, chyba że zostanie jawnie włączone).

Dzięki temu wiele osób może współdzielić jeden serwer Gateway, zachowując izolację swoich „mózgów” AI i danych.

Wyszukiwanie pamięci QMD między agentami

Jeśli jeden agent ma przeszukiwać transkrypcje sesji QMD innego agenta, dodaj dodatkowe kolekcje w agents.list[].memorySearch.qmd.extraCollections. Używaj agents.defaults.memorySearch.qmd.extraCollections tylko wtedy, gdy każdy agent ma dziedziczyć te same współdzielone kolekcje transkrypcji.

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

Ścieżka dodatkowej kolekcji może być współdzielona między agentami, ale nazwa kolekcji pozostaje jawna, gdy ścieżka znajduje się poza przestrzenią roboczą agenta. Ścieżki wewnątrz przestrzeni roboczej pozostają przypisane do agenta, dzięki czemu każdy agent zachowuje własny zestaw wyszukiwania transkrypcji.

Jeden numer WhatsApp, wiele osób (podział DM)

Możesz kierować różne DM WhatsApp do różnych agentów, pozostając przy jednym koncie WhatsApp. Dopasuj nadawcę w formacie E.164 (np. +15551234567) za pomocą peer.kind: "direct". Odpowiedzi nadal przychodzą z tego samego numeru WhatsApp (bez osobnej tożsamości nadawcy dla agenta).

Przykład:

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

Uwagi:

• Kontrola dostępu DM jest globalna dla konta WhatsApp (parowanie/lista dozwolonych), a nie osobna dla agenta.
• W przypadku współdzielonych grup powiąż grupę z jednym agentem albo użyj grup rozgłoszeniowych.

Reguły routingu (jak wiadomości wybierają agenta)

Powiązania są deterministyczne i wygrywa najbardziej szczegółowe:

Wiele kont / numerów telefonów

Kanały obsługujące wiele kont (np. WhatsApp) używają accountId do identyfikowania każdego logowania. Każdy accountId może być kierowany do innego agenta, więc jeden serwer może obsługiwać wiele numerów telefonów bez mieszania sesji.

Jeśli chcesz mieć domyślne konto dla całego kanału, gdy accountId jest pominięty, ustaw channels.<channel>.defaultAccount (opcjonalne). Gdy nie jest ustawione, OpenClaw używa rezerwowo default, jeśli istnieje, w przeciwnym razie pierwszego skonfigurowanego identyfikatora konta (po sortowaniu).

Typowe kanały obsługujące ten wzorzec obejmują:

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

Pojęcia

• agentId: jeden „mózg” (przestrzeń robocza, uwierzytelnianie dla agenta, magazyn sesji dla agenta).
• accountId: jedna instancja konta kanału (np. konto WhatsApp "personal" kontra "biz").
• binding: kieruje wiadomości przychodzące do agentId według (channel, accountId, peer) i opcjonalnie identyfikatorów gildii/zespołu.
• Czaty bezpośrednie zwijają się do agent:<agentId>:<mainKey> („main” dla agenta; session.mainKey).

Przykłady platform

{  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: "1203630...@g.us" },      },    },  ],   // 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",        },      },    },  },}

Typowe wzorce

{  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", accountId: "*" } },    { agentId: "opus", match: { channel: "telegram", accountId: "*" } },  ],}

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

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

Konfiguracja sandbox i narzędzi dla poszczególnych agentów

Każdy agent może mieć własny sandbox i ograniczenia narzędzi:

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

Korzyści:

• Izolacja bezpieczeństwa: ogranicz narzędzia dla niezaufanych agentów.
• Kontrola zasobów: uruchamiaj wybranych agentów w sandbox, pozostawiając innych na hoście.
• Elastyczne polityki: różne uprawnienia dla poszczególnych agentów.

Zobacz Sandbox i narzędzia dla wielu agentów, aby poznać szczegółowe przykłady.

Powiązane

• Agenci ACP — uruchamianie zewnętrznych harnessów kodowania
• Routing kanałów — jak wiadomości są kierowane do agentów
• Obecność — obecność i dostępność agenta
• Sesja — izolacja i routing sesji
• Subagenci — uruchamianie agentów w tle