bot QQ

QQ Bot kết nối với OpenClaw qua API QQ Bot chính thức (Gateway WebSocket). Trò chuyện riêng C2C và lượt nhắc @ trong nhóm là các loại trò chuyện chính, hỗ trợ nội dung đa phương tiện phong phú (hình ảnh, giọng nói, video, tệp). Tin nhắn kênh guild chỉ hỗ trợ văn bản và hình ảnh từ URL từ xa; giọng nói, video, tải tệp lên và hình ảnh cục bộ/Base64 không khả dụng trong các kênh guild. Không hỗ trợ cảm xúc và luồng thảo luận ở bất kỳ đâu.

Trạng thái: plugin chính thức có thể tải xuống.

Cài đặt

openclaw plugins install @openclaw/qqbot

Thiết lập

1. Truy cập Nền tảng mở QQ và dùng ứng dụng QQ trên điện thoại quét mã QR để đăng ký / đăng nhập.
2. Nhấp vào Create Bot để tạo QQ bot mới.
3. Tìm AppID và AppSecret trên trang cài đặt của bot rồi sao chép chúng.

4. Thêm kênh:

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

5. Khởi động lại Gateway.

Thiết lập tương tác:

openclaw channels add

Trình hướng dẫn cũng cung cấp phương thức liên kết bằng mã QR thay cho việc nhập AppID/AppSecret theo cách thủ công: quét mã bằng ứng dụng điện thoại được liên kết với QQ Bot đích để hoàn tất liên kết. OpenClaw lưu thông tin xác thực được trả về trong phạm vi cấu hình của tài khoản.

Cấu hình

Cấu hình tối thiểu:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: "YOUR_APP_SECRET",    },  },}

Các biến môi trường của tài khoản mặc định (chỉ tài khoản cấp cao nhất):

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret được lưu trong tệp:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecretFile: "/path/to/qqbot-secret.txt",    },  },}

AppSecret SecretRef từ môi trường:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },    },  },}

Lưu ý:

• openclaw channels add --channel qqbot --token-file ... chỉ đặt AppSecret; appId phải được đặt sẵn trong cấu hình hoặc QQBOT_APP_ID.
• clientSecret chấp nhận chuỗi văn bản thuần túy, đường dẫn tệp (clientSecretFile) hoặc đối tượng SecretRef có cấu trúc.
• Các chuỗi đánh dấu secretref:... / secretref-env:... cũ bị từ chối đối với clientSecret; hãy dùng đối tượng SecretRef có cấu trúc thay thế.

Chính sách truy cập

• allowFrom / groupAllowFrom kiểm soát ai có thể trò chuyện với bot trong ngữ cảnh C2C / nhóm. dmPolicy / groupPolicy (open | allowlist | disabled) kiểm soát chế độ thực thi. dmPolicy mặc định là allowlist khi allowFrom có một mục cụ thể (không phải ký tự đại diện), nếu không thì là open. groupPolicy mặc định là allowlist khi groupAllowFrom hoặc allowFrom có một mục cụ thể, nếu không thì là open.
• Các lệnh dấu gạch chéo có "Xác thực: danh sách cho phép" yêu cầu một mục tường minh không phải ký tự đại diện trong allowFrom (hoặc groupAllowFrom đối với lệnh gọi từ nhóm), bất kể dmPolicy / groupPolicy — xem Lệnh dấu gạch chéo.

Thiết lập nhiều tài khoản

Chạy nhiều QQ bot trong một phiên bản OpenClaw duy nhất:

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

Mỗi tài khoản sở hữu một kết nối WebSocket, máy khách API và bộ nhớ đệm token biệt lập, được định danh bằng appId. Các dòng nhật ký được gắn thẻ bằng mã định danh của tài khoản sở hữu để dữ liệu chẩn đoán vẫn có thể tách biệt khi bạn chạy nhiều bot trong một Gateway.

Thêm bot thứ hai qua CLI:

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

Trò chuyện nhóm

Tính năng hỗ trợ nhóm sử dụng OpenID của nhóm QQ, không dùng tên hiển thị. Thêm bot vào một nhóm, sau đó nhắc đến bot hoặc cấu hình nhóm để hoạt động mà không cần lượt nhắc.

{  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["*"] đặt giá trị mặc định cho mọi nhóm; một mục groups.GROUP_OPENID cụ thể sẽ ghi đè các giá trị mặc định đó cho một nhóm. Cài đặt nhóm:

commandLevel chấp nhận:

Các mục toolPolicy cũ của QQBot đã ngừng sử dụng. Chạy openclaw doctor --fix để di chuyển chúng sang tools.

Các chế độ kích hoạt là mention và always. requireMention: true ánh xạ tới mention; requireMention: false ánh xạ tới always. Nếu có ghi đè kích hoạt ở cấp phiên, ghi đè đó sẽ được ưu tiên hơn cấu hình.

Hàng đợi tin nhắn đến được duy trì theo từng đối tượng ngang hàng. Đối tượng ngang hàng trong nhóm có giới hạn hàng đợi lớn hơn (50 so với 20 đối với đối tượng trực tiếp), loại bỏ tin nhắn do bot tạo trước tin nhắn của con người khi đầy và hợp nhất các đợt tin nhắn nhóm thông thường thành một lượt có ghi nhận nguồn gửi. Các lệnh dấu gạch chéo chạy lần lượt, độc lập với mọi lô hợp nhất.

Giọng nói (STT / TTS)

STT và TTS hỗ trợ cấu hình hai cấp với cơ chế dự phòng theo mức ưu tiên:

{  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" },            },          },        },      },    },  },}

Đặt enabled: false trên một trong hai để tắt. Các ghi đè TTS cấp tài khoản sử dụng cùng cấu trúc với messages.tts và được hợp nhất sâu lên trên cấu hình TTS của kênh/toàn cục.

Theo mặc định, yêu cầu STT hết thời gian chờ sau 60 giây. STT dành riêng cho plugin sử dụng giá trị ghi đè models.providers.<id>.timeoutSeconds của mô hình được chọn. STT âm thanh của framework lần lượt sử dụng tools.media.audio.models[0].timeoutSeconds, sau đó là tools.media.audio.timeoutSeconds, rồi đến giá trị ghi đè của nhà cung cấp được chọn.

Các tệp đính kèm giọng nói QQ đến được cung cấp cho tác nhân dưới dạng siêu dữ liệu phương tiện âm thanh, đồng thời giữ các tệp giọng nói thô bên ngoài MediaPaths dùng chung. [[audio_as_voice]] trong phản hồi văn bản thuần túy sẽ tổng hợp TTS và gửi tin nhắn thoại QQ nguyên bản khi TTS được cấu hình.

Cũng có thể tinh chỉnh hành vi tải lên/chuyển mã âm thanh đi bằng channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Định dạng đích

Lệnh dấu gạch chéo

Các lệnh tích hợp được chặn trước hàng đợi AI:

Nối thêm ? vào bất kỳ lệnh nào để xem trợ giúp sử dụng (ví dụ /bot-upgrade ?).

Các lệnh "Xác thực: danh sách cho phép" còn yêu cầu openid của người gửi nằm trong danh sách allowFrom tường minh không có ký tự đại diện (groupAllowFrom được ưu tiên đối với các lệnh được gọi từ nhóm, sau đó dự phòng về allowFrom). Ký tự đại diện allowFrom: ["*"] cho phép trò chuyện nhưng không cho phép các lệnh này. Việc chạy một trong các lệnh đó bên ngoài trò chuyện riêng hoặc khi không được ủy quyền sẽ trả về gợi ý thay vì âm thầm loại bỏ tin nhắn.

/bot-me, /bot-version và /bot-upgrade chỉ dùng được trong cuộc trò chuyện riêng tư nhưng không yêu cầu danh sách cho phép — bất kỳ người gửi C2C nào cũng có thể chạy chúng.

Khi phê duyệt thực thi của QQ Bot sử dụng cơ chế dự phòng mặc định trong cùng cuộc trò chuyện, các lượt nhấp vào nút phê duyệt gốc cũng tuân theo cùng danh sách cho phép lệnh tường minh, không có ký tự đại diện. Để cấp quyền chỉ phê duyệt mà không mở rộng quyền truy cập lệnh, hãy cấu hình channels.qqbot.execApprovals.approvers. Phê duyệt thực thi gốc được bật theo mặc định.

Phương tiện và lưu trữ

• Phương tiện đến, đi và qua cầu nối Gateway dùng chung một thư mục gốc dữ liệu tại ~/.openclaw/media/qqbot (tuân theo OPENCLAW_HOME khi được đặt), nhờ đó các tệp tải lên, tải xuống và bộ nhớ đệm chuyển mã nằm trong cùng một thư mục được bảo vệ.
• Việc gửi nội dung đa phương tiện phong phú đến các đích C2C và nhóm đi qua một đường dẫn sendMedia duy nhất. Tệp cục bộ và bộ đệm trong bộ nhớ có kích thước từ 5 MiB trở lên sử dụng các điểm cuối tải lên theo từng phần của QQ; dữ liệu nhỏ hơn và nguồn URL từ xa/Base64 sử dụng API tải lên một lần.
• Nếu một bản nâng cấp nóng làm gián đoạn Gateway trước khi ghi xong openclaw.json, ở lần khởi động tiếp theo, Plugin sẽ khôi phục appId / clientSecret đã biết gần nhất cho tài khoản đó từ một bản chụp nhanh nội bộ (không bao giờ ghi đè một thay đổi cấu hình có chủ ý), nên không cần quét lại mã QR.

Khắc phục sự cố

• Gateway không khởi động / không có tin nhắn đến: xác minh appId và clientSecret là chính xác và bot đã được bật trên QQ Open Platform. Thông tin xác thực bị thiếu sẽ hiển thị dưới dạng "QQBot chưa được cấu hình (thiếu appId hoặc clientSecret)".
• Thiết lập bằng --token-file vẫn hiển thị chưa được cấu hình: --token-file chỉ đặt AppSecret. appId vẫn phải được đặt trong cấu hình hoặc QQBOT_APP_ID.
• Các phản hồi nhóm dồn dập xung đột: khi hàng đợi của một bên ngang hàng bị đầy, hàng đợi tin nhắn đến sẽ loại bỏ tin nhắn do bot gửi trước tin nhắn của con người và gộp các đợt tin nhắn nhóm thông thường (không phải lệnh) thành một lượt có ghi rõ nguồn gửi, vì vậy một luồng trò chuyện dồn dập từ bot sẽ không làm gián đoạn tin nhắn của con người.
• Tin nhắn chủ động không đến: QQ có thể chặn tin nhắn do bot khởi tạo nếu người dùng không tương tác gần đây.
• Giọng nói không được phiên âm: hãy bảo đảm STT đã được cấu hình và có thể kết nối đến nhà cung cấp.

Liên quan

• Ghép nối
• Nhóm
• Khắc phục sự cố kênh