Multi-Agent-Routing

Ziel: mehrere isolierte Agenten (separater Workspace + agentDir + Sitzungen), dazu mehrere Kanal-Accounts (z.B. zwei WhatsApp-Nummern) in einem laufenden Gateway. Eingehende Nachrichten werden ueber Bindings an einen Agenten geroutet.

Was ist “ein Agent”?

Ein Agent ist ein vollstaendig abgegrenztes Gehirn mit eigenem:

  • Workspace (Dateien, AGENTS.md/SOUL.md/USER.md, lokale Notizen, Persona-Regeln).
  • State-Verzeichnis (agentDir) fuer Auth-Profile, Model-Registry und pro-Agent-Config.
  • Sitzungsspeicher (Chat-Historie + Routing-State) unter ~/.openclaw/agents/<agentId>/sessions.

Auth-Profile sind pro Agent. Jeder Agent liest aus seinem eigenen:

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

Zugangsdaten des Haupt-Agenten werden nicht automatisch geteilt. Verwende agentDir nie fuer mehrere Agenten gleichzeitig (das fuehrt zu Auth-/Session-Kollisionen). Wenn du Zugangsdaten teilen willst, kopiere auth-profiles.json in das agentDir des anderen Agenten.

Skills sind pro Agent ueber den skills/-Ordner jedes Workspaces verfuegbar, mit geteilten Skills aus ~/.openclaw/skills. Siehe Skills: pro Agent vs. geteilt.

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

Workspace-Hinweis: Der Workspace jedes Agenten ist das Standard-cwd, keine harte Sandbox. Relative Pfade loesen innerhalb des Workspaces auf, aber absolute Pfade koennen auf andere Host-Orte zugreifen, sofern Sandboxing nicht aktiviert ist. Siehe Sandboxing.

Pfade (Schnelluebersicht)

  • Config: ~/.openclaw/openclaw.json (oder OPENCLAW_CONFIG_PATH)
  • State-Dir: ~/.openclaw (oder OPENCLAW_STATE_DIR)
  • Workspace: ~/.openclaw/workspace (oder ~/.openclaw/workspace-<agentId>)
  • Agent-Dir: ~/.openclaw/agents/<agentId>/agent (oder agents.list[].agentDir)
  • Sitzungen: ~/.openclaw/agents/<agentId>/sessions

Einzelagent-Modus (Standard)

Ohne weitere Einstellungen betreibt OpenClaw einen einzelnen Agenten:

  • agentId ist standardmaessig main.
  • Sitzungen werden als agent:main:<mainKey> geschluesselt.
  • Workspace-Standard ist ~/.openclaw/workspace (oder ~/.openclaw/workspace-<profile>, wenn OPENCLAW_PROFILE gesetzt ist).
  • State-Standard ist ~/.openclaw/agents/main/agent.

Agent-Helfer

Nutze den Agent-Assistenten, um einen neuen isolierten Agenten hinzuzufuegen:

openclaw agents add work

Fuege dann bindings hinzu (oder lass den Assistenten das erledigen), um eingehende Nachrichten zu routen.

Pruefe mit:

openclaw agents list --bindings

Schnellstart

Schritt 1: Jeden Agent-Workspace erstellen

Nutze den Assistenten oder erstelle Workspaces manuell:

openclaw agents add coding
openclaw agents add social

Jeder Agent bekommt seinen eigenen Workspace mit SOUL.md, AGENTS.md und optionalem USER.md, dazu ein dediziertes agentDir und einen Sitzungsspeicher unter ~/.openclaw/agents/<agentId>.

Schritt 2: Kanal-Accounts erstellen

Erstelle einen Account pro Agent auf deinen bevorzugten Kanaelen:

  • Discord: einen Bot pro Agent, Message Content Intent aktivieren, jeden Token kopieren.
  • Telegram: einen Bot pro Agent ueber BotFather, jeden Token kopieren.
  • WhatsApp: jede Telefonnummer pro Account verknuepfen.
openclaw channels login --channel whatsapp --account work

Siehe Kanal-Anleitungen: Discord, Telegram, WhatsApp.

Schritt 3: Agenten, Accounts und Bindings hinzufuegen

Fuege Agenten unter agents.list, Kanal-Accounts unter channels.<channel>.accounts und verbinde sie mit bindings (Beispiele unten).

Schritt 4: Neustart und Verifikation

openclaw gateway restart
openclaw agents list --bindings
openclaw channels status --probe

Mehrere Agenten = mehrere Personen, mehrere Persoenlichkeiten

Mit mehreren Agenten wird jede agentId zu einer vollstaendig isolierten Persona:

  • Verschiedene Telefonnummern/Accounts (pro Kanal-accountId).
  • Verschiedene Persoenlichkeiten (pro-Agent-Workspace-Dateien wie AGENTS.md und SOUL.md).
  • Separate Auth und Sitzungen (kein Uebersprechen, sofern nicht explizit aktiviert).

So koennen mehrere Personen einen Gateway-Server teilen und dabei ihre KI-”Gehirne” und Daten isoliert halten.

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

Du kannst verschiedene WhatsApp-DMs an verschiedene Agenten routen und dabei auf einem WhatsApp-Account bleiben. Matche auf Absender-E.164 (wie +15551234567) mit peer.kind: "direct". Antworten kommen weiterhin von derselben WhatsApp-Nummer (keine pro-Agent-Absenderidentitaet).

Wichtiges Detail: Direktchats werden zum Hauptsitzungsschluessel des Agenten zusammengefuehrt, echte Isolation erfordert also einen Agenten pro Person.

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-Account (Pairing/Allowlist), nicht pro Agent.
  • Fuer geteilte Gruppen binde die Gruppe an einen Agenten oder verwende Broadcast-Gruppen.

Routing-Regeln (wie Nachrichten einen Agenten waehlen)

Bindings sind deterministisch und spezifischster Treffer gewinnt:

  1. peer-Match (exakte DM/Gruppen/Kanal-ID)
  2. parentPeer-Match (Thread-Vererbung)
  3. guildId + roles (Discord-Rollen-Routing)
  4. guildId (Discord)
  5. teamId (Slack)
  6. accountId-Match fuer einen Kanal
  7. Kanal-Level-Match (accountId: "*")
  8. Fallback auf Standard-Agent (agents.list[].default, sonst erster Listeneintrag, Standard: main)

Wenn mehrere Bindings in derselben Stufe matchen, gewinnt das erste in der Config-Reihenfolge. Wenn ein Binding mehrere Match-Felder setzt (zum Beispiel peer + guildId), muessen alle angegebenen Felder zutreffen (AND-Semantik).

Wichtiges Detail zum Account-Scope:

  • Ein Binding, das accountId weglaeest, matcht nur den Standard-Account.
  • Verwende accountId: "*" fuer einen kanalweiten Fallback ueber alle Accounts.
  • Wenn du spaeter dasselbe Binding fuer denselben Agenten mit einer expliziten Account-ID hinzufuegst, stuft OpenClaw das bestehende Kanal-only-Binding zu account-scoped hoch, statt es zu duplizieren.

Mehrere Accounts / Telefonnummern

Kanaele, die mehrere Accounts unterstuetzen (z.B. WhatsApp), verwenden accountId zur Identifikation jedes Logins. Jede accountId kann an einen anderen Agenten geroutet werden, sodass ein Server mehrere Telefonnummern hosten kann, ohne Sitzungen zu vermischen.

Wenn du einen kanalweiten Standard-Account willst, wenn accountId weggelassen wird, setze channels.<channel>.defaultAccount (optional). Wenn nicht gesetzt, faellt OpenClaw auf default zurueck, falls vorhanden, sonst die erste konfigurierte Account-ID (sortiert).

Gaengige Kanaele, die dieses Muster unterstuetzen:

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

Konzepte

  • agentId: ein “Gehirn” (Workspace, pro-Agent-Auth, pro-Agent-Sitzungsspeicher).
  • accountId: eine Kanal-Account-Instanz (z.B. WhatsApp-Account "personal" vs. "biz").
  • binding: routet eingehende Nachrichten an eine agentId ueber (channel, accountId, peer) und optionale Guild-/Team-IDs.
  • Direktchats werden zu agent:<agentId>:<mainKey> zusammengefuehrt (pro-Agent “main”; session.mainKey).

Plattform-Beispiele

Discord-Bots pro Agent

Jeder Discord-Bot-Account wird einer eindeutigen accountId zugeordnet. Binde jeden Account an einen Agenten und halte Allowlists pro Bot.

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

Hinweise:

  • Lade jeden Bot zur Guild ein und aktiviere Message Content Intent.
  • Tokens liegen in channels.discord.accounts.<id>.token (Standard-Account kann DISCORD_BOT_TOKEN verwenden).

Telegram-Bots pro Agent

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

Hinweise:

  • Erstelle einen Bot pro Agent mit BotFather und kopiere jeden Token.
  • Tokens liegen in channels.telegram.accounts.<id>.botToken (Standard-Account kann TELEGRAM_BOT_TOKEN verwenden).

WhatsApp-Nummern pro Agent

Verknuepfe jeden Account, bevor du das Gateway startest:

openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz

~/.openclaw/openclaw.json (JSON5):

{
  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: erster Treffer gewinnt (spezifischster zuerst).
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },

    // Optionaler Pro-Peer-Override (Beispiel: eine bestimmte Gruppe an den Work-Agent senden).
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "personal",
        peer: { kind: "group", id: "[email protected]" },
      },
    },
  ],

  // Standardmaessig deaktiviert: Agent-zu-Agent-Messaging muss explizit aktiviert + allowgelistet werden.
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },

  channels: {
    whatsapp: {
      accounts: {
        personal: {
          // Optionaler Override. Standard: ~/.openclaw/credentials/whatsapp/personal
          // authDir: "~/.openclaw/credentials/whatsapp/personal",
        },
        biz: {
          // Optionaler Override. Standard: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

Beispiel: WhatsApp-Alltagschat + Telegram Deep Work

Nach Kanal aufteilen: WhatsApp an einen schnellen Alltagsagenten routen und Telegram an einen Opus-Agenten.

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        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" } },
  ],
}

Hinweise:

  • Wenn du mehrere Accounts fuer einen Kanal hast, fuege accountId zum Binding hinzu (zum Beispiel { channel: "whatsapp", accountId: "personal" }).
  • Um eine einzelne DM/Gruppe an Opus zu routen, waehrend der Rest auf Chat bleibt, fuege ein match.peer-Binding fuer diesen Peer hinzu; Peer-Matches gewinnen immer ueber kanalweite Regeln.

Beispiel: Gleicher Kanal, ein Peer an Opus

WhatsApp auf dem schnellen Agenten lassen, aber eine DM an Opus routen:

{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-5",
      },
      {
        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" } },
  ],
}

Peer-Bindings gewinnen immer, also halte sie ueber der kanalweiten Regel.

Familien-Agent an eine WhatsApp-Gruppe gebunden

Binde einen dedizierten Familien-Agenten an eine einzelne WhatsApp-Gruppe, mit Mention-Gating und einer strengeren Tool-Policy:

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

Hinweise:

  • Tool-Allow/Deny-Listen betreffen Tools, nicht Skills. Wenn ein Skill eine Binary ausfuehren muss, stelle sicher, dass exec erlaubt ist und die Binary in der Sandbox existiert.
  • Fuer strengeres Gating setze agents.list[].groupChat.mentionPatterns und halte Gruppen-Allowlists fuer den Kanal aktiviert.

Pro-Agent-Sandbox und Tool-Konfiguration

Seit v2026.1.6 kann jeder Agent seine eigene Sandbox und Tool-Einschraenkungen haben:

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // Keine Sandbox fuer den persoenlichen Agenten
        },
        // Keine Tool-Einschraenkungen - alle Tools verfuegbar
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // Immer in Sandbox
          scope: "agent",  // Ein Container pro Agent
          docker: {
            // Optionales einmaliges Setup nach Container-Erstellung
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // Nur Read-Tool
          deny: ["exec", "write", "edit", "apply_patch"],    // Andere ablehnen
        },
      },
    ],
  },
}

Hinweis: setupCommand liegt unter sandbox.docker und wird einmal bei der Container-Erstellung ausgefuehrt. Pro-Agent-sandbox.docker.*-Overrides werden ignoriert, wenn der aufgeloeste Scope "shared" ist.

Vorteile:

  • Sicherheitsisolation: Tools fuer nicht vertrauenswuerdige Agenten einschraenken
  • Ressourcenkontrolle: Bestimmte Agenten in Sandbox halten, waehrend andere auf dem Host laufen
  • Flexible Richtlinien: Unterschiedliche Berechtigungen pro Agent

Hinweis: tools.elevated ist global und absenderbasiert; es ist nicht pro Agent konfigurierbar. Wenn du pro-Agent-Grenzen brauchst, verwende agents.list[].tools, um exec zu verweigern. Fuer Gruppen-Targeting verwende agents.list[].groupChat.mentionPatterns, damit @Mentions sauber auf den beabsichtigten Agenten abgebildet werden.

Siehe Multi-Agent Sandbox und Tools fuer ausfuehrliche Beispiele.

arrow_back
Zurück
Compaction
Weiter
Presence
arrow_forward