WhatsApp

الحالة: جاهز للإنتاج عبر WhatsApp Web ‏(Baileys). يدير Gateway الجلسة (أو الجلسات) المرتبطة؛ ولا توجد قناة WhatsApp منفصلة من Twilio.

التثبيت

يطلب openclaw onboard وopenclaw channels add --channel whatsapp تثبيت Plugin عند اختياره أول مرة؛ ويوفر openclaw channels login --channel whatsapp مسار التثبيت نفسه إذا كان Plugin مفقودًا. تستخدم نسخ التطوير مسار Plugin المحلي؛ بينما تثبّت الإصدارات المستقرة/التجريبية @openclaw/whatsapp من ClawHub أولًا، مع الرجوع إلى npm عند التعذر. يُشحن وقت تشغيل WhatsApp خارج حزمة OpenClaw الأساسية على npm، لذلك تبقى تبعيات وقت التشغيل الخاصة به مع 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 مع مقدم الطلب الحالي المصرح له وتشغيل رسالة تحويل النص إلى كلام من 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 الواردة إلى Plugins ما لم تشترك صراحةً:

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

احصر الاشتراك في حساب واحد ضمن channels.whatsapp.accounts.<id>.pluginHooks.messageReceived. لا تفعّل هذا إلا لـ Plugins التي تثق بها للتعامل مع محتوى 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 الإشارة الذي قد ينبهك أنت، وتستخدم الردود افتراضيًا [{identity.name}] (أو [openclaw]) عندما لا تكون messages.responsePrefix مُعيّنة.

تسوية الرسائل والسياق

[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

ذو صلة

• الاقتران
• المجموعات
• الأمان
• توجيه القنوات
• التوجيه متعدد الوكلاء
• استكشاف الأخطاء وإصلاحها