文档同步

本页由 plugins/adapters/onebot11/README.md 自动生成。请修改包内 README 后运行 pnpm sync:adapter-docs。

@zhin.js/adapter-onebot11

Zhin.js OneBot v11 协议适配器，通过 WebSocket 连接各种支持 OneBot 协议的 QQ 机器人实现（如 go-cqhttp、Shamrock、LagrangeGo 等）。

功能特性

• 🔌 完整 OneBot v11 协议兼容
• 📦 单一适配器：context: onebot11，通过 connection 选择连接方式
• 🌐 正向 WebSocket（connection: ws）：应用连 OneBot 实现的 WS
• 🔄 反向 WebSocket（connection: wss）：应用开 WS 服务端，实现连上来
• 🔐 Access Token 认证支持
• 🔄 自动重连机制
• 💓 心跳检测
• 📨 群聊和私聊消息处理
• 🛠️ 完整的 API 调用支持
• 📝 消息段（Message Segment）完整支持

安装

pnpm add @zhin.js/adapter-onebot11 ws

反向 WS 需同时启用 @zhin.js/host-router。

前置条件

要求	说明
OneBot 实现	已运行 go-cqhttp、Lagrange、Shamrock 等，并开启 WS 服务
正向 WS（connection: ws）	配置 OneBot 实现的 WS 地址；应用主动连接
反向 WS（connection: wss）	需 @zhin.js/host-router；OneBot 实现连到本 Bot 的 path
access_token	可选；须与 OneBot 实现侧配置一致

必填字段见 OneBot11BotConfig：context、name、connection；ws 需 url，wss 需 path。

最小配置

正向 WebSocket（本地开发推荐）：

plugins:
  - "@zhin.js/adapter-onebot11"

bots:
  - context: onebot11
    connection: ws
    name: my-bot
    url: "ws://127.0.0.1:6700"
    access_token: "${ONEBOT11_ACCESS_TOKEN}"

配置

所有 Bot 使用 同一 context：onebot11，通过 connection 区分连接方式。

正向 WebSocket（connection: ws）

plugins:
  - "@zhin.js/adapter-onebot11"

bots:
  - context: onebot11
    connection: ws
    name: my-bot
    url: "ws://localhost:8080"
    access_token: "${ONEBOT_TOKEN}"
    reconnect_interval: 5000
    heartbeat_interval: 30000

反向 WebSocket（connection: wss）

plugins:
  - "@zhin.js/host-router"
  - "@zhin.js/adapter-onebot11"

bots:
  - context: onebot11
    connection: wss
    name: my-bot
    path: "/onebot/ws"
    access_token: "${ONEBOT_TOKEN}"
    heartbeat_interval: 30000

兼容旧配置：若使用 type: 'ws' / type: 'ws_reverse' 而未写 connection，适配器会自动映射为 ws / wss。

支持的 OneBot 实现

推荐实现

实现	协议支持	稳定性	推荐度
go-cqhttp	✅ 完整	⭐⭐⭐⭐⭐	高
LagrangeGo	✅ 完整	⭐⭐⭐⭐	高
Shamrock	✅ 完整	⭐⭐⭐⭐	中
NapCat	✅ 完整	⭐⭐⭐⭐	中

配置示例

go-cqhttp

# config.yml
servers:
  - ws:
      host: 0.0.0.0
      port: 8080
      access-token: "your_token_here"

Shamrock

在 Shamrock 设置中：

1. 启用 WebSocket 服务
2. 设置端口（默认 5800）
3. 配置 Access Token（可选）

使用示例

基础消息处理

import { addCommand, MessageCommand } from 'zhin.js'

addCommand(new MessageCommand('hello <name:text>')
  .action(async (message, result) => {
    return `你好，${result.params.name}！`
  })
)

群聊消息

import { onGroupMessage } from 'zhin.js'

onGroupMessage(async (message) => {
  console.log(`群 ${message.$channel.id} 收到消息`)
  await message.$reply('收到了！')
})

私聊消息

import { onPrivateMessage } from 'zhin.js'

onPrivateMessage(async (message) => {
  await message.$reply('你好！')
})

发送图片

addCommand(new MessageCommand('pic <url:text>')
  .action(async (message, result) => {
    return [
      { type: 'image', data: { file: result.params.url } }
    ]
  })
)

使用 CQ 码

addCommand(new MessageCommand('cq')
  .action(async (message) => {
    return [
      { type: 'face', data: { id: '123' } },
      { type: 'text', data: { text: '表情' } }
    ]
  })
)

消息类型支持

接收消息类型

• ✅ 文本消息（text）
• ✅ 图片消息（image）
• ✅ 语音消息（record）
• ✅ 视频消息（video）
• ✅ @ 提及（at）
• ✅ 表情（face）
• ✅ 引用回复（reply）
• ✅ 戳一戳（poke）
• ✅ 分享（share）
• ✅ 位置（location）
• ✅ 音乐分享（music）
• ✅ JSON 卡片（json）
• ✅ XML 卡片（xml）

发送消息类型

• ✅ 文本消息
• ✅ 图片消息（支持 URL、Base64、本地文件）
• ✅ 语音消息
• ✅ 视频消息
• ✅ @ 提及
• ✅ 表情
• ✅ 引用回复
• ✅ 戳一戳
• ✅ 分享卡片
• ✅ 音乐分享
• ✅ JSON/XML 卡片

API 方法

消息相关

const bot = app.adapters.get('onebot11')?.bots.get('my-bot')

// 发送群消息
await bot.callApi('send_group_msg', {
  group_id: 123456,
  message: '消息内容'
})

// 发送私聊消息
await bot.callApi('send_private_msg', {
  user_id: 123456,
  message: '消息内容'
})

// 撤回消息
await bot.callApi('delete_msg', {
  message_id: 123456
})

信息获取

// 获取登录信息
const loginInfo = await bot.callApi('get_login_info')

// 获取用户信息
const userInfo = await bot.callApi('get_stranger_info', {
  user_id: 123456
})

// 获取群信息
const groupInfo = await bot.callApi('get_group_info', {
  group_id: 123456
})

// 获取群成员列表
const memberList = await bot.callApi('get_group_member_list', {
  group_id: 123456
})

群管理

// 踢出群成员
await bot.callApi('set_group_kick', {
  group_id: 123456,
  user_id: 654321
})

// 禁言群成员
await bot.callApi('set_group_ban', {
  group_id: 123456,
  user_id: 654321,
  duration: 600 // 秒
})

// 设置群名片
await bot.callApi('set_group_card', {
  group_id: 123456,
  user_id: 654321,
  card: '新名片'
})

连接模式对比

正向 WebSocket（客户端模式）

优点：

• ✅ 配置简单
• ✅ 主动连接，无需开放端口
• ✅ 适合本地开发

缺点：

• ❌ 需要 OneBot 实现提供 WebSocket 服务

反向 WebSocket（服务器模式）

优点：

• ✅ OneBot 实现主动连接
• ✅ 支持多个客户端连接
• ✅ 适合生产环境

缺点：

• ❌ 需要开放端口或使用内网穿透
• ❌ 配置相对复杂

消息 ID 格式

OneBot11 适配器的消息 ID 格式：{message_id}

撤回消息时直接使用数字 ID。

注意事项

Access Token

建议配置 Access Token 增强安全性：

{
  access_token: process.env.ONEBOT_TOKEN
}

OneBot 实现需要配置相同的 Token。

重连机制

适配器会自动重连，可配置重连间隔：

{
  reconnect_interval: 5000  // 5秒后重连
}

心跳检测

心跳机制确保连接活跃：

{
  heartbeat_interval: 30000  // 30秒发送一次心跳
}

API 超时

API 调用默认 30 秒超时，可在代码中调整。

故障排查

连接不上 OneBot 服务

1. OneBot 服务是否已启动
2. WebSocket 地址（url）或反向路径（path）是否正确
3. access_token 是否与实现侧一致
4. 防火墙是否阻止连接

消息发送失败

1. QQ 未登录或登录失效
2. 账号风控限制
3. 群/好友不存在
4. 消息段格式错误

反向 WS 无法连接

1. @zhin.js/host-router 已启用且 HTTP 服务正常
2. path 与 OneBot 实现配置的反向 WS 地址一致
3. 端口已从公网或内网可达

CQ 码与消息段

适配器自动处理 CQ 码转换；发送时使用消息段格式即可：

[
  { type: 'text', data: { text: '文本' } },
  { type: 'image', data: { file: 'url' } }
]

文档链接

• OneBot v11 适配器文档
• 适配器概览
• OneBot 11 标准

相关链接

• OneBot 标准
• go-cqhttp
• LagrangeGo
• Shamrock

依赖项

• ws - WebSocket 客户端/服务器库
• zhin.js - Zhin 核心框架

开发

pnpm build  # 构建
pnpm clean  # 清理构建文件

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！