ربات QQ

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

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

# نصب

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

openclaw plugins install @openclaw/qqbot

# راه‌اندازی

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

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

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

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

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

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

openclaw channels add
openclaw 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 استفاده می‌کند، نه نام‌های نمایشی. ربات را به یک گروه اضافه کنید، سپس آن را mention کنید یا گروه را طوری پیکربندی کنید که بدون mention اجرا شود.

{
  channels: {
    qqbot: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["member_openid"],
      groups: {
        "*": {
          requireMention: true,
          historyLimit: 50,
          toolPolicy: "restricted",
        },
        GROUP_OPENID: {
          name: "Release room",
          requireMention: false,
          ignoreOtherMentions: true,
          historyLimit: 20,
          prompt: "Keep replies short and operational.",
        },
      },
    },
  },
}

groups["*"] پیش‌فرض‌ها را برای هر گروه تنظیم می‌کند، و یک ورودی مشخص groups.GROUP_OPENID آن پیش‌فرض‌ها را برای یک گروه بازنویسی می‌کند. تنظیمات گروه شامل موارد زیر است:

• requireMention: پیش از پاسخ ربات، یک @mention لازم باشد. پیش‌فرض: true.
• ignoreOtherMentions: پیام‌هایی را که شخص دیگری را mention می‌کنند اما ربات را نه، حذف کند.
• historyLimit: پیام‌های گروهی اخیرِ بدون mention را به‌عنوان زمینه برای نوبت mention شده بعدی نگه دارد. برای غیرفعال‌سازی روی 0 تنظیم کنید.
• toolPolicy: full، restricted، یا none برای ابزارهای محدود به گروه.
• name: برچسب خوانا که در گزارش‌ها و زمینه گروه استفاده می‌شود.
• prompt: دستور رفتاری مخصوص هر گروه که به زمینه عامل افزوده می‌شود.

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

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

# صدا (STT / TTS)

پشتیبانی STT و TTS پیکربندی دو‌سطحی با عقب‌گرد اولویت‌دار دارد:

تنظیم	مخصوص Plugin	عقب‌گرد چارچوب
STT	channels.qqbot.stt	tools.media.audio.models[0]
TTS	channels.qqbot.tts, channels.qqbot.accounts.<id>.tts	messages.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

# قالب‌های هدف

قالب	توضیح
qqbot:c2c:OPENID	گفت‌وگوی خصوصی (C2C)
qqbot:group:GROUP_OPENID	گفت‌وگوی گروهی
qqbot:channel:CHANNEL_ID	کانال guild

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

# دستورهای اسلش

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

دستور	توضیح
/bot-ping	آزمون تأخیر
/bot-version	نمایش نسخه چارچوب OpenClaw
/bot-help	فهرست کردن همه دستورها
/bot-me	نمایش شناسه کاربر QQ فرستنده (openid) برای راه‌اندازی allowFrom/groupAllowFrom
/bot-upgrade	نمایش پیوند راهنمای ارتقای QQBot
/bot-logs	خروجی گرفتن از گزارش‌های اخیر gateway به‌صورت فایل
/bot-approve	تأیید یک اقدام در انتظار QQ Bot (برای مثال، تأیید بارگذاری C2C یا گروهی) از طریق جریان بومی.

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

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

# معماری موتور

QQ Bot به‌صورت یک موتور خودکفا داخل Plugin ارائه می‌شود:

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

# ورود با کد 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 بپذیرید.

# عیب‌یابی

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

# مرتبط

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