WhatsApp

وضعیت: آمادهٔ استفاده در محیط عملیاتی از طریق WhatsApp Web ‏(Baileys). ‏Gateway مالک نشست‌های پیوندشده است؛ کانال جداگانه‌ای برای Twilio WhatsApp وجود ندارد.

نصب

openclaw onboard و openclaw channels add --channel whatsapp هنگام نخستین انتخاب، نصب Plugin را پیشنهاد می‌کنند؛ اگر Plugin موجود نباشد، openclaw channels login --channel whatsapp نیز همین فرایند نصب را ارائه می‌دهد. نسخه‌های توسعه از مسیر محلی Plugin استفاده می‌کنند؛ نصب‌های پایدار/بتا ابتدا @openclaw/whatsapp را از ClawHub نصب می‌کنند و در صورت شکست به npm روی می‌آورند. محیط اجرای WhatsApp خارج از بستهٔ اصلی npm متعلق به OpenClaw عرضه می‌شود، بنابراین وابستگی‌های زمان اجرای آن در Plugin خارجی باقی می‌مانند. نصب دستی:

openclaw plugins install clawhub:@openclaw/whatsapp

از بستهٔ خام npm ‏(@openclaw/whatsapp) فقط برای مسیر جایگزین رجیستری استفاده کنید؛ فقط زمانی نسخه‌ای دقیق را سنجاق کنید که نصب بازتولیدپذیر لازم باشد.

راه‌اندازی سریع

{channels: {whatsapp: {  dmPolicy: "pairing",  allowFrom: ["+15551234567"],  groupPolicy: "allowlist",  groupAllowFrom: ["+15551234567"],},},}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-authopenclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsappopenclaw pairing approve whatsapp <CODE>

الگوهای استقرار

{  channels: {    whatsapp: {      dmPolicy: "allowlist",      allowFrom: ["+15551234567"],    },  },}

مدل زمان اجرا

• ‏Gateway مالک سوکت WhatsApp و حلقهٔ اتصال مجدد است.
• یک پایشگر نگهبان دو سیگنال را مستقل از یکدیگر ردیابی می‌کند: فعالیت خام انتقال WhatsApp Web و فعالیت پیام‌های برنامه. نشستی که بی‌فعالیت اما متصل است، صرفاً به‌دلیل نرسیدن پیام در زمان اخیر راه‌اندازی مجدد نمی‌شود؛ اتصال مجدد فقط زمانی اجباری می‌شود که دریافت فریم‌های انتقال برای یک بازهٔ داخلی ثابت (غیرقابل پیکربندی توسط کاربر) متوقف شود یا پیام‌های برنامه بیش از ۴ برابر مهلت عادی پیام ساکت بمانند. بلافاصله پس از اتصال مجدد نشستی که اخیراً فعال بوده است، نخستین بازه به‌جای بازهٔ ۴ برابری از مهلت کوتاه‌تر و عادی پیام استفاده می‌کند. OpenClaw می‌تواند به پیام‌های آفلاینی که Baileys در ابتدای آن اتصال مجدد تحویل می‌دهد پاسخ خودکار دهد؛ این رفتار به طول عمر حذف تکراری بر اساس شناسهٔ پیام ورودی محدود است. راه‌اندازی اولیه همچنان از محافظ کوتاه تاریخچهٔ کهنه استفاده می‌کند.
• زمان‌بندی‌های سوکت Baileys به‌صراحت زیر web.whatsapp.* تعریف می‌شوند: keepAliveIntervalMs (فاصلهٔ پینگ برنامه)، connectTimeoutMs (مهلت دست‌دهی آغاز اتصال)، defaultQueryTimeoutMs (انتظار برای پرس‌وجوهای Baileys، به‌علاوهٔ مهلت‌های ارسال خروجی، اعلام حضور و رسید خواندن ورودی در OpenClaw).
• ارسال‌های خروجی نیازمند شنوندهٔ فعال WhatsApp برای حساب مقصد هستند؛ در غیر این صورت، ارسال فوراً شکست می‌خورد.
• ارسال‌های گروهی برای توکن‌های @+<digits> و @<digits> در متن و زیرنویس رسانه، هنگامی که توکن با فرادادهٔ فعلی شرکت‌کننده مطابقت داشته باشد، فرادادهٔ بومی اشاره را ضمیمه می‌کنند؛ این قابلیت گروه‌های مبتنی بر LID را نیز شامل می‌شود.
• گفت‌وگوهای وضعیت و انتشار همگانی (@status، @broadcast) نادیده گرفته می‌شوند.
• گفت‌وگوهای مستقیم از قواعد نشست پیام مستقیم استفاده می‌کنند (session.dmScope؛ مقدار پیش‌فرض main پیام‌های مستقیم را در نشست اصلی عامل ادغام می‌کند). نشست‌های گروهی برای هر JID جدا هستند (agent:<agentId>:whatsapp:group:<jid>).
• کانال‌ها/خبرنامه‌های WhatsApp می‌توانند با JID بومی @newsletter خود، مقصد صریح خروجی باشند و به‌جای معنای پیام مستقیم از فرادادهٔ نشست کانال (agent:<agentId>:whatsapp:channel:<jid>) استفاده کنند.
• انتقال WhatsApp Web از متغیرهای استاندارد محیطی پراکسی روی میزبان Gateway ‏(HTTPS_PROXY، HTTP_PROXY، NO_PROXY و گونه‌های حروف کوچک) پیروی می‌کند. پیکربندی پراکسی در سطح میزبان را بر تنظیمات مختص هر کانال ترجیح دهید.
• با فعال‌بودن messages.removeAckAfterReply، پس از تحویل یک پاسخ قابل‌مشاهده، OpenClaw واکنش تأیید را پاک می‌کند.

تماس با درخواست‌کنندهٔ فعلی از طریق MeowCaller (آزمایشی)

Plugin می‌تواند در نوبت‌های عامل که از WhatsApp آغاز شده‌اند، whatsapp_call را در دسترس قرار دهد. این قابلیت از MeowCaller برای برقراری تماس صوتی WhatsApp با درخواست‌کنندهٔ فعلی و مجاز و پخش پیام TTS متعلق به OpenClaw پس از پاسخ‌دادن او استفاده می‌کند. ابزار هیچ پارامتری برای شمارهٔ مقصد ندارد، بنابراین یک درخواست نمی‌تواند تماس را به مقصد دیگری هدایت کند. این قابلیت به‌طور پیش‌فرض غیرفعال است.

{"channels": {"whatsapp": {  "actions": {    "calls": true  }}}}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.gitcd meowcallergit checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3fmkdir -p "$HOME/.local/bin"go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"mkdir -p "$state_dir"chmod 700 "$state_dir"meowcaller pair --store "$state_dir/wa-voip.db"

محدودیت‌ها: فقط تماس‌های صوتی خروجی یک‌به‌یک، بدون شماره‌های مقصد دلخواه، بدون احراز هویت مشترک با اتصال گفتگو، بدون تماس با خود در حالت شمارهٔ شخصی یا گفت‌وگو با خود، صدای تولیدشده با سقف ۶۰ ثانیه، بدون رسید شنیده‌شدن در سمت گوشی فراتر از تکمیل پاسخ، پخش و قطع تماس در MeowCaller، و OpenClaw فرایند همراه را پس از بازهٔ محدود ۱۱۵ تا ۱۷۵ ثانیه متوقف می‌کند (شامل مراحل اتصال، پاسخ، پخش و خاموش‌شدن MeowCaller).

درخواست‌های تأیید

WhatsApp می‌تواند درخواست‌های تأیید اجرای فرمان و Plugin را به‌شکل واکنش‌های 👍/👎 نمایش دهد؛ این رفتار با پیکربندی سطح بالای انتقال تأیید کنترل می‌شود:

{  approvals: {    exec: {      enabled: true,      mode: "session",    },    plugin: {      enabled: true,      mode: "targets",      targets: [{ channel: "whatsapp", to: "+15551234567" }],    },  },}

approvals.exec و approvals.plugin مستقل هستند؛ فعال‌کردن WhatsApp به‌عنوان کانال فقط انتقال را پیوند می‌دهد و تا زمانی که خانوادهٔ تأیید متناظر فعال و به آنجا مسیریابی نشده باشد چیزی ارسال نمی‌کند. حالت نشست، تأییدهای بومی ایموجی را فقط برای تأییدهایی تحویل می‌دهد که از WhatsApp سرچشمه گرفته‌اند. حالت مقصد از خط لولهٔ مشترک انتقال برای مقصدهای صریح استفاده می‌کند و انتشار جداگانهٔ پیام مستقیم به تأییدکنندگان ایجاد نمی‌کند.

واکنش‌های تأیید WhatsApp به تأییدکنندگان صریح در allowFrom (یا "*") نیاز دارند. defaultTo مقصدهای عادی و پیش‌فرض پیام را تعیین می‌کند، نه فهرست تأییدکنندگان را. فرمان‌های دستی /approve نیز پیش از حل تأیید، از مسیر عادی مجوزدهی فرستنده در WhatsApp عبور می‌کنند.

قلاب‌های Plugin و حریم خصوصی

پیام‌های ورودی WhatsApp ممکن است محتوای شخصی، شماره‌های تلفن، شناسه‌های گروه، نام فرستندگان و فیلدهای هم‌بستگی نشست را دربر داشته باشند. WhatsApp بارهای قلاب ورودی message_received را برای Pluginها منتشر نمی‌کند، مگر اینکه آن را صریحاً فعال کنید:

{  channels: {    whatsapp: {      pluginHooks: {        messageReceived: true,      },    },  },}

فعال‌سازی را با channels.whatsapp.accounts.<id>.pluginHooks.messageReceived به یک حساب محدود کنید. این گزینه را فقط برای Pluginهایی فعال کنید که برای دسترسی به محتوا و شناسه‌های ورودی WhatsApp به آن‌ها اعتماد دارید.

کنترل دسترسی و فعال‌سازی

اتصال‌های پیکربندی‌شده ACP

WhatsApp از اتصال‌های ماندگار ACP از طریق bindings[] در سطح بالا پشتیبانی می‌کند:

{  bindings: [    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "direct", id: "+15555550123" },      },    },    {      type: "acp",      agentId: "codex",      match: {        channel: "whatsapp",        accountId: "work",        peer: { kind: "group", id: "120363424282127706@g.us" },      },    },  ],}

گفت‌وگوهای مستقیم با شماره‌های E.164 مطابقت دارند؛ گروه‌ها با JIDهای گروه WhatsApp مطابقت دارند. فهرست‌های مجاز گروه، خط‌مشی فرستنده و شرط اشاره/فعال‌سازی پیش از آن اجرا می‌شوند که OpenClaw از وجود نشست متصل ACP اطمینان حاصل کند. اتصال منطبق، مالک مسیر است — گروه‌های پخش آن نوبت را به نشست‌های عادی WhatsApp توزیع نمی‌کنند.

رفتار شماره شخصی و گفت‌وگو با خود

هنگامی که شماره خودِ پیوندشده در allowFrom نیز وجود داشته باشد، حفاظت‌های گفت‌وگو با خود فعال می‌شوند: رسید خواندن برای نوبت‌های گفت‌وگو با خود ارسال نمی‌شود، رفتار فعال‌سازی خودکار با JID اشاره که باعث اعلان برای خودتان می‌شود نادیده گرفته می‌شود و هنگامی که messages.responsePrefix تنظیم نشده باشد، پاسخ‌ها به‌طور پیش‌فرض با [{identity.name}] (یا [openclaw]) آغاز می‌شوند.

نرمال‌سازی پیام و زمینه

[Replying to <sender> id:<stanzaId>]<quoted body or media placeholder>[/Replying]

{ channels: { whatsapp: { sendReadReceipts: false } } }

تحویل، قطعه‌بندی و رسانه

نقل‌قول پاسخ

channels.whatsapp.replyToMode نقل‌قول بومی پاسخ را کنترل می‌کند (پاسخ‌های خروجی به‌طور قابل‌مشاهده پیام ورودی را نقل‌قول می‌کنند):

بازنویسی برای هر حساب: channels.whatsapp.accounts.<id>.replyToMode.

{ channels: { whatsapp: { replyToMode: "first" } } }

سطح واکنش

channels.whatsapp.reactionLevel گستره استفاده عامل از واکنش‌های ایموجی را کنترل می‌کند:

بازنویسی برای هر حساب: channels.whatsapp.accounts.<id>.reactionLevel.

{ channels: { whatsapp: { reactionLevel: "ack" } } }

واکنش‌های تأیید

channels.whatsapp.ackReaction هنگام دریافت پیام ورودی، واکنشی فوری ارسال می‌کند که با reactionLevel کنترل می‌شود (در حالت "off" سرکوب می‌شود):

{  channels: {    whatsapp: {      ackReaction: {        emoji: "👀",        direct: true,        group: "mentions", // always | mentions | never      },    },  },}

نکات: بلافاصله پس از پذیرش پیام ورودی (پیش از پاسخ) ارسال می‌شود؛ اگر ackReaction بدون emoji وجود داشته باشد، WhatsApp از ایموجی هویت عامل مسیریابی‌شده استفاده می‌کند و در صورت نبود آن به "👀" بازمی‌گردد (ackReaction را حذف کنید یا برای نبود تأیید، emoji: "" را تنظیم کنید)؛ شکست‌ها ثبت می‌شوند اما تحویل پاسخ را مسدود نمی‌کنند؛ حالت گروه mentions فقط در نوبت‌هایی که با اشاره فعال شده‌اند واکنش نشان می‌دهد، درحالی‌که فعال‌سازی گروه always این بررسی را دور می‌زند؛ WhatsApp فقط از channels.whatsapp.ackReaction استفاده می‌کند (messages.ackReaction قدیمی در اینجا اعمال نمی‌شود).

واکنش‌های وضعیت چرخه حیات

برای اینکه WhatsApp در طول یک نوبت به‌جای باقی‌گذاشتن ایموجی ثابت دریافت، واکنش تأیید را جایگزین کند و میان وضعیت‌هایی مانند در صف، در حال فکر، فعالیت ابزار، Compaction، انجام‌شده و خطا بچرخد، messages.statusReactions.enabled: true را تنظیم کنید:

{  messages: {    statusReactions: {      enabled: true,      emojis: {        deploy: "🛫",        build: "🏗️",        concierge: "💁",      },    },  },}

نکات: channels.whatsapp.ackReaction همچنان واجد شرایط بودن پیام‌های مستقیم و گروه‌ها را کنترل می‌کند؛ وضعیت در صف از همان ایموجی مؤثر واکنش تأیید ساده استفاده می‌کند؛ WhatsApp برای هر پیام یک جایگاه واکنش ربات دارد، بنابراین به‌روزرسانی‌های چرخه حیات واکنش فعلی را در همان محل جایگزین می‌کنند؛ messages.removeAckAfterReply: true پس از زمان نگه‌داری پیکربندی‌شده برای انجام‌شده/خطا، واکنش وضعیت نهایی را پاک می‌کند؛ دسته‌های ایموجی ابزار شامل tool، coding، web، deploy، build و concierge هستند.

چندحسابی و اطلاعات اعتبارسنجی

ابزارها، کنش‌ها و نوشتن پیکربندی

• پشتیبانی ابزار عامل شامل کنش واکنش WhatsApp (react) است.
• دروازه‌های کنش: channels.whatsapp.actions.reactions، channels.whatsapp.actions.polls (مقدار پیش‌فرض کنش‌های موجود true است)، channels.whatsapp.actions.calls (مقدار پیش‌فرض false است؛ MeowCaller را در بالا ببینید).
• نوشتن پیکربندی به ابتکار کانال به‌طور پیش‌فرض فعال است؛ با channels.whatsapp.configWrites: false آن را غیرفعال کنید.

عیب‌یابی

openclaw channels login --channel whatsappopenclaw channels status

{  web: {    whatsapp: {      keepAliveIntervalMs: 15000,      connectTimeoutMs: 60000,      defaultQueryTimeoutMs: 60000,    },  },}

openclaw channels status --probeopenclaw doctoropenclaw logs --followopenclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \  ~/.openclaw/credentials/whatsapp/<accountId>.bakopenclaw channels logout --channel whatsapp --account <accountId>openclaw channels login --channel whatsapp --account <accountId>

اعلان‌های سیستمی

WhatsApp از طریق نگاشت‌های groups و direct از اعلان‌های سیستمی به سبک Telegram برای گروه‌ها و گفت‌وگوهای مستقیم پشتیبانی می‌کند.

تفکیک برای پیام‌های گروهی: ابتدا نگاشت مؤثر groups تعیین می‌شود — اگر حساب اصلاً کلید groups مخصوص خود را تعریف کند، آن کلید به‌طور کامل جایگزین نگاشت ریشه groups می‌شود (بدون ادغام عمیق). سپس جست‌وجوی اعلان روی همان نگاشت حاصل انجام می‌شود:

1. اعلان مختص گروه (groups["<groupId>"].systemPrompt): زمانی استفاده می‌شود که ورودی گروه وجود داشته باشد و کلید systemPrompt آن تعریف شده باشد. رشته خالی ("") نویسه عام را سرکوب می‌کند و هیچ اعلانی اعمال نمی‌شود.
2. اعلان نویسه عام گروه (groups["*"].systemPrompt): زمانی استفاده می‌شود که ورودی گروه مشخص وجود نداشته باشد، یا وجود داشته باشد اما کلید systemPrompt نداشته باشد.

تفکیک پیام‌های مستقیم، همین الگو را به‌طور یکسان روی نگاشت direct و direct["*"] دنبال می‌کند.

تفاوت با Telegram: Telegram در پیکربندی چندحسابی، groups ریشه را برای همه حساب‌ها سرکوب می‌کند (حتی حساب‌هایی که groups مخصوص خود را ندارند) تا ربات پیام‌های گروه‌هایی را که عضو آن‌ها نیست دریافت نکند. WhatsApp این محافظ را اعمال نمی‌کند — groups/direct ریشه، صرف‌نظر از تعداد حساب‌ها، توسط هر حسابی که بازنویسی مخصوص خود را نداشته باشد به ارث برده می‌شود. در پیکربندی چندحسابی WhatsApp، اگر اعلان‌های مختص هر حساب می‌خواهید، نگاشت کامل را صریحاً زیر هر حساب تعریف کنید.

رفتار مهم:

• channels.whatsapp.groups هم نگاشت پیکربندی هر گروه و هم فهرست مجاز گروه در سطح گفت‌وگو است. در دامنه ریشه یا حساب، groups["*"] برای آن دامنه به معنی «همه گروه‌ها پذیرفته می‌شوند» است.
• فقط زمانی systemPrompt نویسه عام اضافه کنید که از قبل می‌خواهید آن دامنه همه گروه‌ها را بپذیرد. برای اینکه فقط مجموعه ثابتی از شناسه‌های گروه واجد شرایط بمانند، به‌جای استفاده از groups["*"]، اعلان را در هر ورودی صریحاً مجازشده تکرار کنید.
• پذیرش گروه و مجوز فرستنده دو بررسی جداگانه‌اند. groups["*"] دامنه گروه‌هایی را که به پردازش گروه می‌رسند گسترش می‌دهد؛ همه فرستندگان آن گروه‌ها را مجاز نمی‌کند — این مورد همچنان توسط groupPolicy/groupAllowFrom کنترل می‌شود.
• channels.whatsapp.direct برای پیام‌های مستقیم اثر جانبی مشابهی ندارد: direct["*"] فقط پس از آنکه یک پیام مستقیم توسط dmPolicy همراه با allowFrom یا قواعد مخزن جفت‌سازی پذیرفته شد، پیکربندی پیش‌فرض را فراهم می‌کند.

نمونه:

{  channels: {    whatsapp: {      groups: {        // Use only if all groups should be admitted at the root scope.        // Applies to all accounts that do not define their own groups map.        "*": { systemPrompt: "Default prompt for all groups." },      },      direct: {        // Applies to all accounts that do not define their own direct map.        "*": { systemPrompt: "Default prompt for all direct chats." },      },      accounts: {        work: {          groups: {            // This account defines its own groups, so root groups are fully            // replaced. To keep a wildcard, define "*" explicitly here too.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "Focus on project management.",            },            // Use only if all groups should be admitted in this account.            "*": { systemPrompt: "Default prompt for work groups." },          },          direct: {            // This account defines its own direct map, so root direct entries are            // fully replaced. To keep a wildcard, define "*" explicitly here too.            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },            "*": { systemPrompt: "Default prompt for work direct chats." },          },        },      },    },  },}

اشاره‌گرهای مرجع پیکربندی

مرجع اصلی: مرجع پیکربندی - WhatsApp

مرتبط

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