WhatsApp

​

التثبيت

openclaw plugins install clawhub:@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-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 الخام ونشاط رسائل التطبيق. لا تُعاد جلسة هادئة لكنها متصلة لمجرد عدم وصول رسالة مؤخرًا؛ ولا تُفرض إعادة الاتصال إلا عندما تتوقف إطارات النقل عن الوصول خلال نافذة داخلية ثابتة (غير قابلة للتهيئة من المستخدم)، أو تظل رسائل التطبيق صامتة لما يتجاوز 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 (تجريبي)

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -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"

​

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

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

​

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

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

​

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

​

ارتباطات ACP المُهيّأة

{
  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" },
      },
    },
  ],
}

​

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

​

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

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

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

​

التسليم والتقسيم والوسائط

​

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

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

​

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

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

​

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

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // دائمًا | الإشارات | مطلقًا
      },
    },
  },
}

​

تفاعلات حالة دورة الحياة

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        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 whatsapp
openclaw channels status

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

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

موجّهات النظام

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

• يمثّل 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: "الموجّه الافتراضي لمحادثات العمل المباشرة." },
          },
        },
      },
    },
  },
}

​

مؤشرات مرجع التهيئة

​

ذو صلة

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