Multi-Agenten-Routing

Führen Sie mehrere isolierte Agenten aus – jeder mit eigenem Workspace, Zustandsverzeichnis (agentDir) und Sitzungsverlauf – plus mehrere Kanal-Konten (z. B. zwei WhatsApp-Konten) in einem laufenden Gateway. Eingehende Nachrichten werden über Bindings an den richtigen Agenten weitergeleitet.

Ein Agent ist hier der vollständige Scope pro Persona: Workspace-Dateien, Authentifizierungsprofile, Modell-Registry und Sitzungsspeicher. agentDir ist das Zustandsverzeichnis auf der Festplatte, das diese agentenspezifische Konfiguration unter ~/.openclaw/agents/<agentId>/ enthält. Ein Binding ordnet ein Kanal-Konto (z. B. einen Slack-Workspace oder eine WhatsApp-Nummer) einem dieser Agenten zu.

Was ist „ein Agent“?

Ein Agent ist ein vollständig abgegrenztes Gehirn mit eigenem:

• Workspace (Dateien, AGENTS.md/SOUL.md/USER.md, lokale Notizen, Persona-Regeln).
• Zustandsverzeichnis (agentDir) für Authentifizierungsprofile, Modell-Registry und agentenspezifische Konfiguration.
• Sitzungsspeicher (Chatverlauf + Routing-Zustand) unter ~/.openclaw/agents/<agentId>/sessions.

Authentifizierungsprofile sind agentenspezifisch. Jeder Agent liest aus seiner eigenen Datei:

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

Skills werden aus jedem Agenten-Workspace sowie gemeinsamen Roots wie ~/.openclaw/skills geladen und dann nach der effektiven Skill-Allowlist des Agenten gefiltert, sofern konfiguriert. Verwenden Sie agents.defaults.skills für eine gemeinsame Basis und agents.list[].skills für agentenspezifischen Ersatz. Siehe Skills: agentenspezifisch vs. gemeinsam und Skills: Skill-Allowlists für Agenten.

Das Gateway kann einen Agenten (Standard) oder viele Agenten nebeneinander hosten.

Pfade (Schnellübersicht)

• Konfiguration: ~/.openclaw/openclaw.json (oder OPENCLAW_CONFIG_PATH)
• Zustandsverzeichnis: ~/.openclaw (oder OPENCLAW_STATE_DIR)
• Workspace: ~/.openclaw/workspace (oder ~/.openclaw/workspace-<agentId>)
• Agentenverzeichnis: ~/.openclaw/agents/<agentId>/agent (oder agents.list[].agentDir)
• Sitzungen: ~/.openclaw/agents/<agentId>/sessions

Einzelagentenmodus (Standard)

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

• agentId ist standardmäßig main.
• Sitzungen werden als agent:main:<mainKey> geschlüsselt.
• Der Workspace ist standardmäßig ~/.openclaw/workspace (oder ~/.openclaw/workspace-<profile>, wenn OPENCLAW_PROFILE gesetzt ist).
• Der Zustand ist standardmäßig ~/.openclaw/agents/main/agent.

Agentenhelfer

Verwenden Sie den Agenten-Wizard, um einen neuen isolierten Agenten hinzuzufügen:

openclaw agents add work

Fügen Sie anschließend bindings hinzu (oder lassen Sie dies den Wizard erledigen), um eingehende Nachrichten weiterzuleiten.

Prüfen Sie mit:

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 Personen, mehrere Persönlichkeiten

Mit mehreren Agenten wird jede agentId zu einer vollständig isolierten Persona:

• Unterschiedliche Telefonnummern/Konten (pro Kanal accountId).
• Unterschiedliche Persönlichkeiten (agentenspezifische Workspace-Dateien wie AGENTS.md und SOUL.md).
• Getrennte Authentifizierung + Sitzungen (keine Überschneidungen, sofern nicht ausdrücklich aktiviert).

So können mehrere Personen einen Gateway-Server gemeinsam nutzen, während ihre KI-„Gehirne“ und Daten isoliert bleiben.

Agentenübergreifende QMD-Speichersuche

Wenn ein Agent die QMD-Sitzungstranskripte eines anderen Agenten durchsuchen soll, fügen Sie zusätzliche Collections unter agents.list[].memorySearch.qmd.extraCollections hinzu. Verwenden Sie agents.defaults.memorySearch.qmd.extraCollections nur, wenn jeder Agent dieselben gemeinsamen Transkript-Collections erben 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" }], // resolves inside workspace -> collection named "notes-main"          },        },      },      { id: "family", workspace: "~/workspaces/family" },    ],  },  memory: {    backend: "qmd",    qmd: { includeDefaultMemory: false },  },}

Der zusätzliche Collection-Pfad kann zwischen Agenten geteilt werden, aber der Collection-Name bleibt explizit, wenn der Pfad außerhalb des Agenten-Workspace liegt. Pfade innerhalb des Workspace bleiben agentenspezifisch, sodass jeder Agent seinen eigenen Transkript-Suchbestand behält.

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

Sie können verschiedene WhatsApp-DMs an verschiedene Agenten weiterleiten und dabei ein WhatsApp-Konto verwenden. Gleichen Sie den Absender in E.164 (wie +15551234567) mit peer.kind: "direct" ab. Antworten kommen weiterhin von derselben WhatsApp-Nummer (keine agentenspezifische Absenderidentität).

Beispiel:

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

Hinweise:

• DM-Zugriffskontrolle ist global pro WhatsApp-Konto (Pairing/Allowlist), nicht pro Agent.
• Für gemeinsame Gruppen binden Sie die Gruppe an einen Agenten oder verwenden Sie Broadcast-Gruppen.

Routing-Regeln (wie Nachrichten einen Agenten auswählen)

Bindings sind deterministisch und die spezifischste Übereinstimmung gewinnt:

Mehrere Konten / Telefonnummern

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

Wenn Sie ein kanalweites Standardkonto wünschen, wenn accountId ausgelassen wird, setzen Sie channels.<channel>.defaultAccount (optional). Wenn nicht gesetzt, fällt OpenClaw auf default zurück, sofern vorhanden, andernfalls auf die erste konfigurierte Konto-ID (sortiert).

Häufige Kanäle, die dieses Muster unterstützen, sind:

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

Konzepte

• agentId: ein „Gehirn“ (Workspace, agentenspezifische Authentifizierung, agentenspezifischer Sitzungsspeicher).
• accountId: eine Kanal-Kontoinstanz (z. B. WhatsApp-Konto "personal" vs. "biz").
• binding: leitet eingehende Nachrichten anhand von (channel, accountId, peer) und optional Guild-/Team-IDs an eine agentId weiter.
• Direktchats fallen auf agent:<agentId>:<mainKey> zusammen (agentenspezifisches „main“; 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",      },    ],  },   // 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",        },      },    },  },}

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

Sandbox- und Tool-Konfiguration pro Agent

Jeder Agent kann eigene Sandbox- und Tool-Beschränkungen haben:

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

Vorteile:

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

Siehe Multi-Agent-Sandbox und Tools für detaillierte Beispiele.

Verwandte Themen

• ACP-Agents — externe Coding-Harnesses ausführen
• Kanal-Routing — wie Nachrichten an Agents weitergeleitet werden
• Presence — Präsenz und Verfügbarkeit von Agents
• Session — Sitzungsisolation und Routing
• Sub-Agents — Agent-Läufe im Hintergrund starten