WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

• يطلب مسار التهيئة (openclaw onboard) وopenclaw channels add --channel whatsapp تثبيت WhatsApp plugin في أول مرة تختاره.
• يوفر openclaw channels login --channel whatsapp أيضًا مسار التثبيت عندما لا يكون plugin موجودًا بعد.
• قناة التطوير + نسخة git: تكون افتراضيًا على مسار plugin المحلي.
• Stable/Beta: يستخدم حزمة npm @openclaw/whatsapp على وسم الإصدار الرسمي الحالي.

openclaw plugins install @openclaw/whatsapp

winget install --id Git.Git -e

​

الإعداد السريع

{
  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-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

أنماط النشر

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

​

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

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

​

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

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

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

​

التحكم في الوصول والتفعيل

​

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

• تخطي إيصالات القراءة لأدوار المحادثة الذاتية
• تجاهل سلوك التشغيل التلقائي عبر 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,
        },
      },
    },
  },
}

​

التسليم، والتقسيم إلى أجزاء، والوسائط

​

اقتباس الردود

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

​

مستوى التفاعل

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

​

تفاعلات الإقرار

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

• تُرسل فورا بعد قبول الوارد (قبل الرد)
• تُسجّل الإخفاقات لكنها لا تمنع تسليم الرد العادي
• يتفاعل وضع المجموعة mentions في الدورات التي تُشغّل بالذكر؛ يعمل تفعيل المجموعة always كتجاوز لهذا الفحص
• يستخدم WhatsApp channels.whatsapp.ackReaction (لا يُستخدم messages.ackReaction القديم هنا)

​

الحسابات المتعددة وبيانات الاعتماد

​

الأدوات والإجراءات وكتابات التهيئة

• يتضمن دعم أدوات الوكيل إجراء تفاعل WhatsApp ‏(react).
• بوابات الإجراءات:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• تُفعّل كتابات التهيئة التي تبدأها القناة افتراضيًا (عطّلها عبر channels.whatsapp.configWrites=false).

​

استكشاف الأخطاء وإصلاحها

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

​

مطالبات النظام

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

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

• 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

• الوصول: 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

​

ذو صلة

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