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, Modellregistrierung 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, Modellregistrierung, 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 Basis und agents.entries.*.skills für einen agentenspezifischen Ersatz (explizite Einträge ersetzen den Standard, sie werden nicht zusammengeführt). Siehe Skills: agentenspezifisch und gemeinsam genutzt und Skills: Agentenzulassungslisten.

Der Plugin-eigene Speicher richtet sich nach der Konfiguration dieses 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 kein kompiliertes Wiki-Wissen gemeinsam nutzen dürfen.

Pfade

Einzelagentenmodus (Standard)

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

• agentId verwendet standardmäßig main.
• Sitzungsschlüssel haben das Format agent:main:<mainKey> (der Standardwert mainKey ist main).
• Der Workspace verwendet standardmäßig ~/.openclaw/workspace (oder workspace-<profile>, wenn OPENCLAW_PROFILE auf einen anderen Wert als default gesetzt ist).
• Der Zustand verwendet standardmäßig ~/.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 an, dies für Sie zu erledigen), 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

Jeder 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 nur durch explizite Funktionen oder die Plugin-Konfiguration aktiviert.

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

Agentenspezifische Memory-Wiki-Vaults

Memory Wiki verwendet standardmäßig ein globales Vault. Um das kompilierte 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 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 zur Bridge-Filterung, Migration und zu 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.entries.*.memory.search.qmd.extraCollections zusätzliche Sammlungen hinzu. Verwenden Sie memory.search.qmd.extraCollections, wenn alle Agenten dieselben Sammlungen gemeinsam nutzen sollen.

{  agents: {    defaults: {      workspace: "~/workspaces/main",    },    entries: {      main: {        workspace: "~/workspaces/main",        memory: {          search: {            qmd: {              extraCollections: [{ path: "notes" }], // wird im Workspace aufgelöst -> Sammlung mit dem Namen "notes-main"            },          },        },      },      family: { workspace: "~/workspaces/family" },    },  },  memory: {    backend: "qmd",    search: {      qmd: {        extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],      },    },    qmd: { includeDefaultMemory: false },  },}

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

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

Leiten Sie verschiedene WhatsApp-DMs in 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 DM-Zugriffssteuerung (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; die spezifischste Übereinstimmung gewinnt. Die vollständige Rangfolge (exakter Kommunikationspartner, übergeordneter Kommunikationspartner, Platzhalter für Kommunikationspartner, Guild und Rollen, Guild, Team, Konto, Kanal, Standardagent) finden Sie unter Kanal-Routing. Einige Regeln sind hier besonders hervorzuheben:

• Wenn mehrere Bindungen innerhalb derselben Rangstufe ü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 nur mit dem Standardkonto überein, nicht mit jedem Konto. Verwenden Sie accountId: "*" für einen kanalweiten Fallback oder accountId: "<name>" für ein einzelnes Konto. Wenn dieselbe Bindung erneut mit einer expliziten Konto-ID hinzugefügt wird, wird die bestehende 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. Jedes accountId wird an einen eigenen Agenten weitergeleitet, sodass ein Server mehrere Telefonnummern hosten kann, ohne Sitzungen zu vermischen.

Setzen Sie channels.<channel>.defaultAccount, um das Konto auszuwählen, das verwendet wird, wenn accountId weggelassen wird. Ist dies nicht festgelegt, 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“ (Arbeitsbereich, 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 anhand von Guild-/Team-IDs an einen agentId weiter.
• Direktchats werden in agent:<agentId>:<mainKey> zusammengeführt (agentenspezifisch „main“; 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: Die erste Übereinstimmung gewinnt (die spezifischste zuerst).  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },     // Optionale Override-Regel 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: Die Kommunikation zwischen Agenten muss ausdrücklich aktiviert und in die Positivliste aufgenommen werden.  tools: {    agentToAgent: {      enabled: false,      allow: ["home", "work"],    },  },   channels: {    whatsapp: {      accounts: {        personal: {          // Optionale Override-Regel. Standard: ~/.openclaw/credentials/whatsapp/personal          // authDir: "~/.openclaw/credentials/whatsapp/personal",        },        biz: {          // Optionale Override-Regel. 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 eigene Sandbox- und Tool-Einschränkungen haben:

{  agents: {    list: [      {        id: "personal",        workspace: "~/.openclaw/workspace-personal",        sandbox: {          mode: "off",  // Keine Sandbox für den persönlichen Agenten        },        // Keine Tool-Einschrä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 verweigern        },      },    ],  },}

Dies bietet Ihnen:

• Sicherheitsisolierung: Tools für nicht vertrauenswürdige Agenten einschränken.
• Ressourcenkontrolle: Bestimmte Agenten in einer Sandbox ausführen, 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 — Ausführen externer Coding-Harnesses
• Kanal-Routing — wie Nachrichten an Agenten weitergeleitet werden
• Präsenz — Präsenz und Verfügbarkeit von Agenten
• Sitzung — Sitzungsisolierung und Routing
• Unteragenten — Starten von Agentenläufen im Hintergrund