> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loongclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# QQ Bot

> Configure the QQ Bot channel surface in Loong.

# QQ Bot

This is a shipped runtime-backed surface: direct sends are implemented, the reply-loop runtime is implemented, and Loong owns the QQ gateway session directly through `channels serve qqbot`.

## At A Glance

| Field                    | Value                                          |
| ------------------------ | ---------------------------------------------- |
| Catalog id               | `qqbot`                                        |
| Config key               | `qqbot`                                        |
| Implementation status    | `runtime_backed`                               |
| Transport                | `qq_official_bot_gateway_or_plugin_bridge`     |
| Aliases                  | `qq`, `qq-bot`, `tencent-qq`                   |
| Default send target kind | `conversation`                                 |
| Runtime owner            | `gateway run` or direct `channels serve qqbot` |

## Minimal Config

```toml theme={null}
[qqbot]
enabled = true
app_id_env = "QQBOT_APP_ID"
client_secret_env = "QQBOT_CLIENT_SECRET"
allowed_peer_ids = ["openid_alice"]
```

## Smoke Test

```bash theme={null}
loong channels send qqbot --target "c2c:openid_alice" --text "hello from loong"
loong channels serve qqbot
```

What success looks like:

* `QQ Bot [qqbot]` appears in the gateway-supervised runtime set
* `channels serve qqbot` starts a native Loong-owned runtime instead of a managed plugin selection flow
* doctor keeps direct send / serve readiness checks visible and actionable

## Current Command Surface

| Operation    | Current path           | Usage or status                                                                                                                                                              |
| ------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| send         | `channels send qqbot`  | executes directly against the QQ gateway contract; target contract stays `qqbot:<account>:c2c:<openid>`, `qqbot:<account>:group:<openid>`, or `qqbot:<account>:channel:<id>` |
| serve        | `channels serve qqbot` | starts the native Loong-owned QQ gateway reply loop                                                                                                                          |
| health check | `loong doctor`         | current readiness and remediation surface                                                                                                                                    |
| inventory    | `loong channels`       | current operator inventory surface                                                                                                                                           |

## Required Fields For Send

| Requirement          | Config paths                                                        | Env pointer paths                                                           | Default env           |
| -------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------- |
| channel enabled      | `qqbot.enabled`<br />`qqbot.accounts.<account>.enabled`             | none                                                                        | none                  |
| qq bot app id        | `qqbot.app_id`<br />`qqbot.accounts.<account>.app_id`               | `qqbot.app_id_env`<br />`qqbot.accounts.<account>.app_id_env`               | `QQBOT_APP_ID`        |
| qq bot client secret | `qqbot.client_secret`<br />`qqbot.accounts.<account>.client_secret` | `qqbot.client_secret_env`<br />`qqbot.accounts.<account>.client_secret_env` | `QQBOT_CLIENT_SECRET` |

## Required Fields For Serve

| Requirement          | Config paths                                                              | Env pointer paths                                                           | Default env           |
| -------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------- |
| channel enabled      | `qqbot.enabled`<br />`qqbot.accounts.<account>.enabled`                   | none                                                                        | none                  |
| qq bot app id        | `qqbot.app_id`<br />`qqbot.accounts.<account>.app_id`                     | `qqbot.app_id_env`<br />`qqbot.accounts.<account>.app_id_env`               | `QQBOT_APP_ID`        |
| qq bot client secret | `qqbot.client_secret`<br />`qqbot.accounts.<account>.client_secret`       | `qqbot.client_secret_env`<br />`qqbot.accounts.<account>.client_secret_env` | `QQBOT_CLIENT_SECRET` |
| allowed peer ids     | `qqbot.allowed_peer_ids`<br />`qqbot.accounts.<account>.allowed_peer_ids` | none                                                                        | none                  |

## Stable Target Templates

| Target                           | Meaning               |
| -------------------------------- | --------------------- |
| `qqbot:<account>:c2c:<openid>`   | direct message openid |
| `qqbot:<account>:group:<openid>` | group openid          |
| `qqbot:<account>:channel:<id>`   | guild channel id      |

## Account Scope Note

QQ Bot openids are scoped to the selected account. Keep account ids stable so route meaning does not drift when you rotate gateway credentials or bridge implementations.

## Runtime Notes

* QQ Bot no longer depends on managed bridge discovery for its main shipped runtime path.
* The native runtime uses the configured QQ gateway credentials directly.

## Gateway And Ownership

This surface can run directly through `channels serve qqbot`, or under [Gateway And Supervision](/use-loong/gateway-and-supervision) when the QQ Bot lane should join a larger supervised runtime set.

## Operator Notes

* Keep `allowed_peer_ids` explicit and narrow.
* Loong validates `allowed_peer_ids` locally before forwarding a QQ send, so a mistyped openid is rejected before it reaches the upstream gateway.
* `channels serve qqbot` owns the runtime loop directly; failures belong to the native runtime path instead of an external managed-plugin selection layer.
* Treat QQ Bot as a multi-account surface from the start if you expect separate direct, group, or guild identities.

## Related Docs

* Continue to [Weixin](/use-loong/channel-guides/weixin) for the WeChat bridge-first lane.
* Continue to [OneBot](/use-loong/channel-guides/onebot) when the upstream bridge already speaks OneBot v11.
* Continue to [Gateway And Supervision](/use-loong/gateway-and-supervision) when QQ Bot should join a longer-lived supervised runtime.
* Continue to [Channel Setup](/use-loong/channel-setup) for the shared public setup contract.