Multi-Agenten-Routing

Führen Sie mehrere isolierte Agenten in einem Gateway-Prozess aus, jeweils mit eigenem Workspace, Zustandsverzeichnis (agentDir) und SQLite-gestütztem Sitzungsverlauf sowie mehreren Kanalkonten (z. B. zwei WhatsApp-Nummern). Eingehende Nachrichten werden über Bindungen an den richtigen Agenten weitergeleitet.

Ein Agent umfasst den vollständigen Bereich einer Persona: Workspace-Dateien, Authentifizierungsprofile, Modellregister und Sitzungsspeicher. Eine Bindung ordnet ein Kanalkonto (einen Slack-Workspace, eine WhatsApp-Nummer usw.) einem dieser Agenten zu.

Was ist ein Agent?

Jeder Agent verfügt über einen eigenen:

• Workspace: Dateien, AGENTS.md/SOUL.md/USER.md, lokale Notizen, Persona-Regeln.
• Zustandsverzeichnis (agentDir): Authentifizierungsprofile, Modellregister, agentenspezifische Konfiguration.
• Sitzungsspeicher: Chatverlauf und Routing-Zustand in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite.

Authentifizierungsprofile gelten jeweils pro Agent und werden aus folgendem Pfad gelesen:

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

Skills werden aus dem Workspace jedes Agenten sowie aus gemeinsam genutzten Stammverzeichnissen wie ~/.openclaw/skills geladen und anschließend anhand der effektiven Skill-Zulassungsliste des Agenten gefiltert. Verwenden Sie agents.defaults.skills für eine gemeinsame Grundlage und agents.list[].skills als agentenspezifischen Ersatz (explizite Einträge ersetzen den Standard, sie werden nicht zusammengeführt). Siehe Skills: agentenspezifisch oder gemeinsam genutzt und Skills: Zulassungslisten für Agenten.

Der Plugin-eigene Speicher folgt der Konfiguration des jeweiligen Plugins; durch das Hinzufügen eines zweiten Agenten wird nicht automatisch jeder globale Plugin-Speicher aufgeteilt. Konfigurieren Sie beispielsweise agentenspezifische Memory-Wiki-Vaults, wenn Personas zusammengestelltes Wiki-Wissen nicht gemeinsam nutzen dürfen.

Pfade

Einzelagentenmodus (Standard)

Wenn Sie nichts konfigurieren, führt OpenClaw einen Agenten aus:

• agentId ist standardmäßig main.
• Sitzungsschlüssel haben die Form agent:main:<mainKey> (der Standardwert von mainKey ist main).
• Der Workspace ist standardmäßig ~/.openclaw/workspace (oder workspace-<profile>, wenn OPENCLAW_PROFILE auf einen anderen Wert als default gesetzt ist).
• Der Zustand befindet sich standardmäßig unter ~/.openclaw/agents/main/agent.

Agenten-Hilfsfunktion

Fügen Sie einen neuen isolierten Agenten hinzu:

openclaw agents add work

Flags: --workspace <dir>, --model <id>, --agent-dir <dir>, --bind <channel[:accountId]> (wiederholbar), --non-interactive (erfordert --workspace).

Fügen Sie bindings hinzu, um eingehende Nachrichten weiterzuleiten (der Assistent bietet Ihnen dies an), und überprüfen Sie anschließend die Konfiguration:

openclaw agents list --bindings

Schnellstart

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

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

Mehrere Agenten, mehrere Personas

Jede konfigurierte agentId bildet eine eigenständige Persona-Grenze für den zentralen Agentenzustand:

• Unterschiedliche Konten pro Kanal (je accountId).
• Unterschiedliche Persönlichkeiten (agentenspezifische AGENTS.md/SOUL.md).
• Getrennte Authentifizierung und Sitzungen; agentenübergreifender Zugriff wird ausschließlich über explizite Funktionen oder die Plugin-Konfiguration aktiviert.

Dadurch können sich mehrere Personen ein Gateway teilen, während der zentrale Zustand der Agenten getrennt bleibt.

Agentenspezifische Memory-Wiki-Vaults

Memory Wiki verwendet standardmäßig ein globales Vault. Um das zusammengestellte Wissen eines Support-Agenten vom Wissen eines Marketing-Agenten zu trennen, setzen Sie plugins.entries.memory-wiki.config.vault.scope auf agent:

{  plugins: {    entries: {      "memory-wiki": {        enabled: true,        config: {          vault: {            scope: "agent",            path: "~/.openclaw/wiki",          },        },      },    },  },}

Der konfigurierte Pfad ist das übergeordnete Verzeichnis. OpenClaw hängt die normalisierte Agenten-ID an und erzeugt dadurch Pfade wie ~/.openclaw/wiki/support und ~/.openclaw/wiki/marketing. Agentenspezifische CLI- und Gateway-Vorgänge erfordern einen expliziten Agenten, wenn mehrere Agenten konfiguriert sind. Weitere Informationen zu Bridge-Filterung, Migration und Vertrauensgrenzen finden Sie unter Agentenspezifische Memory-Wiki-Vaults.

Agentenübergreifende QMD-Speichersuche

Damit ein Agent die QMD-Sitzungstranskripte eines anderen Agenten durchsuchen kann, fügen Sie unter agents.list[].memorySearch.qmd.extraCollections zusätzliche Sammlungen hinzu. Verwenden Sie agents.defaults.memorySearch.qmd.extraCollections, wenn jeder Agent dieselben Sammlungen gemeinsam nutzen soll.

{  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" }], // wird innerhalb des Workspace aufgelöst -> Sammlung mit dem Namen "notes-main"          },        },      },      { id: "family", workspace: "~/workspaces/family" },    ],  },  memory: {    backend: "qmd",    qmd: { includeDefaultMemory: false },  },}

Der Pfad einer zusätzlichen Sammlung kann von mehreren Agenten gemeinsam genutzt werden, sein name bleibt jedoch explizit, wenn sich der Pfad außerhalb des Agenten-Workspace befindet. Pfade innerhalb des Workspace bleiben agentenspezifisch, sodass jeder Agent seinen eigenen Satz für die Transkriptsuche behält.

Eine WhatsApp-Nummer, mehrere Personen (DM-Aufteilung)

Leiten Sie unterschiedliche WhatsApp-Direktnachrichten auf einem WhatsApp-Konto an unterschiedliche Agenten weiter, indem Sie die E.164-Nummer des Absenders (+15551234567) mit peer.kind: "direct" abgleichen. Antworten werden weiterhin von derselben WhatsApp-Nummer gesendet — es gibt keine agentenspezifische Absenderidentität.

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

Die Zugriffskontrolle für Direktnachrichten (Kopplung/Zulassungsliste) gilt global pro WhatsApp-Konto, nicht pro Agent. Binden Sie gemeinsam genutzte Gruppen an einen Agenten oder verwenden Sie Broadcast-Gruppen.

Routing-Regeln

Bindungen sind deterministisch, und die spezifischste Bindung gewinnt. Die vollständige Rangfolge (exakter Peer, übergeordneter Peer, Peer-Platzhalter, Guild+Rollen, Guild, Team, Konto, Kanal, Standardagent) finden Sie unter Kanal-Routing. Einige hier besonders erwähnenswerte Regeln:

• Wenn innerhalb derselben Rangstufe mehrere Bindungen übereinstimmen, gewinnt die erste in der Konfigurationsreihenfolge.
• Wenn eine Bindung mehrere Abgleichsfelder festlegt (beispielsweise peer + guildId), müssen alle angegebenen Felder übereinstimmen (AND-Semantik).
• Eine Bindung ohne accountId stimmt ausschließlich mit dem Standardkonto überein, nicht mit jedem Konto. Verwenden Sie accountId: "*" als kanalweiten Fallback oder accountId: "<name>" für ein bestimmtes Konto. Wenn dieselbe Bindung erneut mit einer expliziten Konto-ID hinzugefügt wird, wird die vorhandene reine Kanalbindung aktualisiert, statt sie zu duplizieren.

Mehrere Konten/Telefonnummern

Kanäle, die mehrere Konten unterstützen (z. B. WhatsApp), verwenden accountId, um jede Anmeldung zu identifizieren. Jede accountId wird an einen eigenen Agenten weitergeleitet, sodass ein Server mehrere Telefonnummern hosten kann, ohne Sitzungen zu vermischen.

Legen Sie mit channels.<channel>.defaultAccount das Konto fest, das verwendet wird, wenn accountId fehlt. Wenn dieser Wert nicht gesetzt ist, greift OpenClaw auf default zurück, sofern vorhanden, andernfalls auf die erste konfigurierte Konto-ID (sortiert).

Kanäle mit Unterstützung für mehrere Konten: discord, feishu, googlechat, imessage, irc, line, mattermost, matrix, nextcloud-talk, nostr, signal, slack, telegram, whatsapp, zalo, zalouser.

Konzepte

• agentId: ein „Gehirn“ (Workspace, agentenspezifische Authentifizierung, agentenspezifischer Sitzungsspeicher).
• accountId: eine Instanz eines Kanalkontos (z. B. WhatsApp-Konto personal gegenüber biz).
• binding: leitet eingehende Nachrichten anhand von (channel, accountId, peer) und optional Gilden-/Team-IDs an eine agentId weiter.
• Direktchats werden zu agent:<agentId>:<mainKey> zusammengeführt (agentenspezifischer „Hauptkanal“; siehe session.mainKey).

Plattformbeispiele

{  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",      },    ],  },   // Deterministisches Routing: Der erste Treffer gewinnt (spezifischster zuerst).  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },     // Optionale Überschreibung pro Peer (Beispiel: eine bestimmte Gruppe an den Arbeitsagenten senden).    {      agentId: "work",      match: {        channel: "whatsapp",        accountId: "personal",        peer: { kind: "group", id: "1203630...@g.us" },      },    },  ],   // Standardmäßig deaktiviert: Agent-zu-Agent-Nachrichten müssen ausdrücklich aktiviert und zugelassen werden.  tools: {    agentToAgent: {      enabled: false,      allow: ["home", "work"],    },  },   channels: {    whatsapp: {      accounts: {        personal: {          // Optionale Überschreibung. Standard: ~/.openclaw/credentials/whatsapp/personal          // authDir: "~/.openclaw/credentials/whatsapp/personal",        },        biz: {          // Optionale Überschreibung. Standard: ~/.openclaw/credentials/whatsapp/biz          // authDir: "~/.openclaw/credentials/whatsapp/biz",        },      },    },  },}

Gängige Muster

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

Agentenspezifische Sandbox- und Tool-Konfiguration

Jeder Agent kann über eigene Sandbox- und Tool-Beschränkungen verfügen:

{  agents: {    list: [      {        id: "personal",        workspace: "~/.openclaw/workspace-personal",        sandbox: {          mode: "off",  // Keine Sandbox für den persönlichen Agenten        },        // Keine Tool-Beschränkungen – alle Tools sind verfügbar      },      {        id: "family",        workspace: "~/.openclaw/workspace-family",        sandbox: {          mode: "all",     // Immer in einer Sandbox          scope: "agent",  // Ein Container pro Agent          docker: {            // Optionale einmalige Einrichtung nach der Container-Erstellung            setupCommand: "apt-get update && apt-get install -y git curl",          },        },        tools: {          allow: ["read"],                    // Nur das Lese-Tool          deny: ["exec", "write", "edit", "apply_patch"],    // Andere sperren        },      },    ],  },}

Dies bietet Ihnen:

• Sicherheitsisolierung: Beschränken Sie Tools für nicht vertrauenswürdige Agenten.
• Ressourcenkontrolle: Führen Sie bestimmte Agenten in einer Sandbox aus, während andere auf dem Host verbleiben.
• Flexible Richtlinien: unterschiedliche Berechtigungen pro Agent.

Ausführliche Beispiele finden Sie unter Sandbox und Tools für mehrere Agenten.

Verwandte Themen

• ACP-Agenten — externe Coding-Harnesses ausführen
• Kanal-Routing — wie Nachrichten an Agenten weitergeleitet werden
• Präsenz — Präsenz und Verfügbarkeit von Agenten
• Sitzung — Sitzungsisolierung und Routing
• Unteragenten — Agentenläufe im Hintergrund starten