گروه‌ها

OpenClaw چت‌های گروهی را در سطح‌های مختلف به‌صورت یکسان مدیریت می‌کند: Discord، iMessage، Matrix، Microsoft Teams، QQBot، Signal، Slack، Telegram، WhatsApp، Zalo.

برای اتاق‌های همیشه‌فعال که باید زمینه‌ای آرام فراهم کنند مگر اینکه عامل صراحتاً پیام قابل‌مشاهده‌ای بفرستد، رویدادهای اتاق محیطی را ببینید.

معرفی مبتدی (۲ دقیقه)

OpenClaw روی حساب‌های پیام‌رسان خودتان «زندگی می‌کند». کاربر ربات جداگانه‌ای برای WhatsApp وجود ندارد. اگر شما در یک گروه باشید، OpenClaw می‌تواند آن گروه را ببیند و همان‌جا پاسخ بدهد.

رفتار پیش‌فرض:

• گروه‌ها محدود هستند (groupPolicy: "allowlist").
• پاسخ‌ها به منشن نیاز دارند، مگر اینکه صراحتاً دروازه‌گذاری منشن را غیرفعال کنید.
• پاسخ‌های قابل‌مشاهده در گروه‌ها/کانال‌ها به‌طور پیش‌فرض از ابزار message استفاده می‌کنند.

ترجمه: فرستنده‌های موجود در allowlist می‌توانند با منشن کردن OpenClaw آن را فعال کنند.

جریان سریع (برای یک پیام گروهی چه اتفاقی می‌افتد):

groupPolicy? disabled -> dropgroupPolicy? allowlist -> group allowed? no -> droprequireMention? yes -> mentioned? no -> store for context onlymention/reply/command/DM -> user requestalways-on group chatter -> user request, or room event when configured

پاسخ‌های قابل‌مشاهده

برای درخواست‌های عادی گروه/کانال، OpenClaw به‌طور پیش‌فرض از messages.groupChat.visibleReplies: "automatic" استفاده می‌کند. متن نهایی دستیار از مسیر قدیمی پاسخ قابل‌مشاهده ارسال می‌شود، مگر اینکه اتاق را برای خروجی فقط از طریق ابزار پیام تنظیم کنید.

وقتی یک اتاق مشترک باید به عامل اجازه بدهد خودش با فراخوانی message(action=send) تصمیم بگیرد چه زمانی صحبت کند، از messages.groupChat.visibleReplies: "message_tool" استفاده کنید. این حالت برای اتاق‌های گروهی که با مدل‌های نسل جدید و قابل‌اعتماد در استفاده از ابزار، مانند GPT 5.5، پشتیبانی می‌شوند بهترین نتیجه را دارد. اگر مدل آن ابزار را از دست بدهد و متن نهایی معناداری برگرداند، OpenClaw آن متن نهایی را به‌جای ارسال به اتاق، خصوصی نگه می‌دارد.

برای مدل‌ها یا runtimeهای ضعیف‌تر که تحویل فقط از طریق ابزار را قابل‌اعتماد نمی‌فهمند، از "automatic" استفاده کنید. در حالت خودکار، متن نهایی دستیار مسیر پاسخ قابل‌مشاهده منبع است، بنابراین مدلی که نمی‌تواند به‌طور پایدار message(action=send) را فراخوانی کند همچنان می‌تواند معمولی پاسخ بدهد.

در حالت خودکار، پاسخ‌های نهایی متنی معمولی مستقیماً در اتاق ارسال می‌شوند. اگر پاسخ قابل‌مشاهده به فایل، تصویر یا پیوست‌های دیگر نیاز داشته باشد، عامل همچنان ممکن است برای آن پیوست به‌جای تلاش برای عبور دادن آن از پاسخ متن نهایی، از message(action=send) استفاده کند.

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

برای چت‌های مستقیم و هر رویداد منبع دیگر، از messages.visibleReplies: "message_tool" استفاده کنید تا همان رفتار پاسخ قابل‌مشاهده فقط از طریق ابزار را به‌صورت سراسری اعمال کنید. نوبت‌های مستقیم WebChat داخلی به‌طور پیش‌فرض از تحویل پاسخ نهایی خودکار استفاده می‌کنند تا Pi و Codex همان قرارداد پاسخ قابل‌مشاهده را دریافت کنند. برای اینکه عمداً خروجی قابل‌مشاهده به message(action=send) نیاز داشته باشد، messages.visibleReplies: "message_tool" را تنظیم کنید. messages.groupChat.visibleReplies همچنان override اختصاصی‌تر برای اتاق‌های گروهی/کانالی باقی می‌ماند.

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

پیوندهای مکالمه‌ای متعلق به Plugin استثنا هستند. وقتی یک Plugin رشته‌ای را bind کند و مالک نوبت ورودی شود، پاسخ برگشتی Plugin همان پاسخ قابل‌مشاهده bind است؛ به message(action=send) نیاز ندارد. آن پاسخ خروجی runtime مربوط به Plugin است، نه متن نهایی خصوصی مدل.

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

نشست‌ها به‌طور پیش‌فرض خلاصه‌های پرجزئیات ابزار/پیشرفت را سرکوب می‌کنند. هنگام اشکال‌زدایی از /verbose on استفاده کنید تا آن خلاصه‌ها برای نشست فعلی نشان داده شوند، و برای بازگشت به رفتار فقط پاسخ نهایی از /verbose off استفاده کنید. همان وضعیت verbose در چت‌های مستقیم، گروه‌ها، کانال‌ها و موضوعات انجمن اعمال می‌شود.

برای ثبت گفت‌وگوی گروهی همیشه‌فعال بدون منشن به‌عنوان زمینه آرام اتاق به‌جای درخواست کاربر، از رویدادهای اتاق محیطی استفاده کنید:

{  messages: {    groupChat: {      unmentionedInbound: "room_event",    },  },}

پیش‌فرض unmentionedInbound: "user_request" است.

پیام‌های منشن‌شده، فرمان‌ها، درخواست‌های لغو، و DMها همچنان درخواست کاربر باقی می‌مانند.

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

{  messages: {    groupChat: {      visibleReplies: "message_tool",    },  },}

Gateway پس از ذخیره شدن فایل، پیکربندی messages را hot-reload می‌کند. فقط زمانی restart کنید که پایش فایل یا بارگذاری مجدد پیکربندی در deployment غیرفعال باشد.

برای اینکه خروجی قابل‌مشاهده در هر چت منبع الزاماً از ابزار پیام عبور کند:

{  messages: {    visibleReplies: "message_tool",  },}

فرمان‌های slash بومی (Discord، Telegram، و سطح‌های دیگر با پشتیبانی فرمان بومی) از visibleReplies: "message_tool" عبور می‌کنند و همیشه به‌صورت قابل‌مشاهده پاسخ می‌دهند تا UI فرمان بومی کانال پاسخی را که انتظار دارد دریافت کند. این فقط برای نوبت‌های فرمان بومی اعتبارسنجی‌شده اعمال می‌شود؛ فرمان‌های /... تایپ‌شده به‌صورت متن و نوبت‌های عادی چت همچنان از پیش‌فرض گروه پیکربندی‌شده پیروی می‌کنند.

قابلیت مشاهده زمینه و allowlistها

دو کنترل متفاوت در ایمنی گروه دخیل هستند:

• مجوز فعال‌سازی: چه کسی می‌تواند عامل را فعال کند (groupPolicy، groups، groupAllowFrom، allowlistهای مخصوص کانال).
• قابلیت مشاهده زمینه: چه زمینه تکمیلی به مدل تزریق می‌شود (متن پاسخ، نقل‌قول‌ها، تاریخچه رشته، فراداده forward شده).

به‌طور پیش‌فرض، OpenClaw رفتار معمول چت را در اولویت می‌گذارد و زمینه را عمدتاً همان‌طور که دریافت شده نگه می‌دارد. یعنی allowlistها عمدتاً تعیین می‌کنند چه کسی می‌تواند اقدام‌ها را فعال کند، نه اینکه برای هر قطعه نقل‌قول‌شده یا تاریخی یک مرز حذف اطلاعات سراسری باشند.

اگر می‌خواهید...

برای allowlistهای قابل‌استفاده‌مجدد فرستنده، گروه‌های دسترسی را ببینید.

کلیدهای نشست

• نشست‌های گروهی از کلیدهای نشست agent:<agentId>:<channel>:group:<id> استفاده می‌کنند (اتاق‌ها/کانال‌ها از agent:<agentId>:<channel>:channel:<id> استفاده می‌کنند).
• موضوعات انجمن Telegram به شناسه گروه :topic:<threadId> اضافه می‌کنند تا هر موضوع نشست خودش را داشته باشد.
• چت‌های مستقیم از نشست اصلی استفاده می‌کنند (یا در صورت پیکربندی، به‌ازای هر فرستنده).
• Heartbeatها برای نشست‌های گروهی رد می‌شوند.

الگو: DMهای شخصی + گروه‌های عمومی (یک عامل)

بله، اگر ترافیک «شخصی» شما DMها و ترافیک «عمومی» شما گروه‌ها باشد، این روش خوب کار می‌کند.

دلیل: در حالت تک‌عاملی، DMها معمولاً وارد کلید نشست اصلی (agent:main:main) می‌شوند، در حالی که گروه‌ها همیشه از کلیدهای نشست غیراصلی (agent:main:<channel>:group:<id>) استفاده می‌کنند. اگر sandboxing را با mode: "non-main" فعال کنید، آن نشست‌های گروهی در backend پیکربندی‌شده sandbox اجرا می‌شوند، در حالی که نشست DM اصلی شما روی میزبان می‌ماند. اگر backend انتخاب نکنید، Docker backend پیش‌فرض است.

این به شما یک «مغز» عامل می‌دهد (workspace + حافظه مشترک)، اما دو وضعیت اجرایی:

• DMها: ابزارهای کامل (میزبان)
• گروه‌ها: sandbox + ابزارهای محدودشده

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // groups/channels are non-main -> sandboxed        scope: "session", // strongest isolation (one container per group/channel)        workspaceAccess: "none",      },    },  },  tools: {    sandbox: {      tools: {        // If allow is non-empty, everything else is blocked (deny still wins).        allow: ["group:messaging", "group:sessions"],        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],      },    },  },}

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",        docker: {          binds: [            // hostPath:containerPath:mode            "/home/user/FriendsShared:/data:ro",          ],        },      },    },  },}

مرتبط:

• کلیدهای پیکربندی و پیش‌فرض‌ها: پیکربندی Gateway
• اشکال‌زدایی اینکه چرا یک ابزار مسدود شده است: Sandbox در برابر سیاست ابزار در برابر Elevated
• جزئیات bind mountها: Sandboxing

برچسب‌های نمایش

• برچسب‌های UI وقتی displayName در دسترس باشد از آن استفاده می‌کنند، با قالب <channel>:<token>.
• #room برای اتاق‌ها/کانال‌ها رزرو شده است؛ چت‌های گروهی از g-<slug> استفاده می‌کنند (حروف کوچک، فاصله‌ها -> -، حفظ #@+._-).

سیاست گروه

کنترل کنید پیام‌های گروه/اتاق در هر کانال چگونه مدیریت شوند:

{  channels: {    whatsapp: {      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"      groupAllowFrom: ["+15551234567"],    },    telegram: {      groupPolicy: "disabled",      groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username)    },    signal: {      groupPolicy: "disabled",      groupAllowFrom: ["+15551234567"],    },    imessage: {      groupPolicy: "disabled",      groupAllowFrom: ["chat_id:123"],    },    msteams: {      groupPolicy: "disabled",      groupAllowFrom: ["user@org.com"],    },    discord: {      groupPolicy: "allowlist",      guilds: {        GUILD_ID: { channels: { help: { allow: true } } },      },    },    slack: {      groupPolicy: "allowlist",      channels: { "#general": { allow: true } },    },    matrix: {      groupPolicy: "allowlist",      groupAllowFrom: ["@owner:example.org"],      groups: {        "!roomId:example.org": { enabled: true },        "#alias:example.org": { enabled: true },      },    },  },}

مدل ذهنی سریع (ترتیب ارزیابی برای پیام‌های گروهی):

دروازه‌بانی منشن (پیش‌فرض)

پیام‌های گروهی به منشن نیاز دارند، مگر اینکه برای هر گروه بازنویسی شده باشد. پیش‌فرض‌ها برای هر زیرسیستم زیر *.groups."*" قرار دارند.

پاسخ دادن به پیام ربات، وقتی کانال از فراداده پاسخ پشتیبانی کند، به‌عنوان یک منشن ضمنی شمرده می‌شود. نقل‌قول کردن پیام ربات نیز در کانال‌هایی که فراداده نقل‌قول را ارائه می‌کنند می‌تواند به‌عنوان منشن ضمنی شمرده شود. موارد داخلی فعلی شامل Telegram، WhatsApp، Slack، Discord، Microsoft Teams و ZaloUser هستند.

{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },        "123@g.us": { requireMention: false },      },    },    telegram: {      groups: {        "*": { requireMention: true },        "123456789": { requireMention: false },      },    },    imessage: {      groups: {        "*": { requireMention: true },        "123": { requireMention: false },      },    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],          historyLimit: 50,        },      },    ],  },}

محدود کردن دامنه الگوهای منشن پیکربندی‌شده

mentionPatterns پیکربندی‌شده محرک‌های جایگزین رگکس هستند. وقتی پلتفرم منشن بومی ربات را ارائه نمی‌کند، یا وقتی می‌خواهید متن ساده‌ای مانند openclaw: به‌عنوان منشن شمرده شود، از آن‌ها استفاده کنید. منشن‌های بومی پلتفرم جدا هستند: وقتی Discord، Slack، Telegram، Matrix یا کانال دیگری بتواند ثابت کند پیام صراحتا ربات را منشن کرده است، همان منشن بومی همچنان فعال می‌شود، حتی اگر الگوهای رگکس پیکربندی‌شده رد شده باشند.

به‌صورت پیش‌فرض، الگوهای منشن پیکربندی‌شده هرجا که آن کانال داده‌های ارائه‌دهنده و مکالمه را به تشخیص منشن پاس بدهد اعمال می‌شوند. برای جلوگیری از اینکه الگوهای گسترده عامل را در هر گروهی بیدار کنند، آن‌ها را برای هر کانال با channels.<channel>.mentionPatterns محدود کنید.

وقتی الگوهای منشن رگکس باید به‌صورت پیش‌فرض برای یک کانال خاموش باشند، از mode: "deny" استفاده کنید، سپس با allowIn اتاق‌های مشخصی را فعال کنید:

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b", "\\bops bot\\b"],    },  },  channels: {    slack: {      mentionPatterns: {        mode: "deny",        allowIn: ["C0123OPS"],      },    },  },}

وقتی الگوهای منشن رگکس باید به‌صورت گسترده اعمال شوند، از mode: "allow" پیش‌فرض استفاده کنید (یا mode را حذف کنید)، سپس آن‌ها را در اتاق‌های شلوغ با denyIn خاموش کنید:

{  messages: {    groupChat: {      mentionPatterns: ["\\bopenclaw\\b"],    },  },  channels: {    telegram: {      mentionPatterns: {        denyIn: ["-1001234567890", "-1001234567890:topic:42"],      },    },  },}

حل‌وفصل سیاست:

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

پیکربندی‌های کانال در سطح حساب، وقتی آن کانال از چند حساب پشتیبانی می‌کند، می‌توانند همان سیاست را زیر channels.<channel>.accounts.<accountId>.mentionPatterns تنظیم کنند. سیاست حساب برای آن حساب بر سیاست سطح بالای کانال مقدم است.

محدودیت‌های ابزار گروه/کانال (اختیاری)

برخی پیکربندی‌های کانال از محدود کردن ابزارهایی که داخل یک گروه/اتاق/کانال مشخص در دسترس هستند پشتیبانی می‌کنند.

• tools: ابزارها را برای کل گروه مجاز/رد می‌کند.
• toolsBySender: بازنویسی‌های هر فرستنده درون گروه. از پیشوندهای کلید صریح استفاده کنید: channel:<channelId>:<senderId>، id:<senderId>، e164:<phone>، username:<handle>، name:<displayName> و wildcard "*". شناسه‌های کانال از شناسه‌های کانال متعارف OpenClaw استفاده می‌کنند؛ نام‌های مستعاری مانند teams به msteams نرمال‌سازی می‌شوند. کلیدهای قدیمی بدون پیشوند همچنان پذیرفته می‌شوند و فقط به‌عنوان id: مطابقت داده می‌شوند.

ترتیب حل‌وفصل (خاص‌ترین مورد برنده است):

نمونه (Telegram):

{  channels: {    telegram: {      groups: {        "*": { tools: { deny: ["exec"] } },        "-1001234567890": {          tools: { deny: ["exec", "read", "write"] },          toolsBySender: {            "id:123456789": { alsoAllow: ["exec"] },          },        },      },    },  },}

فهرست‌های مجاز گروه

وقتی channels.whatsapp.groups، channels.telegram.groups یا channels.imessage.groups پیکربندی شده باشد، کلیدها به‌عنوان فهرست مجاز گروه عمل می‌کنند. برای مجاز کردن همه گروه‌ها درحالی‌که همچنان رفتار پیش‌فرض منشن را تنظیم می‌کنید، از "*" استفاده کنید.

نیت‌های رایج (کپی/پیست):

{  channels: { whatsapp: { groupPolicy: "disabled" } },}

{  channels: {    whatsapp: {      groups: {        "123@g.us": { requireMention: true },        "456@g.us": { requireMention: false },      },    },  },}

{  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

{  channels: {    whatsapp: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15551234567"],      groups: { "*": { requireMention: true } },    },  },}

فعال‌سازی (فقط مالک)

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

• /activation mention
• /activation always

مالک با channels.whatsapp.allowFrom تعیین می‌شود (یا اگر تنظیم نشده باشد، E.164 خود بات). فرمان را به‌صورت یک پیام مستقل ارسال کنید. سطوح دیگر در حال حاضر /activation را نادیده می‌گیرند.

فیلدهای زمینه

بارهای ورودی گروه این موارد را تنظیم می‌کنند:

• ChatType=group
• GroupSubject (اگر شناخته شده باشد)
• GroupMembers (اگر شناخته شده باشد)
• WasMentioned (نتیجه دروازه‌گذاری منشن)
• موضوع‌های انجمن Telegram همچنین شامل MessageThreadId و IsForum هستند.

پرامپت سیستمی عامل در نخستین نوبت یک نشست گروهی جدید، یک مقدمه گروهی را شامل می‌شود. این مقدمه به مدل یادآوری می‌کند مانند انسان پاسخ دهد، خطوط خالی را به حداقل برساند و از فاصله‌گذاری معمول چت پیروی کند، و از تایپ توالی‌های لفظی \n خودداری کند. گروه‌های غیر Telegram همچنین جدول‌های Markdown را توصیه نمی‌کنند؛ راهنمایی متن غنی Telegram از پرامپت کانال Telegram می‌آید. نام‌های گروه و برچسب‌های شرکت‌کنندگان که از کانال آمده‌اند، به‌صورت فراداده نامطمئن حصارگذاری‌شده رندر می‌شوند، نه دستورهای سیستمی درون‌خطی.

نکات ویژه iMessage

• هنگام مسیریابی یا قرار دادن در فهرست مجاز، chat_id:<id> را ترجیح دهید.
• فهرست چت‌ها: imsg chats --limit 20.
• پاسخ‌های گروه همیشه به همان chat_id برمی‌گردند.

پرامپت‌های سیستمی WhatsApp

برای قواعد مرجع پرامپت سیستمی WhatsApp، از جمله تفکیک پرامپت گروهی و مستقیم، رفتار wildcard، و معنای بازنویسی حساب، WhatsApp را ببینید.

نکات ویژه WhatsApp

برای رفتارهای فقط WhatsApp (تزریق تاریخچه، جزئیات مدیریت منشن)، پیام‌های گروهی را ببینید.

مرتبط

• گروه‌های پخش
• مسیریابی کانال
• پیام‌های گروهی
• جفت‌سازی