مسیریابی چندعاملی

چندین عامل ایزوله را اجرا کنید — هرکدام با فضای کاری، دایرکتوری وضعیت (agentDir) و تاریخچه نشست خودش — به‌همراه چندین حساب کانال (مثلا دو WhatsApp) در یک Gateway در حال اجرا. پیام‌های ورودی از طریق اتصال‌ها به عامل درست هدایت می‌شوند.

در اینجا عامل محدوده کامل هر پرسونا است: فایل‌های فضای کاری، پروفایل‌های احراز هویت، رجیستری مدل، و ذخیره‌گاه نشست. agentDir دایرکتوری وضعیت روی دیسک است که این پیکربندی مختص هر عامل را در ~/.openclaw/agents/<agentId>/ نگه می‌دارد. یک اتصال یک حساب کانال (مثلا یک فضای کاری Slack یا یک شماره WhatsApp) را به یکی از آن عامل‌ها نگاشت می‌کند.

# «یک عامل» چیست؟

یک عامل مغزی با محدوده کامل است که موارد زیر را به‌صورت مستقل دارد:

• فضای کاری (فایل‌ها، AGENTS.md/SOUL.md/USER.md، یادداشت‌های محلی، قواعد پرسونا).
• دایرکتوری وضعیت (agentDir) برای پروفایل‌های احراز هویت، رجیستری مدل، و پیکربندی مختص هر عامل.
• ذخیره‌گاه نشست (تاریخچه گفتگو + وضعیت مسیریابی) زیر ~/.openclaw/agents/<agentId>/sessions.

پروفایل‌های احراز هویت مختص هر عامل هستند. هر عامل از مسیر خودش می‌خواند:

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

Skills از فضای کاری هر عامل به‌علاوه ریشه‌های مشترک مانند ~/.openclaw/skills بارگذاری می‌شوند، سپس در صورت پیکربندی، با فهرست مجاز Skills مؤثر عامل فیلتر می‌شوند. از agents.defaults.skills برای خط پایه مشترک و از agents.list[].skills برای جایگزینی مختص هر عامل استفاده کنید. Skills: مختص هر عامل در برابر مشترک و Skills: فهرست‌های مجاز Skills عامل را ببینید.

Gateway می‌تواند یک عامل (پیش‌فرض) یا عامل‌های متعدد را کنار هم میزبانی کند.

# مسیرها (نقشه سریع)

• پیکربندی: ~/.openclaw/openclaw.json (یا OPENCLAW_CONFIG_PATH)
• دایرکتوری وضعیت: ~/.openclaw (یا OPENCLAW_STATE_DIR)
• فضای کاری: ~/.openclaw/workspace (یا ~/.openclaw/workspace-<agentId>)
• دایرکتوری عامل: ~/.openclaw/agents/<agentId>/agent (یا agents.list[].agentDir)
• نشست‌ها: ~/.openclaw/agents/<agentId>/sessions

# حالت تک‌عاملی (پیش‌فرض)

اگر کاری نکنید، OpenClaw یک عامل واحد را اجرا می‌کند:

• agentId به‌صورت پیش‌فرض main است.
• نشست‌ها با agent:main:<mainKey> کلیدگذاری می‌شوند.
• فضای کاری به‌صورت پیش‌فرض ~/.openclaw/workspace است (یا وقتی OPENCLAW_PROFILE تنظیم شده باشد ~/.openclaw/workspace-<profile>).
• وضعیت به‌صورت پیش‌فرض ~/.openclaw/agents/main/agent است.

# کمک‌کننده عامل

از جادوگر عامل برای افزودن یک عامل ایزوله جدید استفاده کنید:

openclaw agents add work

سپس برای مسیریابی پیام‌های ورودی، bindings را اضافه کنید (یا بگذارید جادوگر این کار را انجام دهد).

با این دستور بررسی کنید:

openclaw agents list --bindings

# شروع سریع

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

# چندین عامل = چندین نفر، چندین شخصیت

با چندین عامل، هر agentId به یک پرسونای کاملا ایزوله تبدیل می‌شود:

• شماره تلفن‌ها/حساب‌های متفاوت (برای هر accountId کانال).
• شخصیت‌های متفاوت (فایل‌های فضای کاری مختص هر عامل مانند AGENTS.md و SOUL.md).
• احراز هویت + نشست‌های جداگانه (بدون تداخل، مگر اینکه صراحتا فعال شود).

این امکان می‌دهد چندین نفر یک سرور Gateway را به‌اشتراک بگذارند، در حالی که «مغزهای» AI و داده‌هایشان ایزوله باقی می‌ماند.

# جستجوی حافظه QMD میان‌عاملی

اگر یک عامل باید رونوشت‌های نشست QMD عامل دیگری را جستجو کند، مجموعه‌های اضافی را زیر agents.list[].memorySearch.qmd.extraCollections اضافه کنید. فقط وقتی از agents.defaults.memorySearch.qmd.extraCollections استفاده کنید که همه عامل‌ها باید همان مجموعه‌های رونوشت مشترک را به ارث ببرند.

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

مسیر مجموعه اضافی می‌تواند بین عامل‌ها مشترک باشد، اما وقتی مسیر خارج از فضای کاری عامل است، نام مجموعه صریح باقی می‌ماند. مسیرهای داخل فضای کاری همچنان در محدوده عامل می‌مانند تا هر عامل مجموعه جستجوی رونوشت خودش را نگه دارد.

# یک شماره WhatsApp، چندین نفر (تفکیک پیام مستقیم)

می‌توانید پیام‌های مستقیم WhatsApp متفاوت را به عامل‌های متفاوت هدایت کنید، در حالی که همچنان روی یک حساب WhatsApp می‌مانید. بر اساس فرستنده E.164 (مانند +15551234567) با peer.kind: "direct" مطابقت دهید. پاسخ‌ها همچنان از همان شماره WhatsApp می‌آیند (بدون هویت فرستنده مختص هر عامل).

نمونه:

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

یادداشت‌ها:

• کنترل دسترسی پیام مستقیم به‌صورت سراسری برای هر حساب WhatsApp است (جفت‌سازی/فهرست مجاز)، نه برای هر عامل.
• برای گروه‌های مشترک، گروه را به یک عامل متصل کنید یا از گروه‌های پخش استفاده کنید.

# قواعد مسیریابی (پیام‌ها چگونه یک عامل را انتخاب می‌کنند)

اتصال‌ها قطعی هستند و خاص‌ترین مورد برنده است:

# چندین حساب / شماره تلفن

کانال‌هایی که از چندین حساب پشتیبانی می‌کنند (مثلا WhatsApp)، از accountId برای شناسایی هر ورود استفاده می‌کنند. هر accountId می‌تواند به عامل متفاوتی هدایت شود، بنابراین یک سرور می‌تواند بدون مخلوط‌کردن نشست‌ها چندین شماره تلفن را میزبانی کند.

اگر وقتی accountId حذف شده است یک حساب پیش‌فرض سراسری کانال می‌خواهید، channels.<channel>.defaultAccount را تنظیم کنید (اختیاری). وقتی تنظیم نشده باشد، OpenClaw در صورت وجود به default برمی‌گردد، وگرنه نخستین شناسه حساب پیکربندی‌شده (مرتب‌شده) را استفاده می‌کند.

کانال‌های رایجی که از این الگو پشتیبانی می‌کنند شامل موارد زیر هستند:

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

# مفاهیم

• agentId: یک «مغز» (فضای کاری، احراز هویت مختص هر عامل، ذخیره‌گاه نشست مختص هر عامل).
• accountId: یک نمونه حساب کانال (مثلا حساب WhatsApp با نام "personal" در برابر "biz").
• binding: پیام‌های ورودی را بر اساس (channel, accountId, peer) و به‌صورت اختیاری شناسه‌های guild/team به یک agentId هدایت می‌کند.
• گفتگوهای مستقیم به agent:<agentId>:<mainKey> فروکاسته می‌شوند («اصلی» مختص هر عامل؛ session.mainKey).

# نمونه‌های پلتفرم

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

# الگوهای رایج

{
  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 و ابزار برای هر عامل

هر عامل می‌تواند sandbox و محدودیت‌های ابزار خودش را داشته باشد:

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

مزایا:

• جداسازی امنیتی: ابزارها را برای عامل‌های نامطمئن محدود کنید.
• کنترل منابع: عامل‌های مشخصی را sandbox کنید و بقیه را روی میزبان نگه دارید.
• سیاست‌های انعطاف‌پذیر: مجوزهای متفاوت برای هر عامل.

برای مثال‌های دقیق، sandbox و ابزارهای چندعاملی را ببینید.

# مرتبط

• عامل‌های ACP — اجرای harnessهای کدنویسی خارجی
• مسیریابی کانال — پیام‌ها چگونه به عامل‌ها مسیریابی می‌شوند
• حضور — حضور و دردسترس‌بودن عامل
• Session — جداسازی و مسیریابی session
• زیرعامل‌ها — ایجاد اجراهای عامل پس‌زمینه