使用ts实现的oneBot应用启动器，支持icqq、qq官方机器人、微信以及钉钉机器人
[](https://github.com/icqqjs/onebots/actions/workflows/release.yml)
[](https://github.com/lc-cn/onebots/actions/workflows/build_deploy_docs.yml)
[](https://www.npmjs.com/package/onebots)
[](https://www.npmjs.com/package/onebots)
[](https://onebot.dev/)
[](https://12.onebot.dev/) [](https://nodejs.org)
[](https://jq.qq.com/?_wv=1027&k=B22VGXov)
[Docs](https://docs.onebots.org)
使用示例
全局安装(0.4.8以后不推荐)
1 安装依赖
- 注意：
npm install -g onebots
2 初始化配置文件
在你想存放配置文件的目录执行如下命令
onebots
3 更改生成的默认配置文件成你想要的配置配置后再次运行上面的指令，启动项目
局部安装
1 初始化node项目
npm init -y
2. 安装onebots以及对应适配器的依赖
npm install onebots
npm install @icqqjs/icqq # 如需使用icqq适配器，请务必安装
npm install web-wechat # 如需使用微信适配器，请务必安装
npm install qq-official-bot # 如需使用qq官方机器人适配器，请务必安装
npm install node-dd-bot # 如需使用钉钉机器人适配器，请务必安装
安装:
- 在你的项目根目录新建文件
.npmrc ,并录入以下内容
@icqqjs:registry=https://npm.pkg.github.com
- 命令行输入
npm login --scope=@icqqjs --auth-type=legacy --registry=https://npm.pkg.github.com ，回车，根据提示登录github
npm login --scope=@icqqjs --auth-type=legacy --registry=https://npm.pkg.github.com
UserName: # 你的github账号
Password: # 前往 https://github.com/settings/tokens/new 获取，scopes勾选 read:packages
E-Mail: # 你的公开邮箱地址
3. 安装依赖
```shell
npm install @icqqjs/icqq # or > yarn add @icqqjs/icqq
3. 执行如下命令生成配置文件
npx onebots -r icqq #注册icqq适配器并启动onebots
npx onebots -r wechat #注册微信适配器并启动onebots
npx onebots -r qq #注册qq官方适配器并启动onebots
npx onebots -r dingtalk #注册钉钉适配器并启动onebots
# 你也可以同时注册多个适配器，多次使用-r即可，例如 npx onebots -r qq -r icqq -r wechat
4. 更改生成的默认配置文件成你想要的配置配置后再次运行上面的指令，启动项目
默认配置文件
port: 6727 # 监听端口
log_level: info # 日志等级
platform: 5 # 机器人客户端协议（1:Android 2:APad 3:Watch 4:IMac 5:IPad）
timeout: 30 #登录超时时间(秒)
general: # 通用配置，在单个配置省略时的默认值
V11: # oneBotV11的通用配置
heartbeat: 3 # 心跳间隔 (秒)
access_token: "" # 访问api的token
post_timeout: 15 # 上报超时时间，(秒)
secret: "" # 上报数据的sha1签名密钥
rate_limit_interval: 4 # ws心跳间隔(秒)
post_message_format: string # "string"或"array"
reconnect_interval: 3 # 重连间隔 (秒)
use_http: true # 是否使用 http
enable_cors: true # 是否允许跨域
filters: {} # 过滤器配置
use_ws: true # 是否使用websocket
http_reverse: [] # http上报地址
ws_reverse: [] # 反向ws连接地址
V12: # oneBotV12的通用配置
heartbeat: 3 # 心跳间隔 (秒)
access_token: "" # 访问api的token
request_timeout: 15 # 上报超时时间 (秒)
reconnect_interval: 3 # 重连间隔 (秒)
enable_cors: true # 是否允许跨域
use_http: true # 是否启用http
use_ws: true # 是否启用 websocket
filters: {} # 过滤器配置
webhook: [] # http 上报地址
ws_reverse: [] # 反向ws连接地址
protocol:
platform: 2
sign_api_addr: "" #你的签名地址
password: "" # 账号密码，未配置则扫码登陆
# ...其他配置项参考icqq的Config配置
# 每个账号的单独配置(用于覆盖通用配置)
icqq.123456789:
password: "" # 账号密码，未配置则扫码登陆
version: V11 # 使用的oneBot版本
# ...其他配置项参见上方对应oneBot版本的通用配置
protocol:
platform: 2
sign_api_addr: "" #你的签名地址
# ...其他配置项参考icqq的Config配置
qq.123456789: # `${适配器名称}:${appId}`
versions:
- version: V11
# 。。。其他配置项参见上方对应oneBot版本的通用配置
protocol: # 将会覆盖通用配置中的protocol
token: '' # qq机器人token
secret: '' # qq机器人secret
sandbox: false # 是否沙箱环境
intents: # 需要监听的intents
- 'GROUP_AT_MESSAGE_CREATE' # 群聊@事件 没有群聊权限请注释
- 'C2C_MESSAGE_CREATE' # 私聊事件 没有私聊权限请注释
- 'DIRECT_MESSAGE' # 频道私信事件
# - 'GUILD_MESSAGES' # 私域机器人频道消息事件，公域机器人请注释
- 'GUILDS' # 频道变更事件
- 'GUILD_MEMBERS' # 频道成员变更事件
- 'GUILD_MESSAGE_REACTIONS' # 频道消息表态事件
- 'INTERACTION' # 互动事件
- 'PUBLIC_GUILD_MESSAGES' # 公域机器人频道消息事件，私域机器人请注释
# 。。。其他配置项参见上方对应oneBot版本的通用配置
dingtalk.abcedfg: # `${适配器名称}:${clientId}`
versions:
- version: V11
- version: V12
protocol:
clientSecret: '' # 钉钉机器人秘钥 必填
username: '钉钉机器人' #钉钉后台配置的机器人名称 不填则显示'钉钉机器人'
avatar: '' # 机器人头像 不填则显示钉钉logo
wechat.bot1: # `${适配器名称}:${机器人唯一标识}`
versions:
- version: V11
- version: V12
protocol: {}
配置解释
Config
| 配置项 |
类型 |
默认值 |
desc |
| port |
number |
6727 |
服务监听端口 |
| logLevel |
string |
info |
日志级别 |
| general |
{V11:V11.Config,V12:V12.Config} |
general |
通用配置 |
| [adapter].[number] |
OneBotConfig |
- |
机器人配置 |
OneBotConfig
| 配置项 |
类型 |
默认值 |
desc |
| password |
string |
- |
仅icqq生效，账号密码 未填写或填写为空则扫码登陆 |
| V11 |
V11.Config |
configV11 |
V11配置 |
| V12 |
V12.Config |
configV12 |
V12配置 |
| protocol |
传递给client初始化的配置 |
{} |
|
ConfigV11
| 配置项 |
类型 |
默认值 |
desc |
| heartbeat |
number |
3 |
心跳间隔 单位：秒 |
| access_token |
string |
- |
访问令牌 |
| secret |
string |
- |
签名密钥 |
| rate_limit_interval |
number |
4 |
限速间隔 单位：秒 |
| post_message_format |
string |
string |
消息格式化 |
| reconnect_interval |
number |
3 |
重连间隔 单位：秒 |
| use_http |
boolean |
false |
是否使用http协议 |
| enable_cors |
boolean |
false |
是否允许跨域 |
| filters |
Filters |
{} |
事件过滤器配置 |
| use_ws |
boolean |
false |
是否使用ws协议 |
| http_reverse_url |
string[] |
- |
http上报地址地址 |
| ws_reverse_url |
string[] |
- |
反向ws连接地址 |
ConfigV12
| 配置项 |
类型 |
默认值 |
desc |
| heartbeat |
number |
3 |
心跳间隔 单位：秒 |
| access_token |
string |
- |
访问令牌 |
| request_timeout |
number |
15 |
请求超时 单位：秒 |
| reconnect_interval |
number |
3 |
重连间隔 单位：秒 |
| enable_cors |
boolean |
false |
是否允许跨域 |
| filters |
Filters |
{} |
事件过滤器配置 |
| use_http |
boolean |
false |
是否使用http协议 |
| use_ws |
boolean |
false |
是否使用ws协议 |
| webhook_reverse_url |
string[] |
- |
webhook上报地址 |
| ws_reverse_url |
string[] |
- |
反向ws连接地址 |
事件过滤器
语法说明
onebots 的事件过滤器最外层是一个JSON对象，其中的键是键如果是运算法，则值作为运算符的参数，如果不是运算符，则表示对事件数据对象相应 key 进行过滤。- 过滤规则中任何一个对象, 只有在它的所有项都匹配的情况下, 才会让事件通过（等价于一个 and 运算），如果值为一个数组，则表示事件对应
key 值需满足其中一个。
- 可用逻辑运算符有：
$and (逻辑与) 、$or (逻辑或) 、 $not (逻辑非)、$nor (逻辑异或)、$regexp (文本正则匹配)、$like (文本模糊匹配)、$gt (数值大于比较)、$gte (数值大于等于比较)、$lt (数值小于比较)、$lte (数值小于等于比较)、$between (数值范围比较)
示例
1. 仅上报私聊事件
filters:
message_type: private
2. 私聊或指定群聊
filters:
$or:
message_type: private
group_id:
- 123456789 987654321
3. 私聊事件且不是指定用户
filters:
message_type: private
$not:
user_id:
- 123456789 987654321
4. 私聊事件(排除指定用户的事件)或指定群聊事件
filters:
$or:
- message_type: private
$not:
user_id: 123456789
- message_type: group
group_id: 987654321
5. 仅上报消息事件且用户年龄大于18岁
filters:
type: message
sender:
age:
$gt: 18
6. 仅上报消息事件且消息内容以！开头的消息
filters:
type: message
raw_message:
.regexp: '^！|\!'
7. 不上报消息内容包含cnm的消息
filters:
$not:
type: message
raw_message:
$like: cnm
使用API管理oneBot
| url |
method |
params |
desc |
| /list |
GET |
|
获取当前运行的机器人列表 |
| /detail |
GET |
uin |
获取指定机器人配置 |
| /qrcode |
GET |
uin |
获取指定机器人登录二维码 |
| /add |
POST |
{uin,...config} |
添加机器人 config 为机器人配置 |
| /edit |
POST |
{uin,...config} |
修改机器人配置 config 为机器人配置 |
| /remove |
get |
uin,force |
移除机器人,force为true时，将删除机器人data目录 |
鸣谢
- icqqjs/icqq 底层服务支持
- takayama-lily/onebot oneBot V11 原先版本