---
read_when:
    - می‌خواهید OpenClaw را به QQ متصل کنید
    - به راه‌اندازی اعتبارنامه‌های QQ Bot نیاز دارید
    - شما پشتیبانی از چت گروهی یا خصوصی QQ Bot را می‌خواهید
summary: راه‌اندازی، پیکربندی و استفاده از ربات QQ
title: ربات QQ
x-i18n:
    generated_at: "2026-06-27T17:13:27Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: eb452e331ce196d1517af2f87a5187cb4b2cb53aee2bbff47cbdf73e2b3e7dee
    source_path: channels/qqbot.md
    workflow: 16
---

QQ Bot از طریق API رسمی QQ Bot (Gateway مبتنی بر WebSocket) به 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 از نوع 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 استفاده می‌کند، نه نام‌های نمایشی. ربات را
به یک گروه اضافه کنید، سپس آن را منشن کنید یا گروه را طوری پیکربندی کنید که بدون منشن اجرا شود.

```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`: پیش از پاسخ ربات، یک @mention را الزامی کنید. پیش‌فرض: `true`.
- `commandLevel`: کنترل کنید کدام فرمان‌های اسلش داخلی می‌توانند در گروه‌ها اجرا شوند.
  پیش‌فرض: `all`، که وقتی این تنظیم حذف شود رفتار گروهی ازپیش‌موجود QQBot را حفظ می‌کند.
- `ignoreOtherMentions`: پیام‌هایی را که شخص دیگری را منشن می‌کنند اما ربات را نه، کنار بگذارید.
- `historyLimit`: پیام‌های گروهی اخیر بدون منشن را به‌عنوان زمینه برای نوبت منشن‌شده بعدی نگه دارید. برای غیرفعال‌سازی، `0` تنظیم کنید.
- `tools`: ابزارها را برای کل گروه مجاز/ممنوع کنید.
- `toolsBySender`: بازنویسی‌های ابزار گروهی به‌ازای هر فرستنده؛ [گروه‌ها](/fa/channels/groups#groupchannel-tool-restrictions-optional) را ببینید.
- `name`: برچسب خوانا که در لاگ‌ها و زمینه گروه استفاده می‌شود.
- `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 کانال/سراسری ادغام می‌شوند.

پیوست‌های صوتی ورودی 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 استفاده شود.

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

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

| فرمان          | توضیح                                                                                                   |
| -------------- | -------------------------------------------------------------------------------------------------------- |
| `/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 فرستنده در یک فهرست صریح و غیرعام `allowFrom` نیاز دارند. یک `allowFrom: ["*"]` عام اجازه گفت‌وگو می‌دهد اما دسترسی فرمان مدیر را اعطا نمی‌کند. پیام‌های گروهی ابتدا با `groupAllowFrom` تطبیق داده می‌شوند و سپس به `allowFrom` برمی‌گردند. اجرای فرمان مدیر در گروه به‌جای حذف بی‌صدا، یک راهنما برمی‌گرداند.

وقتی تأییدهای اجرای QQ Bot از جایگزین پیش‌فرض همان گفت‌وگو استفاده می‌کنند، کلیک‌های دکمه تأیید
بومی از همان فهرست مجاز فرمان صریح و غیرعام پیروی می‌کنند. برای اعطای دسترسی
فقط‌تأیید بدون دسترسی گسترده‌تر به فرمان‌ها، `channels.qqbot.execApprovals.approvers` را پیکربندی کنید.

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

QQ Bot به‌عنوان یک موتور خودبسنده داخل Plugin ارائه می‌شود:

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

## عیب‌یابی

- **ربات پاسخ می‌دهد «به مریخ رفته است»:** اعتبارنامه‌ها پیکربندی نشده‌اند یا 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)