Skip to content

OneBot 接入与网络拓扑 ​

WeqBot 对外提供 OneBot v11 兼容接口。这一页讲清怎么连、怎么鉴权、出错怎么读。

动作清单见动作列表(由代码自动生成,不会漂)。

网络拓扑 ​

四类网络可以同时存在,每类都是数组:

类型方向用途
wsServers正向 WS客户端连过来,收发都在这一条连接上
httpServersHTTP 服务端客户端 POST action;不主动推事件
wsClients反向 WSbot 主动连客户端
httpClientsHTTP 上报bot 主动 POST 事件到客户端

一个账号挂多个

一个账号可以同时挂多个正向 WS、多个反向 WS、多个 HTTP 监听。这是 OneBot v11 的常规 用法,也是刻意支持的。

配置形状 ​

json
{
  "onebotByUin": {
    "2863253201": {
      "networks": {
        "wsServers": [
          {
            "name": "client",
            "host": "127.0.0.1",
            "port": 6700,
            "role": "Universal",
            "messageFormat": "array",
            "reportSelfMessage": true,
            "accessToken": "可选"
          }
        ],
        "httpServers": [],
        "wsClients": [],
        "httpClients": []
      }
    }
  }
}

OneBot 配置按 QQ 号隔离,键是 uin;不同账号可以有不同的端口拓扑。 四类键缺一不可,不用就写空数组 []。

公共字段 ​

字段默认说明
name必填配置名,日志与诊断用
enabledtruefalse 时保留配置但不启动
accessToken无空表示不鉴权
messageFormat—array 或 string
reportSelfMessage—是否下发自己发出的消息(message_sent)

服务端字段 ​

字段默认说明
host127.0.0.1监听地址
port必填端口(0 表示随机,实际端口在日志里)
path/WS 的端点路径;HTTP 里是 action 前缀
roleUniversal仅 WS:Api / Event / Universal
enableWebSocketfalse仅 HTTP:在同一个监听上接受 WS 客户端
maxPayloadBytes100 MiB单帧上限,超过以 1009 关闭

客户端字段 ​

字段默认说明
url必填对端地址
roleUniversal仅 WS
reconnectIntervalMs内部默认仅 WS:重连间隔
timeoutMs内部默认仅 HTTP client
maxPayloadBytes100 MiB仅 WS

WS 角色 ​

role能收 action能收事件
Api✅✗
Event✗✅
Universal✅✅

:path 只是端点路径(默认 /),不按路径分流。角色只由配置的 role 字段决定 —— 同一个路径上的连接能收 action 还是事件,取决于它的 role。

鉴权 ​

接受两种传法:

http
Authorization: Bearer <token>
text
ws://127.0.0.1:6700/?access_token=<token>

accessToken 为空表示不鉴权(默认)。Authorization 头必须是 Bearer <token> 形式,裸 token 不被接受(isAuthorized 的 allowRawToken 当前没有任何调用方开启)。

默认只听 127.0.0.1

改 host 前先想清楚:OneBot 暴露的写能力包括发消息、踢人、改群名。绑到公网等于把这些 交给任何能连上的人,即使有 token。

HTTP 服务端 ​

路由是 POST /<action>,路径即 action 名:

bash
curl -H 'Authorization: Bearer <token>' \
  'http://127.0.0.1:6700/get_login_info'

curl -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"group_id":12345,"message":"hello"}' \
  'http://127.0.0.1:6700/send_msg'

GET 请求不执行 action

GET 只用于健康检查,返回 { "status": "ok", "retcode": 0, "data": { "online": true } }。 所有 action 都是 POST —— 包括 get_login_info 这类只读的。

echo 通过查询参数传:?echo=1。

请求体上限 10 MiB(HTTP 接口不该用来传整段媒体)。超过会以 400 拒绝。

path 配置的实际作用

path 是 action 的前缀,不是可路由的独立端点:

text
path = ''      → POST /send_msg
path = '/api'  → POST /api/send_msg

HTTP 不推事件

需要在收到新消息时被通知,请用 WS 正向或反向。HTTP 服务端只用于调用 action。

请求与响应 ​

请求 ​

json
{ "action": "send_group_msg", "params": { "group_id": 55555, "message": "hi" }, "echo": "1" }

echo 是可选的,但强烈建议带:客户端靠它把响应和请求配对。

响应 ​

json
{ "status": "ok", "retcode": 0, "data": { "message_id": 1000001 }, "echo": "1" }

失败时:

json
{ "status": "failed", "retcode": 100, "data": null, "wording": "群号不存在", "echo": "1" }

echo 必须原样回传

早期版本这里丢过 echo,表现是「所有 action 都超时,但事件推送照常」—— 严格按 echo 过滤的客户端会一直等。现在响应总是带回传入的 echo,不传就不加这个键 (避免序列化成 "echo": null)。

错误码 ​

retcodestatus含义
0ok成功
100failed业务失败(QQ 拒绝、目标不存在等)
1200failed内部错误
1400failed参数错误
1404failed不支持的 action(当前后端没实现,或属于敏感能力)

详见错误码。

Action 注册是动态的 ​

文档里有、实际可能没有

ALL_ACTIONS 有 214 条,但注册由后端能力决定:后端没实现的能力不会注册,调用时 返回 1404,而不是注册了再崩。

所以「文档列出这条」不等于「这个部署能调」。启动日志会打印注册数与跳过数:

text
08:30:00 INFO  [cli] bot 已上线 {"uin":"…","onebot":{"port":6700,"actions":N}}

N 是实际注册成功的数量。

动作列表里每条都标了能力判定方式:

标记含义
始终注册不依赖后端任何能力,一定有
需要后端方法后端实现了列出的方法才注册
按能力域判定按功能域整体判定(如 qzone 开关关掉就整组不注册)

deny-list 是代码里的常量(DENIED_ACTIONS),不是配置项。

消息格式 ​

message 参数接受三种形状:

  • CQ 码字符串:"hello[CQ:face,id=1]"
  • segment 数组:[{ "type": "text", "data": { "text": "hello" } }]
  • 单个 segment 对象:{ "type": "text", "data": { "text": "hello" } }

布尔参数接受 true / false、1 / 0、"true" / "false"。

send_msg 不传 message_type 时按唯一目标 ID 推断。

详见消息段。

单帧与背压 ​

项值
单帧入站上限100 MiB(maxPayloadBytes 可配),超过以 1009 关闭
慢客户端缓冲上限8 MiB,超过直接断开

为什么是断开而不是排队

无限排队会吃内存。慢客户端只会拖垮整个进程,不如让它自己重连。

下一步 ​

版本未定(0.0.0 是占位);文档与代码同步演进,以主仓为准