OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Regional platforms

ربات QQ

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

وضعیت: Plugin رسمی قابل دانلود.

نصب

bash
openclaw plugins install @openclaw/qqbot

راه‌اندازی

  1. به پلتفرم باز QQ بروید و برای ثبت‌نام / ورود، کد QR را با QQ تلفن خود اسکن کنید.
  2. برای ایجاد یک ربات QQ جدید، روی Create Bot کلیک کنید.
  3. در صفحه تنظیمات ربات، AppID و AppSecret را پیدا و کپی کنید.
  1. کانال را اضافه کنید:
bash
openclaw channels add --channel qqbot --token "AppID:AppSecret"
  1. Gateway را راه‌اندازی مجدد کنید.

دوام ورودی

برای رویدادهای نوبت Gateway در QQ، ‏OpenClaw پیش از جلو بردن توالی ذخیره‌شده ازسرگیری Gateway، رویداد خام را ماندگار می‌کند. نوبت‌های در انتظار یا قابل تلاش مجدد پس از راه‌اندازی مجدد Gateway باقی می‌مانند، برای هر مکالمه به‌صورت سریالی اجرا می‌شوند و تا زمانی که رکورد تکمیل فعال یا نگه‌داری‌شده وجود دارد، از شناسه رویداد ارائه‌دهنده برای جلوگیری از ورودی‌های تکراری صف استفاده می‌کنند.

اگر پذیرش پایدار ناموفق باشد، OpenClaw سوکت فعلی Gateway را بدون جلو بردن توالی خاتمه می‌دهد. سپس مسیر اتصال مجدد/ازسرگیری می‌تواند رویداد ثبت‌نشده را دوباره درخواست کند. تحویل در مرز صف به عامل همچنان حداقل یک‌بار انجام می‌شود؛ بنابراین خرابی هنگام واگذاری می‌تواند یک نوبت را دوباره پخش کند.

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

bash
openclaw channels add

ویزارد همچنین اتصال با کد QR را به‌عنوان جایگزینی برای واردکردن دستی AppID/AppSecret ارائه می‌دهد: برای تکمیل اتصال، کد را با برنامه تلفن مرتبط با QQ Bot مقصد اسکن کنید. OpenClaw اعتبارنامه‌های بازگردانده‌شده را در محدوده پیکربندی حساب ماندگار می‌کند.

پیکربندی

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

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

متغیرهای محیطی حساب پیش‌فرض (فقط حساب سطح بالا):

  • QQBOT_APP_ID
  • QQBOT_CLIENT_SECRET

AppSecret مبتنی بر فایل:

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

AppSecret از نوع SecretRef محیطی:

json5
{  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 استفاده کنید.

جریان‌دهی

json5
{  channels: {    qqbot: {      streaming: {        mode: "partial", // جریان‌دهی بلوکی: "partial" (پیش‌فرض) یا "off"        nativeTransport: true, // استفاده از API رسمی stream_messages در QQ برای پیام‌های خصوصی C2C      },    },  },}
  • streaming.mode: "off" جریان‌دهی بلوکی را برای حساب غیرفعال می‌کند.
  • streaming.nativeTransport: true پاسخ‌های C2C (پیام خصوصی) را از طریق API رسمی stream_messages در QQ جریان‌دهی می‌کند؛ مقصدهای گروه/کانال تحت تأثیر قرار نمی‌گیرند.
  • مقادیر اسکالر قدیمی streaming: true|false و کلید streaming.c2cStreamApi از طریق openclaw doctor --fix به این ساختار مهاجرت می‌کنند.
  • /bot-streaming on|off همین پیکربندی را از یک پیام خصوصی تغییر می‌دهد.

سیاست دسترسی

  • allowFrom / groupAllowFrom تعیین می‌کنند چه کسی می‌تواند در زمینه‌های C2C / گروه با ربات گفت‌وگو کند. dmPolicy / groupPolicy‏ (open | allowlist | disabled) حالت اعمال را کنترل می‌کنند. وقتی allowFrom یک ورودی مشخص (غیرعام) داشته باشد، dmPolicy به‌طور پیش‌فرض allowlist است؛ در غیر این صورت open. وقتی groupAllowFrom یا allowFrom یک ورودی مشخص داشته باشد، groupPolicy به‌طور پیش‌فرض allowlist است؛ در غیر این صورت open.
  • فرمان‌های اسلش «Auth: allowlist» صرف‌نظر از dmPolicy / groupPolicy به یک ورودی صریح غیرعام در allowFrom (یا برای فراخوانی‌های گروهی در groupAllowFrom) نیاز دارند — به فرمان‌های اسلش مراجعه کنید.

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

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

json5
{  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:

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

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

پشتیبانی گروه از OpenIDهای گروه QQ استفاده می‌کند، نه نام‌های نمایشی. ربات را به یک گروه اضافه کنید، سپس به آن اشاره کنید یا گروه را برای اجرا بدون اشاره پیکربندی کنید.

json5
{  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 true پیش از پاسخ‌دادن ربات، یک اشاره @ لازم است.
commandLevel all کدام فرمان‌های اسلش داخلی می‌توانند در گروه اجرا شوند (پایین را ببینید).
ignoreOtherMentions false پیام‌هایی را که به شخص دیگری اشاره می‌کنند اما به ربات نه، حذف می‌کند.
historyLimit 50 پیام‌های اخیر بدون اشاره که به‌عنوان زمینه برای نوبت اشاره‌شده بعدی نگه داشته می‌شوند. 0 تاریخچه را غیرفعال می‌کند.
tools — ابزارها را برای کل گروه مجاز/غیرمجاز می‌کند.
toolsBySender — بازنویسی ابزار به‌ازای هر فرستنده؛ به گروه‌ها مراجعه کنید.
name پیشوند openid برچسب خوانایی که در گزارش‌ها و زمینه گروه استفاده می‌شود.
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 نگاشت می‌شود. بازنویسی فعال‌سازی در سطح نشست، در صورت وجود، بر پیکربندی اولویت دارد.

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

صدا (STT / TTS)

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

تنظیم مختص Plugin بازگشت چارچوب
STT channels.qqbot.stt نخستین ورودی tools.media.models[] با قابلیت صوتی
TTS channels.qqbot.tts، channels.qqbot.accounts.<id>.tts tts
json5
{  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 در سطح حساب از همان ساختار tts استفاده می‌کنند و به‌صورت عمیق روی پیکربندی TTS کانال/سراسری ادغام می‌شوند.

درخواست‌های STT به‌طور پیش‌فرض پس از 60 ثانیه منقضی می‌شوند. STT مختص Plugin از بازنویسی انتخاب‌شده models.providers.<id>.timeoutSeconds استفاده می‌کند. STT صوتی چارچوب ابتدا از timeoutSeconds ورودی انتخاب‌شده tools.media.models[] دارای قابلیت صوتی و سپس از بازنویسی ارائه‌دهنده انتخاب‌شده استفاده می‌کند.

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

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

  • sttDirectFormats
  • uploadDirectFormats
  • transcodeEnabled

قالب‌های مقصد

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

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

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

فرمان احراز هویت دامنه توضیحات
/bot-ping — همه آزمون تأخیر
/bot-help — همه فهرست‌کردن همه فرمان‌ها
/bot-me — فقط خصوصی نمایش شناسه کاربری QQ فرستنده (openid) برای راه‌اندازی allowFrom / groupAllowFrom
/bot-version — فقط خصوصی نمایش نسخه چارچوب OpenClaw و نسخه Plugin
/bot-upgrade — فقط خصوصی نمایش پیوند راهنمای ارتقای QQBot
/bot-approve فهرست مجاز فقط خصوصی مدیریت پیکربندی تأیید اجرای فرمان (روشن / خاموش / همیشه / بازنشانی / وضعیت)
/bot-logs فهرست مجاز فقط خصوصی برون‌بری گزارش‌های اخیر Gateway به‌صورت فایل
/bot-clear-storage فهرست مجاز فقط خصوصی حذف بارگیری‌های ذخیره‌شده در حافظه نهان در پوشه رسانه QQBot
/bot-streaming فهرست مجاز فقط خصوصی تغییر وضعیت پاسخ‌های جریانی C2C
/bot-group-allways فهرست مجاز فقط خصوصی تغییر حالت پیش‌فرض فعال‌سازی گروه (نیازمند اشاره در برابر همیشه فعال)

برای راهنمای استفاده، ? را به هر فرمانی بیفزایید (برای مثال /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 بارگذاری یک‌مرحله‌ای استفاده می‌کنند.
  • اگر ارتقای گرم پیش از پایان نوشتن openclaw.json، Gateway را متوقف کند، Plugin در شروع بعدی آخرین appId / clientSecret شناخته‌شده آن حساب را از یک تصویر لحظه‌ای داخلی بازیابی می‌کند (بدون آنکه هرگز یک تغییر عمدی پیکربندی را بازنویسی کند)، بنابراین اسکن دوباره کد QR ضروری نیست.

عیب‌یابی

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

مرتبط

Was this useful?
On this page

On this page