گروه‌ها

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

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

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

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

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

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

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

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

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

برای اتاق‌های گروهی/کانالی، مقدار پیش‌فرض OpenClaw برابر messages.groupChat.visibleReplies: "message_tool" است. openclaw doctor --fix این مقدار پیش‌فرض را در پیکربندی‌های کانال‌های تنظیم‌شده‌ای که آن را ندارند می‌نویسد. یعنی عامل همچنان turn را پردازش می‌کند و می‌تواند وضعیت حافظه/نشست را به‌روزرسانی کند، اما پاسخ نهایی معمول آن به‌صورت خودکار در اتاق ارسال نمی‌شود. برای صحبت کردن به‌صورت قابل مشاهده، عامل از message(action=send) استفاده می‌کند.

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

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

برای گپ‌های مستقیم و هر turn منبع دیگر، از messages.visibleReplies: "message_tool" استفاده کنید تا همین رفتار پاسخ قابل مشاهدهٔ فقط-ابزار به‌صورت سراسری اعمال شود. harnessها هم می‌توانند این را به‌عنوان مقدار پیش‌فرض تنظیم‌نشدهٔ خود انتخاب کنند؛ harness کدکس این کار را برای گپ‌های مستقیم در حالت کدکس انجام می‌دهد. messages.groupChat.visibleReplies همچنان override مشخص‌تر برای اتاق‌های گروهی/کانالی است.

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

نشانگرهای تایپ همچنان هنگام کار عامل در حالت فقط-ابزار ارسال می‌شوند. حالت پیش‌فرض تایپ گروه برای این turnها از "message" به "instant" ارتقا داده می‌شود، چون ممکن است هرگز متن پیام معمول دستیار قبل از تصمیم عامل دربارهٔ فراخوانی ابزار پیام وجود نداشته باشد. پیکربندی صریح حالت تایپ همچنان اولویت دارد.

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

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

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

برای الزام خروجی قابل مشاهده به عبور از ابزار پیام برای هر گپ منبع:

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

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

# نمایانی context و allowlistها

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

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

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

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

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

# کلیدهای نشست

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

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

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

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

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

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

{
  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
• اشکال‌زدایی اینکه چرا یک ابزار مسدود شده است: جعبهٔ شنی در برابر سیاست ابزار در برابر 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: ["[email protected]"],
    },
    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 },
        "[email protected]": { 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,
        },
      },
    ],
  },
}

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

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

• tools: اجازه/رد ابزارها برای کل گروه.
• toolsBySender: بازنویسی‌های هر فرستنده داخل گروه. از پیشوندهای کلید صریح استفاده کنید: id:<senderId>، e164:<phone>، username:<handle>، name:<displayName>، و wildcard "*". کلیدهای قدیمی بدون پیشوند همچنان پذیرفته می‌شوند و فقط به‌عنوان 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: {
        "[email protected]": { requireMention: true },
        "[email protected]": { 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 هستند.

نکات مخصوص کانال:

• BlueBubbles می‌تواند به‌صورت اختیاری شرکت‌کنندگان بی‌نام گروه macOS را پیش از پر کردن GroupMembers از پایگاه‌داده Contacts محلی غنی کند. این به‌طور پیش‌فرض خاموش است و فقط پس از عبور کنترل‌های عادی گروه اجرا می‌شود.

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

# جزئیات iMessage

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

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

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

# جزئیات WhatsApp

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

# مرتبط

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