Multi-Agent Routing

Ziel: Mehrere isolierte Agents (jeweils eigener Workspace + agentDir + Sessions) plus mehrere Channel-Accounts (z.B. zwei WhatsApp-Nummern) in einem laufenden Gateway. Eingehende Nachrichten werden per Bindings an einen Agent geroutet.

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).
• State-Verzeichnis (agentDir) für Auth-Profile, Model-Registry und Agent-spezifische Konfiguration.
• Session-Speicher (Chat-Verlauf + Routing-Status) unter ~/.openclaw/agents/<agentId>/sessions.

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

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

Credentials des Haupt-Agents werden nicht automatisch geteilt. Verwende niemals dasselbe agentDir für mehrere Agents (das führt zu Auth/Session-Konflikten). Wenn du Credentials teilen willst, kopiere auth-profiles.json in das agentDir des anderen Agents.

Skills sind pro Agent im skills/-Ordner des jeweiligen Workspace, mit geteilten Skills aus ~/.openclaw/skills. Siehe Skills: pro Agent vs. geteilt.

Das Gateway kann einen Agent (Standard) oder mehrere Agents parallel hosten.

Hinweis zum Workspace: Der Workspace jedes Agents ist das Standard-cwd, keine harte Sandbox. Relative Pfade werden im Workspace aufgelöst, aber absolute Pfade können andere Host-Verzeichnisse erreichen, sofern Sandboxing nicht aktiviert ist. Siehe Sandboxing.

Pfade (Kurzübersicht)

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

Single-Agent-Modus (Standard)

Ohne weitere Konfiguration läuft OpenClaw mit einem einzelnen Agent:

• agentId ist standardmäßig main.
• Sessions werden als agent:main:<mainKey> gespeichert.
• Workspace ist standardmäßig ~/.openclaw/workspace (oder ~/.openclaw/workspace-<profile> wenn OPENCLAW_PROFILE gesetzt ist).
• State ist standardmäßig ~/.openclaw/agents/main/agent.

Agent-Assistent

Mit dem Agent-Wizard fügst du einen neuen isolierten Agent hinzu:

openclaw agents add work

Dann füge bindings hinzu (oder lass den Wizard das machen), um eingehende Nachrichten zu routen.

Prüfe mit:

openclaw agents list --bindings

Mehrere Agents = mehrere Personen, mehrere Persönlichkeiten

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

• Verschiedene Telefonnummern/Accounts (pro Channel accountId).
• Verschiedene Persönlichkeiten (Agent-spezifische Workspace-Dateien wie AGENTS.md und SOUL.md).
• Getrennte Auth + Sessions (kein Crosstalk, außer explizit aktiviert).

So können mehrere Personen einen Gateway-Server teilen und trotzdem ihre KI-”Gehirne” und Daten isoliert halten.

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

Du kannst verschiedene WhatsApp-DMs an verschiedene Agents routen, während du einen WhatsApp-Account verwendest. Matche auf Absender-E.164 (wie +15551234567) mit peer.kind: "dm". Antworten kommen weiterhin von derselben WhatsApp-Nummer (keine Agent-spezifische Absenderidentität).

Wichtiges Detail: Direkte Chats werden auf den Main-Session-Key des Agents zusammengeführt, echte Isolation erfordert also einen Agent 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: "dm", id: "+15551230001" } } },
    { agentId: "mia", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } },
  ],
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551230001", "+15551230002"],
    },
  },
}

Hinweise:

• DM-Zugriffskontrolle ist global pro WhatsApp-Account (Pairing/Allowlist), nicht pro Agent.
• Für geteilte Gruppen binde die Gruppe an einen Agent oder nutze Broadcast-Gruppen.

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

Bindings sind deterministisch und spezifischste gewinnt:

1. peer-Match (exakte DM/Gruppen/Channel-ID)
2. guildId (Discord)
3. teamId (Slack)
4. accountId-Match für einen Channel
5. Channel-weiter Match (accountId: "*")
6. Fallback auf Standard-Agent (agents.list[].default, sonst erster Listeneintrag, Standard: main)

Mehrere Accounts / Telefonnummern

Channels, die mehrere Accounts unterstützen (z.B. WhatsApp), verwenden accountId zur Identifikation jedes Logins. Jede accountId kann an einen anderen Agent geroutet werden, sodass ein Server mehrere Telefonnummern hosten kann, ohne Sessions zu vermischen.

Konzepte

• agentId: Ein “Gehirn” (Workspace, Agent-spezifische Auth, Agent-spezifischer Session-Speicher).
• accountId: Eine Channel-Account-Instanz (z.B. WhatsApp-Account "personal" vs "biz").
• binding: Routet eingehende Nachrichten an eine agentId per (channel, accountId, peer) und optional Guild/Team-IDs.
• Direkte Chats werden zu agent:<agentId>:<mainKey> zusammengeführt (Agent-spezifischer “Main”; session.mainKey).

Beispiel: Zwei WhatsApps zu zwei Agents

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

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

  // Standardmäßig aus: Agent-zu-Agent-Messaging muss explizit aktiviert + allowlisted 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 für Alltags-Chat + Telegram für Deep Work

Aufteilen nach Channel: WhatsApp an einen schnellen Alltags-Agent und Telegram an einen Opus-Agent 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-5",
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}

Hinweise:

• Bei mehreren Accounts für einen Channel füge accountId zum Binding hinzu (z.B. { channel: "whatsapp", accountId: "personal" }).
• Um eine einzelne DM/Gruppe an Opus zu routen und den Rest auf Chat zu lassen, füge ein match.peer-Binding für diesen Peer hinzu; Peer-Matches gewinnen immer gegen Channel-weite Regeln.

Beispiel: Gleicher Channel, ein Peer zu Opus

WhatsApp auf dem schnellen Agent 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-5",
      },
    ],
  },
  bindings: [
    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}

Peer-Bindings gewinnen immer, also setze sie über die Channel-weite Regel.

Family-Agent an eine WhatsApp-Gruppe gebunden

Binde einen dedizierten Family-Agent an eine einzelne WhatsApp-Gruppe, mit Mention-Gating und strengerer 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 sind Tools, keine Skills. Wenn ein Skill ein Binary ausführen muss, stelle sicher, dass exec erlaubt ist und das Binary in der Sandbox existiert.
• Für strengeres Gating setze agents.list[].groupChat.mentionPatterns und halte Gruppen-Allowlists für den Channel aktiviert.

Agent-spezifische Sandbox- und Tool-Konfiguration

Ab v2026.1.6 kann jeder Agent eigene Sandbox- und Tool-Einschränkungen haben:

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // Keine Sandbox für den Personal-Agent
        },
        // Keine Tool-Einschränkungen - alle Tools verfügbar
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // Immer sandboxed
          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 verweigern
        },
      },
    ],
  },
}

Hinweis: setupCommand liegt unter sandbox.docker und wird einmal bei Container-Erstellung ausgeführt. Agent-spezifische sandbox.docker.*-Overrides werden ignoriert, wenn der aufgelöste Scope "shared" ist.

Vorteile:

• Sicherheitsisolation: Tools für nicht vertrauenswürdige Agents einschränken
• Ressourcenkontrolle: Bestimmte Agents sandboxen, während andere auf dem Host laufen
• Flexible Policies: Unterschiedliche Berechtigungen pro Agent

Hinweis: tools.elevated ist global und absenderbasiert; es ist nicht pro Agent konfigurierbar. Wenn du Agent-spezifische Grenzen brauchst, nutze agents.list[].tools um exec zu verweigern. Für Gruppen-Targeting nutze agents.list[].groupChat.mentionPatterns, damit @Mentions sauber auf den gewünschten Agent gemappt werden.

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