روبوت QQ

يتصل QQ Bot بـ OpenClaw عبر واجهة QQ Bot API الرسمية (بوابة WebSocket). تُعد المحادثات الخاصة C2C وعمليات الإشارة @ في المجموعات نوعَي المحادثة الأساسيين، مع دعم الوسائط الغنية (الصور والصوت والفيديو والملفات). تُدعَم رسائل قنوات النقابات للنصوص والصور ذات عناوين URL البعيدة فقط؛ ولا تتوفر الرسائل الصوتية أو مقاطع الفيديو أو عمليات رفع الملفات أو الصور المحلية/Base64 في قنوات النقابات. التفاعلات وسلاسل المحادثات غير مدعومة في أي مكان.

الحالة: Plugin رسمي قابل للتنزيل.

التثبيت

openclaw plugins install @openclaw/qqbot

الإعداد

1. انتقل إلى منصة QQ المفتوحة وامسح رمز QR ضوئيًا باستخدام تطبيق QQ على الهاتف للتسجيل / تسجيل الدخول.
2. انقر على Create Bot لإنشاء بوت QQ جديد.
3. ابحث عن AppID وAppSecret في صفحة إعدادات البوت وانسخهما.

4. أضف القناة:

openclaw channels add --channel qqbot --token "AppID:AppSecret"

5. أعد تشغيل Gateway.

الإعداد التفاعلي:

openclaw channels add

يوفر المعالج أيضًا الربط عبر رمز QR بديلًا عن كتابة AppID/AppSecret يدويًا: امسح الرمز باستخدام تطبيق الهاتف المرتبط بـ QQ Bot المستهدف لإكمال الربط. يحفظ OpenClaw بيانات الاعتماد المُعادة ضمن نطاق إعدادات الحساب.

التهيئة

الحد الأدنى من الإعدادات:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: "YOUR_APP_SECRET",    },  },}

متغيرات البيئة للحساب الافتراضي (الحساب ذو المستوى الأعلى فقط):

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret مستند إلى ملف:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecretFile: "/path/to/qqbot-secret.txt",    },  },}

AppSecret عبر SecretRef من البيئة:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },    },  },}

ملاحظات:

• openclaw channels add --channel qqbot --token-file ... يعيّن AppSecret فقط؛ ويجب أن يكون appId معيّنًا مسبقًا في الإعدادات أو QQBOT_APP_ID.
• clientSecret يقبل سلسلة نصية صريحة أو مسار ملف (clientSecretFile) أو كائن SecretRef منظّمًا.
• تُرفض سلاسل العلامات القديمة secretref:... / secretref-env:... مع clientSecret؛ استخدم بدلًا منها كائن SecretRef منظّمًا.

البث

{  channels: {    qqbot: {      streaming: {        mode: "partial", // block streaming: "partial" (default) or "off"        nativeTransport: true, // use QQ's official C2C stream_messages API for DMs      },    },  },}

• streaming.mode: "off" يعطّل بث الكتل للحساب.
• streaming.nativeTransport: true يبث ردود C2C (الرسائل الخاصة) عبر واجهة stream_messages الرسمية من QQ؛ ولا تتأثر أهداف المجموعات/القنوات.
• تُنقل القيم المفردة القديمة streaming: true|false والمفتاح streaming.c2cStreamApi إلى هذه البنية عبر openclaw doctor --fix.
• /bot-streaming on|off يبدّل الإعداد نفسه من رسالة خاصة.

سياسة الوصول

• allowFrom / groupAllowFrom يحددان من يمكنه التحدث مع البوت في سياقات C2C / المجموعات. تتحكم dmPolicy / groupPolicy ‏(open | allowlist | disabled) في وضع الإنفاذ. تكون القيمة الافتراضية لـ dmPolicy هي allowlist بمجرد احتواء allowFrom على إدخال محدد (ليس حرف بدل)، وإلا فتكون open. وتكون القيمة الافتراضية لـ groupPolicy هي allowlist بمجرد احتواء groupAllowFrom أو allowFrom على إدخال محدد، وإلا فتكون open.
• تتطلب أوامر الشرطة المائلة "المصادقة: قائمة السماح" إدخالًا صريحًا ليس حرف بدل في allowFrom (أو groupAllowFrom للاستدعاءات ضمن المجموعات) بغض النظر عن dmPolicy / groupPolicy — راجع أوامر الشرطة المائلة.

إعداد حسابات متعددة

شغّل عدة بوتات QQ ضمن مثيل OpenClaw واحد:

{  channels: {    qqbot: {      enabled: true,      appId: "111111111",      clientSecret: "secret-of-bot-1",      accounts: {        bot2: {          enabled: true,          appId: "222222222",          clientSecret: "secret-of-bot-2",        },      },    },  },}

يمتلك كل حساب اتصال WebSocket وعميل API وذاكرة تخزين مؤقت للرموز معزولة، ومفهرسة بواسطة appId. تُوسَم أسطر السجل بمعرّف الحساب المالك لكي تبقى بيانات التشخيص قابلة للفصل عند تشغيل عدة بوتات ضمن Gateway واحد.

أضف بوتًا ثانيًا عبر CLI:

openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

محادثات المجموعات

يستخدم دعم المجموعات معرّفات OpenID لمجموعات QQ، وليس أسماء العرض. أضف البوت إلى مجموعة، ثم أشر إليه أو اضبط المجموعة لتعمل من دون إشارة.

{  channels: {    qqbot: {      groupPolicy: "allowlist",      groupAllowFrom: ["member_openid"],      groups: {        "*": {          requireMention: true,          commandLevel: "all",          historyLimit: 50,          tools: { deny: ["exec", "read", "write"] },        },        GROUP_OPENID: {          name: "Release room",          requireMention: false,          ignoreOtherMentions: true,          commandLevel: "safety",          historyLimit: 20,          prompt: "Keep replies short and operational.",        },      },    },  },}

يعيّن groups["*"] القيم الافتراضية لكل مجموعة؛ ويتجاوز إدخال groups.GROUP_OPENID محدد تلك القيم الافتراضية لمجموعة واحدة. إعدادات المجموعة:

يقبل commandLevel:

أُوقفت إدخالات QQBot القديمة toolPolicy. شغّل openclaw doctor --fix لنقلها إلى tools.

وضعا التنشيط هما mention وalways. يُعيَّن requireMention: true إلى mention؛ ويُعيَّن requireMention: false إلى always. يتغلب تجاوز التنشيط على مستوى الجلسة، عند وجوده، على الإعدادات.

قائمة الانتظار الواردة مخصصة لكل نظير. تحصل نظراء المجموعات على حد أكبر لقائمة الانتظار (50 مقابل 20 للنظراء المباشرين)، وتستبعد الرسائل التي أنشأها البوت قبل رسائل البشر عند امتلائها، وتدمج دفعات رسائل المجموعة العادية في دور واحد منسوب إلى مرسليه. تعمل أوامر الشرطة المائلة واحدًا تلو الآخر، بصورة مستقلة عن أي دفعة دمج.

الصوت (STT / TTS)

يدعم STT وTTS إعدادًا من مستويين مع رجوع احتياطي حسب الأولوية:

{  channels: {    qqbot: {      stt: {        provider: "your-provider",        model: "your-stt-model",      },      tts: {        provider: "your-provider",        model: "your-tts-model",        voice: "your-voice",      },      accounts: {        "qq-main": {          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },      },    },  },}

عيّن enabled: false في أي منهما للتعطيل. تستخدم تجاوزات TTS على مستوى الحساب البنية نفسها التي يستخدمها messages.tts وتندمج بعمق فوق إعدادات TTS للقناة/العامة.

تنتهي مهلة طلبات STT بعد 60 ثانية افتراضيًا. يستخدم STT الخاص بالـ Plugin تجاوز models.providers.<id>.timeoutSeconds المحدد. يستخدم STT الصوتي لإطار العمل tools.media.audio.models[0].timeoutSeconds، ثم tools.media.audio.timeoutSeconds، ثم تجاوز المزوّد المحدد.

تُعرَض مرفقات QQ الصوتية الواردة للوكلاء كبيانات وصفية لوسائط صوتية مع إبقاء ملفات الصوت الخام خارج MediaPaths العام. يؤدي وجود [[audio_as_voice]] في رد نصي عادي إلى توليف TTS وإرسال رسالة صوتية أصلية من QQ عندما يكون TTS مهيأً.

يمكن أيضًا ضبط سلوك رفع/تحويل ترميز الصوت الصادر باستخدام channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

تنسيقات الأهداف

أوامر الشرطة المائلة

الأوامر المضمنة التي تُعترض قبل قائمة انتظار الذكاء الاصطناعي:

ألحق ? بأي أمر للحصول على مساعدة الاستخدام (على سبيل المثال /bot-upgrade ?).

تتطلب الأوامر ذات "المصادقة: قائمة السماح" أيضًا وجود openid الخاص بالمرسل في قائمة allowFrom صريحة لا تحتوي على حرف بدل (تكون الأولوية لـ groupAllowFrom للأوامر الصادرة من المجموعات، مع الرجوع إلى allowFrom). يسمح حرف البدل allowFrom: ["*"] بالدردشة، لكنه لا يسمح بهذه الأوامر. يؤدي تشغيل أحدها خارج الدردشة الخاصة، أو من دون تخويل، إلى إرجاع تلميح بدلًا من إسقاط الرسالة بصمت.

تقتصر /bot-me و/bot-version و/bot-upgrade على الدردشة الخاصة، لكنها لا تتطلب قائمة السماح — يمكن لأي مرسل C2C تشغيلها.

عندما تستخدم موافقات تنفيذ QQ Bot الرجوع الافتراضي إلى الدردشة نفسها، تتبع نقرات أزرار الموافقة الأصلية قائمة السماح الصريحة نفسها للأوامر من دون أحرف بدل. لمنح صلاحية الموافقة فقط من دون صلاحية أوسع للأوامر، اضبط channels.qqbot.execApprovals.approvers. تكون موافقات التنفيذ الأصلية مفعّلة افتراضيًا.

الوسائط والتخزين

• تشترك وسائط الوارد والصادر وجسر Gateway في جذر حمولة واحد ضمن ~/.openclaw/media/qqbot (مع مراعاة OPENCLAW_HOME عند ضبطه)، بحيث تظل عمليات الرفع والتنزيل وذاكرات التخزين المؤقت لتحويل الترميز ضمن دليل محمي واحد.
• يمر تسليم الوسائط الغنية لأهداف C2C والمجموعات عبر مسار sendMedia واحد. تستخدم الملفات المحلية والمخازن المؤقتة في الذاكرة بحجم 5 MiB أو أكثر نقاط نهاية الرفع المجزأ في QQ؛ بينما تستخدم الحمولات الأصغر ومصادر URL البعيدة/Base64 واجهة API للرفع دفعة واحدة.
• إذا قاطعت ترقية فورية Gateway قبل أن ينتهي من كتابة openclaw.json، يستعيد Plugin آخر قيم معروفة لـ appId / clientSecret لذلك الحساب من لقطة داخلية عند بدء التشغيل التالي (من دون استبدال أي تغيير مقصود في الإعدادات)، لذا لا يلزم إعادة مسح رمز QR.

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

• لا يبدأ Gateway / لا توجد رسائل واردة: تحقّق من صحة appId و clientSecret ومن تمكين البوت على QQ Open Platform. يظهر اعتماد مفقود على هيئة "QQBot غير مهيأ (appId أو clientSecret مفقود)".
• لا يزال الإعداد باستخدام --token-file يظهر أنه غير مهيأ: لا يضبط --token-file سوى AppSecret. ولا بد من ضبط appId في الإعدادات أو QQBOT_APP_ID.
• تتعارض ردود المجموعة المتدفقة على دفعات: تطرد قائمة انتظار الوارد الرسائل التي أنشأها البوت قبل الرسائل البشرية عندما تمتلئ قائمة انتظار أحد النظراء، وتدمج دفعات رسائل المجموعة العادية (غير الأوامر) في دور واحد منسوب إلى أصحابه، بحيث لا ينبغي أن يحرم تدفق محادثات البوت الرسائل البشرية من المعالجة.
• الرسائل الاستباقية لا تصل: قد يحظر QQ الرسائل التي يبدأها البوت إذا لم يتفاعل المستخدم مؤخرًا.
• لم يُنسخ الصوت نصيًا: تأكّد من تهيئة STT وإمكانية الوصول إلى المزوّد.

ذات صلة

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