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 و فعالیت پیام‌های برنامه. نشست ساکت اما متصل صرفاً به‌دلیل نرسیدن پیام در زمان اخیر راه‌اندازی مجدد نمی‌شود؛ اتصال مجدد فقط زمانی اجباری می‌شود که فریم‌های انتقال برای یک بازهٔ داخلی ثابت (غیرقابل‌پیکربندی توسط کاربر) نرسند یا پیام‌های برنامه برای مدتی بیش از 4 برابر مهلت عادی پیام ساکت بمانند. بلافاصله پس از اتصال مجدد یک نشست که اخیراً فعال بوده است، نخستین بازه به‌جای بازهٔ 4 برابری از مهلت کوتاه‌تر و عادی پیام استفاده می‌کند. 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_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 عبور می‌کنند.

قلاب‌های 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 نیز وجود داشته باشد، حفاظت‌های گفت‌وگو با خود فعال می‌شوند: رسید خواندن برای نوبت‌های گفت‌وگو با خود ارسال نمی‌شود، رفتار فعال‌سازی خودکار mention-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 قدیمی در اینجا اعمال نمی‌شود).

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

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

{  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 از اعلان‌های سیستمی به سبک 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

مرتبط

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