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

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

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

## نصب

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

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

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

1. به [QQ Open Platform](https://q.qq.com/) بروید و کد QR را با QQ روی
   تلفن خود اسکن کنید تا ثبت‌نام / ورود انجام شود.
2. روی **Create Bot** کلیک کنید تا یک ربات QQ جدید ساخته شود.
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 با 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 bot را زیر یک نمونه 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 خودش را راه‌اندازی می‌کند و یک کش توکن مستقل
(ایزوله‌شده با `appId`) نگه می‌دارد.

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

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

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

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

```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`: پیام‌هایی را که شخص دیگری را 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`                |

```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` | کانال 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 پیکربندی شده و ارائه‌دهنده در دسترس است.

## مرتبط

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