QQ Bot connects to Apus via the official QQ Bot API (WebSocket gateway). C2C private chat and group @-mentions are the primary chat types, with rich media (images, voice, video, files). Guild channel messages are supported for text and remote-URL images only; voice, video, file uploads, and local/Base64 images are not available in guild channels. Reactions and threads are not supported anywhere.

Status: official downloadable plugin.

Install

apus plugins install @tencent-connect/apus-qqbot

If the bot was installed as @openclaw/qqbot under plugin id qqbot, apus plugins update qqbot and apus update rewrite it to @tencent-connect/apus-qqbot under plugin id apus-qqbot. Channel config stays under channels.qqbot.

Setup

1. Go to the QQ Open Platform and scan the QR code with your phone QQ to register / log in.
2. Click Create Bot to create a new QQ bot.
3. Find AppID and AppSecret on the bot's settings page and copy them.

4. Add the channel:

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

5. Check apus channels status --probe; start the Gateway if it is offline. Config changes follow hot reload.

Inbound durability

For QQ gateway turn events, Apus persists the raw event before advancing the saved gateway resume sequence. Pending or retryable turns survive a Gateway restart, remain serialized per conversation, and use the provider event ID to suppress duplicate queue entries while the active or retained completion record exists.

If durable admission fails, Apus terminates the current gateway socket without advancing the sequence. The reconnect/resume path can then request the uncommitted event again. Delivery is still at least once across the queue-to-agent boundary, so a crash during handoff can replay a turn.

Interactive setup:

apus channels add

The wizard also offers QR-code binding as an alternative to typing AppID/AppSecret manually: scan the code with the phone app tied to the target QQ Bot to complete binding. Apus persists the returned credentials under the account's config scope.

Configure

Minimal config:

{
  channels: {
    qqbot: {
      enabled: true,
      dmPolicy: "open",
      allowFrom: ["apus:approval-disabled"],
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_APP_SECRET",
    },
  },
}

These examples keep direct messages open with dmPolicy: "open" while the apus:approval-disabled marker leaves native approval actions disabled. To enable those actions, replace the marker with specific approver QQ OpenIDs.

Default-account env vars (top-level account only):

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

Use a SecretRef to keep the AppSecret out of the channel config. For an environment-backed secret:

{
  channels: {
    qqbot: {
      enabled: true,
      dmPolicy: "open",
      allowFrom: ["apus:approval-disabled"],
      appId: "YOUR_APP_ID",
      clientSecret: {
        source: "env",
        provider: "default",
        id: "QQBOT_CLIENT_SECRET",
      },
    },
  },
}

For a file-backed AppSecret, configure a singleValue file provider:

{
  secrets: {
    providers: {
      qqbot_secret: {
        source: "file",
        path: "/path/to/qqbot-secret.txt",
        mode: "singleValue",
      },
    },
  },
  channels: {
    qqbot: {
      enabled: true,
      dmPolicy: "open",
      allowFrom: ["apus:approval-disabled"],
      appId: "YOUR_APP_ID",
      clientSecret: { source: "file", provider: "qqbot_secret", id: "value" },
    },
  },
}

Notes:

• apus channels add --channel qqbot --token-file ... sets the AppSecret only; appId must already be set in config or QQBOT_APP_ID. Run apus doctor --fix afterward to migrate the legacy file setting.
• clientSecret accepts plaintext or an environment-, file-, exec-, or store-backed SecretRef. Apus resolves the reference before handing the credential to the QQ Bot plugin.
• clientSecretFile is a migration-only legacy setting. apus doctor --fix replaces it with a file-backed clientSecret SecretRef. New configurations should use clientSecret directly.
• Top-level credentials and environment fallbacks belong only to the default account. Named accounts configure their own appId and clientSecret.

Streaming

{
  channels: {
    qqbot: {
      streaming: {
        mode: "partial", // block streaming: "partial" (default) or "off"
        nativeTransport: true, // use QQ's official C2C stream_messages API for DMs
      },
    },
  },
}

• streaming.mode: "off" disables block streaming for the account.
• streaming.nativeTransport: true streams C2C (DM) replies through QQ's official stream_messages API; group/channel targets are unaffected.
• Legacy streaming: true|false scalars and the streaming.c2cStreamApi key migrate to this shape via apus doctor --fix.
• /bot-streaming on|off toggles the same config from a DM.

Access policy

• allowFrom / groupAllowFrom gate who can chat with the bot in C2C / group contexts. dmPolicy / groupPolicy (open | allowlist | disabled) control the enforcement mode. dmPolicy defaults to allowlist once allowFrom has a concrete (non-wildcard) entry, otherwise open. groupPolicy defaults to allowlist once either groupAllowFrom or allowFrom has a concrete entry, otherwise open.
• contextVisibility controls quoted-message text that QQ supplies as supplemental context. The default, "all", keeps quoted text as received. Set "allowlist" to include quoted bodies only when the quoted sender passes the configured sender policy, or "allowlist_quote" to keep explicit quotes while filtering other supplemental context. See Groups.
• "Auth: allowlist" slash commands require an explicit non-wildcard entry in allowFrom (or groupAllowFrom for group invocations) regardless of dmPolicy / groupPolicy — see Slash commands.

Multi-account setup

Run multiple QQ bots under a single Apus instance:

{
  channels: {
    qqbot: {
      enabled: true,
      dmPolicy: "open",
      allowFrom: ["apus:approval-disabled"],
      appId: "111111111",
      clientSecret: { source: "env", provider: "default", id: "QQBOT_DEFAULT_SECRET" },
      accounts: {
        bot2: {
          enabled: true,
          dmPolicy: "open",
          allowFrom: ["apus:approval-disabled"],
          appId: "222222222",
          clientSecret: { source: "env", provider: "default", id: "QQBOT_BOT2_SECRET" },
        },
      },
    },
  },
}

Each account owns an isolated WebSocket connection, API client, and token cache, keyed by appId. Log lines are tagged with the owning account id so diagnostics stay separable when you run several bots under one Gateway.

At startup, a missing SecretRef value makes only its account unavailable; healthy siblings and the Gateway remain available. An explicit failed reference does not fall back to environment or plugin backup credentials. Malformed refs and unknown secret providers still fail startup or reload. On reload, an unchanged account can retain its last-known-good credential; see Secrets runtime model.

Add a second bot via CLI:

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

Group chats

Group support uses QQ group OpenIDs, not display names. Add the bot to a group, then mention it or configure the group to run without a mention.

{
  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["*"] sets defaults for every group; a concrete groups.GROUP_OPENID entry overrides those defaults for one group. Group settings:

commandLevel accepts:

Old QQBot toolPolicy entries are retired. Run apus doctor --fix to migrate them to tools.

Activation modes are mention and always. requireMention: true maps to mention; requireMention: false maps to always. A session-level activation override, when present, wins over config.

The inbound queue is per peer. Group peers get a larger queue cap (50 vs. 20 for direct peers), evict bot-authored messages before human ones when full, and merge bursts of normal group messages into one attributed turn. Slash commands run one by one, independent of any merge batch.

Voice (STT / TTS)

STT and TTS support two-level configuration with priority fallback:

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

Set enabled: false on either to disable. Account-level TTS overrides use the same shape as tts and deep-merge over channel/global TTS config.

STT requests time out after 60 seconds by default. Plugin-specific STT uses the selected models.providers.<id>.timeoutSeconds override. Framework audio STT uses the selected audio-capable tools.media.models[] entry's timeoutSeconds, then the selected provider override.

Inbound QQ voice attachments are exposed to agents as audio media metadata while keeping raw voice files out of generic MediaPaths. [[audio_as_voice]] in a plain-text reply synthesizes TTS and sends a native QQ voice message when TTS is configured.

Outbound audio upload/transcode behavior can also be tuned with channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Target formats

Slash commands

Built-in commands intercepted before the AI queue:

Append ? to any command for usage help (for example /bot-upgrade ?).

"Auth: allowlist" commands additionally require the sender's openid in an explicit non-wildcard allowFrom list (groupAllowFrom takes precedence for group-issued commands, falling back to allowFrom). A wildcard allowFrom: ["*"] permits chat but not these commands. Running one of them outside private chat, or without authorization, returns a hint rather than silently dropping the message.

/bot-me, /bot-version, and /bot-upgrade are private-chat-only but do not require the allowlist — any C2C sender can run them.

When QQ Bot exec approvals use the default same-chat fallback, native approval button clicks follow the same explicit non-wildcard command allowlist. To grant approval-only access without broader command access, configure channels.qqbot.execApprovals.approvers. Native exec approvals are enabled by default.

Media and storage

• Inbound, outbound, and gateway-bridge media share one payload root under ~/.apus/media/qqbot (honoring APUS_HOME when set), so uploads, downloads, and transcode caches stay under one guarded directory.
• Rich media delivery for C2C and group targets goes through one sendMedia path. Local files and in-memory buffers of 5 MiB or more use QQ's chunked upload endpoints; smaller payloads and remote-URL/Base64 sources use the one-shot upload API.
• If a hot upgrade interrupts the Gateway before it finishes writing apus.json, the plugin restores the last-known appId / clientSecret for that account from an internal snapshot on the next start (never overwriting an intentional config change), so re-scanning the QR code is not required.

Troubleshooting

• Gateway does not start / no inbound messages: verify appId and clientSecret are correct and the bot is enabled on the QQ Open Platform. A missing credential surfaces as "QQBot not configured (missing appId or clientSecret)".
• Setup with --token-file still shows unconfigured: --token-file only sets the AppSecret. appId must still be set in config or QQBOT_APP_ID.
• Bursty group replies collide: the inbound queue evicts bot-authored messages ahead of human ones when a peer's queue fills up, and merges bursts of normal (non-command) group messages into one attributed turn, so a flood of bot chatter should not starve human messages.
• Proactive messages not arriving: QQ may block bot-initiated messages if the user has not interacted recently.
• Voice not transcribed: ensure STT is configured and the provider is reachable.

Related

• Pairing
• Groups
• Channel troubleshooting