ربات QQ

QQ Bot از طریق API رسمی QQ Bot (Gateway مبتنی بر WebSocket) به OpenClaw وصل می‌شود. این Plugin از گفت‌وگوی خصوصی C2C، @پیام‌های گروهی، و پیام‌های کانال انجمن با رسانه‌های غنی (تصویر، صدا، ویدئو، فایل) پشتیبانی می‌کند.

وضعیت: Plugin قابل دانلود. پیام‌های مستقیم، گفت‌وگوهای گروهی، کانال‌های انجمن، و رسانه پشتیبانی می‌شوند. واکنش‌ها و رشته‌ها پشتیبانی نمی‌شوند.

نصب

پیش از راه‌اندازی، QQ Bot را نصب کنید:

openclaw plugins install @openclaw/qqbot

راه‌اندازی

1. به QQ Open Platform بروید و کد QR را با QQ روی تلفن خود اسکن کنید تا ثبت‌نام / ورود انجام شود.
2. برای ایجاد یک ربات QQ جدید، روی Create Bot کلیک کنید.
3. AppID و AppSecret را در صفحه تنظیمات ربات پیدا و کپی کنید.

AppSecret به‌صورت متن ساده ذخیره نمی‌شود — اگر بدون ذخیره‌کردن آن صفحه را ترک کنید، باید یک مورد جدید بازتولید کنید.

4. کانال را اضافه کنید:

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

5. Gateway را بازراه‌اندازی کنید.

مسیرهای راه‌اندازی تعاملی:

openclaw channels addopenclaw configure --section channels

پیکربندی

پیکربندی حداقلی:

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

نکته‌ها:

• جایگزین محیطی فقط برای حساب پیش‌فرض QQ Bot اعمال می‌شود.
• openclaw channels add --channel qqbot --token-file ... فقط AppSecret را فراهم می‌کند؛ AppID باید از قبل در پیکربندی یا QQBOT_APP_ID تنظیم شده باشد.
• clientSecret افزون بر رشته متن ساده، ورودی SecretRef را نیز می‌پذیرد.
• رشته‌های نشانگر قدیمی secretref:/... مقادیر معتبر clientSecret نیستند؛ از اشیای ساختاریافته SecretRef مانند نمونه بالا استفاده کنید.

راه‌اندازی چندحسابی

چند QQ bot را زیر یک نمونه OpenClaw اجرا کنید:

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

هر حساب اتصال WebSocket خودش را راه‌اندازی می‌کند و یک حافظه نهان توکن مستقل (ایزوله‌شده بر اساس appId) نگه می‌دارد.

یک ربات دوم را از طریق CLI اضافه کنید:

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

گفت‌وگوهای گروهی

پشتیبانی گفت‌وگوی گروهی QQ Bot از 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 آن پیش‌فرض‌ها را برای یک گروه بازنویسی می‌کند. تنظیمات گروه شامل این موارد است:

• requireMention: پیش از پاسخ ربات، یک @mention را الزامی کنید. پیش‌فرض: true.
• commandLevel: کنترل کنید کدام فرمان‌های اسلش داخلی می‌توانند در گروه‌ها اجرا شوند. پیش‌فرض: all، که وقتی این تنظیم حذف شود رفتار گروهی ازپیش‌موجود QQBot را حفظ می‌کند.
• ignoreOtherMentions: پیام‌هایی را که شخص دیگری را منشن می‌کنند اما ربات را نه، کنار بگذارید.
• historyLimit: پیام‌های گروهی اخیر بدون منشن را به‌عنوان زمینه برای نوبت منشن‌شده بعدی نگه دارید. برای غیرفعال‌سازی، 0 تنظیم کنید.
• tools: ابزارها را برای کل گروه مجاز/ممنوع کنید.
• toolsBySender: بازنویسی‌های ابزار گروهی به‌ازای هر فرستنده؛ گروه‌ها را ببینید.
• name: برچسب خوانا که در لاگ‌ها و زمینه گروه استفاده می‌شود.
• prompt: اعلان رفتاری به‌ازای هر گروه که به زمینه عامل افزوده می‌شود.

commandLevel این مقادیر را می‌پذیرد:

• all: فرمان‌های داخلی شناخته‌شده را مانند قبل در دسترس نگه می‌دارد. برخی فرمان‌ها ممکن است در منوها پنهان بمانند، اما کاربران مجاز همچنان می‌توانند آن‌ها را در گروه اجرا کنند.
• safety: فرمان‌های رایج همکاری مانند /help، /btw، و /stop را مجاز می‌کند؛ از کاربران می‌خواهد فرمان‌های حساس مانند /config، /tools، و /bash را در گفت‌وگوی خصوصی اجرا کنند.
• strict: فقط کنترل‌های نشست گروهی لازم برای عملیات سخت‌گیرانه گروه را مجاز می‌کند. /stop همچنان فوری باقی می‌ماند تا یک فرستنده مجاز بتواند اجرای فعال را قطع کند.

ورودی‌های قدیمی toolPolicy در QQBot بازنشسته شده‌اند. برای مهاجرت آن‌ها به tools، openclaw doctor --fix را اجرا کنید.

حالت‌های فعال‌سازی mention و always هستند. requireMention: true به mention نگاشت می‌شود؛ requireMention: false به always نگاشت می‌شود. بازنویسی فعال‌سازی در سطح نشست، در صورت وجود، بر پیکربندی اولویت دارد.

صف ورودی به‌ازای هر همتا است. همتاهای گروهی سقف صف بزرگ‌تری دارند، هنگام پر بودن پیام‌های انسانی را جلوتر از گفت‌وگوی نوشته‌شده توسط ربات نگه می‌دارند، و فوران پیام‌های عادی گروه را در یک نوبت منتسب‌شده ادغام می‌کنند. فرمان‌های اسلش همچنان یکی‌یکی اجرا می‌شوند.

صدا (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 کانال/سراسری ادغام می‌شوند.

پیوست‌های صوتی ورودی QQ به‌عنوان فراداده رسانه صوتی در اختیار عامل‌ها قرار می‌گیرند، در حالی که فایل‌های صوتی خام بیرون از MediaPaths عمومی نگه داشته می‌شوند. پاسخ‌های متنی ساده [[audio_as_voice]] وقتی TTS پیکربندی شده باشد، TTS را سنتز می‌کنند و یک پیام صوتی بومی QQ می‌فرستند.

رفتار بارگذاری/تبدیل‌کد صدای خروجی را نیز می‌توان با channels.qqbot.audioFormatPolicy تنظیم کرد:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

قالب‌های هدف

هر ربات مجموعه OpenIDهای کاربری خودش را دارد. یک OpenID دریافت‌شده توسط ربات A نمی‌تواند برای ارسال پیام از طریق ربات B استفاده شود.

فرمان‌های اسلش

فرمان‌های داخلی که پیش از صف هوش مصنوعی رهگیری می‌شوند:

برای راهنمای استفاده، به هر فرمان ? اضافه کنید (برای نمونه /bot-upgrade ?).

فرمان‌های مدیر (/bot-me، /bot-upgrade، /bot-logs، /bot-clear-storage، /bot-streaming، /bot-approve) فقط پیام مستقیم هستند و به openid فرستنده در یک فهرست صریح و غیرعام allowFrom نیاز دارند. یک allowFrom: ["*"] عام اجازه گفت‌وگو می‌دهد اما دسترسی فرمان مدیر را اعطا نمی‌کند. پیام‌های گروهی ابتدا با groupAllowFrom تطبیق داده می‌شوند و سپس به allowFrom برمی‌گردند. اجرای فرمان مدیر در گروه به‌جای حذف بی‌صدا، یک راهنما برمی‌گرداند.

وقتی تأییدهای اجرای QQ Bot از جایگزین پیش‌فرض همان گفت‌وگو استفاده می‌کنند، کلیک‌های دکمه تأیید بومی از همان فهرست مجاز فرمان صریح و غیرعام پیروی می‌کنند. برای اعطای دسترسی فقط‌تأیید بدون دسترسی گسترده‌تر به فرمان‌ها، channels.qqbot.execApprovals.approvers را پیکربندی کنید.

معماری موتور

QQ Bot به‌عنوان یک موتور خودبسنده داخل Plugin ارائه می‌شود:

• هر حساب مالک یک پشته منبع ایزوله (اتصال WebSocket، کلاینت API، حافظه نهان توکن، ریشه ذخیره رسانه) است که با appId کلیدگذاری می‌شود. حساب‌ها هرگز وضعیت ورودی/خروجی را به اشتراک نمی‌گذارند.
• لاگر چندحسابی، خطوط لاگ را با حساب مالک برچسب‌گذاری می‌کند تا هنگام اجرای چند ربات زیر یک Gateway، عیب‌یابی‌ها قابل تفکیک بمانند.
• مسیرهای ورودی، خروجی، و پل Gateway یک ریشه محموله رسانه واحد را زیر ~/.openclaw/media به اشتراک می‌گذارند، بنابراین بارگذاری‌ها، دانلودها، و حافظه‌های نهان تبدیل‌کد به‌جای یک درخت به‌ازای هر زیرسامانه، زیر یک پوشه محافظت‌شده قرار می‌گیرند.
• تحویل رسانه غنی برای هدف‌های C2C و گروهی از یک مسیر sendMedia عبور می‌کند. فایل‌ها و بافرهای محلی بالاتر از آستانه فایل بزرگ از نقطه‌های پایانی بارگذاری تکه‌ای QQ استفاده می‌کنند، در حالی که محموله‌های کوچک‌تر از API رسانه یک‌مرحله‌ای استفاده می‌کنند.
• اعتبارنامه‌ها می‌توانند به‌عنوان بخشی از snapshotهای استاندارد اعتبارنامه OpenClaw پشتیبان‌گیری و بازیابی شوند؛ موتور هنگام بازیابی، پشته منبع هر حساب را بدون نیاز به یک جفت‌سازی تازه با کد QR دوباره متصل می‌کند.

ورود با کد QR

به‌عنوان جایگزینی برای چسباندن دستی AppID:AppSecret، موتور از یک جریان ورود با کد QR برای پیوند دادن QQ Bot به OpenClaw پشتیبانی می‌کند:

1. مسیر راه‌اندازی QQ Bot را اجرا کنید (برای نمونه openclaw channels add --channel qqbot) و هنگام پرسش، جریان کد QR را انتخاب کنید.
2. کد QR تولیدشده را با برنامه تلفن متصل به QQ Bot هدف اسکن کنید.
3. جفت‌سازی را روی تلفن تأیید کنید. OpenClaw اعتبارنامه‌های برگشتی را در credentials/ زیر دامنه حساب درست ذخیره می‌کند.

اعلان‌های تأیید تولیدشده توسط خود ربات (برای نمونه، جریان‌های «اجازه این اقدام داده شود؟» که توسط API QQ Bot ارائه می‌شوند) به‌صورت اعلان‌های بومی OpenClaw ظاهر می‌شوند که می‌توانید به‌جای پاسخ‌دادن از طریق کلاینت خام QQ، با /bot-approve بپذیرید.

عیب‌یابی

• ربات پاسخ می‌دهد «به مریخ رفته است»: اعتبارنامه‌ها پیکربندی نشده‌اند یا Gateway شروع نشده است.
• هیچ پیام ورودی وجود ندارد: بررسی کنید appId و clientSecret درست باشند و ربات در QQ Open Platform فعال شده باشد.
• خودپاسخ‌های تکراری: OpenClaw نمایه‌های ارجاع خروجی QQ را به‌عنوان نوشته‌شده توسط ربات ثبت می‌کند و رویدادهای ورودی‌ای را که msgIdx فعلی آن‌ها با همان حساب ربات مطابقت دارد نادیده می‌گیرد. این کار از حلقه‌های بازتاب پلتفرم جلوگیری می‌کند، درحالی‌که همچنان به کاربران اجازه می‌دهد پیام‌های قبلی ربات را نقل‌قول کنند یا به آن‌ها پاسخ دهند.
• راه‌اندازی با --token-file همچنان پیکربندی‌نشده نشان داده می‌شود: --token-file فقط AppSecret را تنظیم می‌کند. همچنان به appId در پیکربندی یا QQBOT_APP_ID نیاز دارید.
• پیام‌های پیش‌دستانه نمی‌رسند: اگر کاربر اخیراً تعامل نداشته باشد، QQ ممکن است پیام‌های آغازشده توسط ربات را رهگیری کند.
• صدا رونویسی نمی‌شود: مطمئن شوید STT پیکربندی شده و ارائه‌دهنده در دسترس است.

مرتبط

• جفت‌سازی
• گروه‌ها
• عیب‌یابی کانال