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

چند عامل ایزوله را اجرا کنید — هرکدام با فضای کاری، دایرکتوری وضعیت (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 codingopenclaw agents add social

openclaw channels login --channel whatsapp --account work

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

عامل‌های متعدد = افراد متعدد، شخصیت‌های متعدد

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

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

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

جست‌وجوی حافظه 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 بمانید. با peer.kind: "direct" بر اساس فرستنده E.164 (مانند +15551234567) تطبیق دهید. پاسخ‌ها همچنان از همان شماره 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 موجود باشد به آن fallback می‌کند، وگرنه نخستین شناسه حساب پیکربندی‌شده (مرتب‌شده) را انتخاب می‌کند.

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

• whatsapp, telegram, discord, slack, signal, imessage
• irc, line, googlechat, mattermost, matrix, nextcloud-talk
• 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 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: "1203630...@g.us" },      },    },  ],   // 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", accountId: "*" } },    { agentId: "opus", match: { channel: "telegram", accountId: "*" } },  ],}

{  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", accountId: "*", peer: { kind: "direct", id: "+15551234567" } },    },    { agentId: "chat", match: { channel: "whatsapp", accountId: "*" } },  ],}

{  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: "120363999999999999@g.us" },      },    },  ],}

پیکربندی 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 کنید و بقیه را روی host نگه دارید.
• سیاست‌های انعطاف‌پذیر: مجوزهای متفاوت برای هر عامل.

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

مرتبط

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