Mai-with-u · Schaled · Aug 22, 2026 · Aug 23, 2026 · Aug 24, 2026
diff --git a/.gitignore b/.gitignore
@@ -147,4 +147,4 @@ package-lock.json
 
 # OpenCode
 .sisyphus
-.omo
+.omozh/manual/adapters/LuckyLiliiaDoc/
diff --git a/.vitepress/sidebar/en.ts b/.vitepress/sidebar/en.ts
@@ -159,6 +159,7 @@ export const sidebar: DefaultTheme.Sidebar = {
         { text: 'NapCat QQ Connection', link: '/en/manual/adapters/napcat' },
         { text: 'GoCQ Adapter', link: '/en/manual/adapters/gocq' },
         { text: 'SnowLuma Adapter', link: '/en/manual/adapters/snowluma' },
+        { text: 'QQ Official Adapter', link: '/en/manual/adapters/qq-official-adapter' },
         { text: 'Telegram Adapter', link: '/en/manual/adapters/telegram' },
         { text: 'Discord Adapter', link: '/en/manual/adapters/discord' },
       ]

diff --git a/.vitepress/sidebar/zh.ts b/.vitepress/sidebar/zh.ts
@@ -118,6 +118,7 @@ export const sidebar: DefaultTheme.Sidebar = {
         { text: 'NapCat QQ 连接', link: '/manual/adapters/napcat' },
         { text: 'GoCQ 适配器', link: '/manual/adapters/gocq' },
         { text: 'SnowLuma 适配器', link: '/manual/adapters/snowluma' },
+        { text: 'QQ 官方适配器', link: '/manual/adapters/qq-official-adapter' },
         { text: 'Telegram 适配器', link: '/manual/adapters/telegram' },
         { text: 'Discord 适配器', link: '/manual/adapters/discord' },
       ]

diff --git a/en/manual/adapters/index.md b/en/manual/adapters/index.md
@@ -12,6 +12,7 @@ Adapters are responsible for connecting messaging platforms such as QQ, Telegram
 - [NapCat](./napcat.md) (Recommended) — The QQ adapter officially maintained by MaiBot, supporting both the plugin version and the standalone version. The plugin version is the currently recommended solution.
 - [GoCQ](./gocq.md) (Available, outdated) — QQ adaptation solution based on go-cqhttp / AstralGocq, suitable for existing GoCQ environments or specific needs.
 - [SnowLuma](./snowluma.md) (Available, in testing) — Next-generation QQ adaptation solution.
+- [QQ Official Adapter](./qq-official-adapter.md) (Available) — Adapter based on the QQ official open platform API v2, outbound-only connection, no public IP needed.
 
 **Other platforms** — Community adaptations
 - [Telegram](./telegram.md) — Telegram platform adaptation solution

diff --git a/en/manual/adapters/qq-official-adapter.md b/en/manual/adapters/qq-official-adapter.md
@@ -0,0 +1,200 @@
+---
+title: QQ Official Adapter
+---
+# QQ Official Adapter
+
+The QQ Official Adapter connects MaiBot to the QQ platform through the [QQ Official Bot Open Platform](https://q.qq.com), sending and receiving messages in direct chats, group chats, text channels and channel DMs.
+
+::: info Outbound-only connection
+The QQ Official Adapter actively connects to QQ's official WebSocket gateway and Open Platform API from MaiBot. It is an **outbound-only** connection — no public IP, port mapping, or callback URL is required.
+:::
+
+::: warning Different ID system
+The UserID / GroupID used by this adapter come from QQ's official OpenID system (`user_openid` / `member_openid` / `group_openid`), not numeric QQ numbers and group numbers. They cannot be mixed with OneBot v11 IDs.
+:::
+
+## Overview
+
+The QQ Official Adapter is a MaiBot plugin that integrates with the API v2 of QQ's official bot open platform. It actively connects to QQ's official WebSocket gateway to receive messages and sends replies through the Open Platform REST API:
+
+- **Inbound**: QQ's official WebSocket gateway pushes events to the adapter, which converts and injects them into MaiBot
+- **Outbound**: replies generated by MaiBot are converted by the adapter and sent through the QQ official API
+
+Unlike OneBot-based adapters such as NapCat and GoCQ, the QQ Official Adapter only uses QQ's official capabilities. It does not depend on third-party protocols or services, and there is no separate network connection between the adapter and MaiBot to maintain.
+
+Message flow: **QQ official gateway → adapter plugin (inside MaiBot) → MaiBot**
+
+### Adapter Repository
+
+Source code of the QQ Official Adapter: [WhiteCloudOL/qq-official-adapter](https://github.com/WhiteCloudOL/qq-official-adapter)
+
+## Installation
+
+### Step 1: Create a QQ Bot
+
+Open the [QQ Bot Open Platform](https://q.qq.com/qqbot/openclaw/), create a bot, and keep its **AppID** and **AppSecret**.
+
+::: tip AppSecret is the bot password
+AppSecret is equivalent to the bot password. Store it securely, never commit it to a code repository or share it. If you suspect it has leaked, reset it on the open platform immediately.
+:::
+
+### Step 2: Get the Adapter
+
+Clone the adapter repository into MaiBot's `plugins/` folder:
+
+::: code-group
+
+```bash [Bash ~vscode-icons:file-type-shell~]
+# Enter MaiBot's plugins directory
+cd MaiBot/plugins
+
+# Clone the repository
+git clone https://github.com/WhiteCloudOL/qq-official-adapter.git
+```
+
+:::
+
+MaiBot installs the dependencies automatically based on the plugin manifest.
+
+### Step 3: Fill in the Plugin Config
+
+The plugin is **disabled by default** after installation. In the MaiBot WebUI plugin config, find **"QQ 官方机器人适配器"** and fill in the following:
+
+- **Enable adapter** — On
+- **AppID** — The AppID shown on the QQ open platform
+- **AppSecret** — The AppSecret matching the AppID
+
+The chat-list filter is off by default, so you can use it without configuring anything. If you need to restrict which groups or users can connect, enable the "chat filter" and fill in QQ official OpenIDs (see the [config reference](#configuration-reference) below).
+
+Alternatively, you can edit the plugin's config file `plugins/qq-official-adapter/config.toml` directly, set `enabled` to `true` and fill in the credentials — the effect is the same.
+
+### Step 4: Set the MaiBot Main Account
+
+Start MaiBot once and let the plugin connect to the QQ gateway, then find this line in the logs:
+
+```text
+QQ 官方 WebSocket 已就绪: self_id=机器人自身ID
+```
+
+Then fill in the following in MaiBot's `config/bot_config.toml`:
+
+::: code-group
+
+```toml [TOML ~vscode-icons:file-type-toml~]
+[bot]
+platform = "qq"
+qq_account = "日志中的 self_id"
+```
+
+:::
+
+::: warning Don't fill in the wrong account
+`qq_account` must be the `self_id` from the logs (the bot's own ID in the WebSocket `READY` event). **Do not** fill in the AppID, the QQ number, or a OneBot v11 bot QQ number. MaiBot uses it to mark messages sent by the bot itself.
+:::
+
+The bot's display nickname is read automatically from `bot.nickname` (default `"麦麦"`). When mentioned in a group, it enters the chat context as `@nickname`, so there is no need to fill in the bot ID in the plugin config again.
+
+### Step 5: Enable Full Group Messages (group chats only)
+
+To use group chat features, the **group owner** must open the QQ group settings, select the bot being used, and set the "机器人可获取的群聊消息范围" (range of group messages the bot can receive) to "获取群内全部消息" (get all messages in the group). Without this, the bot only receives messages within the platform-allowed scope and cannot fully participate in group chats.
+
+> This setting can only be operated by the group owner and must be set separately for each group that uses the bot.
+
+### Step 6: Restart and Verify
+
+Restart MaiBot and confirm the logs show **"QQ 官方 WebSocket 已就绪"**. It is recommended to test in order:
+
+1. Send plain text in a direct chat.
+2. @ the bot in a group chat and send text.
+3. Send a normal image and a QQ emoji / sticker.
+4. Have MaiBot reply with a pure image, a pure emoji, and a text-plus-image message.
+
+## Configuration Reference
+
+The plugin's config file is located at `plugins/qq-official-adapter/config.toml` and contains the following three sections.
+
+### Plugin Settings (`[plugin]`)
+
+- **`enabled`** — Whether to enable the QQ Official Adapter. When off, the plugin only registers the message gateway and does not connect to the QQ WebSocket. Default: off
+- **`config_version`** — The current config structure version (managed automatically, usually no need to change it manually). Default: "1.1.0"
+
+### Bot Credentials (`[credentials]`)
+
+- **`appid`** — The bot's AppID on the QQ open platform (obtained from `https://q.qq.com`). Default: empty
+- **`app_secret`** — The AppSecret paired with the AppID, used to obtain the access token. Default: empty
+- **`sandbox`** — Whether to use the sandbox environment. When enabled, the WebSocket gateway and message sending use the sandbox address, which is convenient for testing. Default: off
+
+### Chat Filter (`[chat]`)
+
+- **`enable_chat_list_filter`** — Whether to enable the group and private chat list filter. When off, `group_list` / `private_list` are ignored and only the `ban_user_id` rule applies. Default: off
+- **`show_dropped_chat_list_messages`** — Whether to log messages dropped by the chat list filter. Default: off
+- **`group_list_type`** — Group list mode. Whitelist only accepts the groups in the list; blacklist ignores the groups in the list. Default: "whitelist"
+- **`group_list`** — The group list, filled with `group_openid` (deduplicated automatically). Default: empty
+- **`private_list_type`** — Private chat list mode. Whitelist only accepts the private chats in the list; blacklist ignores the private chats in the list. Default: "whitelist"
+- **`private_list`** — The private chat list, filled with `user_openid` (deduplicated automatically). Default: empty
+- **`ban_user_id`** — The globally blocked user list, filled with `user_openid` or `member_openid`. Messages from these users are dropped before entering MaiBot. Default: empty
+
+::: tip The list expects OpenIDs
+The chat lists are filled with QQ official OpenIDs (`group_openid` / `user_openid` / `member_openid`), not numeric group numbers / QQ numbers. You can find the OpenID of a given event in the debug logs.
+:::
+
+### Complete Config Example
+
+::: code-group
+
+```toml [TOML ~vscode-icons:file-type-toml~]
+[plugin]
+enabled = true
+config_version = "1.1.0"
+
+[credentials]
+appid = "你的AppID"
+app_secret = "你的AppSecret"
+sandbox = false
+
+[chat]
+enable_chat_list_filter = false
+show_dropped_chat_list_messages = false
+group_list_type = "whitelist"
+group_list = []
+private_list_type = "whitelist"
+private_list = []
+ban_user_id = []
+```
+
+:::
+
+## Message Capabilities
+
+The QQ Official Adapter supports the following message scenarios:
+
+- **QQ direct chats** — Receives text, images, emoji, voice, video and files; can send text, images, emoji, voice, video, files and structured messages
+- **QQ group chats** — Receives @-mentions, full messages and attachments; can send text, images, emoji, voice, video, files and structured messages
+- **Text channels** — Receives @-mentions, full messages and attachments; can send text, images, Markdown, Ark and Embed
+- **Channel DMs** — Receives text and attachments; can send text, images, Markdown, Ark and Embed
+
+Emoji in QQ groups and direct chats are sent as image rich media, so they never appear as invalid `[表情]` text; pure image or pure emoji replies also do not send extra `[图片]` / `[表情]` placeholder text. Inbound images and emoji keep their original binary for MaiBot to recognize: images that appear for the first time are recognized in the background and injected into the chat context afterwards, and the same image reuses the cached description.
+
+The adapter automatically judges whether a group message really @-mentions the bot (combining the event type, the WebSocket self ID, structured mentions and message elements) and auto-learns the bot's OpenID within the group scope, so there is no need to fill in the bot ID in the plugin config again.
+
+## Verification and Troubleshooting
+
+### Verify the Connection
+
+How do you know it is connected? Check these places:
+
+1. **MaiBot logs**: look for the `QQ 官方 WebSocket 已就绪` message
+2. **WebUI plugin list**: the QQ Official Adapter plugin shows as loaded
+3. **Send a test message**: send a message in a QQ direct chat / group and see whether MaiBot replies
+
+### The bot is @-mentioned in a group but MaiBot doesn't recognize it
+
+First confirm the logs received `GROUP_AT_MESSAGE_CREATE` or `GROUP_MESSAGE_CREATE`. If the logs show the adapter recognized it but MaiBot still cannot send a reply, check whether `qq_account` in `bot_config.toml` equals the `self_id` in the ready log.
+
+### Can't receive group chat or channel messages
+
+Confirm the bot has the permission for the corresponding scenario and has enabled the corresponding message capability on the open platform. If the quick-creation page says "暂不支持进入群聊" (group chats are not supported yet), the plugin cannot bypass the platform limit. For group chat scenarios, the group owner must also enable "获取群内全部消息".
+
+### 401 or authentication failure
+
+Check that the AppID and AppSecret belong to the same bot. After resetting the AppSecret, update the plugin config accordingly and restart.
diff --git a/zh/manual/adapters/index.md b/zh/manual/adapters/index.md
@@ -12,6 +12,7 @@ title: 适配器概览
 - [NapCat](./napcat.md)（推荐使用）— 麦麦官方维护的 QQ 适配器，支持插件版和独立版，插件版是当前推荐方案
 - [GoCQ](./gocq.md)（可用，偏旧）— 基于 go-cqhttp / AstralGocq 的 QQ 适配方案，适合已有 GoCQ 环境或特定需求
 - [SnowLuma](./snowluma.md)（可用，测试中）— 新一代 QQ 适配方案
+- [QQ 官方适配器](./qq-official-adapter.md)（可用）— 基于 QQ 官方开放平台 API v2 的适配器，纯出站连接，无需公网 IP
 
 **其他平台** — 社区适配
 - [Telegram](./telegram.md) — Telegram 平台适配方案