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 خارج حزمة 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 إلى مقدم الطلب الحالي المصرح له وتشغيل رسالة تحويل النص إلى كلام من 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", // دائمًا | الإشارات | مطلقًا      },    },  },}

ملاحظات: يُرسل فور قبول الرسالة الواردة (قبل الرد)؛ وإذا كان 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

ذو صلة

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