WhatsApp

الحالة: جاهز للإنتاج عبر WhatsApp Web (Baileys). يتولى Gateway امتلاك الجلسة/الجلسات المرتبطة.

التثبيت (عند الطلب)

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

الاتصال بمقدم الطلب الحالي باستخدام MeowCaller (تجريبي)

يمكن لـ Plugin الخاص بـ WhatsApp كشف whatsapp_call في أدوار الوكيل الناشئة من WhatsApp. تستخدم الأداة MeowCaller لإجراء مكالمة صوتية عبر WhatsApp إلى مقدم الطلب المخوّل الحالي وتشغّل رسالة OpenClaw TTS بعد أن يجيب. لا تقبل الأداة رقم وجهة، لذلك لا يمكن للمطالبة إعادة توجيه المكالمة إلى طرف ثالث. هذه القدرة التجريبية معطلة افتراضيًا.

{"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 والإجابة والتشغيل والإيقاف

أنماط النشر

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

نموذج وقت التشغيل

• يتولى Gateway امتلاك مقبس WhatsApp وحلقة إعادة الاتصال.
• يستخدم مراقب إعادة الاتصال نشاط نقل WhatsApp Web، وليس حجم رسائل التطبيق الواردة فقط، لذلك لا يُعاد تشغيل جلسة جهاز مرتبط هادئة لمجرد أن لا أحد أرسل رسالة مؤخرًا. لا يزال حد صمت التطبيق الأطول يفرض إعادة اتصال إذا استمرت إطارات النقل في الوصول لكن لم تُعالَج أي رسائل تطبيق خلال نافذة المراقب؛ وبعد إعادة اتصال عابرة لجلسة نشطة مؤخرًا، يستخدم فحص صمت التطبيق هذا مهلة الرسائل العادية لنافذة الاسترداد الأولى.
• توقيتات مقبس Baileys صريحة ضمن web.whatsapp.*: يتحكم keepAliveIntervalMs في نبضات تطبيق WhatsApp Web، ويتحكم connectTimeoutMs في مهلة مصافحة الفتح، ويتحكم defaultQueryTimeoutMs في انتظار استعلامات Baileys بالإضافة إلى حدود عمليات الإرسال/الحضور الصادرة المحلية وإيصالات القراءة الواردة في OpenClaw.
• تتطلب الإرسالات الصادرة مستمع WhatsApp نشطًا للحساب الهدف.
• تُرفق إرسالات المجموعات بيانات ذكر وصفية أصلية لرموز @+<digits> و @<digits> في النص وتسميات الوسائط عندما يطابق الرمز بيانات مشارك WhatsApp الوصفية الحالية، بما في ذلك المجموعات المدعومة بـ LID.
• يتم تجاهل دردشات الحالة والبث (@status, @broadcast).
• يتبع مراقب إعادة الاتصال نشاط نقل WhatsApp Web، وليس حجم رسائل التطبيق الواردة فقط: تبقى جلسات الأجهزة المرتبطة الهادئة عاملة أثناء استمرار إطارات النقل، لكن توقف النقل يفرض إعادة الاتصال قبل مسار قطع الاتصال البعيد اللاحق بوقت كاف.
• تستخدم الدردشات المباشرة قواعد جلسة الرسائل المباشرة (session.dmScope؛ الافتراضي main يدمج الرسائل المباشرة في جلسة الوكيل الرئيسية).
• جلسات المجموعات معزولة (agent:<agentId>:whatsapp:group:<jid>).
• يمكن أن تكون قنوات/نشرات WhatsApp أهدافًا صادرة صريحة مع JID الأصلي @newsletter. تستخدم إرسالات النشرات الصادرة بيانات جلسة القناة الوصفية (agent:<agentId>:whatsapp:channel:<jid>) بدل دلالات جلسة الرسائل المباشرة.
• يحترم نقل WhatsApp Web متغيرات بيئة الوكيل القياسية على مضيف Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / المتغيرات الصغيرة). فضّل إعداد الوكيل على مستوى المضيف بدل إعدادات وكيل WhatsApp الخاصة بالقناة.
• عند تفعيل messages.removeAckAfterReply، يمسح OpenClaw تفاعل إقرار WhatsApp بعد تسليم رد مرئي.

مطالبات الموافقة

يمكن لـ 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. يستخدم وضع الهدف مسار إعادة التوجيه المشترك لأهداف WhatsApp الصريحة ولا ينشئ توسعًا منفصلًا لرسائل مباشرة إلى الموافقين.

تتطلب تفاعلات موافقة WhatsApp موافقين صريحين من WhatsApp من allowFrom أو "*". يتحكم defaultTo في أهداف الرسائل الافتراضية العادية؛ وليس موافقًا للموافقة. لا تزال أوامر /approve اليدوية تمر عبر مسار تخويل مرسل WhatsApp العادي قبل حل الموافقة.

خطافات Plugin والخصوصية

يمكن أن تحتوي رسائل WhatsApp الواردة على محتوى رسائل شخصية، وأرقام هواتف، ومعرّفات مجموعات، وأسماء مرسلين، وحقول ربط للجلسات. لهذا السبب، لا يبث WhatsApp حِمولات hook الواردة message_received إلى Plugins إلا إذا اخترت ذلك صراحة:

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

يمكنك حصر الاشتراك في حساب واحد:

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

فعّل هذا فقط مع 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 مثل +15555550123.
• تطابق المجموعات JIDs مجموعات WhatsApp مثل 120363424282127706@g.us.
• تعمل قوائم سماح المجموعات، وسياسة المرسل، وبوابة الإشارة أو التفعيل قبل أن يضمن OpenClaw وجود جلسة ACP المكوّنة.
• يملك ارتباط ACP مكوّن ومطابق المسار. لا تفرّع مجموعات بث WhatsApp تلك الجولة إلى جلسات WhatsApp عادية.

سلوك الرقم الشخصي والمحادثة الذاتية

عندما يكون الرقم الذاتي المرتبط موجودًا أيضًا في allowFrom، تُفعّل وسائل حماية المحادثة الذاتية في WhatsApp:

• تخطي إيصالات القراءة لجولات المحادثة الذاتية
• تجاهل سلوك التشغيل التلقائي عبر mention-JID الذي كان سيؤدي بخلاف ذلك إلى تنبيه نفسك
• إذا لم يُعيّن 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 في مدى استخدام الوكيل لتفاعلات الرموز التعبيرية على 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 سلسلة فارغة ("")، يُكبَت حرف البدل ولا تُطبَّق أي مطالبة نظام.
2. مطالبة نظام حرف البدل للمجموعات (groups["*"].systemPrompt): تُستخدم عندما يكون إدخال المجموعة المحددة غائبًا تمامًا عن الخريطة، أو عندما يكون موجودًا لكنه لا يعرّف مفتاح systemPrompt.

هرمية الحل للرسائل المباشرة:

تُحدَّد خريطة direct الفعّالة أولًا: إذا عرّف الحساب direct الخاصة به، فإنها تستبدل بالكامل خريطة direct الجذرية (من دون دمج عميق). ثم يُجرى بحث المطالبة على الخريطة المفردة الناتجة:

1. مطالبة النظام الخاصة بالمباشر (direct["<peerId>"].systemPrompt): تُستخدم عندما يكون إدخال النظير المحدد موجودًا في الخريطة و يكون مفتاح systemPrompt الخاص به معرّفًا. إذا كان systemPrompt سلسلة فارغة ("")، يُكبَت حرف البدل ولا تُطبَّق أي مطالبة نظام.
2. مطالبة نظام حرف البدل للمباشر (direct["*"].systemPrompt): تُستخدم عندما يكون إدخال النظير المحدد غائبًا تمامًا عن الخريطة، أو عندما يكون موجودًا لكنه لا يعرّف مفتاح systemPrompt.

الاختلاف عن سلوك الحسابات المتعددة في Telegram: في Telegram، تُكبَت groups الجذرية عمدًا لكل الحسابات في إعداد متعدد الحسابات، حتى الحسابات التي لا تعرّف groups خاصة بها، لمنع بوت من تلقي رسائل مجموعة لمجموعات لا ينتمي إليها. لا يطبّق WhatsApp هذا الحارس: تُورَّث groups الجذرية وdirect الجذرية دائمًا بواسطة الحسابات التي لا تعرّف تجاوزًا على مستوى الحساب، بغض النظر عن عدد الحسابات المُهيأة. في إعداد WhatsApp متعدد الحسابات، إذا أردت مطالبات مجموعة أو مباشرة لكل حساب، فعرّف الخريطة الكاملة ضمن كل حساب صراحة بدلًا من الاعتماد على الإعدادات الافتراضية على مستوى الجذر.

سلوك مهم:

• channels.whatsapp.groups هو خريطة إعدادات لكل مجموعة وقائمة سماح للمجموعات على مستوى المحادثة في الوقت نفسه. في نطاق الجذر أو الحساب، تعني groups["*"] أن "كل المجموعات مقبولة" لذلك النطاق.
• لا تضف systemPrompt لمجموعة بحرف بدل إلا عندما تريد بالفعل أن يقبل ذلك النطاق كل المجموعات. إذا كنت لا تزال تريد أن تكون مجموعة ثابتة فقط من معرّفات المجموعات مؤهلة، فلا تستخدم groups["*"] كافتراضي للمطالبة. بدلًا من ذلك، كرر المطالبة في كل إدخال مجموعة مسموح به صراحة.
• قبول المجموعة وتخويل المرسِل فحصان منفصلان. يوسّع groups["*"] مجموعة المجموعات التي يمكنها الوصول إلى معالجة المجموعات، لكنه لا يخول بحد ذاته كل مرسِل في تلك المجموعات. لا يزال وصول المرسِل مضبوطًا بشكل منفصل بواسطة channels.whatsapp.groupPolicy وchannels.whatsapp.groupAllowFrom.
• لا يملك channels.whatsapp.direct الأثر الجانبي نفسه للرسائل المباشرة. لا يوفر direct["*"] إلا إعداد محادثة مباشرة افتراضيًا بعد قبول الرسالة المباشرة بالفعل بواسطة dmPolicy إضافة إلى allowFrom أو قواعد مخزن الاقتران.

مثال:

{  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

ذات صلة

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