Skip to content

lc-cn/onebots

Repository files navigation

使用ts实现的oneBot应用启动器,支持icqq、qq官方机器人、微信以及钉钉机器人

Build Package Build Docs

npm dm oneBot V11 oneBot V12 node engine qq group

Docs

使用示例

全局安装(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 # 如需使用钉钉机器人适配器,请务必安装
  • 关于@icqqjs的安装引导:

安装:

  1. 在你的项目根目录新建文件 .npmrc ,并录入以下内容
@icqqjs:registry=https://npm.pkg.github.com
  1. 命令行输入 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: # 你的公开邮箱地址
  1. 安装依赖
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目录

鸣谢

  1. icqqjs/icqq 底层服务支持
  2. takayama-lily/onebot oneBot V11 原先版本