Connect DotCraft to QQ

Connect a QQ account to DotCraft as a channel through NapCat or another OneBot v11 gateway.

CAUTION

Third-party QQ protocol frameworks can create account risk. Use a dedicated QQ account and review the risk before deployment.

Quick setup

1. Open the target workspace in DotCraft Desktop.

2. Open Channels, select QQ, then select Connect.

   

3. Set the OneBot listen address. The default is 127.0.0.1:6700.

4. Enter an access token if NapCat should authenticate to the DotCraft endpoint.

5. Add at least one admin user, allowed user, or allowed group.

   

6. Save the channel and turn it on.

7. In NapCat WebUI, add a reverse WebSocket connection to ws://127.0.0.1:6700/.

8. Set the NapCat message format to array.

Desktop should show the QQ channel as connected after NapCat reaches the DotCraft listener.

Platform setup details

In NapCat, configure the QQ account that will speak for DotCraft:

1. Log in with the dedicated QQ account.
2. Open the OneBot / WebSocket client settings.
3. Set the reverse WebSocket URL to the DotCraft listen address.
4. Set the Token to the same value you entered in Desktop.
5. Set message format to array.

If NapCat runs in Docker or on another machine, replace 127.0.0.1 with an address that can reach the machine running DotCraft Desktop.

Test the connection

1. Send a private message to the QQ account from an allowed user.
2. In a group, @mention the bot account.
3. Confirm DotCraft replies in the same QQ conversation.
4. Ask DotCraft to do something that needs approval, then reply with 同意, 允许, yes, or approve.

What works after setup

• Private chats keep a separate DotCraft conversation per QQ user.
• A QQ group shares one conversation.
• Group messages require an @mention by default.
• Empty admin and allowlist settings mean the bot ignores QQ messages.
• Approval replies accept 同意, 允许, yes, approve, 拒绝, no, reject, and deny. Replying 同意全部 or approve all allows the same kind of action for the rest of the session.
• Voice, video, and file delivery are available through channel delivery tools.
• NapCat in Docker does not need access to the workspace files.

Standalone adapter

Run the QQ adapter yourself only when Desktop is not managing the channel process.

cd sdk/typescript
npm run build --workspace @dotcraft/channel-qq
npx dotcraft-channel-qq --workspace /path/to/workspace

Use --config /custom/qq.json when the adapter config is not stored at .craft/qq.json.

The standalone ExternalChannels registration is in the channel configuration reference.

Related docs

• Channel configuration reference — every field, default, and registration shape for the QQ config file.
• Channel adapters — the adapter base class, its message flow, and the handler contract.
• Channel Module integration — embed a TypeScript channel module in your own host process.