llms.txt: machine-readable documentation index. Markdown version of this page is also available.

Simple Robot 5.x Help

QQ机器人

release

概述

QQ机器人组件 是一个 Kotlin 多平台 的 QQ机器人官方API SDK实现库， 也是 Simple Robot 标准API下实现的组件库，异步高效、Java友好！

QQ 组件主要分成三个层次：

  • simbot-component-qq-api

    对 QQ 开放平台 API、模型、网关事件体的原始封装。

  • simbot-component-qq-stdlib

    在 API 之上提供较低封装的 Bot、鉴权与事件接收实现。

  • simbot-component-qq-core

    面向 simbot 的组件实现，也是大多数业务项目真正直接依赖的模块。

目前核心能力覆盖：

  • 频道公域消息、频道/成员相关事件

  • 论坛相关事件

  • 频道私聊 DMS

  • QQ群与 C2C 单聊能力

  • 频道、QQ群与 C2C 消息撤回 API（自 5.0 起补充群聊与单聊支持）

  • C2C 自定义菜单与多场景指令面板管理（自 5.0 起）

  • 群基础信息、机器人群内状态、入群申请管理和成员禁言（自 5.0 起）

其中 QQ 群与 C2C 单聊能力自 4.0.0-beta6 起加入。 更细粒度的事件与对象范围，请以 事件列表 和相邻对象章节为准。

模块

QQ 组件使用 simbot-component-qq-* 坐标，随标准库统一版本发布。

模块

内容

simbot-component-qq-common

共享常量与注解，自 5.0 起提供

simbot-component-qq-api

API 请求、原始事件、消息模型与构建器

simbot-component-qq-stdlib

Bot、鉴权和事件接收处理

simbot-component-qq-core

simbot 组件实现，普通应用直接依赖此模块

simbot-component-qq-internal-ed25519

内部签名支持，通常不需要直接依赖

上述模块均支持 JVM、JS、 wasm-js 和部分 Native 目标。 版本升级与旧坐标迁移参见 5.0 更新与迁移。

命名说明

QQ机器人组件最初只支持 QQ 频道，因此使用 simbot-component-qq-guild 命名。 自 5.0 起，模块坐标调整为 simbot-component-qq-*。 包名与 QQGuildComponent、 QQGuildBotManager 等类型名仍保留原有命名。

前提准备

机器人账号

你需要参考 官方QQ机器人文档 ，并注册一个 机器人账号 。审核通过， 便可登录 QQ开放平台 查看你的机器人账号信息了。

事件订阅方式

官方提供了 webhook 与 websocket 两种事件订阅方式。

目前，这两种接入路径都有对应实现或示例：

  • 如果你要接入 webhook 回调，前往 Webhook

  • 如果你要使用 websocket 收事件，则继续参考本页与 开始使用

你可以在机器人后台中查看、配置自己的回调地址与订阅范围。

安装

安装组件库

安装依赖

  1. 安装simbot核心库实现

    implementation("love.forte.simbot:simbot-core:5.0.0-Alpha2")

    如果使用 Java 而不配合使用 Gradle 的 Kotlin 插件, 那么你需要指定依赖的后缀为 -jvm。

    implementation("love.forte.simbot:simbot-core-jvm:5.0.0-Alpha2")
    implementation 'love.forte.simbot:simbot-core:5.0.0-Alpha2'

    如果使用 Java 而不配合使用 Gradle 的 Kotlin 插件, 那么你需要指定依赖的后缀为 -jvm。

    implementation 'love.forte.simbot:simbot-core-jvm:5.0.0-Alpha2'
    <dependency> <groupId>love.forte.simbot</groupId> <artifactId>simbot-core-jvm</artifactId> <version>5.0.0-Alpha2</version> </dependency>
    implementation("love.forte.simbot:simbot-core-spring-boot-starter:5.0.0-Alpha2")
    implementation 'love.forte.simbot:simbot-core-spring-boot-starter:5.0.0-Alpha2'
    <dependency> <groupId>love.forte.simbot</groupId> <artifactId>simbot-core-spring-boot-starter</artifactId> <version>5.0.0-Alpha2</version> </dependency>
    implementation("love.forte.simbot:simbot-core-spring-boot-starter-v2:5.0.0-Alpha2")
    implementation 'love.forte.simbot:simbot-core-spring-boot-starter-v2:5.0.0-Alpha2'
    <dependency> <groupId>love.forte.simbot</groupId> <artifactId>simbot-core-spring-boot-starter-v2</artifactId> <version>5.0.0-Alpha2</version> </dependency>

  2. 安装组件库

    simbot-component-qq-core 即为QQ机器人组件的核心库， 也就是作为simbot组件所使用的 组件库。

    implementation("love.forte.simbot.component:simbot-component-qq-core:5.0.0-Alpha2")

    如果使用 Java 而不配合使用 Gradle 的 kotlin 插件, 那么你需要指定依赖的后缀为 -jvm。

    implementation("love.forte.simbot.component:simbot-component-qq-core-jvm:5.0.0-Alpha2")
    implementation 'love.forte.simbot.component:simbot-component-qq-core:5.0.0-Alpha2'

    如果使用 Java 而不配合使用 Gradle 的 kotlin 插件, 那么你需要指定依赖的后缀为 -jvm。

    implementation 'love.forte.simbot.component:simbot-component-qq-core-jvm:5.0.0-Alpha2'
    <dependency> <groupId>love.forte.simbot.component</groupId> <artifactId>simbot-component-qq-core-jvm</artifactId> <version>5.0.0-Alpha2</version> </dependency>

  3. 安装Ktor客户端引擎

    QQ机器人组件使用 Ktor 作为 HTTP 客户端实现， 但是默认不会依赖任何具体的引擎。

    因此，你需要选择并使用一个 Ktor Client 引擎实现。

    你可以前往 Ktor文档 处选择一个对应所用平台下合适的 Client Engine。 这里会根据不同平台提供几个示例，你可以选择其他可用目标。

    在 Java11+ 的环境下，可以选择 Java 引擎。

    runtimeOnly("io.ktor:ktor-client-java:$ktor_version")

    如果不使用Kotlin的Gradle插件:

    runtimeOnly("io.ktor:ktor-client-java-jvm:$ktor_version")
    runtimeOnly 'io.ktor:ktor-client-java:$ktor_version'

    如果不使用Kotlin的Gradle插件:

    runtimeOnly 'io.ktor:ktor-client-java-jvm:$ktor_version'
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-java-jvm</artifactId> <version>${ktor_version}</version> <scope>runtime</scope> </dependency>

    OkHttp 引擎基于 OkHttp，是一个不错的库。

    runtimeOnly("io.ktor:ktor-client-okhttp:$ktor_version")

    如果不使用Kotlin的Gradle插件:

    runtimeOnly("io.ktor:ktor-client-okhttp-jvm:$ktor_version")
    runtimeOnly 'io.ktor:ktor-client-okhttp:$ktor_version'

    如果不使用Kotlin的Gradle插件:

    runtimeOnly 'io.ktor:ktor-client-okhttp-jvm:$ktor_version'
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-okhttp-jvm</artifactId> <version>${ktor_version}</version> <scope>runtime</scope> </dependency>

    CIO 是一个比较通用的引擎。 在不知道选什么的情况下，可以考虑使用它。

    runtimeOnly("io.ktor:ktor-client-cio:$ktor_version")

    如果不使用Kotlin的Gradle插件:

    runtimeOnly("io.ktor:ktor-client-cio-jvm:$ktor_version")
    runtimeOnly 'io.ktor:ktor-client-cio:$ktor_version'

    如果不使用Kotlin的Gradle插件:

    runtimeOnly 'io.ktor:ktor-client-cio-jvm:$ktor_version'
    <dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-cio-jvm</artifactId> <version>${ktor_version}</version> <scope>runtime</scope> </dependency>

    JavaScript 平台下可以选择 Js 引擎。

    implementation("io.ktor:ktor-client-js:$ktor_version")
    implementation 'io.ktor:ktor-client-js:$ktor_version'

    native 平台目标下，可能需要根据不同的平台类型选择不同的引擎。

    可以选择 WinHttp 引擎。

    implementation("io.ktor:ktor-client-winhttp:$ktor_version")
    implementation 'io.ktor:ktor-client-winhttp:$ktor_version'

    Linux 下依旧可以选择 CIO 引擎。

    implementation("io.ktor:ktor-client-cio:$ktor_version")
    implementation 'io.ktor:ktor-client-cio:$ktor_version'

    可以选择 Darwin 引擎。

    implementation("io.ktor:ktor-client-darwin:$ktor_version")
    implementation 'io.ktor:ktor-client-darwin:$ktor_version'
29 October 2026
概述开始使用