Use when working with qBittorrent Web API - adding torrents, managing downloads, checking status, or any qBittorrent automation task. Includes curl examples and common patterns.
Scanned 9/6/2026
Install to Claude Code
Skills Directorynpx -y skills add LeoYeAI/openclaw-master-skills --skill qbittorrent-api --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Qbittorrent Api?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/leoyeai-qbittorrent-api)More formats (shields.io, HTML) on the badges page.
---
name: qbittorrent-api
description: Use when working with qBittorrent Web API - adding torrents, managing downloads, checking status, or any qBittorrent automation task. Includes curl examples and common patterns.
---
# qBittorrent Web API
## 配置信息
**优先级顺序**：
1. 项目目录的 `.env` 文件（默认）
2. 项目 `CLAUDE.md` 文件
3. 询问用户提供
```bash
# .env 文件格式
QB_URL="http://192.168.31.88:8080"
QB_USER="admin"
QB_PASS="123123"
```
> **注意**: 执行任何 API 操作前，先检查 `.env` 文件是否存在并包含配置。如果缺少配置，询问用户。
## 认证
qBittorrent 使用 **cookie-based 认证**：
```bash
# 配置（从 .env 读取）
source .env 2>/dev/null || true
COOKIE_FILE="/tmp/qb_cookies.txt"
# 登录并保存 cookie
curl -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
-H "Referer: $QB_URL" \
-d "username=$QB_USER&password=$QB_PASS" \
"$QB_URL/api/v2/auth/login"
# 登出
curl -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
"$QB_URL/api/v2/auth/logout"
```
**重要**: 登录请求需要 `Referer` header。
---
## API 端点速查
### 认证 `/api/v2/auth`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 登录 | `/login` | POST | `username`, `password` |
| 登出 | `/logout` | POST | - |
### 种子管理 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 种子列表 | `/info` | GET | `filter`, `hashes`, `category`, `tag` |
| 种子数量 | `/count` | GET | `filter` |
| 种子详情 | `/properties` | GET | `hash` |
| 添加种子 | `/add` | POST | `urls`, `savepath`, `category`, `tags` |
| 删除种子 | `/delete` | POST | `hashes`, `deleteFiles` |
| 开始 | `/start` | POST | `hashes` |
| 停止 | `/stop` | POST | `hashes` |
| 重新检查 | `/recheck` | POST | `hashes` |
| 重新宣告 | `/reannounce` | POST | `hashes` |
| 重命名 | `/rename` | POST | `hash`, `name` |
| 设置注释 | `/setComment` | POST | `hashes`, `comment` |
### 文件管理 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 文件列表 | `/files` | GET | `hash` |
| 文件优先级 | `/filePrio` | POST | `hash`, `id`, `priority` |
| 重命名文件 | `/renameFile` | POST | `hash`, `oldPath`, `newPath` |
| 重命名文件夹 | `/renameFolder` | POST | `hash`, `oldPath`, `newPath` |
### 速度限制 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 获取下载限速 | `/downloadLimit` | GET | `hashes` |
| 获取上传限速 | `/uploadLimit` | GET | `hashes` |
| 设置下载限速 | `/setDownloadLimit` | POST | `hashes`, `limit` |
| 设置上传限速 | `/setUploadLimit` | POST | `hashes`, `limit` |
| 设置分享限制 | `/setShareLimits` | POST | `hashes`, `ratioLimit`, `seedingTimeLimit` |
### 优先级 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 提高优先级 | `/increasePrio` | POST | `hashes` |
| 降低优先级 | `/decreasePrio` | POST | `hashes` |
| 最高优先级 | `/topPrio` | POST | `hashes` |
| 最低优先级 | `/bottomPrio` | POST | `hashes` |
### 路径管理 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 设置保存路径 | `/setLocation` | POST | `hashes`, `location` |
| 设置保存目录 | `/setSavePath` | POST | `hashes`, `path` |
| 设置下载目录 | `/setDownloadPath` | POST | `hashes`, `path` |
### 分类管理 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 获取分类 | `/categories` | GET | - |
| 创建分类 | `/createCategory` | POST | `category`, `savePath` |
| 编辑分类 | `/editCategory` | POST | `category`, `savePath` |
| 删除分类 | `/removeCategories` | POST | `categories` |
| 设置分类 | `/setCategory` | POST | `hashes`, `category` |
### 标签管理 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 获取标签 | `/tags` | GET | - |
| 创建标签 | `/createTags` | POST | `tags` |
| 删除标签 | `/deleteTags` | POST | `tags` |
| 添加标签 | `/addTags` | POST | `hashes`, `tags` |
| 设置标签 | `/setTags` | POST | `hashes`, `tags` |
| 移除标签 | `/removeTags` | POST | `hashes`, `tags` |
### Tracker 管理 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 获取 Trackers | `/trackers` | GET | `hash` |
| 添加 Trackers | `/addTrackers` | POST | `hash`, `urls` |
| 编辑 Tracker | `/editTracker` | POST | `hash`, `origUrl`, `newUrl` |
| 删除 Trackers | `/removeTrackers` | POST | `hash`, `urls` |
### Web Seeds 管理 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 获取 Web Seeds | `/webseeds` | GET | `hash` |
| 添加 Web Seeds | `/addWebSeeds` | POST | `hash`, `urls` |
| 编辑 Web Seed | `/editWebSeed` | POST | `hash`, `origUrl`, `newUrl` |
| 删除 Web Seeds | `/removeWebSeeds` | POST | `hash`, `urls` |
### Peers 管理 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 添加 Peers | `/addPeers` | POST | `hashes`, `peers` |
### 其他设置 `/api/v2/torrents`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 自动管理 | `/setAutoManagement` | POST | `hashes`, `enable` |
| 超级做种 | `/setSuperSeeding` | POST | `hashes`, `value` |
| 强制开始 | `/setForceStart` | POST | `hashes`, `value` |
| 顺序下载 | `/toggleSequentialDownload` | POST | `hashes` |
| 首尾块优先 | `/toggleFirstLastPiecePrio` | POST | `hashes` |
### 传输信息 `/api/v2/transfer`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 传输信息 | `/info` | GET | - |
| 下载限速 | `/downloadLimit` | GET | - |
| 上传限速 | `/uploadLimit` | GET | - |
| 设置下载限速 | `/setDownloadLimit` | POST | `limit` |
| 设置上传限速 | `/setUploadLimit` | POST | `limit` |
| 切换备用限速 | `/toggleSpeedLimitsMode` | POST | - |
### 应用程序 `/api/v2/app`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 版本 | `/version` | GET | - |
| API 版本 | `/webapiVersion` | GET | - |
| 构建信息 | `/buildInfo` | GET | - |
| 关闭 | `/shutdown` | POST | - |
| 获取设置 | `/preferences` | GET | - |
| 设置偏好 | `/setPreferences` | POST | `json` |
| 默认保存路径 | `/defaultSavePath` | GET | - |
### 日志 `/api/v2/log`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 日志 | `/main` | GET | `normal`, `info`, `warning`, `critical` |
| Peer 日志 | `/peers` | GET | `last_known_id` |
### 同步 `/api/v2/sync`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 主数据 | `/maindata` | GET | `rid` |
| 种子 Peers | `/torrentPeers` | GET | `hash`, `rid` |
### RSS `/api/v2/rss`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 添加文件夹 | `/addFolder` | POST | `path` |
| 添加订阅 | `/addFeed` | POST | `url`, `path` |
| 移除 | `/removeItem` | POST | `path` |
| 移动 | `/moveItem` | POST | `itemPath`, `destPath` |
| 获取文章 | `/items` | GET | `withData` |
| 标记已读 | `/markAsRead` | POST | `itemPath`, `articleId` |
| 刷新 | `/refreshItem` | POST | `itemPath` |
| 设置自动下载规则 | `/setRule` | POST | `ruleName`, `ruleDef` |
| 删除规则 | `/removeRule` | POST | `ruleName` |
| 获取规则 | `/rules` | GET | - |
| 匹配规则 | `/matchingArticles` | GET | `ruleName` |
### 搜索 `/api/v2/search`
| 操作 | 端点 | 方法 | 参数 |
|------|------|------|------|
| 启动搜索 | `/start` | POST | `pattern`, `plugins`, `category` |
| 停止搜索 | `/stop` | POST | `id` |
| 搜索状态 | `/status` | GET | `id` |
| 搜索结果 | `/results` | GET | `id`, `limit`, `offset` |
| 删除搜索 | `/delete` | POST | `id` |
| 获取插件 | `/plugins` | GET | - |
| 安装插件 | `/installPlugin` | POST | `sources` |
| 卸载插件 | `/uninstallPlugin` | POST | `names` |
| 启用插件 | `/enablePlugin` | POST | `names`, `enable` |
| 更新插件 | `/updatePlugins` | POST | - |
---
## 单位说明
| 参数 | 单位 | 换算 |
|------|------|------|
| `limit` (限速) | **bytes/second** | 1 MB/s = 1048576 |
| `size` | bytes | - |
| `progress` | 0-1 浮点数 | 0.5 = 50% |
| `priority` | 整数 | 0=不下载, 1=正常, 6=高, 7=最大 |
---
## 种子状态
| 状态 | 含义 |
|------|------|
| `error` | 错误 |
| `missingFiles` | 文件丢失 |
| `uploading` | 做种中 |
| `pausedUP` | 暂停做种 |
| `queuedUP` | 排队做种 |
| `stalledUP` | 做种停滞 |
| `checkingUP` | 检查中 |
| `forcedUP` | 强制做种 |
| `allocating` | 分配空间 |
| `downloading` | 下载中 |
| `metaDL` | 下载元数据 |
| `pausedDL` | 暂停下载 |
| `queuedDL` | 排队下载 |
| `stalledDL` | 下载停滞 |
| `checkingDL` | 检查中 |
| `forcedDL` | 强制下载 |
| `checkingResumeData` | 检查恢复数据 |
| `moving` | 移动中 |
| `unknown` | 未知 |
---
## 过滤器
`torrents/info` 支持的过滤器：
- `all` - 全部
- `downloading` - 下载中
- `seeding` - 做种中
- `completed` - 已完成
- `paused` - 已暂停
- `active` - 活跃
- `inactive` - 不活跃
- `resumed` - 已恢复
- `stalled` - 停滞
- `stalled_uploading` - 上传停滞
- `stalled_downloading` - 下载停滞
- `errored` - 错误
---
## 添加种子工作流
> **重要**: 添加种子前必须先查询已有保存路径，然后询问用户保存位置。
### 步骤 1: 查询已有保存路径
```bash
# 获取已有保存路径（按使用频率排序，显示前 10 个）
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info" | \
jq -r '.[].save_path' | sort | uniq -c | sort -rn | head -10
# 获取默认保存路径
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/app/defaultSavePath"
```
### 步骤 2: 询问用户保存位置
使用 `AskUserQuestion` 工具，展示已有路径供用户选择：
```
问题: 下载文件保存到哪个目录？
选项:
- /m2/ani/番剧 (最常用)
- /m2/movies
- /downloads (默认)
- 其他路径 (用户自定义)
```
### 步骤 3: 添加种子
用户选择路径后，执行添加操作：
```bash
# Magnet link（用户选择或指定的路径）
curl -c cookies.txt -b cookies.txt \
-d "urls=magnet:?xt=urn:btih:xxxx" \
-d "savepath=$USER_SELECTED_PATH" \
"$QB_URL/api/v2/torrents/add"
# 带分类和标签
curl -c cookies.txt -b cookies.txt \
-d "urls=magnet:?xt=urn:btih:xxxx" \
-d "savepath=$USER_SELECTED_PATH" \
-d "category=movies" \
-d "tags=hd,2024" \
"$QB_URL/api/v2/torrents/add"
# Torrent 文件
curl -c cookies.txt -b cookies.txt \
-F "torrents=@file.torrent" \
-d "savepath=$USER_SELECTED_PATH" \
"$QB_URL/api/v2/torrents/add"
```
---
## 其他操作示例
### 获取种子列表
```bash
# 全部
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info"
# 按状态过滤
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?filter=downloading"
# 按分类过滤
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?category=movies"
# 按标签过滤
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?tag=hd"
# 指定种子
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?hashes=abc123,def456"
```
### 控制种子
```bash
# 开始
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123" \
"$QB_URL/api/v2/torrents/start"
# 停止
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123" \
"$QB_URL/api/v2/torrents/stop"
### 删除种子
> **重要**: 删除种子时的 `deleteFiles` 参数规则：
>
> | 场景 | deleteFiles | 说明 |
> |------|-------------|------|
> | **默认行为** | `false` | 只删除任务，保留已下载的文件 |
> | 用户明确要求删除文件 | `true` | 用户指定要删除文件时 |
> | 未下载完成的种子 | `true` | progress < 100% 时，删除不完整的文件 |
>
> **安全原则**: 除非用户明确指定或种子未完成，否则默认不删除文件。
```bash
# 删除种子（保留文件）- 默认行为
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&deleteFiles=false" \
"$QB_URL/api/v2/torrents/delete"
# 删除种子（同时删除文件）- 用户明确要求时
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&deleteFiles=true" \
"$QB_URL/api/v2/torrents/delete"
# 删除多个种子（用 | 分隔）
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123|def456|ghi789&deleteFiles=false" \
"$QB_URL/api/v2/torrents/delete"
# 删除全部种子
curl -c cookies.txt -b cookies.txt \
-d "hashes=all&deleteFiles=false" \
"$QB_URL/api/v2/torrents/delete"
```
**删除前建议检查**:
```bash
# 检查种子是否完成 (progress=1 表示 100%)
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/info?hashes=abc123" | jq '.[0].progress'
```
#### 删除 API 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `hashes` | string | ✅ | 种子 hash，多个用 `\|` 分隔，`all` 删除全部 |
| `deleteFiles` | bool | ❌ | 是否删除文件，默认 `false` |
### 设置限速
```bash
# 设置种子下载限速 1 MB/s
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&limit=1048576" \
"$QB_URL/api/v2/torrents/setDownloadLimit"
# 设置种子上传限速 512 KB/s
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&limit=524288" \
"$QB_URL/api/v2/torrents/setUploadLimit"
# 全局限速
curl -c cookies.txt -b cookies.txt \
-d "limit=1048576" \
"$QB_URL/api/v2/transfer/setDownloadLimit"
```
### 分类和标签
```bash
# 创建分类
curl -c cookies.txt -b cookies.txt \
-d "category=movies&savePath=/downloads/movies" \
"$QB_URL/api/v2/torrents/createCategory"
# 设置分类
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&category=movies" \
"$QB_URL/api/v2/torrents/setCategory"
# 创建标签
curl -c cookies.txt -b cookies.txt \
-d "tags=hd,4k" \
"$QB_URL/api/v2/torrents/createTags"
# 添加标签
curl -c cookies.txt -b cookies.txt \
-d "hashes=abc123&tags=hd" \
"$QB_URL/api/v2/torrents/addTags"
```
### 文件优先级
```bash
# 设置文件优先级
# priority: 0=不下载, 1=正常, 6=高, 7=最大
curl -c cookies.txt -b cookies.txt \
-d "hash=abc123&id=0&priority=0" \
"$QB_URL/api/v2/torrents/filePrio"
```
### Tracker 管理
```bash
# 获取 trackers
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/torrents/trackers?hash=abc123"
# 添加 tracker
curl -c cookies.txt -b cookies.txt \
-d "hash=abc123&urls=udp://tracker.example.com:1337/announce" \
"$QB_URL/api/v2/torrents/addTrackers"
```
### 获取传输信息
```bash
curl -c cookies.txt -b cookies.txt \
"$QB_URL/api/v2/transfer/info"
```
返回示例：
```json
{
"dl_info_speed": 1048576,
"dl_info_data": 10737418240,
"up_info_speed": 524288,
"up_info_data": 5368709120,
"dl_rate_limit": 0,
"up_rate_limit": 0,
"dht_nodes": 1234,
"connection_status": "connected"
}
```
---
## 完整脚本模板
```bash
#!/bin/bash
# 配置 - 从 CLAUDE.md 获取或使用环境变量
QB_URL="${QB_URL:-http://192.168.31.88:8080}"
QB_USER="${QB_USER:-admin}"
QB_PASS="${QB_PASS:-123123}"
COOKIE_FILE="/tmp/qb_cookies.txt"
# 登录
qb_login() {
curl -s -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
-H "Referer: $QB_URL" \
-d "username=$QB_USER&password=$QB_PASS" \
"$QB_URL/api/v2/auth/login"
}
# 登出
qb_logout() {
curl -s -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
"$QB_URL/api/v2/auth/logout"
rm -f "$COOKIE_FILE"
}
# GET 请求
qb_get() {
local endpoint="$1"
curl -s -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
"$QB_URL/api/v2/$endpoint"
}
# POST 请求
qb_post() {
local endpoint="$1"
local data="$2"
curl -s -c "$COOKIE_FILE" -b "$COOKIE_FILE" \
-d "$data" \
"$QB_URL/api/v2/$endpoint"
}
# 使用示例
qb_login
# 获取下载中的种子
qb_get "torrents/info?filter=downloading" | jq '.'
# 添加种子
qb_post "torrents/add" "urls=magnet:?xt=urn:btih:xxxx&savepath=/downloads"
qb_logout
```
---
## 常见问题
| 问题 | 解决方案 |
|------|----------|
| 登录失败 | 检查 Referer header |
| Cookie 不生效 | 确保同时使用 `-c` 和 `-b` |
| 限速不生效 | 单位是 bytes/s，不是 KB/s |
| 找不到种子 | 用 `torrents/info` 查询 hash |
| 中文乱码 | 确保 URL 编码 |
| 403 Forbidden | 检查白名单设置或 CSRF 保护 |
---
## 官方文档
- OpenAPI: https://www.qbittorrent.org/openapi-demo/
- Wiki: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)
- API Changelog: https://github.com/qbittorrent/qBittorrent/blob/master/WebAPI_Changelog.md
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
