qbittorrent-api（qbittorrent API 搜索） Skills下载安装命令和教程

安装方式

通过对话安装

复制提示词发给支持本地命令或 Skills 的 AI 助手，先确认命令和权限，再让它执行。

请帮我安装这个 Agent Skill：qbittorrent-api（qbittorrent API 搜索）
来源仓库：https://github.com/hxbreak/qbittorrent-api
安装命令：
openclaw skills install qbittorrent-api
安装前请先检查当前环境是否支持对应 CLI，并向我确认将要执行的命令、安装目录、联网范围和文件读写权限；确认后再执行。

命令行安装

复制命令到本机终端执行。该命令会通过 OpenClaw 从第三方来源获取 Skill；本站只展示命令，不托管安装包，也不自动执行。

ClawHubOpenClaw

openclaw skills install qbittorrent-api

简介

辅助使用 qBittorrent Web API 进行种子管理、下载控制与状态查询。

适合需要自动化添加种子、暂停恢复任务或监控下载进度的场景。
提供 curl 示例和接口结构说明，便于前后端联调与文档生成。
需确认 API 地址、端口及认证方式（如用户名密码或 Token）。
操作可能影响本地网络流量，建议在非高峰时段执行关键命令。

SKILL.md

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

配置信息

优先级顺序：

项目目录的 .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% 时，删除不完整的文件 |
>
> **安全原则**: 除非用户明确指定或种子未完成，否则默认不删除文件。

删除种子（保留文件）- 默认行为

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_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

适合场景

01

OpenClaw 用户查找和安装 Skill 时

02

用户想查找某类 Agent Skill 时

03

需要根据任务场景推荐可安装能力包时

04

需要对比不同来源的安装命令和来源信息时

能力概览

能力 1

按任务关键词查找相关 Skills

能力 2

展示可复制的安装命令

能力 3

保留来源站点、仓库和原始说明，方便继续核验

能力 4

补充不同宿主或平台的使用分布数据

能力 5

展示第三方安全扫描或审计结果

安装后应在对应宿主中按原始 README 的触发条件使用；具体调用方式请以来源页面和 README 为准。

平台分布

OpenClaw

95.92%

按下载量换算1,572

安全审计

VirusTotal

通过

ClawScan

可疑

Static analysis

通过

权限和风险

需要联网

该 Skill 可能需要联网访问来源站点、仓库或外部 API；具体网络访问范围需要结合源码和 README 复核。

安装前确认

本站仅展示第三方公开信息，不托管安装包，不提供自动安装或运行环境。安装前应自行审查源码、依赖和命令行为。来源安全扫描存在 warning/failed 结果，不能写成本站确认安全。当前只有一个来源，正式发布前建议补源仓库或其他目录站核验。

来源信息

GitHub 仓库

github.com

/hxbreak/qbittorrent-api

SKILL.md 来源

clawhub.ai

/hxbreak/qbittorrent-api

继续浏览同类 Skills

更多研究检索 Skills（73,675）返回 Skills 目录

上一个 Skill

qbittorrent（qbittorrent 命令行）

qbittorrent 用于查找、检索和筛选相关信息，适合在 Codex、Claude、Cursor、Gemini CLI 中需要根据关键词、任务场景或来源线索快速定位候选结果时使用。可结合来源仓库、安装命令和原始 README 继续核验具体用法。安装前建议确认权限范围、维护状态，以及是否会触发联网、命令执行或文件读写。

下一个 Skill

qbo（夸博）

qbo 用于查找、检索和筛选相关信息，适合在 Codex、Claude、Cursor、Gemini CLI 中需要根据关键词、任务场景或来源线索快速定位候选结果时使用。可结合来源仓库、安装命令和原始 README 继续核验具体用法。安装前建议确认权限范围、维护状态，以及是否会触发联网、命令执行或文件读写。

qbittorrent-api（qbittorrent API 搜索）