پیام‌های گروهی WhatsApp

برای مدل گروه‌های میان‌کانالی (Discord، iMessage، Matrix، Microsoft Teams، Signal، Slack، Telegram، WhatsApp، Zalo)، گروه‌ها را ببینید. این صفحه رفتار اختصاصی WhatsApp را روی آن مدل پوشش می‌دهد: فعال‌سازی، فهرست‌های مجاز گروه، کلیدهای نشست برای هر گروه، و تزریق زمینه پیام‌های در انتظار.

هدف: اجازه دهید OpenClaw در گروه‌های WhatsApp حضور داشته باشد، فقط وقتی پینگ می‌شود فعال شود، و آن رشته گفتگو را از نشست پیام مستقیم شخصی جدا نگه دارد.

رفتار

• حالت‌های فعال‌سازی: mention (پیش‌فرض) یا always. mention به یک پینگ نیاز دارد (منشن‌های واقعی WhatsApp از طریق mentionedJids، الگوهای regex امن، یا E.164 ربات در هر جای متن). always عامل را روی هر پیام بیدار می‌کند، اما فقط وقتی باید پاسخ دهد که بتواند ارزش معناداری اضافه کند؛ در غیر این صورت توکن سکوت دقیق NO_REPLY / no_reply را برمی‌گرداند. پیش‌فرض‌ها را می‌توان در پیکربندی (channels.whatsapp.groups) تنظیم کرد و برای هر گروه از طریق /activation بازنویسی کرد. وقتی channels.whatsapp.groups تنظیم شده باشد، به‌عنوان فهرست مجاز گروه نیز عمل می‌کند (برای مجاز کردن همه، "*" را اضافه کنید).
• سیاست گروه: channels.whatsapp.groupPolicy کنترل می‌کند که آیا پیام‌های گروه پذیرفته شوند یا نه (open|disabled|allowlist). allowlist از channels.whatsapp.groupAllowFrom استفاده می‌کند (جایگزین: channels.whatsapp.allowFrom صریح). پیش‌فرض allowlist است (تا زمانی که فرستنده‌ها را اضافه نکنید مسدود می‌ماند).
• نشست‌های هر گروه: کلیدهای نشست شبیه agent:<agentId>:whatsapp:group:<jid> هستند، بنابراین دستورهایی مانند /verbose on، /trace on، یا /think high (که به‌صورت پیام مستقل ارسال می‌شوند) به همان گروه محدود می‌شوند؛ وضعیت پیام مستقیم شخصی دست‌نخورده می‌ماند. Heartbeatها برای رشته‌های گروهی رد می‌شوند.
• تزریق زمینه: پیام‌های گروهی فقط در انتظار (پیش‌فرض 50) که یک اجرا را تحریک نکرده‌اند زیر [Chat messages since your last reply - for context] پیشوند می‌گیرند، و خط تحریک‌کننده زیر [Current message - respond to this] قرار می‌گیرد. پیام‌هایی که از قبل در نشست هستند دوباره تزریق نمی‌شوند.
• نمایش فرستنده: هر دسته گروهی اکنون با [from: Sender Name (+E164)] پایان می‌یابد تا OpenClaw بداند چه کسی صحبت می‌کند.
• زودگذر/یک‌بارنمایش: پیش از استخراج متن/منشن‌ها، آن‌ها را باز می‌کنیم، بنابراین پینگ‌های داخل آن‌ها همچنان تحریک می‌شوند.
• اعلان سیستمی گروه: در اولین نوبت یک نشست گروهی (و هر زمان که /activation حالت را تغییر دهد)، یک توضیح کوتاه شبیه You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), ... Activation: trigger-only ... Address the specific sender noted in the message context. را به اعلان سیستمی تزریق می‌کنیم. اگر فراداده در دسترس نباشد، همچنان به عامل می‌گوییم که این یک گفتگوی گروهی است.

نمونه پیکربندی (WhatsApp)

یک بلوک groupChat به ~/.openclaw/openclaw.json اضافه کنید تا پینگ‌های نام نمایشی حتی وقتی WhatsApp نویسه دیداری @ را از بدنه متن حذف می‌کند کار کنند:

{  channels: {    whatsapp: {      groups: {        "*": { requireMention: true },      },    },  },  agents: {    list: [      {        id: "main",        groupChat: {          historyLimit: 50,          mentionPatterns: ["@?openclaw", "\\+?15555550123"],        },      },    ],  },}

نکته‌ها:

• regexها به بزرگی/کوچکی حروف حساس نیستند و از همان محافظ‌های safe-regex مانند سایر سطوح regex پیکربندی استفاده می‌کنند؛ الگوهای نامعتبر و تکرار تودرتوی ناامن نادیده گرفته می‌شوند.
• وقتی کسی روی مخاطب می‌زند، WhatsApp همچنان منشن‌های کانونی را از طریق mentionedJids می‌فرستد، بنابراین جایگزین شماره به‌ندرت لازم می‌شود، اما یک شبکه ایمنی مفید است.

دستور فعال‌سازی (فقط مالک)

از دستور گفتگوی گروهی استفاده کنید:

• /activation mention
• /activation always

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

روش استفاده

1. حساب WhatsApp خود (همان که OpenClaw را اجرا می‌کند) را به گروه اضافه کنید.
2. بگویید @openclaw … (یا شماره را وارد کنید). فقط فرستنده‌های فهرست مجاز می‌توانند آن را تحریک کنند، مگر اینکه groupPolicy: "open" را تنظیم کنید.
3. اعلان عامل شامل زمینه اخیر گروه به‌همراه نشانگر پایانی [from: …] خواهد بود تا بتواند فرد درست را خطاب قرار دهد.
4. دستورالعمل‌های سطح نشست (/verbose on، /trace on، /think high، /new یا /reset، /compact) فقط روی نشست همان گروه اعمال می‌شوند؛ آن‌ها را به‌صورت پیام مستقل ارسال کنید تا ثبت شوند. نشست پیام مستقیم شخصی شما مستقل می‌ماند.

آزمایش / راستی‌آزمایی

• آزمون دود دستی:
  • یک پینگ @openclaw در گروه بفرستید و پاسخی را تأیید کنید که به نام فرستنده ارجاع می‌دهد.
  • یک پینگ دوم بفرستید و بررسی کنید که بلوک تاریخچه گنجانده شده و سپس در نوبت بعدی پاک می‌شود.
• لاگ‌های Gateway را بررسی کنید (با --verbose اجرا کنید) تا ورودی‌های inbound web message را ببینید که from: <groupJid> و پسوند [from: …] را نشان می‌دهند.

ملاحظات شناخته‌شده

• Heartbeatها عمداً برای گروه‌ها رد می‌شوند تا از پخش‌های پرسر‌وصدا جلوگیری شود.
• سرکوب بازتاب از رشته دسته‌ای ترکیبی استفاده می‌کند؛ اگر متن یکسانی را دو بار بدون منشن ارسال کنید، فقط اولی پاسخ دریافت می‌کند.
• ورودی‌های ذخیره‌گاه نشست به‌صورت agent:<agentId>:whatsapp:group:<jid> در ذخیره‌گاه نشست ظاهر می‌شوند (~/.openclaw/agents/<agentId>/sessions/sessions.json به‌صورت پیش‌فرض)؛ نبودن یک ورودی فقط یعنی آن گروه هنوز اجرایی را تحریک نکرده است.
• نشانگرهای تایپ در گروه‌ها از agents.defaults.typingMode پیروی می‌کنند. وقتی پاسخ‌های قابل مشاهده در حالت فقط-ابزار-پیام فعال شده باشند، تایپ به‌صورت پیش‌فرض بلافاصله شروع می‌شود تا اعضای گروه بتوانند ببینند عامل در حال کار است، حتی اگر پاسخ نهایی خودکاری ارسال نشود. پیکربندی صریح حالت تایپ همچنان اولویت دارد.

مرتبط

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