OneBot 协议

机器人支持对接任何支持 OneBot 协议（v11）open in new window的服务端，以支持更多的平台。连接方式支持 WebSocket 或反向 WebSocket。

Gensokyo 是一个可以将 QQ 官方机器人 API 映射到 OneBot 协议的服务端。下文以通过 Gensokyo 连接 QQ 频道机器人为例，展示一下 OneBot 协议的用法：

注意

OneBot 协议的配置和使用方式，对于不同的 OneBot 服务端都不尽相同。下文内容仅供参考，请根据实际情况进行测试。

通用 Gensokyo 配置

修改 Gensokyo 配置，填写 QQ 频道机器人的连接信息：

# 基础设置
app_id: 102095867        # 填写机器人 APPID
uin: 0
use_uin: false
token: "*******"         # 填写机器人令牌
client_secret: "*******" # 填写机器人密钥

# 事件订阅
# 由于我们的机器人都是私域，因此关闭 ATMessageEventHandler 事件，打开 CreateMessageHandler 事件
text_intent:
  # - "ATMessageEventHandler"
  - "DirectMessageHandler"
  # - "ReadyHandler"
  # - "ErrorNotifyHandler"
  # - "GuildEventHandler"
  # - "MemberEventHandler"
  # - "ChannelEventHandler"
  - "CreateMessageHandler"
  # - "InteractionHandler"
  # - "GroupATMessageEventHandler"
  # - "C2CMessageEventHandler"
  # - "ThreadEventHandler"

...

# 开发增强类
sandbox_mode: true # 是否使用沙箱模式，根据需求自己决定

连接设置

可选 WebSocket 或反向 WebSocket 连接。两种连接方式所需配置不同。

1. WebSocket

修改 Gensokyo 配置，填写【正向 ws 设置】部分：

# 正向ws设置
ws_server_path: "ws"
enable_ws_server: true
ws_server_token: "12345"

将 enable_ws_server 设为 true 以开启 WebSocket 服务。ws_server_path 和 ws_server_token 可按自己需要填写，或保持默认。

启动 Gensokyo，看到以下日志代表 WebSocket 服务器启动成功：

正向ws启动成功,监听0.0.0.0:15630/ws请注意设置ws_server_token(可空),并对外放通端口...

启动跑团机器人，在登录页面选择 OneBot，连接方式选择 WebSocket，并填写对应信息：

其中【机器人 ID】代表 OneBot 协议的 X-Self-ID 字段。在 Gensokyo 中，对应的是基础设置里的 app_id。

【服务端地址】中的端口号和路径，即 15630/ws 部分，对应的是上文 Gensokyo 的日志输出。

【Token】代表配置文件中的 ws_server_token。

2. 反向 WebSocket

反向 WebSocket 会把跑团机器人作为 OneBot 连接的服务端，因此需要先启动跑团机器人。

在登录页面选择 OneBot，连接方式选择 反向 WebSocket，并填写对应信息：

其中【机器人 ID】代表 OneBot 协议的 X-Self-ID 字段。在 Gensokyo 中，对应的是基础设置里的 app_id。

【监听路径】和【端口号】按自己需要填写，通常保持默认即可。

点击【连接！】按钮。在命令行中看到以下日志代表 WebSocket 服务器启动成功：

[I] server server listening at http://127.0.0.1:4176

修改 Gensokyo 配置，填写【反向 ws 设置】部分：

#反向ws设置
ws_address: ["ws://127.0.0.1:4176/onebot"]

其中端口号和路径来自于你之前填写的【监听路径】和【端口号】。（如果存在端口冲突情况，实际日志打印出的端口号可能会与填写的不同，此时以日志中的为准）

启动 Gensokyo，看到以下日志，代表已经成功和跑团机器人建立了连接：

Successfully connected to ws://127.0.0.1:4176/onebot

选择子频道，开始使用

点击登录后，会卡在选择子频道的界面。这是因为当前的协议不能准确地表达频道，而不同场景下对此问题的处理方式不同，可能会造成功能异常。保险起见，我们暂时屏蔽了主动获取频道信息的功能。

所幸这一功能缺失并不阻塞我们的使用。可以按照图中的提示，在频道里发一条消息，就可以看到对应的频道出现。选择该频道后，即可像正常一样开始使用了。

再次提醒，这里使用 Gensokyo 连接 QQ 频道仅仅是为了举个例子。实际使用中，基于不同的 OneBot 服务端，使用方法也会存在很多区别。也欢迎大家分享自己的使用经验~

# OneBot 协议

# 通用 Gensokyo 配置

# 连接设置

# 1. WebSocket