WhatsApp

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

نصب

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 و فعالیت پیام‌های برنامه. نشستی که ساکت اما متصل است، صرفاً به‌دلیل نرسیدن پیام در زمان اخیر دوباره راه‌اندازی نمی‌شود؛ اتصال مجدد فقط زمانی اجباری می‌شود که فریم‌های انتقال برای یک بازه داخلی ثابت (غیرقابل‌پیکربندی توسط کاربر) متوقف شوند یا پیام‌های برنامه برای مدتی بیش از 4 برابر مهلت عادی پیام ساکت بمانند. بلافاصله پس از اتصال مجدد یک نشست که اخیراً فعال بوده است، آن بازه نخست به‌جای بازه 4 برابری از مهلت عادی و کوتاه‌تر پیام استفاده می‌کند. OpenClaw می‌تواند به پیام‌های آفلاینی که Baileys در ابتدای آن اتصال مجدد تحویل می‌دهد، به‌طور خودکار پاسخ دهد؛ این رفتار به طول‌عمر حذف موارد تکراری شناسه پیام ورودی محدود است. راه‌اندازی اولیه محافظ کوتاه در برابر تاریخچه قدیمی را حفظ می‌کند.
• ارسال‌های خروجی به شنونده فعال 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 و گونه‌های حروف کوچک) پیروی می‌کند. پیکربندی پراکسی در سطح میزبان را به تنظیمات هر کانال ترجیح دهید.

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

Plugin می‌تواند whatsapp_call را در نوبت‌های عامل که از WhatsApp آغاز شده‌اند، ارائه کند. این قابلیت از 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"

محدودیت‌ها: فقط تماس‌های صوتی خروجی یک‌به‌یک، بدون شماره‌های مقصد دلخواه، بدون احراز هویت مشترک با اتصال گفت‌وگو، بدون تماس با خود در حالت شماره شخصی/گفت‌وگو با خود، صدای تولیدشده با سقف 60 ثانیه، بدون رسید شنیده‌شدن در سمت گوشی فراتر از تکمیل پاسخ/پخش/قطع تماس MeowCaller، و OpenClaw فرایند همراه را پس از یک بازه محدود 115 تا 175 ثانیه‌ای متوقف می‌کند (که مراحل اتصال، پاسخ، پخش و خاموش‌شدن 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 عبور می‌کنند.

واکنش‌های پرسش

برای یک پرامپت ask_user با یک پرسش غیرمحرمانه تک‌انتخابی و یک تا چهار گزینه، WhatsApp ‏1️⃣ تا 4️⃣ را کنار برچسب گزینه‌ها نشان می‌دهد. برای پاسخ‌دادن، با شماره متناظر به پرامپت تحویل‌شده واکنش نشان دهید. OpenClaw از طریق Gateway شماره را به گزینه معیار نگاشت می‌کند؛ ضربه‌های قدیمی یا تکراری نادیده گرفته می‌شوند. پرامپت‌های چندپرسشی، چندانتخابی و متن‌آزاد همچنان فقط با پاسخ متنی کار می‌کنند. قواعد عادی پذیرش پیام مستقیم/گروهی 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 که باعث اعلان به خودتان می‌شود نادیده گرفته می‌شود، و وقتی 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 قدیمی در اینجا اعمال نمی‌شود).

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

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

{  messages: {    statusReactions: {      enabled: true,    },  },}

نکات: channels.whatsapp.ackReaction همچنان واجد شرایط‌بودن پیام‌های مستقیم و گروه‌ها را کنترل می‌کند؛ وضعیت در صف از همان ایموجی مؤثر واکنش‌های تأیید ساده استفاده می‌کند؛ WhatsApp برای هر پیام یک جایگاه واکنش بات دارد، بنابراین به‌روزرسانی‌های چرخه‌عمر واکنش جاری را درجا جایگزین می‌کنند و پس از وضعیت نهایی انجام‌شده/خطا، واکنش تأیید را بازمی‌گردانند.

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

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

• پشتیبانی ابزار عامل شامل کنش واکنش 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

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 از اعلان‌های سیستمی به سبک Telegram برای گروه‌ها و گفت‌وگوهای مستقیم، از طریق نگاشت‌های groups و direct پشتیبانی می‌کند.

تفکیک برای پیام‌های گروه: ابتدا نگاشت مؤثر 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: {        // فقط در صورتی استفاده کنید که همهٔ گروه‌ها باید در محدودهٔ ریشه پذیرفته شوند.        // برای همهٔ حساب‌هایی اعمال می‌شود که نگاشت groups خود را تعریف نمی‌کنند.        "*": { systemPrompt: "اعلان پیش‌فرض برای همهٔ گروه‌ها." },      },      direct: {        // برای همهٔ حساب‌هایی اعمال می‌شود که نگاشت direct خود را تعریف نمی‌کنند.        "*": { systemPrompt: "اعلان پیش‌فرض برای همهٔ گفت‌وگوهای مستقیم." },      },      accounts: {        work: {          groups: {            // این حساب groups خود را تعریف می‌کند، بنابراین groups ریشه به‌طور کامل            // جایگزین می‌شود. برای حفظ نویسهٔ عام، "*" را اینجا نیز صریحاً تعریف کنید.            "120363406415684625@g.us": {              requireMention: false,              systemPrompt: "بر مدیریت پروژه تمرکز کن.",            },            // فقط در صورتی استفاده کنید که همهٔ گروه‌ها باید در این حساب پذیرفته شوند.            "*": { systemPrompt: "اعلان پیش‌فرض برای گروه‌های کاری." },          },          direct: {            // این حساب نگاشت direct خود را تعریف می‌کند، بنابراین مدخل‌های direct ریشه            // به‌طور کامل جایگزین می‌شوند. برای حفظ نویسهٔ عام، "*" را اینجا نیز صریحاً تعریف کنید.            "+15551234567": { systemPrompt: "اعلان برای یک گفت‌وگوی مستقیم کاری مشخص." },            "*": { systemPrompt: "اعلان پیش‌فرض برای گفت‌وگوهای مستقیم کاری." },          },        },      },    },  },}

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

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

مرتبط

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