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 (درگاه 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 را راه‌اندازی مجدد کنید.

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

bash
openclaw channels add

ویزارد همچنین به‌عنوان جایگزینی برای واردکردن دستی AppID/AppSecret، اتصال با کد QR را ارائه می‌دهد: برای تکمیل اتصال، کد را با برنامه تلفن مرتبط با 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 استفاده کنید.

سیاست دسترسی

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

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

صدا (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
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 در سطح حساب، همان ساختار messages.tts را دارند و به‌صورت عمیق روی پیکربندی TTS کانال/سراسری ادغام می‌شوند.

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

پیوست‌های صوتی ورودی QQ به‌عنوان فراداده رسانه صوتی در اختیار عامل‌ها قرار می‌گیرند، درحالی‌که فایل‌های صوتی خام از MediaPaths عمومی دور نگه داشته می‌شوند. وقتی TTS پیکربندی شده باشد، [[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