---
read_when:
    - คุณต้องการเชื่อมต่อ OpenClaw กับ QQ
    - คุณต้องตั้งค่าข้อมูลประจำตัวของ QQ Bot
    - คุณต้องการการรองรับแชตกลุ่มหรือแชตส่วนตัวของ QQ Bot
summary: การตั้งค่า การกำหนดค่า และการใช้งาน QQ Bot
title: บอต QQ
x-i18n:
    generated_at: "2026-06-27T17:13:10Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: eb452e331ce196d1517af2f87a5187cb4b2cb53aee2bbff47cbdf73e2b3e7dee
    source_path: channels/qqbot.md
    workflow: 16
---

QQ Bot เชื่อมต่อกับ OpenClaw ผ่าน QQ Bot API อย่างเป็นทางการ (WebSocket gateway)
Plugin รองรับแชตส่วนตัว C2C, @messages ในกลุ่ม และข้อความในช่องกิลด์พร้อมสื่อสมบูรณ์
(รูปภาพ เสียง วิดีโอ ไฟล์)

สถานะ: Plugin ที่ดาวน์โหลดได้ รองรับข้อความส่วนตัว แชตกลุ่ม ช่องกิลด์ และ
สื่อ ไม่รองรับรีแอ็กชันและเธรด

## ติดตั้ง

ติดตั้ง QQ Bot ก่อนตั้งค่า:

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

## ตั้งค่า

1. ไปที่ [QQ Open Platform](https://q.qq.com/) และสแกนคิวอาร์โค้ดด้วย
   QQ บนโทรศัพท์ของคุณเพื่อลงทะเบียน / เข้าสู่ระบบ
2. คลิก **สร้างบอต** เพื่อสร้าง QQ 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" },
    },
  },
}
```

หมายเหตุ:

- การสำรองไปใช้ env ใช้กับบัญชี 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`: การแทนที่เครื่องมือกลุ่มรายผู้ส่ง; ดู [กลุ่ม](/th/channels/groups#groupchannel-tool-restrictions-optional)
- `name`: ป้ายชื่อที่เป็นมิตรซึ่งใช้ในล็อกและบริบทกลุ่ม
- `prompt`: พรอมป์พฤติกรรมรายกลุ่มที่ต่อท้ายบริบทของเอเจนต์

`commandLevel` รับค่า:

- `all`: คงคำสั่งในตัวที่รู้จักให้ใช้งานได้เหมือนเดิม บางคำสั่งอาจ
  ยังซ่อนจากเมนู แต่ผู้ใช้ที่ได้รับอนุญาตยังคงเรียกใช้ในกลุ่มได้
- `safety`: อนุญาตคำสั่งการทำงานร่วมกันทั่วไป เช่น `/help`, `/btw` และ
  `/stop`; ขอให้ผู้ใช้เรียกใช้คำสั่งอ่อนไหว เช่น `/config`, `/tools` และ
  `/bash` ในแชตส่วนตัว
- `strict`: อนุญาตเฉพาะการควบคุมเซสชันกลุ่มที่จำเป็นสำหรับการทำงานกลุ่มแบบเข้มงวด
  `/stop` ยังคงเป็นคำสั่งเร่งด่วนเพื่อให้ผู้ส่งที่ได้รับอนุญาตสามารถขัดจังหวะ
  การรันที่กำลังทำงานอยู่ได้

รายการ `toolPolicy` ของ QQBot แบบเก่าถูกเลิกใช้แล้ว เรียกใช้ `openclaw doctor --fix` เพื่อย้ายไปเป็น `tools`

โหมดการเปิดใช้งานคือ `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` และ deep-merge
ทับคอนฟิก TTS ระดับช่องทาง/ส่วนกลาง

ไฟล์แนบเสียง QQ ขาเข้าจะแสดงต่อเอเจนต์เป็นเมทาดาทาสื่อเสียง ขณะเดียวกัน
เก็บไฟล์เสียงดิบออกจาก `MediaPaths` ทั่วไป ข้อความตอบกลับแบบข้อความล้วน
`[[audio_as_voice]]` จะสังเคราะห์ TTS และส่งข้อความเสียง QQ แบบเนทีฟเมื่อ
กำหนดค่า TTS แล้ว

พฤติกรรมอัปโหลด/แปลงรหัสเสียงขาออกยังปรับแต่งได้ด้วย
`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 user ID (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` การเรียกใช้คำสั่งผู้ดูแลในกลุ่มจะส่งคำใบ้กลับแทนที่จะทิ้งอย่างเงียบ ๆ

เมื่อการอนุมัติ exec ของ QQ Bot ใช้การสำรองแชตเดียวกันแบบเริ่มต้น การคลิก
ปุ่มอนุมัติแบบเนทีฟจะใช้ allowlist คำสั่งแบบระบุชัดเจนที่ไม่ใช่ไวลด์การ์ดเดียวกัน
หากต้องการให้สิทธิ์เฉพาะการอนุมัติโดยไม่ให้สิทธิ์คำสั่งที่กว้างกว่า ให้กำหนดค่า
`channels.qqbot.execApprovals.approvers`

## สถาปัตยกรรมเอนจิน

QQ Bot มาพร้อมเอนจินแบบครบในตัวภายใน Plugin:

- แต่ละบัญชีเป็นเจ้าของสแตกทรัพยากรที่แยกอิสระ (การเชื่อมต่อ WebSocket, ไคลเอนต์ API, แคชโทเค็น, รากที่เก็บสื่อ) ที่ระบุด้วย `appId` บัญชีต่าง ๆ ไม่แชร์สถานะขาเข้า/ขาออกกัน
- ตัวบันทึกล็อกหลายบัญชีติดแท็กบรรทัดล็อกด้วยบัญชีเจ้าของ เพื่อให้การวินิจฉัยแยกกันได้เมื่อคุณเรียกใช้บอตหลายตัวภายใต้ gateway เดียว
- เส้นทางบริดจ์ขาเข้า ขาออก และ gateway ใช้รากเพย์โหลดสื่อเดียวกันภายใต้ `~/.openclaw/media` ดังนั้นการอัปโหลด ดาวน์โหลด และแคชการแปลงรหัสจึงอยู่ภายใต้ไดเรกทอรีที่มีการป้องกันเดียว แทนที่จะเป็นโครงสร้างแยกตามซับซิสเต็ม
- การส่งสื่อสมบูรณ์ผ่านเส้นทาง `sendMedia` เดียวสำหรับเป้าหมาย C2C และกลุ่ม ไฟล์ในเครื่องและบัฟเฟอร์ที่เกินเกณฑ์ไฟล์ขนาดใหญ่ใช้เอนด์พอยต์อัปโหลดแบบแบ่งชิ้นของ QQ ส่วนเพย์โหลดที่เล็กกว่าใช้ API สื่อแบบครั้งเดียว
- ข้อมูลลับสามารถสำรองและกู้คืนเป็นส่วนหนึ่งของสแนปชอตข้อมูลลับมาตรฐานของ OpenClaw ได้; เอนจินจะแนบสแตกทรัพยากรของแต่ละบัญชีใหม่เมื่อกู้คืน โดยไม่ต้องจับคู่คิวอาร์โค้ดใหม่

## การเริ่มใช้งานด้วยคิวอาร์โค้ด

อีกทางเลือกแทนการวาง `AppID:AppSecret` ด้วยตนเอง เอนจินรองรับโฟลว์การเริ่มใช้งานด้วยคิวอาร์โค้ดสำหรับเชื่อม QQ Bot กับ OpenClaw:

1. เรียกใช้เส้นทางตั้งค่า QQ Bot (เช่น `openclaw channels add --channel qqbot`) และเลือกโฟลว์คิวอาร์โค้ดเมื่อระบบถาม
2. สแกนคิวอาร์โค้ดที่สร้างขึ้นด้วยแอปโทรศัพท์ที่ผูกกับ QQ Bot เป้าหมาย
3. อนุมัติการจับคู่บนโทรศัพท์ OpenClaw จะคงข้อมูลลับที่ส่งกลับไว้ใน `credentials/` ภายใต้ขอบเขตบัญชีที่ถูกต้อง

พรอมป์การอนุมัติที่บอตสร้างเอง (เช่น โฟลว์ "อนุญาตการดำเนินการนี้หรือไม่?" ที่เปิดเผยโดย QQ Bot API) จะแสดงเป็นพรอมป์ OpenClaw แบบเนทีฟ ซึ่งคุณสามารถยอมรับด้วย `/bot-approve` แทนการตอบผ่านไคลเอนต์ QQ ดิบ

## การแก้ไขปัญหา

- **บอตตอบกลับว่า "gone to Mars":** ยังไม่ได้กำหนดค่าข้อมูลประจำตัว หรือยังไม่ได้เริ่ม Gateway
- **ไม่มีข้อความขาเข้า:** ตรวจสอบว่า `appId` และ `clientSecret` ถูกต้อง และเปิดใช้งาน
  บอตบน QQ Open Platform แล้ว
- **ตอบกลับตัวเองซ้ำ:** OpenClaw บันทึกดัชนีอ้างอิงขาออกของ QQ เป็น
  รายการที่บอตเขียน และละเว้นเหตุการณ์ขาเข้าที่ `msgIdx` ปัจจุบันตรงกับ
  บัญชีบอตเดียวกันนั้น วิธีนี้ป้องกันลูปเสียงสะท้อนจากแพลตฟอร์ม ขณะยังอนุญาตให้ผู้ใช้
  อ้างอิงหรือตอบกลับข้อความก่อนหน้าของบอตได้
- **ตั้งค่าด้วย `--token-file` แล้วยังแสดงว่ายังไม่ได้กำหนดค่า:** `--token-file` ตั้งค่าเฉพาะ
  AppSecret เท่านั้น คุณยังต้องมี `appId` ใน config หรือ `QQBOT_APP_ID`
- **ข้อความเชิงรุกไม่มาถึง:** QQ อาจสกัดข้อความที่บอตเริ่มส่งเอง หาก
  ผู้ใช้ไม่ได้โต้ตอบเมื่อเร็วๆ นี้
- **เสียงไม่ถูกถอดความ:** ตรวจสอบว่าได้กำหนดค่า STT แล้ว และผู้ให้บริการเข้าถึงได้

## ที่เกี่ยวข้อง

- [การจับคู่](/th/channels/pairing)
- [กลุ่ม](/th/channels/groups)
- [การแก้ไขปัญหาแชนเนล](/th/channels/troubleshooting)