# NapCat API 端口使用报告

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

---

## 目录

1. [概述](#1-概述)
2. [WebUI 管理界面](#2-webui-管理界面)
3. [OneBot11 HTTP API](#3-onebot11-http-api)
4. [WebSocket API](#4-websocket-api)
5. [常用 API 接口](#5-常用-api-接口)
6. [配置文件说明](#6-配置文件说明)
7. [curl 命令示例](#7-curl-命令示例)
8. [参考资源](#8-参考资源)

---

## 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`

```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 服务器：

```json
{
  "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
```

**方式二：请求头**
```http
Authorization: Bearer your-token
```

**方式三：自定义 Header**
```http
Authorization: your-token
```

### 3.4 HTTP Client 配置（反向 HTTP）

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

```json
{
  "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 服务器，等待客户端连接。

#### 配置示例

```json
{
  "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/
```

#### 消息格式

**发送消息（客户端 → 服务器）：**
```json
{
  "action": "send_private_msg",
  "params": {
    "user_id": 123456789,
    "message": "Hello"
  },
  "echo": "unique-id"
}
```

**接收消息（服务器 → 客户端）：**
```json
{
  "post_type": "message",
  "message_type": "private",
  "user_id": 123456789,
  "message": "Hello"
}
```

### 4.2 WebSocket Client（反向 WS）

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

#### 配置示例

```json
{
  "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 | 否 | 是否纯文本发送 |

**请求示例：**
```json
{
  "user_id": 123456789,
  "message": "Hello World"
}
```

**返回示例：**
```json
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "message_id": 12345
  }
}
```

---

#### 发送群消息

**接口：** `send_group_msg`

**请求参数：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `group_id` | int64 | 是 | 群号 |
| `message` | string/array | 是 | 消息内容 |
| `auto_escape` | boolean | 否 | 是否纯文本发送 |

**请求示例：**
```json
{
  "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`

**请求参数：** 无

**返回示例：**
```json
{
  "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 | 否 | 是否不使用缓存 |

**返回示例：**
```json
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "group_id": 123456789,
    "group_name": "群名称",
    "member_count": 100,
    "max_member_count": 500
  }
}
```

---

#### 获取群成员列表

**接口：** `get_group_member_list`

**请求参数：**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `group_id` | int64 | 是 | 群号 |

**返回示例：**
```json
{
  "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`

**返回示例：**
```json
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "user_id": 123456789,
    "nickname": "QQ昵称"
  }
}
```

---

#### 获取好友列表

**接口：** `get_friend_list`

**返回示例：**
```json
{
  "status": "ok",
  "retcode": 0,
  "data": [
    {
      "user_id": 123456789,
      "nickname": "好友昵称"
    }
  ]
}
```

---

#### 获取版本信息

**接口：** `get_version_info`

**返回示例：**
```json
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "app_name": "NapCat",
    "app_version": "4.17.20",
    "protocol_version": "v11"
  }
}
```

---

#### 获取状态

**接口：** `get_status`

**返回示例：**
```json
{
  "status": "ok",
  "retcode": 0,
  "data": {
    "online": true,
    "good": true
  }
}
```

---

### 5.4 消息类型格式

#### 文本消息

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

#### 图片消息

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

#### At 消息

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

#### 合并消息段

```json
[
  {"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 主配置文件结构

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

### 6.3 完整配置示例

```json
{
  "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 基础调用示例

#### 获取登录号信息

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

#### 发送私聊消息

```bash
# 使用 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!"
  }'
```

#### 发送群消息

```bash
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!"
  }'
```

#### 发送图片消息

```bash
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 群管理示例

#### 获取群列表

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

#### 获取群信息

```bash
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
  }'
```

#### 获取群成员列表

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

#### 群成员禁言

```bash
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
  }'
```

#### 设置群管理员

```bash
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 其他常用接口

#### 撤回消息

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

#### 获取版本信息

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

#### 获取好友列表

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

---

## 8. 参考资源

### 8.1 官方资源

- **GitHub 仓库**: https://github.com/NapNeko/NapCatQQ
- **官方文档**: https://napneko.github.io/
- **API 文档**: https://napneko.github.io/zh-CN/develop/api
- **安装指南**: https://napneko.github.io/guide/install
- **配置指南**: https://napneko.github.io/config/basic

### 8.2 OneBot 协议

- **OneBot 协议文档**: https://onebot.dev/
- **OneBot v11 协议**: https://onebots.pages.dev/protocol/onebot-v11/

### 8.3 相关项目

- **go-cqhttp 文档**: https://docs.go-cqhttp.org/api/
- **NoneBot2**: https://nonebot.dev/
- **Koishi**: https://koishi.chat/

### 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*