JOJO/agent-Specialization

Fork 0

JOJO 5f6622a212 chore: add docs and remove sub_agent

2026-03-17 22:46:43 +08:00

18 KiB

Raw Permalink Blame History

NapCat API 端口使用报告

调研时间：2026-03-15
版本：基于 NapCat v4.x 版本
官方文档：https://napneko.github.io/

1. 概述

NapCat 是一个基于 NTQQ 的现代化 QQ Bot 框架，实现了 OneBot v11 协议标准。它支持多种通信方式：

HTTP API：RESTful API 调用
WebSocket Server：正向 WebSocket（服务器模式）
WebSocket Client：反向 WebSocket（客户端模式）

通信方式对比

方式	方向	端口/地址	适用场景
HTTP Server	服务端	自定义（默认3000）	主动调用API
HTTP Client	客户端	上报到指定URL	被动接收消息
WebSocket Server	服务端	自定义（默认3001）	双向通信
WebSocket Client	客户端	连接到指定WS地址	连接框架

2. WebUI 管理界面

WebUI 是 NapCat 的可视化管理界面，用于配置网络和查看日志。

2.1 访问信息

配置项	默认值	说明
监听地址	`0.0.0.0`	监听所有网络接口
端口	`6099`	WebUI 访问端口
Token	随机生成	登录验证密钥

2.2 访问 URL

http://IP地址:6099/webui

注意：

首次启动时，Token 会在启动日志中显示
格式：[WebUi] WebUi Local Panel Url: http://127.0.0.1:6099/webui?token=xxxx
若端口被占用，会自动尝试 port+1，最多尝试100次

2.3 WebUI 配置文件

配置文件路径：webui.json

{
  "host": "0.0.0.0",
  "port": 6099,
  "token": "your-token-here",
  "loginRate": 3
}

2.4 WebUI 功能

QQ 登录（二维码登录）
网络配置管理（HTTP/WS 服务端和客户端）
日志查看
系统配置

3. OneBot11 HTTP API

3.1 HTTP Server 配置

在 WebUI 或配置文件中添加 HTTP 服务器：

{
  "network": {
    "httpServers": [
      {
        "name": "HttpServer",
        "enable": true,
        "host": "0.0.0.0",
        "port": 3000,
        "token": "your-access-token",
        "messagePostFormat": "array"
      }
    ]
  }
}

3.2 HTTP 配置参数说明

参数	类型	默认值	说明
`name`	string	必填	配置名称，唯一标识
`enable`	boolean	false	是否启用
`host`	string	0.0.0.0	监听主机地址
`port`	number	3000	监听端口
`token`	string	空	访问令牌，用于鉴权
`messagePostFormat`	string	array	消息上报格式：string/array

3.3 HTTP API 调用方式

请求格式

POST http://host:port/{action}

认证方式

方式一：Query 参数

POST http://localhost:3000/send_private_msg?access_token=your-token

方式二：请求头

Authorization: Bearer your-token

方式三：自定义 Header

Authorization: your-token

3.4 HTTP Client 配置（反向 HTTP）

用于将消息上报到指定的 HTTP 地址：

{
  "network": {
    "httpClients": [
      {
        "name": "httpClient",
        "enable": true,
        "url": "http://localhost:8080",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "token": "",
        "debug": false
      }
    ]
  }
}

4. WebSocket API

4.1 WebSocket Server（正向 WS）

NapCat 作为 WebSocket 服务器，等待客户端连接。

配置示例

{
  "network": {
    "websocketServers": [
      {
        "name": "WsServer",
        "enable": true,
        "host": "0.0.0.0",
        "port": 3001,
        "token": "your-token",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "heartInterval": 30000,
        "enableForcePushEvent": true,
        "debug": false
      }
    ]
  }
}

连接 URL

ws://host:port/

消息格式

发送消息（客户端 → 服务器）：

{
  "action": "send_private_msg",
  "params": {
    "user_id": 123456789,
    "message": "Hello"
  },
  "echo": "unique-id"
}

接收消息（服务器 → 客户端）：

{
  "post_type": "message",
  "message_type": "private",
  "user_id": 123456789,
  "message": "Hello"
}

4.2 WebSocket Client（反向 WS）

NapCat 作为 WebSocket 客户端，主动连接到服务器。

配置示例

{
  "network": {
    "websocketClients": [
      {
        "name": "WsClient",
        "enable": true,
        "url": "ws://127.0.0.1:8080/onebot/v11/ws",
        "token": "your-token",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "heartInterval": 30000,
        "reconnectInterval": 3000
      }
    ]
  }
}

常见框架对接地址

框架	WebSocket URL
NoneBot2	`ws://127.0.0.1:8080/onebot/v11/ws`
Koishi	`ws://127.0.0.1:5140/onebot`
AstrBot	`ws://127.0.0.1:6199/ws`

5. 常用 API 接口

5.1 消息相关接口

发送私聊消息

接口： send_private_msg

请求参数：

字段	类型	必填	说明
`user_id`	int64	是	对方 QQ 号
`message`	string/array	是	消息内容
`auto_escape`	boolean	否	是否纯文本发送

请求示例：

{
  "user_id": 123456789,
  "message": "Hello World"
}

返回示例：

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "message_id": 12345
  }
}

发送群消息

接口： send_group_msg

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`message`	string/array	是	消息内容
`auto_escape`	boolean	否	是否纯文本发送

请求示例：

{
  "group_id": 987654321,
  "message": "Hello Group"
}

发送消息（通用）

接口： send_msg

请求参数：

字段	类型	必填	说明
`message_type`	string	否	消息类型：private/group
`user_id`	int64	条件	私聊时的 QQ 号
`group_id`	int64	条件	群聊时的群号
`message`	string/array	是	消息内容

撤回消息

接口： delete_msg

请求参数：

字段	类型	必填	说明
`message_id`	int32	是	消息 ID

5.2 群管理接口

获取群列表

接口： get_group_list

请求参数： 无

返回示例：

{
  "status": "ok",
  "retcode": 0,
  "data": [
    {
      "group_id": 123456789,
      "group_name": "群名称",
      "member_count": 100,
      "max_member_count": 500
    }
  ]
}

获取群信息

接口： get_group_info

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`no_cache`	boolean	否	是否不使用缓存

返回示例：

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "group_id": 123456789,
    "group_name": "群名称",
    "member_count": 100,
    "max_member_count": 500
  }
}

获取群成员列表

接口： get_group_member_list

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号

返回示例：

{
  "status": "ok",
  "retcode": 0,
  "data": [
    {
      "user_id": 123456789,
      "nickname": "昵称",
      "card": "群名片",
      "role": "member",
      "join_time": 1234567890
    }
  ]
}

获取群成员信息

接口： get_group_member_info

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`user_id`	int64	是	QQ 号
`no_cache`	boolean	否	是否不使用缓存

群组踢人

接口： set_group_kick

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`user_id`	int64	是	要踢的 QQ 号
`reject_add_request`	boolean	否	是否拒绝加群申请

群组禁言

接口： set_group_ban

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`user_id`	int64	是	要禁言的 QQ 号
`duration`	int32	否	禁言时长（秒），默认1800

设置群管理员

接口： set_group_admin

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`user_id`	int64	是	要设置的 QQ 号
`enable`	boolean	否	true为设置，false为取消

设置群名片

接口： set_group_card

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`user_id`	int64	是	QQ 号
`card`	string	否	群名片内容

设置群名

接口： set_group_name

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`group_name`	string	是	新群名

退出群组

接口： set_group_leave

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`is_dismiss`	boolean	否	是否解散（群主专用）

设置群专属头衔

接口： set_group_special_title

请求参数：

字段	类型	必填	说明
`group_id`	int64	是	群号
`user_id`	int64	是	QQ 号
`special_title`	string	否	专属头衔
`duration`	int32	否	有效期（秒），-1为永久

5.3 账号相关接口

获取登录号信息

接口： get_login_info

返回示例：

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "user_id": 123456789,
    "nickname": "QQ昵称"
  }
}

获取好友列表

接口： get_friend_list

返回示例：

{
  "status": "ok",
  "retcode": 0,
  "data": [
    {
      "user_id": 123456789,
      "nickname": "好友昵称"
    }
  ]
}

获取版本信息

接口： get_version_info

返回示例：

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "app_name": "NapCat",
    "app_version": "4.17.20",
    "protocol_version": "v11"
  }
}

获取状态

接口： get_status

返回示例：

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "online": true,
    "good": true
  }
}

5.4 消息类型格式

文本消息

{
  "type": "text",
  "data": {
    "text": "消息内容"
  }
}

图片消息

{
  "type": "image",
  "data": {
    "file": "图片路径或URL"
  }
}

At 消息

{
  "type": "at",
  "data": {
    "qq": "123456789"
  }
}

合并消息段

[
  {"type": "text", "data": {"text": "你好"}},
  {"type": "at", "data": {"qq": "123456789"}},
  {"type": "text", "data": {"text": "欢迎！"}}
]

6. 配置文件说明

6.1 配置文件位置

Windows: NapCat 安装目录/config/
Linux: /opt/QQ/resources/app/app_launcher/napcat/config/
Docker: /app/napcat/config/

6.2 主配置文件结构

{
  "network": {
    "httpServers": [],
    "httpClients": [],
    "websocketServers": [],
    "websocketClients": []
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false
}

6.3 完整配置示例

{
  "network": {
    "httpServers": [
      {
        "name": "HttpServer",
        "enable": true,
        "host": "0.0.0.0",
        "port": 3000,
        "token": "your-http-token",
        "messagePostFormat": "array"
      }
    ],
    "httpClients": [
      {
        "name": "httpClient",
        "enable": false,
        "url": "http://localhost:8080",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "token": "",
        "debug": false
      }
    ],
    "websocketServers": [
      {
        "name": "WsServer",
        "enable": true,
        "host": "0.0.0.0",
        "port": 3001,
        "token": "your-ws-token",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "heartInterval": 30000,
        "enableForcePushEvent": true,
        "debug": false
      }
    ],
    "websocketClients": [
      {
        "name": "WsClient",
        "enable": false,
        "url": "ws://127.0.0.1:8080/onebot/v11/ws",
        "token": "",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "heartInterval": 30000,
        "reconnectInterval": 3000
      }
    ]
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false
}

7. curl 命令示例

7.1 基础调用示例

获取登录号信息

curl -X POST "http://localhost:3000/get_login_info" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

发送私聊消息

# 使用 Query 参数认证
curl -X POST "http://localhost:3000/send_private_msg?access_token=your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123456789,
    "message": "Hello from NapCat!"
  }'

# 使用 Header 认证
curl -X POST "http://localhost:3000/send_private_msg" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "user_id": 123456789,
    "message": "Hello from NapCat!"
  }'

发送群消息

curl -X POST "http://localhost:3000/send_group_msg" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "group_id": 987654321,
    "message": "Hello Group!"
  }'

发送图片消息

curl -X POST "http://localhost:3000/send_group_msg" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "group_id": 987654321,
    "message": [
      {"type": "text", "data": {"text": "看这张图："}},
      {"type": "image", "data": {"file": "https://example.com/image.jpg"}}
    ]
  }'

7.2 群管理示例

获取群列表

curl -X POST "http://localhost:3000/get_group_list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

获取群信息

curl -X POST "http://localhost:3000/get_group_info" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "group_id": 987654321,
    "no_cache": false
  }'

获取群成员列表

curl -X POST "http://localhost:3000/get_group_member_list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "group_id": 987654321
  }'

群成员禁言

curl -X POST "http://localhost:3000/set_group_ban" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "group_id": 987654321,
    "user_id": 123456789,
    "duration": 3600
  }'

设置群管理员

curl -X POST "http://localhost:3000/set_group_admin" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "group_id": 987654321,
    "user_id": 123456789,
    "enable": true
  }'

7.3 其他常用接口

撤回消息

curl -X POST "http://localhost:3000/delete_msg" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "message_id": 12345
  }'

获取版本信息

curl -X POST "http://localhost:3000/get_version_info" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

获取好友列表

curl -X POST "http://localhost:3000/get_friend_list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token"

8. 参考资源

8.4 社区支持

Telegram 群组: NapCatQQ
QQ 交流群: 搜索 NapCat 相关群组

附录：API 快速参考表

API 名称	功能描述	权限要求
`send_private_msg`	发送私聊消息	好友关系
`send_group_msg`	发送群消息	群成员
`send_msg`	通用发送消息	-
`delete_msg`	撤回消息	消息发送者/管理员
`get_login_info`	获取登录信息	-
`get_friend_list`	获取好友列表	-
`get_group_list`	获取群列表	-
`get_group_info`	获取群信息	群成员
`get_group_member_list`	获取群成员列表	群成员
`get_group_member_info`	获取群成员信息	群成员
`set_group_kick`	群组踢人	管理员/群主
`set_group_ban`	群组禁言	管理员/群主
`set_group_admin`	设置群管理员	群主
`set_group_card`	设置群名片	管理员/群主
`set_group_name`	设置群名	管理员/群主
`set_group_leave`	退出群组	群成员
`set_group_special_title`	设置群专属头衔	群主
`get_version_info`	获取版本信息	-
`get_status`	获取运行状态	-

报告生成时间：2026-03-15
报告版本：v1.0

18 KiB Raw Permalink Blame History Unescape Escape

NapCat API 端口使用报告

目录

1. 概述

通信方式对比

2. WebUI 管理界面

2.1 访问信息

2.2 访问 URL

2.3 WebUI 配置文件

2.4 WebUI 功能

3. OneBot11 HTTP API

3.1 HTTP Server 配置

3.2 HTTP 配置参数说明

3.3 HTTP API 调用方式

请求格式

认证方式

3.4 HTTP Client 配置（反向 HTTP）

4. WebSocket API

4.1 WebSocket Server（正向 WS）

配置示例

连接 URL

消息格式

4.2 WebSocket Client（反向 WS）

配置示例

常见框架对接地址

5. 常用 API 接口

5.1 消息相关接口

发送私聊消息

发送群消息

发送消息（通用）

撤回消息

5.2 群管理接口

获取群列表

获取群信息

获取群成员列表

获取群成员信息

群组踢人

群组禁言

设置群管理员

设置群名片

设置群名

退出群组

设置群专属头衔

5.3 账号相关接口

获取登录号信息

获取好友列表

获取版本信息

获取状态

5.4 消息类型格式

文本消息

图片消息

At 消息

合并消息段

6. 配置文件说明

6.1 配置文件位置

6.2 主配置文件结构

6.3 完整配置示例

7. curl 命令示例

7.1 基础调用示例

获取登录号信息

发送私聊消息

发送群消息

发送图片消息

7.2 群管理示例

获取群列表

获取群信息

获取群成员列表

群成员禁言

设置群管理员

7.3 其他常用接口

撤回消息

获取版本信息

获取好友列表

8. 参考资源

8.1 官方资源

8.2 OneBot 协议

8.3 相关项目

8.4 社区支持

附录：API 快速参考表

18 KiB

Raw Permalink Blame History