Çoklu ajan yönlendirmesi

Bir çalışan Gateway içinde birden çok yalıtılmış ajan çalıştırın — her biri kendi çalışma alanı, durum dizini (agentDir) ve oturum geçmişiyle — ayrıca birden çok kanal hesabı (ör. iki WhatsApp) kullanın. Gelen iletiler bağlamalar üzerinden doğru ajana yönlendirilir.

Buradaki ajan, kişi başına tam kapsamdır: çalışma alanı dosyaları, kimlik doğrulama profilleri, model kayıt defteri ve oturum deposu. agentDir, bu ajan başına yapılandırmayı ~/.openclaw/agents/<agentId>/ konumunda tutan disk üzerindeki durum dizinidir. Bağlama, bir kanal hesabını (ör. bir Slack çalışma alanı veya bir WhatsApp numarası) bu ajanlardan birine eşler.

"Tek ajan" nedir?

Bir ajan, kendine ait tam kapsamlı bir beyindir:

• Çalışma alanı (dosyalar, AGENTS.md/SOUL.md/USER.md, yerel notlar, persona kuralları).
• Kimlik doğrulama profilleri, model kayıt defteri ve ajan başına yapılandırma için durum dizini (agentDir).
• ~/.openclaw/agents/<agentId>/sessions altında oturum deposu (sohbet geçmişi + yönlendirme durumu).

Kimlik doğrulama profilleri ajan başınadır. Her ajan kendi şuradan okur:

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

Skills, her ajan çalışma alanından ve ~/.openclaw/skills gibi paylaşılan köklerden yüklenir, ardından yapılandırıldığında etkin ajan Skills izin listesine göre filtrelenir. Paylaşılan bir temel için agents.defaults.skills, ajan başına değiştirme için agents.list[].skills kullanın. Bkz. Skills: ajan başına ve paylaşılan ve Skills: ajan Skills izin listeleri.

Gateway tek ajanı (varsayılan) veya birçok ajanı yan yana barındırabilir.

Yollar (hızlı harita)

• Yapılandırma: ~/.openclaw/openclaw.json (veya OPENCLAW_CONFIG_PATH)
• Durum dizini: ~/.openclaw (veya OPENCLAW_STATE_DIR)
• Çalışma alanı: ~/.openclaw/workspace (veya ~/.openclaw/workspace-<agentId>)
• Ajan dizini: ~/.openclaw/agents/<agentId>/agent (veya agents.list[].agentDir)
• Oturumlar: ~/.openclaw/agents/<agentId>/sessions

Tek ajan modu (varsayılan)

Hiçbir şey yapmazsanız OpenClaw tek bir ajan çalıştırır:

• agentId varsayılan olarak main olur.
• Oturumlar agent:main:<mainKey> olarak anahtarlanır.
• Çalışma alanı varsayılan olarak ~/.openclaw/workspace olur (veya OPENCLAW_PROFILE ayarlandığında ~/.openclaw/workspace-<profile>).
• Durum varsayılan olarak ~/.openclaw/agents/main/agent olur.

Ajan yardımcısı

Yeni bir yalıtılmış ajan eklemek için ajan sihirbazını kullanın:

openclaw agents add work

Ardından gelen iletileri yönlendirmek için bindings ekleyin (veya sihirbazın yapmasına izin verin).

Şununla doğrulayın:

openclaw agents list --bindings

Hızlı başlangıç

openclaw agents add codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

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

Birden çok ajan = birden çok kişi, birden çok kişilik

Birden çok ajan ile her agentId tamamen yalıtılmış bir persona olur:

• Farklı telefon numaraları/hesaplar (kanal başına accountId).
• Farklı kişilikler (AGENTS.md ve SOUL.md gibi ajan başına çalışma alanı dosyaları).
• Ayrı kimlik doğrulama + oturumlar (açıkça etkinleştirilmedikçe çapraz konuşma yok).

Bu, birden çok kişinin tek bir Gateway sunucusunu paylaşmasına, AI "beyinlerini" ve verilerini yalıtılmış tutmasına olanak tanır.

Ajanlar arası QMD bellek araması

Bir ajanın başka bir ajanın QMD oturum dökümlerini araması gerekiyorsa agents.list[].memorySearch.qmd.extraCollections altına ek koleksiyonlar ekleyin. agents.defaults.memorySearch.qmd.extraCollections değerini yalnızca her ajanın aynı paylaşılan döküm koleksiyonlarını devralması gerektiğinde kullanın.

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

Ek koleksiyon yolu ajanlar arasında paylaşılabilir, ancak yol ajan çalışma alanının dışındaysa koleksiyon adı açık kalır. Çalışma alanının içindeki yollar ajan kapsamlı kalır, böylece her ajan kendi döküm arama kümesini korur.

Tek WhatsApp numarası, birden çok kişi (DM bölme)

Tek bir WhatsApp hesabında kalırken farklı WhatsApp DM'lerini farklı ajanlara yönlendirebilirsiniz. Gönderen E.164 (ör. +15551234567) üzerinde peer.kind: "direct" ile eşleştirin. Yanıtlar yine aynı WhatsApp numarasından gelir (ajan başına gönderen kimliği yoktur).

Örnek:

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

Notlar:

• DM erişim denetimi, ajan başına değil WhatsApp hesabı başına geneldir (eşleştirme/izin listesi).
• Paylaşılan gruplar için grubu bir ajana bağlayın veya Yayın grupları kullanın.

Yönlendirme kuralları (iletiler ajanı nasıl seçer)

Bağlamalar deterministiktir ve en özgül olan kazanır:

Birden çok hesap / telefon numarası

Birden çok hesabı destekleyen kanallar (ör. WhatsApp), her oturumu tanımlamak için accountId kullanır. Her accountId farklı bir ajana yönlendirilebilir, böylece tek bir sunucu oturumları karıştırmadan birden çok telefon numarasını barındırabilir.

accountId atlandığında kanal çapında varsayılan bir hesap istiyorsanız channels.<channel>.defaultAccount ayarlayın (isteğe bağlı). Ayarlanmadığında OpenClaw varsa default değerine, yoksa ilk yapılandırılmış hesap kimliğine (sıralanmış) geri döner.

Bu deseni destekleyen yaygın kanallar şunları içerir:

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

Kavramlar

• agentId: tek bir "beyin" (çalışma alanı, ajan başına kimlik doğrulama, ajan başına oturum deposu).
• accountId: tek bir kanal hesabı örneği (ör. WhatsApp hesabı "personal" ile "biz").
• binding: gelen iletileri (channel, accountId, peer) ve isteğe bağlı guild/takım kimlikleriyle bir agentId değerine yönlendirir.
• Doğrudan sohbetler agent:<agentId>:<mainKey> değerine daraltılır (ajan başına "main"; session.mainKey).

Platform örnekleri

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

Yaygın desenler

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

Ajan başına sandbox ve araç yapılandırması

Her ajanın kendi sandbox'ı ve araç kısıtlamaları olabilir:

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

Avantajlar:

• Güvenlik izolasyonu: güvenilmeyen ajanlar için araçları kısıtlayın.
• Kaynak denetimi: belirli ajanları sandbox'a alırken diğerlerini host üzerinde tutun.
• Esnek ilkeler: ajan başına farklı izinler.

Ayrıntılı örnekler için Çok ajanlı sandbox ve araçlar bölümüne bakın.

İlgili

• ACP ajanları — harici kodlama harness'larını çalıştırma
• Kanal yönlendirme — mesajların ajanlara nasıl yönlendirildiği
• Presence — ajan presence'ı ve kullanılabilirliği
• Session — session izolasyonu ve yönlendirme
• Alt ajanlar — arka plan ajan çalıştırmaları başlatma