Çok ajanlı yönlendirme

Bir çalışan Gateway içinde, her biri kendi çalışma alanına, durum dizinine (agentDir) ve oturum geçmişine sahip birden çok yalıtılmış ajanı ve ayrıca birden çok kanal hesabını (örn. iki WhatsApp) çalıştırın. Gelen iletiler, bağlamalar aracılığıyla 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 diskteki durum dizinidir. Bir bağlama, bir kanal hesabını (örn. bir Slack çalışma alanı veya WhatsApp numarası) bu ajanlardan biriyle eşler.

# "Tek ajan" nedir?

Bir ajan, kendi kapsamı tamamen ayrılmış bir beyindir ve şunlara sahiptir:

• Ç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 etkili ajan Skills izin listesine göre filtrelenir. Paylaşılan 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, yan yana tek ajan (varsayılan) veya çok sayıda ajan 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 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 bunu sihirbazın yapmasına izin verin).

Şununla doğrulayın:

openclaw agents list --bindings

# Hızlı başlangıç

openclaw agents add coding
openclaw agents add social

openclaw channels login --channel whatsapp --account work

openclaw gateway restart
openclaw agents list --bindings
openclaw 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 haline gelir:

• 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şırken AI "beyinlerini" ve verilerini yalıtılmış tutmasını sağlar.

# 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ı 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 ayrımı)

Tek WhatsApp hesabında kalırken farklı WhatsApp DM'lerini farklı ajanlara yönlendirebilirsiniz. peer.kind: "direct" ile gönderen E.164 üzerinde (ör. +15551234567) 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 özel olan kazanır:

# Birden çok hesap / telefon numarası

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

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

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

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

# Kavramlar

• agentId: tek "beyin" (çalışma alanı, ajan başına kimlik doğrulama, ajan başına oturum deposu).
• accountId: tek kanal hesabı örneği (örn. WhatsApp hesabı "personal" ile "biz").
• binding: gelen iletileri (channel, accountId, peer) ve isteğe bağlı guild/team kimlikleriyle bir agentId değerine yönlendirir.
• Doğrudan sohbetler agent:<agentId>:<mainKey> değerine daralır (ajan başına "ana"; 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 personal
openclaw 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",
        },
      },
    },
  },
}

# Yaygin kaliplar

{
  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 basina sandbox ve arac yapilandirmasi

Her ajanin kendi sandbox'i ve arac kisitlamalari 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:

• Guvenlik yalitimi: guvenilmeyen ajanlar icin araclari kisitlayin.
• Kaynak kontrolu: belirli ajanlari sandbox'a alirken digerlerini host uzerinde tutun.
• Esnek ilkeler: ajan basina farkli izinler.

Ayrintili ornekler icin Cok ajanli sandbox ve araclar sayfasina bakin.

# Ilgili

• ACP ajanlari — harici kodlama kosum takimlarini calistirma
• Kanal yonlendirme — mesajlarin ajanlara nasil yonlendirildigi
• Varlik — ajan varligi ve kullanilabilirligi
• Oturum — oturum yalitimi ve yonlendirme
• Alt ajanlar — arka plan ajan calismalari baslatma