Qbittorrent Api

AI Agent需配置 API Key

用于 qBittorrent Web API 操作，包括添加种子、管理下载、检查状态及任何自动化任务，包含 curl 示例...

任务自动化工具调用

491

下载量

安装量

收藏量

★ 5.0

综合评分ⓘ

概述

更多信息

qBittorrent Web API#

配置信息#

优先级顺序：

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

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

操作端点方法参数登录/loginPOSTusername, password登出/logoutPOST-

种子管理 `/api/v2/torrents`#

操作端点方法参数种子列表/infoGETfilter, hashes, category, tag种子数量/countGETfilter种子详情/propertiesGEThash添加种子/addPOSTurls, savepath, category, tags删除种子/deletePOSThashes, deleteFiles开始/startPOSThashes停止/stopPOSThashes重新检查/recheckPOSThashes重新宣告/reannouncePOSThashes重命名/renamePOSThash, name设置注释/setCommentPOSThashes, comment

文件管理 `/api/v2/torrents`#

操作端点方法参数文件列表/filesGEThash文件优先级/filePrioPOSThash, id, priority重命名文件/renameFilePOSThash, oldPath, newPath重命名文件夹/renameFolderPOSThash, oldPath, newPath

速度限制 `/api/v2/torrents`#

操作端点方法参数获取下载限速/downloadLimitGEThashes获取上传限速/uploadLimitGEThashes设置下载限速/setDownloadLimitPOSThashes, limit设置上传限速/setUploadLimitPOSThashes, limit设置分享限制/setShareLimitsPOSThashes, ratioLimit, seedingTimeLimit

优先级 `/api/v2/torrents`#

操作端点方法参数提高优先级/increasePrioPOSThashes降低优先级/decreasePrioPOSThashes最高优先级/topPrioPOSThashes最低优先级/bottomPrioPOSThashes

路径管理 `/api/v2/torrents`#

操作端点方法参数设置保存路径/setLocationPOSThashes, location设置保存目录/setSavePathPOSThashes, path设置下载目录/setDownloadPathPOSThashes, path

分类管理 `/api/v2/torrents`#

操作端点方法参数获取分类/categoriesGET-创建分类/createCategoryPOSTcategory, savePath编辑分类/editCategoryPOSTcategory, savePath删除分类/removeCategoriesPOSTcategories设置分类/setCategoryPOSThashes, category

标签管理 `/api/v2/torrents`#

操作端点方法参数获取标签/tagsGET-创建标签/createTagsPOSTtags删除标签/deleteTagsPOSTtags添加标签/addTagsPOSThashes, tags设置标签/setTagsPOSThashes, tags移除标签/removeTagsPOSThashes, tags

Tracker 管理 `/api/v2/torrents`#

操作端点方法参数获取 Trackers/trackersGEThash添加 Trackers/addTrackersPOSThash, urls编辑 Tracker/editTrackerPOSThash, origUrl, newUrl删除 Trackers/removeTrackersPOSThash, urls

Web Seeds 管理 `/api/v2/torrents`#

操作端点方法参数获取 Web Seeds/webseedsGEThash添加 Web Seeds/addWebSeedsPOSThash, urls编辑 Web Seed/editWebSeedPOSThash, origUrl, newUrl删除 Web Seeds/removeWebSeedsPOSThash, urls

Peers 管理 `/api/v2/torrents`#

操作端点方法参数添加 Peers/addPeersPOSThashes, peers

其他设置 `/api/v2/torrents`#

操作端点方法参数自动管理/setAutoManagementPOSThashes, enable超级做种/setSuperSeedingPOSThashes, value强制开始/setForceStartPOSThashes, value顺序下载/toggleSequentialDownloadPOSThashes首尾块优先/toggleFirstLastPiecePrioPOSThashes

传输信息 `/api/v2/transfer`#

操作端点方法参数传输信息/infoGET-下载限速/downloadLimitGET-上传限速/uploadLimitGET-设置下载限速/setDownloadLimitPOSTlimit设置上传限速/setUploadLimitPOSTlimit切换备用限速/toggleSpeedLimitsModePOST-

应用程序 `/api/v2/app`#

操作端点方法参数版本/versionGET-API 版本/webapiVersionGET-构建信息/buildInfoGET-关闭/shutdownPOST-获取设置/preferencesGET-设置偏好/setPreferencesPOSTjson默认保存路径/defaultSavePathGET-

日志 `/api/v2/log`#

操作端点方法参数日志/mainGETnormal, info, warning, criticalPeer 日志/peersGETlast_known_id

同步 `/api/v2/sync`#

操作端点方法参数主数据/maindataGETrid种子 Peers/torrentPeersGEThash, rid

RSS `/api/v2/rss`#

操作端点方法参数添加文件夹/addFolderPOSTpath添加订阅/addFeedPOSTurl, path移除/removeItemPOSTpath移动/moveItemPOSTitemPath, destPath获取文章/itemsGETwithData标记已读/markAsReadPOSTitemPath, articleId刷新/refreshItemPOSTitemPath设置自动下载规则/setRulePOSTruleName, ruleDef删除规则/removeRulePOSTruleName获取规则/rulesGET-匹配规则/matchingArticlesGETruleName

搜索 `/api/v2/search`#

操作端点方法参数启动搜索/startPOSTpattern, plugins, category停止搜索/stopPOSTid搜索状态/statusGETid搜索结果/resultsGETid, limit, offset删除搜索/deletePOSTid获取插件/pluginsGET-安装插件/installPluginPOSTsources卸载插件/uninstallPluginPOSTnames启用插件/enablePluginPOSTnames, enable更新插件/updatePluginsPOST-

单位说明#

参数单位换算limit (限速)bytes/second1 MB/s = 1048576sizebytes-progress0-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 工具，展示已有路径供用户选择：

text

问题: 下载文件保存到哪个目录？

选项:
- /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 参数

参数类型必填说明hashesstring✅种子 hash，多个用 | 分隔， all 删除全部deleteFilesbool❌是否删除文件，默认 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 headerCookie 不生效确保同时使用 -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

捕获经验教训、错误及修正内容，以实现持续改进。适用于以下场景：（1）命令或操作意外失败；（2）用户纠正Claude（如“不，那不对……”“实际上……”）；（3）用户请求的功能不存在；（4）外部API或工具出现故障；（5）Claude发现自身知识已过时或不正确；（6）针对重复性任务发现了更优方法。同时，在执行重大任务前应回顾已积累的经验教训。

AI Agent

★ 4116↓ 83.7万3 个月前更新

场景驱动+关键词双模式技能发现工具。当用户用自然语言描述场景/需求（如"我想做一个海报""帮我分析股票"），或明确说"安装技能/find skills/找个skill"时，自动从官方内置、本地已安装、SkillHub、虾评、GitHub、ClawHub 六层联合搜索并推荐最合适的技能，支持一键安装。已完全替代官方...

AI Agent

★ 1482↓ 54.5万3 个月前更新

自我反思+自我批评+自我学习+自组织记忆。智能体评估自身工作、发现错误并持续改进。

AI Agent

★ 1402↓ 32.4万3 个月前更新

Qbittorrent Api

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#

单位说明#

种子状态#

过滤器#

添加种子工作流#

步骤 1: 查询已有保存路径#

步骤 2: 询问用户保存位置#

步骤 3: 添加种子#

其他操作示例#

获取种子列表#

控制种子#

删除 API 参数

设置限速#

分类和标签#

文件优先级#

Tracker 管理#

获取传输信息#

完整脚本模板#

常见问题#

官方文档#

相关推荐

self-improving agent

Find Skills

Self-Improving + Proactive Agent

Agent Browser

Skill Vetter

ontology

认证 `/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`#