How do I install the Qbittorrent API skill?

Run npx skillmds@latest add leoyeai-openclaw-master-skills/qbittorrent-api in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Qbittorrent API skill do?

Use when working with qBittorrent Web API - adding torrents, managing downloads, checking status, or any qBittorrent automation task. Includes curl examples and common patterns. It is listed under Integrations & APIs on SkillMD.

Is Qbittorrent API safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Qbittorrent API?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Qbittorrent API free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Qbittorrent API?

LeoYeAI (@leoyeai-openclaw-master-skills) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Qbittorrent API by leoyeai-openclaw-master-skills

Name: Qbittorrent API
Rating: 4.2 (5 reviews)
Author: LeoYeAI

qBittorrent Web API

配置信息

优先级顺序：

项目目录的 .env 文件（默认）
项目 CLAUDE.md 文件
询问用户提供

# .env 文件格式
QB_URL="http://192.168.31.88:8080"
QB_USER="admin"
QB_PASS="123123"

注意: 执行任何 API 操作前，先检查 .env 文件是否存在并包含配置。如果缺少配置，询问用户。

认证

qBittorrent 使用 cookie-based 认证：

# 配置（从 .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: 查询已有保存路径

# 获取已有保存路径（按使用频率排序，显示前 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: 添加种子

用户选择路径后，执行添加操作：

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

其他操作示例

获取种子列表

# 全部
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"

控制种子

# 开始
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"

删除前建议检查:

# 检查种子是否完成 (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`

设置限速

# 设置种子下载限速 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"

分类和标签

# 创建分类
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"

文件优先级

# 设置文件优先级
# 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 管理

# 获取 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"

获取传输信息

curl -c cookies.txt -b cookies.txt \
  "$QB_URL/api/v2/transfer/info"

返回示例：

{
  "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"
}

完整脚本模板

#!/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

Qbittorrent API

File contents

qBittorrent Web API

配置信息

认证

API 端点速查

认证 /api/v2/auth

种子管理 /api/v2/torrents

文件管理 /api/v2/torrents

速度限制 /api/v2/torrents

优先级 /api/v2/torrents

路径管理 /api/v2/torrents

分类管理 /api/v2/torrents

标签管理 /api/v2/torrents

Tracker 管理 /api/v2/torrents

Web Seeds 管理 /api/v2/torrents

Peers 管理 /api/v2/torrents

其他设置 /api/v2/torrents

传输信息 /api/v2/transfer

应用程序 /api/v2/app

日志 /api/v2/log

同步 /api/v2/sync

RSS /api/v2/rss

搜索 /api/v2/search