配置文件

GoroBot 采用模块化的配置管理方案。核心框架与各个适配器、插件独立管理各自的配置文件。配置管理基于 conic 库，支持 JSON / YAML 等格式、结构体动态绑定与配置热重载（WatchConfig）。

首次运行机器人时，各模块会在 conf/ 目录下自动生成默认配置文件。

目录结构

典型的 conf/ 配置目录结构如下：

conf/
├── config.json            # 框架核心主配置文件
├── qbot/                  # QQ 官方机器人适配器配置
│   └── config.yaml
├── onebot/                # OneBot 适配器配置
│   └── config.json
├── lagrange/              # Lagrange 适配器配置
│   └── config.json
└── telegram/              # Telegram 适配器配置
    └── config.json

框架核心配置文件 (conf/config.json)

主配置文件控制框架的全局行为，如日志输出级别、机器人所有者（管理员）映射以及资源文件路径等。

示例配置

{
  "log_level": 1,
  "owner": {
    "qq": "100000000",
    "qbot:<your_bot_appid>": "qbot:user&<your_user_openid>",
    "telegram:<your_bot_id>": "telegram:user&<your_user_id>"
  },
  "admin": {
    "qq": ["100000001", "100000002"],
    "telegram:<your_bot_id>": ["telegram:user&<admin_user_id>"]
  },
  "resource_path": "./data/resources"
}

字段说明

日志级别 (log_level) 说明

适配器配置文件

1. QQ 官方机器人 (conf/qbot/config.yaml)

QBot 适配器用于接入 QQ 开放平台官方机器人。默认使用 WebSocket Gateway 长连接，也支持 Webhook 回调或双向并存模式。

示例配置

debug: false
mode: "websocket" # 连接模式: "websocket" (默认), "webhook", 或 "both"
intents: 0        # 订阅事件掩码，留空或 0 则使用框架内置默认值

api:
  appid: "your_app_id"
  secret: "your_secret_key"

# 可选：仅在 mode 为 "webhook" 或 "both"，或者需要对外提供图片等静态资源服务时配置
webhook:
  host: "0.0.0.0"
  port: 8443
  path: "/bot"
  base_url: "https://your.domain.net:8443"
  tls:
    cert_path: "/path/to/server.crt"
    key_path: "/path/to/server.key"

字段说明

2. OneBot 适配器 (conf/onebot/config.json)

OneBot 适配器支持 OneBot v11 协议标准。支持 HTTP、WebSocket 客户端（正向 WS）以及反向 WebSocket（ws_reverse）三种通信模式。

示例配置（正向 WebSocket 模式）

{
  "mode": "ws",
  "ws": {
    "host": "127.0.0.1",
    "port": 3001,
    "access_token": "your_token"
  },
  "message_format": "array",
  "heartbeat": {
    "enable": true,
    "interval": 30000
  },
  "ignore_self": true,
  "command_prefix": "/",
  "debug": false
}

示例配置（反向 WebSocket 模式）

{
  "mode": "ws_reverse",
  "ws_reverse": {
    "host": "0.0.0.0",
    "port": 8080,
    "path": "/onebot/v11/ws",
    "access_token": "",
    "reconnect_interval": 300
  },
  "message_format": "array",
  "ignore_self": true,
  "command_prefix": "/"
}

示例配置（HTTP 模式）

{
  "mode": "http",
  "http": {
    "host": "127.0.0.1",
    "port": 5700,
    "post_url": "http://127.0.0.1:5701",
    "access_token": "",
    "secret": "",
    "timeout": 30
  },
  "message_format": "array",
  "ignore_self": true,
  "command_prefix": "/"
}

字段说明

3. Lagrange 适配器 (conf/lagrange/config.json)

Lagrange 适配器基于 LagrangeGo 实现 QQ 客户端协议支持。

示例配置

{
  "app_info": "linux 9.0.90",
  "sign_server_url": "https://sign.example.com",
  "music_sign_server_url": "",
  "command_prefix": "/",
  "account": {
    "uin": 100000000,
    "password": "",
    "sig_path": "keystore.json"
  },
  "ignore_self": true
}

字段说明

4. Telegram 适配器 (conf/telegram/config.json)

Telegram 适配器用于接入 Telegram Bot API。

示例配置

{
  "token": "your_bot_token_from_botfather",
  "server_url": ""
}

字段说明

Universal ID (统一实体标识) 说明

为了统一跨平台的用户、群组与消息寻址，GoroBot 采用了 Universal ID 机制。

格式定义为：

protocol:type&arg1&arg2...

常见格式示例

在 conf/config.json 的 owner 配置中，可通过配置该 ID 赋予特定用户管理员权限。

在自定义插件中管理配置

开发者编写插件时，也可以方便地利用 conic 库为自己的插件提供独立的配置文件：

package myplugin

import (
	"path"
	"github.com/Jel1ySpot/conic"
	GoroBot "github.com/Jel1ySpot/GoroBot/pkg/core"
	"github.com/Jel1ySpot/GoroBot/pkg/util"
)

type Config struct {
	Greeting string `json:"greeting"`
	Limit    int    `json:"limit"`
}

type Service struct {
	conic  *conic.Conic
	config Config
}

func (s *Service) Init(grb *GoroBot.Instant) error {
	configDir := "conf/myplugin/"
	configFile := path.Join(configDir, "config.json")

	s.conic = conic.New()
	s.conic.SetConfigFile(configFile)
	s.conic.WatchConfig()
	s.conic.BindRef("", &s.config)

	if !util.FileExists(configFile) {
		_ = util.MkdirIfNotExists(configDir)
		s.config = Config{Greeting: "你好", Limit: 10}
		_ = s.conic.WriteConfig() // 自动写出默认配置
	}

	return s.conic.ReadConfig()
}