跳到主要内容
版本：3.2.0.0

Bot配置文件

有关bot的配置文件相关内容，请先阅读 BOT配置 。

架构​

mirai组件为其下的BOT配置文件提供了 json-schema 。

架构资源​

你可以通过 此处 下载 bot.config.json 架构文件， 或者使用远程资源路径：

https://component-mirai.simbot.forte.love/schema/bot/0.3.0/bot.config.json

如何使用​

以 IntelliJ IDEA 为例， 对一个 JSON 文件使用JSON架构可以参考其 官方文档。

提示

JSON架构 的约束适用于 JSON、YAML 文件。

配置​

捉迷藏

在 Spring Boot Starter 中，bot配置文件的默认放置路径为 simbot-bots/*.bot.json

明文密码​

my-bot.bot.json
{
    "component": "simbot.mirai",
    "code": 123456789,
    "authorization": {
        "type": "text",
        "text": "你的密码"
    }
}

MD5密码​

my-bot.bot.json
{
    "component": "simbot.mirai",
    "code": 123456789,
    "authorization": {
        "type": "md5_text",
        "md5": "e807f1fcf82d132f9bb018ca6738a19f"
    }
}
完整配置参考
FYI

仅供参考，以具体代码效果为准。

配置属性 config 下的几乎所有属性都是可选的（甚至包括 config 属性自己），因此你没有必要书写过于完整的配置文件。

下述的完整配置参考中，config.deviceInfo 将会被省略。

下述部分属性不会提供所有的可能（例如 authorization），对所有属性的完整解释参见后续说明。

my-bot.bot.json
{
  "component": "simbot.mirai",
  "code": 123,
  "authorization": {
     "type": "text",
     "text": "明文密码"
  },
  "config": {
      "workingDir": ".",
      "heartbeatPeriodMillis": 60000,
      "statHeartbeatPeriodMillis": 300000,
      "heartbeatTimeoutMillis": 5000,
      "heartbeatStrategy": "STAT_HB",
      "reconnectionRetryTimes": 2147483647,
      "autoReconnectOnForceOffline": false,
      "protocol": "ANDROID_PHONE",
      "highwayUploadCoroutineCount": 16,
      "deviceInfo": {
         "type": "auto"
      },
      "noNetworkLog": false,
      "noBotLog": false,
      "isShowingVerboseEventLog": false,
      "cacheDir": "cache/123",
      "contactListCache": {
        "saveIntervalMillis": 60000,
        "friendListCacheEnabled": false,
        "groupMemberListCacheEnabled": false
      },
      "loginCacheEnabled": true,
      "convertLineSeparator": true,
      "recallMessageCacheStrategyConfig": {
        "type": "invalid"
      },
      "disableAccountSecretes": false
  }
}
更诚实

配置文件对应的实际内容可参考 API文档 。

参数释义​

参数类型含义
component 必须 const固定值：simbot.mirai，代表当前配置文件是针对mirai组件的
code 必须 integer账号。
passwordInfo 弃用 PasswordInfoConfiguration密码配置。已弃用，参考 BotAuthorizationConfiguration
authorization 必须 BotAuthorizationConfiguration密码配置。后续会提供详细解释。
configConfig其他详细配置
config.workingDirstring同原生mirai配置，mirai的工作目录。默认为 "." 。
config.heartbeatPeriodMillisinteger同原生mirai配置，连接心跳包周期。
config.statHeartbeatPeriodMillisinteger同原生mirai配置，状态心跳包周期。
config.heartbeatTimeoutMillisinteger同原生mirai配置，每次心跳时等待结果的时间。
config.heartbeatStrategyenum

同原生mirai配置，枚举类型。心跳策略。可选元素：

  • STAT_HB
  • REGISTER
  • NONE
    • config.reconnectionRetryTimesinteger同原生mirai配置，最多尝试多少次重连。
    config.autoReconnectOnForceOfflineboolean同原生mirai配置，Boolean类型。在被挤下线时 (`BotOfflineEvent.Force`) 自动重连。
    config.protocolenum同原生mirai配置，枚举类型。使用协议类型。可选元素：
  • ANDROID_PHONE
  • ANDROID_PAD
  • ANDROID_WATCH
  • IPAD
  • MACOS
    • config.highwayUploadCoroutineCountinteger同原生mirai配置，Highway 通道上传图片, 语音, 文件等资源时的协程数量。
    config.deviceInfoDeviceInfoConfiguration使用的自定义设备信息配置，详见下文。
    config.noNetworkLogboolean不展示mirai网络日志。默认false
    config.noBotLogboolean不展示mirai Bot日志。默认false
    config.isShowingVerboseEventLogboolean同原生mirai配置，是否显示过于冗长的事件日志。默认false。
    config.cacheDirstring

    类似原生mirai配置，缓存数据目录, 相对于 workingDir 。

    与原生配置的默认行为不同的是，cacheDir的默认值为 cache/$CODE$ （$CODE$ 为当前配置的账号）。

    config.contactListCacheContactListCacheConfiguration同原生mirai配置，详见下文。
    config.loginCacheEnabledboolean同原生mirai配置，登录缓存。开启后在密码登录成功时会保存秘钥等信息, 在下次启动时通过这些信息登录, 而不提交密码。可以减少验证码出现的频率。
    秘钥信息会由密码加密保存. 如果秘钥过期, 则会进行普通密码登录。默认为true。
    config.convertLineSeparatorboolean同原生mirai配置，是否处理接受到的特殊换行符, 默认为 true。
  • 若为 true, 会将收到的 CRLF(\r\n) 和 CR(\r) 替换为 LF(\n)
  • 若为 false, 则不做处理
    • config.recallMessageCacheStrategyenum已弃用 用于 消息撤回事件(MiraiMessageRecallEvent) 的消息缓存策略。 可选值为枚举类型 MiraiBotVerifyInfoConfiguration.RecallMessageCacheStrategyType 中的可选元素：
    元素名释义
    INVALID无效的缓存策略，即不进行缓存。
    MEMORY_LRU基于内存的 LRU 缓存策略
    config.recallMessageCacheStrategyConfigurationRecallMessageCacheStrategyConfiguration用于 消息撤回事件(MiraiMessageRecallEvent) 的消息缓存策略，详见下文。
    config.accountSecretsboolean已弃用。是否禁用 account.secrets 的保存，默认为 false 。 相当于 BotConfiguration.disableAccountSecretes() 。
    config.disableAccountSecretesboolean是否禁用 account.secrets 的保存，默认为 false。 相当于 BotConfiguration.disableAccountSecretes() 。

    BotAuthorizationConfiguration​

    BotAuthorizationConfiguration 是用于配置bot登录信息的配置类型。其大致结构如下：

    {
      "authorization": {
        "type": "authorization_type",
        "paramA": "valueA",
        "paramB": "valueB"
      }
    }

    上述示例中可见，authorization 一定存在一个 type 属性来标记当前配置的类型。type 是一个具有固定可选范围的字符串值，并且 type 的选择会决定其他的可用属性。 下面会分别介绍所有的type以及它们对应的具体结构。

    text​

    当 type 值为 text 时，代表所配置的内容为 明文密码。

    {
      "authorization": {
        "type": "text",
        "text": "password"
      }
    }

    md5_text​

    与 type=text 时类似，当 type 值为 md5_text 时，代表所配置的内容为 MD5密码(字符串)。

    {
      "authorization": {
        "type": "md5_text",
        "md5": "e807f1fcf84d112f3bb018ca6738a19f"
      }
    }

    md5_bytes​

    与 type=md5_text 时类似，当 type 值为 md5_text 时，代表所配置的内容为 MD5密码(字节组)。

    {
      "authorization": {
        "type": "md5_bytes",
        "md5": [-24, 7, -15, -4, -14, 45, 18, 47, -101, -80, 24, -54, 102, 56, -95, -97]
      }
    }

    env​

    下文几个以 env_ 开头的配置类型代表那些直接通过虚拟机参数或者环境变量来进行动态配置的方式。 这类配置方式暂且称其为环境变量类的配置。

    在环境变量配置中，会存在两个属性：prop 和 env。比如如下示例：

    {
      "code": 123456,
      "authorization": {
        "type": "env_xxx",
        "prop": "mirai.$CODE$.password",
        "env": "mirai.$CODE$.password"
      }
    }

    上述配置代表，当前配置的bot的密码，会先通过虚拟机参数，也就是 System.getProperty("simbot.mirai.123456.password") 获取。 如果无法获取，则会尝试通过环境变量，也就是 System.getenv("simbot.mirai.123456.password") 获取。

    带入上述示例，你可以通过如下启动命令来动态提供账号 123456 的密码信息。

    java -jar -Dsimbot.mirai.123456.password=myPassword myBot.jar

    注意，prop 是优先于 env 进行获取的。

    占位符?

    也许你发现了，上述配置中存在一串占位符 $CODE$。占位符会在 后续 进行简单介绍。

    prop 和 env 本质上都是 可选 属性，但是它们二者必须至少 存在一个 。

    因此下述配置将会引发运行时异常：

    缺少属性
    {
      "authorization": {
        "type": "env_xxx"
      }
    }

    env_text​

    通过环境变量属性配置 明文密码。

    {
      "authorization": {
        "type": "env_text",
        "prop": "xxx",
        "env": "xxx"
      }
    }

    env_md5_text​

    通过环境变量属性配置 md5密码(字符串)。

    {
      "authorization": {
        "type": "env_md5_text",
        "prop": "xxx",
        "env": "xxx"
      }
    }

    qr_code​

    通过 二维码扫码 登陆账号。

    {
      "authorization": {
        "type": "qr_code"
      }
    }
    since mirai 2.15

    二维码扫码是 mirai v2.15+ 追加的新能力（参考 mirai#1281 ）

    DeviceInfoConfiguration​

    DeviceInfoConfiguration 是用来配置当前账号所使用的设备信息(DeviceInfo)的配置类型。其大致结构如下：

    {
      "config": {
        "deviceInfo": {
          "type": "xxx",
          "paramA": "valueA",
          "paramB": "valueB"
        }
      }
    }

    上述示例中可见，deviceInfo 一定存在一个 type 属性来标记当前配置的类型。type 是一个具有固定可选范围的字符串值，并且 type 的选择会决定其他的可用属性。 下面会分别介绍所有的 type 可选项以及它们对应的具体结构。

    random​

    random 代表使用mirai所提供的随机设备信息API来生成并使用一个随机的设备信息实例。

    {
      "config": {
        "deviceInfo": {
          "type": "random",
          "seed": null
        }
      }
    }

    属性 seed 是一个 可选项，且 可为空，默认值为 null。其代表进行随机时所需要使用的随机种子。

    simbot_random​

    simbot_random 代表使用simbot组件所提供的随机设备信息。simbot组件所提供的随机设备信息相比较于mirai原生的随机设备信息而言， 其中替换了部分属性内容，使得设备信息中留下了一些 simbot 的痕迹。

    {
      "config": {
        "deviceInfo": {
          "type": "simbot_random",
          "seed": 1
        }
      }
    }

    属性 seed 是一个 可选项，默认值为 1。其代表进行随机时所需要使用的随机种子。

    resource​

    resource 代表寻找并读取一个本地或资源目录中的配置文件。

    {
      "config": {
        "deviceInfo": {
          "type": "resource",
          "paths": ["foo/bar/device.json"]
        }
      }
    }

    属性 path 是 必选项，且元素数量应当 至少为1。path 代表了需要按照顺序寻找的资源文件列表，因此 path 所指向的路径都应当为一个具体的文件，而不是目录。

    path 是支持 占位符 的。

    下述配置为例：

    {
      "config": {
        "deviceInfo": {
          "type": "resource",
          "paths": ["foo/bar/device-$CODE$.json"]
        }
      }
    }

    假设当前bot账号为 123456，则上述中配置的路径最终结果为 "foo/bar/device-123456.json" 。

    path 在解析时，会首先尝试寻找本地目录，而后寻找资源目录。例如下述配置中：

    {
      "config": {
        "deviceInfo": {
          "type": "resource",
          "paths": ["foo/device-$CODE$.json"]
        }
      }
    }

    解析器首先会去寻找本地目录 foo/device.json，也就是项目根目录下 foo 目录下的 device.json 文件。 假如未寻得，则会通过类加载器尝试加载当前资源目录下的 foo/device.json 结果。如果上述过程结束且 paths 所有内容都无命中结果， 将会抛出异常。

    如果你希望指定具体地寻找范围，比如仅寻找本地路径、仅寻找资源路径或者深层寻找资源路径，你可以通过为元素标记前缀来完成：

    {
      "config": {
        "deviceInfo": {
          "type": "resource",
          "paths": [
            "file:device-local.json",
            "classpath:device-resource.json",
            "classpath*:device-any.json"
          ]
        }
      }
    }

    当使用前缀 file: 时，指定其后的路径为本地文件。

    当使用前缀 classpath: 时，指定其后的路径为资源路径。

    当使用前缀 classpath*: 时，指定其后的路径为资源路径，但是会获取可能得到的所有资源并取首个结果。

    file_based​

    file_based 代表使用类似于mirai原生配置中的 BotConfiguration.fileBasedDeviceInfo 来进行配置。

    {
      "config": {
        "deviceInfo": {
          "type": "file_based",
          "file": "device.json",
          "fromResource": null
        }
      }
    }

    与 resource 不同的是，file_based 是基于 DeviceInfo.loadAsDeviceInfo() 的， 其最终结果与行为会类似于使用 BotConfiguration.fileBasedDeviceInfo()。

    file_based 仅支持 使用本地文件，且所需要读取的设备信息文件的格式也与DeviceInfo 的结构存在些许不同， 它们是存在"版本号"的信息格式。因此 file_based 的所需格式与 resource的所需格式可能并不通用。

    不过，虽然"仅支持"本地文件，但是它提供了一个可选参数 fromResource 来允许在读取文件之前进行检测： 当 file 处的文件不存在或内容为空时，会尝试从资源路径中寻找 fromResource 并将其复制到 file 处。 如果此行为尝试失败，则会输出警告日志，但不会终止流程。

    {
      "config": {
        "deviceInfo": {
          "type": "file_based",
          "file": "device.json",
          "fromResource": "device-resource.json"
        }
      }
    }

    上述配置中，如果当前项目根目录中不存在 device.json 文件，则会尝试从资源目录中读取 device-resource.json 并将其内容复制到项目根目录的 device.json 文件中。


    与mirai原生配置 BotConfiguration.fileBasedDeviceInfo() 不同的是，file_based 的属性 file 不会 被限制在 workingDir 中，而是会被直接使用。 因此在配置的时候请注意相对路径或绝对路径的使用，以及系统权限等问题。


    file 和 fromResource 支持占位符替换，例如：

    {
      "config": {
        "deviceInfo": {
          "type": "file_based",
          "file": "device-$CODE$.json",
          "fromResource": "device-resource-$CODE$.json"
        }
      }
    }

    object​

    object 代表直接使用最原本的 DeviceInfo 序列化结果对象来作为属性值。

    {
      "config": {
        "deviceInfo": {
          "type": "object",
          "object": {}
        }
      }
    }
    完整属性示例
    仅供参考

    下述示例仅为参考，不建议直接使用。属性具体含义请参考mirai DeviceInfo 类说明。

    {
        "config": {
          "deviceInfo": {
            "type": "object",
            "object": {
              "display": [76, 73, 82, 65, 73, 45, 83, 73, 77, 66, 79, 84, 46, 50, 48, 48, 49, 50, 50, 46, 48, 48, 49],
              "product": [108, 105, 114, 97, 105, 45, 115, 105, 109, 98, 111, 116],
              "device": [108, 105, 114, 97, 105, 45, 115, 105, 109, 98, 111, 116],
              "board": [108, 105, 114, 97, 105, 45, 115, 105, 109, 98, 111, 116],
              "brand": [101, 111, 114, 116, 101],
              "model": [108, 105, 114, 97, 105, 45, 115, 105, 109, 98, 111, 116],
              "bootloader": [117, 110, 107, 110, 111, 119, 110],
              "fingerprint": [109, 97, 109, 111, 101, 47, 109, 105, 114, 97, 105, 47, 109, 105, 114, 97, 105, 58, 49, 48, 47, 77, 73, 82, 65, 73, 46, 50, 48, 48, 49, 50, 50, 46, 48, 48, 49, 47, 54, 53, 56, 51, 55, 54, 48, 58, 117, 115, 101, 114, 47, 114, 101, 108, 101, 97, 115, 101, 45, 107, 101, 121, 115],
              "bootId": [-44, 29, -116, -39, -113, 0, -78, 4, -23, -128, 9, -104, -20, -8, 66, 126],
              "procVersion": [76, 105, 110, 117, 120, 32, 118, 101, 114, 115, 105, 111, 110, 32, 51, 46, 48, 46, 51, 49, 45, 50, 71, 54, 57, 72, 122, 115, 105, 32, 40, 97, 110, 100, 114, 111, 105, 100, 45, 98, 117, 105, 108, 100, 64, 120, 120, 120, 46, 120, 120, 120, 46, 120, 120, 120, 46, 120, 120, 120, 46, 99, 111, 109, 41],
              "baseBand": [],
              "version": {
                "incremental": [53, 56, 57, 49, 57, 51, 56],
                "release": [49, 48],
                "codename": [82, 69, 76],
                "sdk": 29
              },
              "simInfo": [84, 45, 77, 111, 98, 105, 108, 101],
              "osType": [97, 110, 100, 114, 111, 105, 100],
              "macAddress": [48, 50, 58, 48, 48, 58, 48, 48, 58, 48, 48, 58, 48, 48, 58, 48, 48],
              "wifiBSSID": [48, 50, 58, 48, 48, 58, 48, 48, 58, 48, 48, 58, 48, 48, 58, 48, 48],
              "wifiSSID": [60, 117, 110, 107, 110, 111, 119, 110, 32, 115, 115, 105, 100, 62],
              "imsiMd5": [-44, 29, -116, -39, -113, 0, -78, 4, -23, -128, 9, -104, -20, -8, 66, 126],
              "imei": "899752952597699",
              "apn": [119, 105, 102, 105]
            }
          }
        }
    }

    simple_object​

    simple_object 与上文中的 object 很类似，只不过 simple_object 代表使用simbot所提供的 SimpleDeviceInfo 序列化结果对象来作为属性值。

    SimpleDeviceInfo 属性名与 DeviceInfo 基本一致，只不过将 DeviceInfo 中所有原本为字节数组的属性变更为了字符串，使得其属性可以相对表现得更直观。

    {
      "config": {
        "deviceInfo": {
          "type": "simple_object",
          "object": {}
        }
      }
    }
    完整属性示例
    仅供参考

    下述示例仅为参考，不建议直接使用。属性具体含义请参考mirai DeviceInfo 类说明（ SimpleDeviceInfo 字段含义于其一致）。

    {
        "config": {
          "deviceInfo": {
            "type": "simple_object",
            "object": {
              "display": "MIRAI.496596.001",
              "product": "mirai",
              "device": "mirai",
              "board": "mirai",
              "brand": "mamoe",
              "model": "mirai",
              "bootloader": "unknown",
              "fingerprint": "mamoe/mirai/mirai:10/MIRAI.200122.001/7041834:user/release-keys",
              "bootId": "8B176CE7-2C0D-554E-440D-1D6FC8F53AD1",
              "procVersion": "Linux version 3.0.31-o66PpLqf (android-build@xxx.xxx.xxx.xxx.com)",
              "baseBand": "",
              "version": {
                "incremental": "5891938",
                "release": "10",
                "codename": "REL",
                "sdk": 29
              },
              "simInfo": "T-Mobile",
              "osType": "android",
              "macAddress": "02:00:00:00:00:00",
              "wifiBSSID": "02:00:00:00:00:00",
              "wifiSSID": "<unknown ssid>",
              "imsiMd5": "5df6e66cc541fe594f228c889cd7828b",
              "imei": "078869213288891",
              "apn": "wifi"
            }
          }
        }
    }
    兼容性

    需要注意的是，SimpleDeviceInfo 是 simbot 通过对照 DeviceInfo 类的结构而手动构造出来的类型，因此其无法保证与 DeviceInfo 之间能够保持长久的兼容对照。 假若 DeviceInfo 在后续版本产生变更， SimpleDeviceInfo 是无法保证能够适配兼容的。因此请谨慎使用 SimpleDeviceInfo。

    auto 默认​

    auto 是在未配置的情况下默认使用的类型，其代表会尝试自动寻找配置文件，如果找不到则会使用 file_based 作为生成策略。

    {
      "config": {
        "deviceInfo": {
          "type": "auto",
          "baseDir": null,
          "fileBasedFilename": "device.json"
        }
      }
    }

    baseDir 是一个可选的，且可为null。其代表在自动搜寻配置文件时的基础目录。当为 null 的时候将不会搜寻配置文件。

    当 baseDir 不为 null 时，解析器首先会按照顺序尝试搜寻如下目录：

    1. 本地文件: $baseDir/device-$CODE$.json
    2. 资源文件: $baseDir/device-$CODE$.json
    3. 本地文件: $baseDir/device.json
    4. 资源文件: $baseDir/device.json

    如下示例中，

    {
      "config": {
        "deviceInfo": {
          "type": "auto",
          "baseDir": "devices"
        }
      }
    }

    假设当前 code 为 123456，则最终寻找的目标路径为：

    • devices/device-123456.json
    • devices/device.json

    baseDir 支持 占位符 。

    例如：

    {
      "config": {
        "deviceInfo": {
          "type": "auto",
          "baseDir": "devices-$CODE$"
        }
      }
    }

    假设当前 code 为 123456, 则上述配置中的的 baseDir 最终会被替换为 devices-123456，并最终会去寻找如下目标：

    • devices-123456/device-123456.json
    • devices-123456/device.json

    ContactListCacheConfiguration​

    类型结构同原生mirai配置字段 contactListCache，其属性如下：

    saveIntervalMillis​

    同原生mirai配置，在有修改时自动保存间隔. 默认 60 秒. 在每次登录完成后有修改时都会立即保存一次.

    friendListCacheEnabled​

    同原生mirai配置，开启好友列表缓存.

    groupMemberListCacheEnabled​

    同原生mirai配置，开启群成员列表缓存.

    参考配置​

    {
       "config": {
          "contactListCache": {
            "saveIntervalMillis": 60000,
            "friendListCacheEnabled": false,
            "groupMemberListCacheEnabled": false
          }
       }
    }

    RecallMessageCacheStrategyConfiguration​

    RecallMessageCacheStrategyConfiguration 是用于配置对撤回消息内容缓存策略的配置类型。 其大致结构如下：

    {
       "config": {
          "recallMessageCacheStrategyConfig": {
            "type": "type",
            "param1": "value1"
          }
       }
    }

    上述示例中可见，recallMessageCacheStrategyConfig 一定存在一个 type 属性来标记当前配置的类型。type 是一个具有固定可选范围的字符串值，并且 type 的选择会决定其他的可用属性。 下面会分别介绍所有的 type 以及它们对应的具体结构。

    invalid​

    代表无效的缓存策略，即不进行缓存。

    {
       "config": {
          "recallMessageCacheStrategyConfig": {
            "type": "invalid"
          }
       }
    }

    memory_lru​

    即通过在内存中使用LRU缓存的策略。

    {
       "config": {
          "recallMessageCacheStrategyConfig": {
            "type": "memory_lru",
            "groupMaxSize": 1536,
            "friendMaxSize": 96,
            "loadFactor": 0.75
          }
       }
    }

    memory_lru 的本质即在内部通过 Map 进行缓存，提供的属性 loadFactor 也是使用在Map中的属性。

    groupMaxSize 和 friendMaxSize 分别代表对群消息和好友消息的缓存数量上限。

    所有属性均有默认值。

    custom_properties​

    指定一个自定义实现类和自定义属性来自行实现缓存效果的配置。

    {
       "config": {
          "recallMessageCacheStrategyConfig": {
            "type": "custom_properties",
            "className": "com.example.xxx.CustomPropertiesMiraiRecallMessageCacheStrategyImpl",
            "properties": {
              "foo": "bar"
            }
          }
       }
    }

    custom_properties 代表使用者自行提供一个实现，并自行解析所有提供的配置属性来实现一个缓存器。 其中 className 属性是必须的，且需要保证此实现类至少存在一个无参公开构造用来进行实例化。

    properties 属性为可自定义的键值对配置集，但是需要注意键与值都应为字符串格式。

    占位符替换​

    在上述详细释义中，你可能会发现有些配置中（尤其是存在 type 的多选择配置）会出现占位符 $CODE$。其实这个占位符很简单，它会在这个配置进行处理前，将 $CODE$ 替换为当前bot的code信息。

    例如你所配置的 code 值为 123456，那么 $CODE$ 最终就会被替换为 123456。

    需要注意的是，并非所有配置都允许这个占位符。如果某个配置项支持，那么在说明中（也包括源码中的文档注释）将会有所体现。