开始使用

希望从完整示例开始？前往第一个 OneBot 11 机器人。

本页介绍如何安装 OneBot 11 组件、注册 Bot 并监听事件。请先准备所需的账号信息、可用的协议服务端等，再选择核心库或 Spring Boot 的示例。

页面中的代码片段用于说明各步骤。组合到同一个程序时，请先创建应用并注册监听器，再注册和启动 Bot，最后等待应用结束。示例中的 join 或 block 应放在启动流程末尾。

前期准备

准备OneBot11协议服务端
OneBot组件是一个 OneBot 协议的客户端实现，因此在使用之前，你需要准备一个支持 OneBot11 的服务端，例如 NapCat, Language.OneBot 等。
鉴于 OneBot 生态的特殊性，此处不对具体服务端实现作更多展开说明。你只需要确保它：
- 支持 OneBot11
- 提供 HTTP API
- 如需事件订阅，则提供正向 WebSocket

安装

安装依赖

安装simbot核心库实现
在安装组件库之前，确保你已经安装了可用的核心库实现，比如核心库或 Spring Boot starter。
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>
前往使用 Spring Boot 3 或集成Spring Boot 了解更多内容。
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>
前往使用 Spring Boot 2 了解更多内容。
安装 simbot-component-onebot-v11-core 依赖
implementation("love.forte.simbot.component:simbot-component-onebot-v11-core:5.0.0-Alpha2")
如果使用 Java 而不配合使用 Gradle 的 kotlin 插件, 那么你需要指定依赖的后缀为 -jvm。
implementation("love.forte.simbot.component:simbot-component-onebot-v11-core-jvm:5.0.0-Alpha2")
implementation 'love.forte.simbot.component:simbot-component-onebot-v11-core:5.0.0-Alpha2'
如果使用 Java 而不配合使用 Gradle 的 kotlin 插件, 那么你需要指定依赖的后缀为 -jvm。
implementation 'love.forte.simbot.component:simbot-component-onebot-v11-core-jvm:5.0.0-Alpha2'
<dependency> <groupId>love.forte.simbot.component</groupId> <artifactId>simbot-component-onebot-v11-core-jvm</artifactId> <version>5.0.0-Alpha2</version> </dependency>
安装Ktor客户端引擎
OneBot11组件使用 Ktor 作为 HTTP 客户端实现，但是默认不会依赖任何具体的引擎。
因此，你需要选择并使用一个 Ktor Client 引擎实现。
注意，你需要选择一个支持 WebSocket 的引擎。
你可以前往 Ktor文档处选择一个对应所用平台下合适的 Client Engine。这里会根据不同平台提供几个示例，你可以选择其他可用目标。
引擎版本需要与组件使用的 Ktor 版本一致。simbot 5.0 与其组件使用 Ktor 3，具体版本参见 5.0 更新与迁移。
在 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>
引擎大部分情况下可以 runtime only，除非你需要显式地定制化它。
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'

使用

创建Application

simbot-core 提供了一个基础的 Application 实现类型： SimpleApplication。

val app = launchSimpleApplication {
    // 使用OneBot组件相关的内容。
    useOneBot11()
    // 其他配置...
}

// 继续注册监听器和 Bot，最后再等待应用结束

final var applicationAsync = Applications.launchApplicationAsync(
    Simple.INSTANCE,
    configurer -> {
        // 安装OneBot组件相关内容
        configurer.install(OneBot11Component.Factory);
        configurer.install(OneBotBotManager.Factory);
        // 其他...
    }
);

// 后续可在此 Future 完成后注册监听器和 Bot
var applicationFuture = applicationAsync.asFuture();

final var application = Applications.launchApplicationBlocking(
    Simple.INSTANCE,
    configurer -> {
        // 安装OneBot组件相关内容
        configurer.install(OneBot11Component.Factory);
        configurer.install(OneBotBotManager.Factory);
        // 其他...
    }
);

// 继续注册监听器和 Bot，最后再等待应用结束

var applicationAsync = Applications.launchApplicationAsync(
        Simple.INSTANCE,
        configurer -> {
            // 安装OneBot组件相关内容
            configurer.install(OneBot11Component.Factory);
            configurer.install(OneBotBotManager.Factory);
            // 其他...
        }
);

// 后续可在响应式链中注册监听器和 Bot
var applicationMono = Mono.fromFuture(applicationAsync.asFuture());

在 Spring Boot 中，不需要你手动构建 Application。你只需要在你的启动类上标记 @EnableSimbot 来启用 simbot 即可。

OneBot 组件支持 SPI 自动加载，因此默认不需要手动安装 OneBot11Component 和 OneBotBotManager。

@EnableSimbot
@SpringBootApplication
open class BotApplication

fun main(vararg args: String) {
    runApplication<BotApplication>(*args)
}

@EnableSimbot
@SpringBootApplication
public class BotApplication {
    public static void main(String[] args) {
        SpringApplication.run(BotApplication.class, args);
    }
}

注册Bot

在 Application 构建完成后，即可从 Application.botManagers 中寻找你所需的管理器（比如OneBot的Bot管理器： OneBotBotManager）并注册你的Bot。

suspend fun main() {
    val app = launchSimpleApplication {
        useOneBot11()
        // ...
    }

    app.configure()
    app.join()
}

suspend fun Application.configure() {
    // 寻找、获得所需的BotManager
    val botManager = botManagers.firstOneBotBotManager()
    // 注册你所需的bot
    val bot = botManager.register(
        OneBotBotConfiguration().apply {
            // 这几个是必选属性
            /// 在OneBot组件中用于区分不同Bot的唯一ID， 建议可以直接使用QQ号。
            botUniqueId = "11112222"
            apiServerHost = Url("http://127.0.0.1:3001")
            eventServerHost = Url("ws://127.0.0.1:3001")
            // 其他配置, 一般都是可选属性
            /// token
            accessToken = null
            /// ...
        }
    )

    // 启动你的bot
    bot.start()
}

public static void main(String[] args) {
    final var applicationAsync = Applications.launchApplicationAsync(
        Simple.INSTANCE,
        configurer -> {
            // 安装OneBot组件相关内容
            configurer.install(OneBot11Component.Factory);
            configurer.install(OneBotBotManager.Factory);
            // 其他...
        }
    );

    applicationAsync
        .asFuture()
        // Application 转化为 Future
        .thenApply(app -> {
            // 配置
            configure(app);
            return app;
        })
        .thenCompose(Application::asFuture)
        // 阻塞这个Future直到Application被cancel
        .join();
}

public static void configure(Application application) {
    // 寻找所需的BotManager
    // 可以选择遍历寻找
    final var found = application.getBotManagers().stream()
        .filter(it -> it instanceof OneBotBotManager)
        .map(it -> (OneBotBotManager) it)
        .findFirst()
        .orElseThrow();

    // 也可以选择使用辅助API
    final var oneBotBotManager = OneBotBotManagerUsageKt
        .firstOneBotBotManager(application.getBotManagers());

    // 注册Bot
    /// 准备配置类
    final var botConfiguration = new OneBotBotConfiguration();
    // 这几个是必选属性
    /// 在OneBot组件中用于区分不同Bot的唯一ID， 建议可以直接使用QQ号。
    botConfiguration.setBotUniqueId("11112222");
    /// API 的服务地址。默认localhost:3001
    botConfiguration.setApiServerHost(URLUtilsKt.Url("http://localhost:3001"));
    /// 连接事件的服务地址。默认localhost:3001
    botConfiguration.setEventServerHost(URLUtilsKt.Url("ws://localhost:3001"));
    // 其他配置, 一般都是可选属性
    /// token
    botConfiguration.accessToken(null);
    // 或
    botConfiguration.setApiAccessToken(null);
    botConfiguration.setEventAccessToken(null);
    /// ...

    // 注册
    final var bot = oneBotBotManager.register(botConfiguration);
    // 启动
    final var future = bot.startAsync().whenComplete((r, ex) -> {
        // 在使用 Future 的时候，记得处理异常
        if (ex != null) {
            Logger.getGlobal().log(
                Level.SEVERE,
                "bot启动出现异常！",
                ex
            );
        }
    });
    // 你可以选择处理等待这个future，也可以选择不管他，直接在异步中处理。
}

public static void main(String[] args) {
    final var application = Applications.launchApplicationBlocking(
            Simple.INSTANCE,
            configurer -> {
                // 安装OneBot组件相关内容
                configurer.install(OneBot11Component.Factory);
                configurer.install(OneBotBotManager.Factory);
                // 其他...
            }
    );

    configure(application);
    application.joinBlocking();
}

public static void configure(Application application) {
    // 寻找所需的BotManager
    // 可以选择遍历寻找
    final var found = application.getBotManagers().stream()
            .filter(it -> it instanceof OneBotBotManager)
            .map(it -> (OneBotBotManager) it)
            .findFirst()
            .orElseThrow();

    // 也可以选择使用辅助API
    final var oneBotBotManager = OneBotBotManagerUsageKt
        .firstOneBotBotManager(application.getBotManagers());

    // 注册Bot
    /// 准备配置类
    final var botConfiguration = new OneBotBotConfiguration();
    // 这几个是必选属性
    /// 在OneBot组件中用于区分不同Bot的唯一ID， 建议可以直接使用QQ号。
    botConfiguration.setBotUniqueId("11112222");
    /// API 的服务地址。默认localhost:3001
    botConfiguration.setApiServerHost(URLUtilsKt.Url("http://localhost:3001"));
    /// 连接事件的服务地址。默认localhost:3001
    botConfiguration.setEventServerHost(URLUtilsKt.Url("ws://localhost:3001"));
    // 其他配置, 一般都是可选属性
    /// token
    botConfiguration.accessToken(null);
    // 或
    botConfiguration.setApiAccessToken(null);
    botConfiguration.setEventAccessToken(null);
    /// ...

    // 注册
    final var bot = oneBotBotManager.register(botConfiguration);
    // 启动
    bot.startBlocking();
}

public static void main(String[] args) {
    var applicationAsync = Applications.launchApplicationAsync(
        Simple.INSTANCE,
        configurer -> {
            // 安装OneBot组件相关内容
            configurer.install(OneBot11Component.Factory);
            configurer.install(OneBotBotManager.Factory);
            // 其他...
        }
    );

    // 例如：转化为 reactor.core.publisher.Mono;
    var mono = Mono.fromFuture(applicationAsync.asFuture())
        // 配置 Application
        .doOnNext(CoreMain::configure)
        .flatMap(app ->
            Mono.from(app.joinReactive())
        );

    // 使用这个响应式类型，例如阻塞它。
    /// 阻塞直到被cancel
    mono.block();
}

public static void configure(Application application) {
    // 寻找所需的BotManager
    // 可以选择遍历寻找
    final var found = application.getBotManagers().stream()
        .filter(it -> it instanceof OneBotBotManager)
        .map(it -> (OneBotBotManager) it)
        .findFirst()
        .orElseThrow();

    // 也可以选择使用辅助API
    final var oneBotBotManager = OneBotBotManagerUsageKt
        .firstOneBotBotManager(application.getBotManagers());

    // 注册Bot
    /// 准备配置类
    final var botConfiguration = new OneBotBotConfiguration();
    // 这几个是必选属性
    /// 在OneBot组件中用于区分不同Bot的唯一ID， 建议可以直接使用QQ号。
    botConfiguration.setBotUniqueId("11112222");
    /// API 的服务地址。默认localhost:3001
    botConfiguration.setApiServerHost(URLUtilsKt.Url("http://localhost:3001"));
    /// 连接事件的服务地址。默认localhost:3001
    botConfiguration.setEventServerHost(URLUtilsKt.Url("ws://localhost:3001"));
    // 其他配置, 一般都是可选属性
    /// token
    botConfiguration.accessToken(null);
    // 或
    botConfiguration.setApiAccessToken(null);
    botConfiguration.setEventAccessToken(null);
    /// ...

    // 注册
    final var bot = oneBotBotManager.register(botConfiguration);
    // 启动
    Mono.from(bot.startReactive())
        // 在使用响应式编程的时候，记得处理异常
        .doOnError(ex -> {
            Logger.getGlobal().log(
                Level.SEVERE,
                "bot启动出现异常！",
                ex
            );
        })
        // 也可以返回 Mono 继续处理
        // 这里直接让它在异步中运行。
        .subscribe();
}

在 Spring 中，通常可以选择使用 .bot.json 格式的配置文件来快速、自动地批量注册bot。

默认情况下，在你的项目的资源目录 resource 中创建目录 /simbot-bots/，再参考 Bot 配置并配置 JSON 格式的配置文件，例如 abc.bot.json。

默认情况下starter会自动扫描上述资源目录并加载、自动启动它们，这一切是在异步中进行的。

事件监听

从 Application 中获取 EventDispatcher 即可注册事件监听函数。

Kotlin 中，可以使用 Application.listeners {} 扩展函数。

// 省略构建Application相关内容...

suspend fun Application.configure() {
    // bot相关内容省略....

    // Kotlin 中，可以使用 Application.listeners 扩展函数。
    listeners {
        // 使用 listen 监听一个事件
        // 此处是一个标准库中通用的类型：聊天群消息事件
        listen<ChatGroupMessageEvent> { event ->
            println("Event: $event")
            if (event.messageContent.plainText?.trim() == "你好") {
                event.reply("你也好")
            }

            // 使用listen时必须返回一个EventResult类型的结果
            EventResult.empty()
        }

        // 使用 process 监听一个事件
        // 此处监听的是OneBot组件中的专属类型：OneBot的好友消息事件
        process<OneBotFriendMessageEvent> { event ->
            println("Event: $event")
            if (event.messageContent.plainText?.trim() == "你好") {
                event.reply("你也好")
            }

            // 使用 process 不需要返回 EventResult，默认视为返回 EventResult.empty()
        }
    }
}

// 省略构建Application相关内容...

public static void configure(Application application) {
    // bot相关内容省略....

    final var eventDispatcher = application.getEventDispatcher();

    // 监听一个OneBot组件中的专属类型：OneBot的好友消息事件
    eventDispatcher.register(
        EventListeners.async(
            OneBotFriendMessageEvent.class,
            (context, event) -> {
                System.out.println("Event: " + event);
                if ("你好".equals(event.getMessageContent().getPlainText())) {
                    // 返回一个异步的EventResult类型的结果
                    return event.replyAsync("你也好")
                        .thenApply(result -> EventResult.empty());
                }

                // 返回一个异步的EventResult类型的结果
                return CompletableFuture.completedFuture(EventResult.empty());
            }
        )
    );
}

// 省略构建Application相关内容...

public static void configure(Application application) {
    // bot相关内容省略....

    final var eventDispatcher = application.getEventDispatcher();

    // 监听一个OneBot组件中的专属类型：OneBot的好友消息事件
    eventDispatcher.register(
        EventListeners.block(
            OneBotFriendMessageEvent.class,
            (context, event) -> {
                System.out.println("Event: " + event);
                if ("你好".equals(event.getMessageContent().getPlainText())) {
                    event.replyBlocking("你也好");
                }

                // 返回一个EventResult类型的结果
                return EventResult.empty();
            }
        )
    );
}

// 省略构建Application相关内容...

public static void configure(Application application) {
    // bot相关内容省略....

    final var eventDispatcher = application.getEventDispatcher();

    // 监听一个OneBot组件中的专属类型：OneBot的好友消息事件
    eventDispatcher.register(
        EventListeners.async(
            OneBotFriendMessageEvent.class,
            (context, event) -> {
                System.out.println("Event: " + event);
                if ("你好".equals(event.getMessageContent().getPlainText())) {
                    return Mono.from(event.replyReactive("你也好"))
                        .thenReturn(EventResult.empty())
                        // 返回一个异步的EventResult类型的结果
                        .toFuture();
                }

                // 返回一个异步的EventResult类型的结果
                return Mono.just(
                    EventResult.empty()
                ).toFuture();
            }
        )
    );
}

在 Spring 中，使用注解 @Listener 注册一个监听函数。可监听到的事件即为参数中的事件类型。因此，方法参数里的事件类型最多只能有 1 个。

@Component
class MyHandles {
    /**
     * 此处是一个标准库中通用的类型：聊天群消息事件
     */
    @Listener
    suspend fun onGroupMessage(event: ChatGroupMessageEvent) {
        println("ChatGroupMessageEvent: $event")
    }

    /**
     * 此处监听的是OneBot组件中的专属类型：OneBot的好友消息事件
     * 并且过滤消息：消息中的文本消息去除前后空字符后，等于 '你好'
     */
    @Listener
    @ContentTrim
    @Filter("你好")
    suspend fun onFriendMessage(event: OneBotFriendMessageEvent) {
        println("OneBotFriendMessageEvent: $event")
        // 回复消息
        event.reply("你也好")
    }
}

@Component
public class MyHandles {
    /**
     * 此处是一个标准库中通用的类型：聊天群消息事件
     */
    @Listener
    public void onGroupMessage(ChatGroupMessageEvent event) {
        System.out.println("ChatGroupMessageEvent: " + event);
    }

    /**
     * 此处监听的是OneBot组件中的专属类型：OneBot的好友消息事件
     * 并且过滤消息：消息中的文本消息去除前后空字符后，等于 '你好'
     */
    @Listener
    @ContentTrim
    @Filter("你好")
    public CompletableFuture<?> onFriendMessage(OneBotFriendMessageEvent event) {
        System.out.println("OneBotFriendMessageEvent: " + event);
        return event.replyAsync("你也好");
        // 可以直接返回任意 CompletableFuture 类型
    }
}

@Component
public class MyHandles {
    /**
     * 此处是一个标准库中通用的类型：聊天群消息事件
     */
    @Listener
    public void onGroupMessage(ChatGroupMessageEvent event) {
        System.out.println("ChatGroupMessageEvent: " + event);
    }

    /**
     * 此处监听的是OneBot组件中的专属类型：OneBot的好友消息事件
     * 并且过滤消息：消息中的文本消息去除前后空字符后，等于 '你好'
     */
    @Listener
    @ContentTrim
    @Filter("你好")
    public void onFriendMessage(OneBotFriendMessageEvent event) {
        System.out.println("OneBotFriendMessageEvent: " + event);
        event.replyBlocking("你也好");
    }
}

@Component
public class MyHandles {
    /**
     * 此处是一个标准库中通用的类型：聊天群消息事件
     */
    @Listener
    public void onGroupMessage(ChatGroupMessageEvent event) {
        System.out.println("ChatGroupMessageEvent: " + event);
    }

    /**
     * 此处监听的是OneBot组件中的专属类型：OneBot的好友消息事件
     * 并且过滤消息：消息中的文本消息去除前后空字符后，等于 '你好'
     */
    @Listener
    @ContentTrim
    @Filter("你好")
    public Mono<?> onFriendMessage(OneBotFriendMessageEvent event) {
        System.out.println("OneBotFriendMessageEvent: " + event);
        return Mono.from(event.replyReactive("你也好"));
        // 可以直接返回任意(kotlinx.coroutines支持的)响应式类型，
        // 不过需要注意，确保运行时环境中有对应的依赖，
        // 以Mono为例，需要添加 [[[kotlinx-coroutines-reactor|https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive]]]
    }
}

07 November 2026