Zhin.js adapter for OneBot v11 protocol
npm install @zhin.js/adapter-onebot11Zhin.js OneBot v11 协议适配器,通过 WebSocket 连接各种支持 OneBot 协议的 QQ 机器人实现(如 go-cqhttp、Shamrock、LagrangeGo 等)。
- 🔌 完整 OneBot v11 协议兼容
- 🌐 WebSocket 客户端和服务器模式
- 🔐 Access Token 认证支持
- 🔄 自动重连机制
- 💓 心跳检测
- 📨 群聊和私聊消息处理
- 🛠️ 完整的 API 调用支持
- 📝 消息段(Message Segment)完整支持
``bash`
pnpm add @zhin.js/adapter-onebot11 ws
`typescript
// zhin.config.ts
import { defineConfig } from 'zhin.js'
export default defineConfig({
bots: [
{
context: 'onebot11',
type: 'ws', // WebSocket 客户端
name: 'my-bot',
url: 'ws://localhost:8080', // OneBot 服务地址
access_token: process.env.ONEBOT_TOKEN, // 访问令牌(可选)
reconnect_interval: 5000, // 重连间隔(毫秒)
heartbeat_interval: 30000 // 心跳间隔(毫秒)
}
],
plugins: [
'adapter-onebot11'
]
})
`
`typescript`
export default defineConfig({
bots: [
{
context: 'onebot11.wss', // WebSocket 服务器
type: 'ws_reverse',
name: 'my-bot',
path: '/onebot/ws', // WebSocket 路径
access_token: process.env.ONEBOT_TOKEN, // 访问令牌(可选)
heartbeat_interval: 30000
}
],
plugins: [
'http', // 需要 HTTP 服务
'adapter-onebot11'
]
})
| 实现 | 协议支持 | 稳定性 | 推荐度 |
|------|---------|--------|--------|
| go-cqhttp | ✅ 完整 | ⭐⭐⭐⭐⭐ | 高 |
| LagrangeGo | ✅ 完整 | ⭐⭐⭐⭐ | 高 |
| Shamrock | ✅ 完整 | ⭐⭐⭐⭐ | 中 |
| NapCat | ✅ 完整 | ⭐⭐⭐⭐ | 中 |
#### go-cqhttp
`yaml`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(可选)
`typescript
import { addCommand, MessageCommand } from 'zhin.js'
addCommand(new MessageCommand('hello
.action(async (message, result) => {
return 你好,${result.params.name}!`
})
)
`typescript
import { onGroupMessage } from 'zhin.js'
onGroupMessage(async (message) => {
console.log(群 ${message.$channel.id} 收到消息)`
await message.$reply('收到了!')
})
`typescript
import { onPrivateMessage } from 'zhin.js'
onPrivateMessage(async (message) => {
await message.$reply('你好!')
})
`
`typescript`
addCommand(new MessageCommand('pic
.action(async (message, result) => {
return [
{ type: 'image', data: { file: result.params.url } }
]
})
)
`typescript`
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 卡片
`typescript
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
})
`
`typescript
// 获取登录信息
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
})
`
`typescript
// 踢出群成员
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: '新名片'
})
`
优点:
- ✅ 配置简单
- ✅ 主动连接,无需开放端口
- ✅ 适合本地开发
缺点:
- ❌ 需要 OneBot 实现提供 WebSocket 服务
优点:
- ✅ OneBot 实现主动连接
- ✅ 支持多个客户端连接
- ✅ 适合生产环境
缺点:
- ❌ 需要开放端口或使用内网穿透
- ❌ 配置相对复杂
OneBot11 适配器的消息 ID 格式:{message_id}
撤回消息时直接使用数字 ID。
建议配置 Access Token 增强安全性:
`typescript`
{
access_token: process.env.ONEBOT_TOKEN
}
OneBot 实现需要配置相同的 Token。
适配器会自动重连,可配置重连间隔:
`typescript`
{
reconnect_interval: 5000 // 5秒后重连
}
心跳机制确保连接活跃:
`typescript`
{
heartbeat_interval: 30000 // 30秒发送一次心跳
}
API 调用默认 30 秒超时,可在代码中调整。
A: 检查:
1. OneBot 服务是否启动
2. WebSocket 地址是否正确
3. Access Token 是否匹配
4. 防火墙是否阻止连接
A: 可能原因:
1. 未登录或登录失败
2. 被风控限制
3. 群/好友不存在
4. 消息格式错误
A: 确认:
1. HTTP 服务已启动
2. WebSocket 路径配置正确
3. OneBot 配置的反向 WS 地址正确
4. 端口已开放
A: OneBot11 适配器自动处理 CQ 码转换,使用消息段格式即可:
`typescript`
[
{ type: 'text', data: { text: '文本' } },
{ type: 'image', data: { file: 'url' } }
]
- OneBot 标准
- go-cqhttp
- LagrangeGo
- Shamrock
- Zhin.js 官方文档
- ws - WebSocket 客户端/服务器库zhin.js
- - Zhin 核心框架
`bash``
pnpm build # 构建
pnpm clean # 清理构建文件
MIT License
欢迎提交 Issue 和 Pull Request!