WhatsApp

Status: آمادهٔ تولید از طریق WhatsApp Web (Baileys). Gateway مالک نشست(های) پیوندشده است.

نصب (در صورت نیاز)

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

نصب دستی همچنان در دسترس است:

openclaw plugins install clawhub:@openclaw/whatsapp

فقط وقتی به fallback رجیستری نیاز دارید از بستهٔ خام npm (@openclaw/whatsapp) استفاده کنید. فقط وقتی به نصب قابل‌بازتولید نیاز دارید، نسخهٔ دقیق را pin کنید.

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

{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>

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

WhatsApp plugin می‌تواند whatsapp_call را در نوبت‌های عاملِ آغازشده از WhatsApp در دسترس قرار دهد. این ابزار از MeowCaller برای برقراری تماس صوتی WhatsApp با درخواست‌کنندهٔ مجاز فعلی استفاده می‌کند و پس از پاسخ‌دادن او، یک پیام TTS از OpenClaw پخش می‌کند. این ابزار شمارهٔ مقصد نمی‌پذیرد، بنابراین یک prompt نمی‌تواند تماس را به شخص ثالث منتقل کند. این قابلیت آزمایشی به‌صورت پیش‌فرض غیرفعال است.

{"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

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

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

مدل زمان‌اجرا

• Gateway مالک socket و حلقهٔ اتصال مجدد WhatsApp است.
• دیده‌بان اتصال مجدد از فعالیت انتقال WhatsApp Web استفاده می‌کند، نه فقط حجم پیام‌های ورودی برنامه؛ بنابراین یک نشست دستگاه پیوندشدهٔ کم‌صدا صرفا به این دلیل که اخیرا کسی پیامی نفرستاده، راه‌اندازی مجدد نمی‌شود. یک سقف طولانی‌تر برای سکوت برنامه همچنان اگر فریم‌های انتقال همچنان برسند اما در پنجرهٔ دیده‌بان هیچ پیام برنامه‌ای پردازش نشود، اتصال مجدد را اجبار می‌کند؛ پس از یک اتصال مجدد گذرا برای نشستی که اخیرا فعال بوده، آن بررسی سکوت برنامه برای نخستین پنجرهٔ بازیابی از timeout عادی پیام استفاده می‌کند.
• زمان‌بندی‌های socket در Baileys به‌صورت صریح زیر web.whatsapp.* هستند: keepAliveIntervalMs pingهای برنامهٔ WhatsApp Web را کنترل می‌کند، connectTimeoutMs timeout handshake آغازین را کنترل می‌کند، و defaultQueryTimeoutMs انتظارهای query در Baileys به‌علاوهٔ کران‌های عملیات ارسال خروجی/حضور محلی و رسید خواندن ورودی OpenClaw را کنترل می‌کند.
• ارسال‌های خروجی برای حساب هدف به یک listener فعال WhatsApp نیاز دارند.
• ارسال‌های گروهی برای توکن‌های @+<digits> و @<digits> در متن و captionهای رسانه، وقتی توکن با فرادادهٔ فعلی مشارکت‌کنندهٔ WhatsApp منطبق باشد، از جمله گروه‌های پشتیبانی‌شده با LID، فرادادهٔ mention بومی را پیوست می‌کنند.
• گفتگوهای وضعیت و broadcast نادیده گرفته می‌شوند (@status، @broadcast).
• دیده‌بان اتصال مجدد فعالیت انتقال WhatsApp Web را دنبال می‌کند، نه فقط حجم پیام‌های ورودی برنامه: نشست‌های دستگاه پیوندشدهٔ کم‌صدا تا وقتی فریم‌های انتقال ادامه دارند برقرار می‌مانند، اما توقف انتقال بسیار پیش از مسیر دیرتر قطع اتصال راه‌دور، اتصال مجدد را اجبار می‌کند.
• گفتگوهای مستقیم از قواعد نشست DM استفاده می‌کنند (session.dmScope؛ مقدار پیش‌فرض main، DMها را به نشست اصلی عامل فرو می‌ریزد).
• نشست‌های گروهی جدا هستند (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters می‌توانند هدف‌های خروجی صریح با JID بومی @newsletter خود باشند. ارسال‌های newsletter خروجی به‌جای معناشناسی نشست DM از فرادادهٔ نشست کانال (agent:<agentId>:whatsapp:channel:<jid>) استفاده می‌کنند.
• انتقال WhatsApp Web متغیرهای محیطی proxy استاندارد روی میزبان gateway را رعایت می‌کند (HTTPS_PROXY، HTTP_PROXY، NO_PROXY / گونه‌های حروف کوچک). پیکربندی proxy در سطح میزبان را به تنظیمات proxy مخصوص کانال WhatsApp ترجیح دهید.
• وقتی messages.removeAckAfterReply فعال باشد، OpenClaw واکنش ack در WhatsApp را پس از تحویل پاسخ قابل‌مشاهده پاک می‌کند.

promptهای تأیید

WhatsApp می‌تواند promptهای تأیید exec و plugin را با واکنش‌های 👍 / 👎 نمایش دهد. تحویل با پیکربندی سطح‌بالای forwarding تأیید کنترل می‌شود:

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

approvals.exec و approvals.plugin مستقل هستند. فعال‌کردن WhatsApp به‌عنوان یک کانال فقط انتقال را پیوند می‌دهد؛ مگر اینکه خانوادهٔ تأیید متناظر فعال باشد و به WhatsApp مسیریابی شود، promptهای تأیید ارسال نمی‌کند. حالت نشست، تأییدهای emoji بومی را فقط برای تأییدهایی تحویل می‌دهد که از WhatsApp آغاز شده‌اند. حالت هدف از pipeline مشترک forwarding برای هدف‌های صریح WhatsApp استفاده می‌کند و fanout جداگانهٔ approver-DM ایجاد نمی‌کند.

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

hookهای Plugin و حریم خصوصی

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

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

می‌توانید این فعال‌سازی را به یک حساب محدود کنید:

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

این گزینه را فقط برای 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 مانند +15555550123 مطابقت دارند.
• گروه‌ها با JIDهای گروه WhatsApp مانند 120363424282127706@g.us مطابقت دارند.
• allowlistهای گروه، خط‌مشی فرستنده، و کنترل mention یا activation پیش از اینکه OpenClaw وجود نشست ACP پیکربندی‌شده را تضمین کند اجرا می‌شوند.
• یک اتصال ACP پیکربندی‌شده که مطابقت داشته باشد مالک مسیر است. گروه‌های پخش WhatsApp آن نوبت را به نشست‌های معمولی WhatsApp پخش نمی‌کنند.

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

وقتی شماره خودِ پیوندشده در allowFrom نیز وجود داشته باشد، محافظ‌های گفت‌وگوی با خود در WhatsApp فعال می‌شوند:

• رد کردن رسیدهای خواندن برای نوبت‌های گفت‌وگو با خود
• نادیده گرفتن رفتار فعال‌سازی خودکار mention-JID که در غیر این صورت خودتان را ping می‌کند
• اگر messages.responsePrefix تنظیم نشده باشد، پاسخ‌های گفت‌وگو با خود به‌صورت پیش‌فرض [{identity.name}] یا [openclaw] خواهند بود

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

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

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

{  channels: {    whatsapp: {      accounts: {        work: {          sendReadReceipts: false,        },      },    },  },}

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

نقل‌قول در پاسخ

WhatsApp از نقل‌قول بومی در پاسخ پشتیبانی می‌کند، که در آن پاسخ‌های خروجی به‌صورت قابل‌مشاهده پیام ورودی را نقل می‌کنند. آن را با channels.whatsapp.replyToMode کنترل کنید.

پیش‌فرض "off" است. بازنویسی‌های هر حساب از channels.whatsapp.accounts.<id>.replyToMode استفاده می‌کنند.

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

سطح واکنش

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

پیش‌فرض: "minimal".

بازنویسی‌های هر حساب از channels.whatsapp.accounts.<id>.reactionLevel استفاده می‌کنند.

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

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

WhatsApp از واکنش‌های تأیید دریافت فوری هنگام دریافت ورودی از طریق channels.whatsapp.ackReaction پشتیبانی می‌کند. واکنش‌های تأیید دریافت با reactionLevel کنترل می‌شوند — وقتی 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 در طول یک نوبت، به‌جای باقی گذاشتن یک ایموجی رسید ثابت، واکنش تأیید را جایگزین کند. وقتی فعال باشد، OpenClaw از همان جایگاه واکنش پیام ورودی برای وضعیت‌های چرخه حیات مانند در صف، در حال فکر کردن، فعالیت ابزار، 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
• نوشتن پیکربندی آغازشده از کانال به‌صورت پیش‌فرض فعال است (از طریق 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 آن تعریف شده باشد. اگر systemPrompt یک رشته خالی ("") باشد، wildcard سرکوب می‌شود و هیچ پرامپت سیستمی اعمال نمی‌شود.
2. پرامپت سیستم wildcard گروه (groups["*"].systemPrompt): وقتی استفاده می‌شود که ورودی گروه مشخص کاملاً از نگاشت غایب باشد، یا وجود داشته باشد اما هیچ کلید systemPrompt تعریف نکند.

سلسله‌مراتب حل برای پیام‌های مستقیم:

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

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

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

رفتار مهم:

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

مثال:

{  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

فیلدهای مهم WhatsApp:

• دسترسی: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• تحویل: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• چندحسابی: accounts.<id>.enabled, accounts.<id>.authDir, بازنویسی‌های سطح حساب
• عملیات: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• رفتار نشست: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• پرامپت‌ها: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

مرتبط

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