Routing wieloagentowy

Uruchom wiele izolowanych agentów — każdy z własnym workspace, 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 wiązania.

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

Czym jest „jeden agent”?

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

• Workspace (pliki, AGENTS.md/SOUL.md/USER.md, notatki lokalne, reguły persony).
• Katalogiem stanu (agentDir) na profile uwierzytelniania, rejestr modeli i konfigurację per agent.
• Magazynem sesji (historia czatu + stan routingu) pod ~/.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 workspace każdego agenta oraz 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 zamiany 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 (albo OPENCLAW_CONFIG_PATH)
• Katalog stanu: ~/.openclaw (albo OPENCLAW_STATE_DIR)
• Workspace: ~/.openclaw/workspace (albo ~/.openclaw/workspace-<agentId>)
• Katalog agenta: ~/.openclaw/agents/<agentId>/agent (albo agents.list[].agentDir)
• Sesje: ~/.openclaw/agents/<agentId>/sessions

Tryb pojedynczego agenta (domyślny)

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

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

Pomocnik agenta

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

openclaw agents add work

Następnie dodaj bindings (albo pozwól kreatorowi to zrobić), 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 izolowaną personą:

• Różne numery telefonu/konta (per kanał accountId).
• Różne osobowości (pliki workspace per agent, takie jak AGENTS.md i SOUL.md).
• Oddzielne uwierzytelnianie + sesje (bez komunikacji między nimi, chyba że zostanie jawnie włączona).

Pozwala to wielu osobom współdzielić jeden serwer Gateway przy zachowaniu izolacji ich „mózgów” AI i danych.

Wyszukiwanie pamięci QMD między agentami

Jeśli jeden agent powinien przeszukiwać transkrypcje sesji QMD innego agenta, dodaj dodatkowe kolekcje pod agents.list[].memorySearch.qmd.extraCollections. Używaj agents.defaults.memorySearch.qmd.extraCollections tylko wtedy, gdy każdy agent powinien 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 workspace agenta. Ścieżki wewnątrz workspace pozostają ograniczone do agenta, więc 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ę E.164 (np. +15551234567) za pomocą peer.kind: "direct". Odpowiedzi nadal przychodzą z tego samego numeru WhatsApp (brak tożsamości nadawcy per agent).

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 per konto WhatsApp (parowanie/lista dozwolonych), a nie per agent.
• W przypadku współdzielonych grup powiąż grupę z jednym agentem albo użyj grup broadcast.

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

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

Wiele kont / numerów telefonu

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

Jeśli chcesz domyślne konto dla całego kanału, gdy accountId jest pominięte, ustaw channels.<channel>.defaultAccount (opcjonalnie). Gdy nie jest ustawione, OpenClaw wraca do default, jeśli istnieje, w przeciwnym razie do pierwszego skonfigurowanego identyfikatora konta (posortowanego).

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

Koncepcje

• agentId: jeden „mózg” (workspace, uwierzytelnianie per agent, magazyn sesji per agent).
• 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) oraz opcjonalnie identyfikatorów gildii/zespołu.
• Czaty bezpośrednie zwijają się do agent:<agentId>:<mainKey> („main” per agent; 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: "[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",        },      },    },  },}

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

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

Każdy agent może mieć własne ograniczenia piaskownicy i 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 określonych agentów w piaskownicy, pozostawiając innych na hoście.
• Elastyczne polityki: różne uprawnienia dla poszczególnych agentów.

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

Powiązane

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