---
read_when:
    - می‌خواهید OpenClaw را به QQ متصل کنید
    - به تنظیم اعتبارنامه‌های QQ Bot نیاز دارید
    - پشتیبانی از چت گروهی یا خصوصی QQ Bot را می‌خواهید
summary: راه‌اندازی، پیکربندی و استفاده از ربات QQ
title: بات QQ
x-i18n:
    generated_at: "2026-05-03T11:33:16Z"
    model: gpt-5.5
    provider: openai
    source_hash: 471c24110bf0ab8896d22f5bb5932ac4e03ff5169560c99ba6b9d1ca4025d9a8
    source_path: channels/qqbot.md
    workflow: 16
---

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

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

## نصب

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

```bash
openclaw plugins install @openclaw/qqbot
```

## راه‌اندازی

1. به [QQ Open Platform](https://q.qq.com/) بروید و کد QR را با QQ گوشی خود
   اسکن کنید تا ثبت‌نام / وارد شوید.
2. برای ایجاد یک ربات QQ جدید روی **Create Bot** کلیک کنید.
3. **AppID** و **AppSecret** را در صفحهٔ تنظیمات ربات پیدا و کپی کنید.

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

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

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

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

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

```bash
openclaw channels add
openclaw configure --section channels
```

## پیکربندی

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

```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 از نوع Env SecretRef:

```json5
{
  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 را زیر یک نمونهٔ OpenClaw اجرا کنید:

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

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

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

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

### چت‌های گروهی

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

```json5
{
  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`: پیام‌هایی را که شخص دیگری را منشن می‌کنند اما ربات را نه، کنار بگذارد.
- `historyLimit`: پیام‌های اخیر گروه بدون منشن را به‌عنوان زمینه برای نوبت منشن‌شدهٔ بعدی نگه دارد. برای غیرفعال‌سازی، `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`                |

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

پیوست‌های صوتی ورودی 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` | کانال صنف      |

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

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

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

| فرمان        | توضیح                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| `/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 عرضه می‌شود:

- هر حساب مالک یک پشتهٔ منابع ایزوله (اتصال وب‌سوکت، کلاینت API، کش توکن، ریشهٔ ذخیره‌سازی رسانه) است که با `appId` کلیدگذاری می‌شود. حساب‌ها هرگز وضعیت ورودی/خروجی را به اشتراک نمی‌گذارند.
- لاگر چندحسابی، خطوط لاگ را با حساب مالک برچسب‌گذاری می‌کند تا هنگام اجرای چند ربات زیر یک Gateway، عیب‌یابی‌ها جداپذیر بمانند.
- مسیرهای ورودی، خروجی، و پل Gateway از یک ریشهٔ محمولهٔ رسانه زیر `~/.openclaw/media` مشترک استفاده می‌کنند، بنابراین بارگذاری‌ها، دانلودها، و کش‌های ترنس‌کد به‌جای یک درخت جدا برای هر زیرسامانه، زیر یک دایرکتوری محافظت‌شده قرار می‌گیرند.
- تحویل رسانهٔ غنی از یک مسیر `sendMedia` برای هدف‌های C2C و گروهی عبور می‌کند. فایل‌ها و بافرهای محلی بالاتر از آستانهٔ فایل بزرگ از نقطه‌های پایانی بارگذاری تکه‌ای QQ استفاده می‌کنند، در حالی که محموله‌های کوچک‌تر از API رسانهٔ تک‌مرحله‌ای استفاده می‌کنند.
- اعتبارنامه‌ها می‌توانند به‌عنوان بخشی از اسنپ‌شات‌های استاندارد اعتبارنامهٔ 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` آن‌ها را بپذیرید.

## عیب‌یابی

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

## مرتبط

- [جفت‌سازی](/fa/channels/pairing)
- [گروه‌ها](/fa/channels/groups)
- [عیب‌یابی کانال](/fa/channels/troubleshooting)
