视频下载瑞士军刀yt-dlp详解：1700+站点支持与OpenClaw技能封装指南

感谢国内各大厂商在过去一个月的飞速进展，OpenClaw的部署安装已不再像一个月前那样困难重重。我也基本将国内近半数的OpenClaw保姆级教程撰写完毕……是时候进入下一个阶段了：养虾。

养虾，究竟养的是什么？

• 给虾配上实用高效的技能（skills）；
• 让虾不常忘记事情；
• 让虾能够持续自我进化；
• 让多只虾可以彼此协作；
• 等等等等……这些都属于“养虾”的范畴。

世界上没有两个人（或两个组织）的工作流是完全相同的，这或许也意味着没有两只虾会完全一样：它们需要记忆的内容不同，拥有的技能各异，进化路径分岔，彼此协作的模式也千差万别。

养虾的最高境界，就是能培育出完美契合每个组织（哪怕目前只有一个人操作OpenClaw）业务场景的智能体（Agents）。

虽然虾各有不同，但总有一些极其重要、表现远超同类的基础设施。因此，从今天起，我将启动一个全新的“养虾基建系列”，为大家介绍那些在特定任务方向上你大概率绕不开的基建工具。

今天是该系列的第一篇：为大家介绍视频下载领域的瑞士军刀——yt-dlp。它支持超过1700个网站的视频下载。如果你的工作流经常围绕视频展开（如下载、提取音频、抽取文本、二次加工等），那么你绝对不能错过它。它的最终归宿，是被封装成OpenClaw的技能（Skill）。

---

第一章：yt-dlp 是什么？开源世界的接力赛

1.1 从 youtube-dl 到 yt-dlp：一场善意的“迭代”

要理解 yt-dlp 的来历，得先聊聊它的“前辈” youtube-dl。

2006年，youtube-dl 项目诞生。这是一个用 Python 编写的命令行工具，专门用于从 YouTube 下载视频。在那个在线视频刚刚兴起的年代，youtube-dl 堪称技术爱好者的福音。它开源、免费、跨平台，支持自定义下载参数，很快在开发者社区中积累了极高人气。

随后的十几年里，youtube-dl 逐渐发展成为一个庞然大物。其支持的网站从最初的几家扩展到上千家，功能也从单纯的视频下载扩展到音频提取、字幕下载、播放列表批量处理等方方面面。它成为了 GitHub 上 Star 数最多的项目之一，被无数用户视为必备工具。

然而，到了2020年左右，youtube-dl 的开发节奏明显放缓。

问题的根源在于其维护模式。youtube-dl 采用了一种相对传统但响应较慢的开源治理方式。与此同时，视频网站的反爬机制却在不断进化——YouTube频繁调整页面结构，TikTok不断更换API，各大平台都在用技术手段阻止自动化下载。当 youtube-dl 的更新速度跟不上网站变化时，用户便开始遭遇各种下载失败。

2020年，一位名叫 pukkandan 的开发者基于 youtube-dl 创建了一个分支版本，命名为 youtube-dlc（“c”代表“community”，社区版）。这个版本旨在更积极地合并社区贡献，以更快的速度应对网站变化。

但这仅仅是开始。2021年，pukkandan 决定更进一步，从 youtube-dlc 中分化出一个全新的项目，这就是 yt-dlp。名字中的“yt”代表 YouTube（虽然它远不止支持YouTube），“dlp”则是“download plus”的缩写——意味着下载，且功能更多。

这个时机把握得恰到好处。在 yt-dlp 诞生后不久，youtube-dl 的维护几乎陷入停滞，而 yt-dlp 凭借其活跃的开发和丰富的功能，迅速接管了大部分用户。如今，yt-dlp 在 GitHub 上已收获近十万 Star，成为视频下载工具领域毋庸置疑的事实标准。

1.2 为什么称它为“瑞士军刀”？

瑞士军刀之所以经典，不在于某一项功能特别突出，而在于它将多种实用工具集成在了一个紧凑的空间里。yt-dlp 也是如此。

想象这样一个场景：你需要下载一个 YouTube 播放列表的所有视频，但只想要1080p的MP4格式，同时提取并嵌入字幕，自动跳过片头广告，最后将文件按“上传日期-频道名-视频标题”的格式命名，并存放到指定文件夹。

使用普通下载工具，你可能需要打开多个软件，进行无数次点击设置。而使用 yt-dlp，一行命令即可搞定。

这种“一键解决复杂需求”的能力，正是 yt-dlp 的核心竞争力。它像一位训练有素的数字管家，你只需下达指令，它便能自动完成网络请求、格式解析、数据下载、格式转换到文件整理的全套流程。

---

第二章：震撼数字背后的硬实力

2.1 支持的网站：超过 1700 个平台

yt-dlp 究竟能下载多少个网站的视频？答案是：超过1700个。

这个数字可能有些抽象。换个说法：你日常使用互联网时接触到的几乎所有主流视频平台，yt-dlp 基本都能处理。

• 海外主流平台：YouTube、Twitch、Instagram、Vimeo、Reddit等视频网站、直播平台、社交媒体……这些都是基础配置。
• 国内平台覆盖全面：B站（支持分P、弹幕、收藏夹）、抖音、快手、小红书、西瓜视频、优酷、爱奇艺（部分）、腾讯视频（部分）、微博视频……
• 新闻媒体与专业站点：全球各大电视台、新闻网站、学术平台、教育站点、技术分享社区等。
• 音乐平台也不在话下：SoundCloud、Bandcamp、Spotify（播客）等，可以直接下载音频文件。

更有趣的是其模块化的“提取器”（Extractor）架构。每个支持的网站都对应一个独立的提取器模块，负责处理该网站的页面解析和链接提取。这意味着当某个网站改版时，只需更新对应的提取器，不会影响其他功能。这种架构也使得社区贡献新网站支持变得相对容易。

2.2 下载速度：从龟速到火箭的蜕变

许多早期 youtube-dl 用户都有痛苦的记忆：下载速度奇慢无比。

这并非 youtube-dl 的过错，而是 YouTube 引入的“n-sig”签名节流机制所致。简单来说，如果系统检测到请求来自非浏览器环境（如命令行工具），就会故意将速度限制在几十KB/s。下载一个1GB的视频可能需要数小时。

yt-dlp 团队很快找到了绕过此限制的方法并实现了修复。效果立竿见影：在相同网络环境下，yt-dlp 的下载速度可达 16-17 MB/s，而 youtube-dl 仅 50-60 KB/s——差距高达两三百倍。

此外，yt-dlp 还引入了多线程分段下载功能。现代视频网站普遍采用 HLS 或 DASH 技术，将视频切割成大量片段。通过 --concurrent-fragments（或简写 -N）参数，你可以指定同时下载的片段数，从而大幅提升下载速度。若再配合 aria2c 等外部下载器，速度还能更进一步。

2.3 音视频质量：不做选择题，全都要

早期工具常面临两难：要么下载高清视频（无声音），要么下载带声音但画质一般的版本。因为 YouTube 等平台将视频流和音频流分离存储。

yt-dlp 彻底解决了这个问题。当要求下载“最佳质量”时，它会自动选择画质最好的视频流和音质最好的音频流，下载后调用 FFmpeg 合并成一个完整的文件。整个过程对用户透明。

更强大的是格式选择功能。通过 -F 参数，yt-dlp 会列出目标视频所有可用格式及其ID。然后可以用 -f 参数精确指定，例如只下载音频，或指定分辨率。甚至可以使用条件语句，如 -f “bestvideo[height<=1080]+bestaudio/best”，让工具自动选择最佳组合。

---

第三章：那些让人惊叹的高级功能

3.1 SponsorBlock：自动跳过广告的神器

如果你常看 YouTube 的技术教程或测评，一定对“本期视频由XX赞助”的开场感到厌烦。SponsorBlock 是一个众包项目，用户手动标记视频中的赞助、片头片尾等片段，形成公开数据库。

yt-dlp 内置了 SponsorBlock 支持。使用 --sponsorblock-remove 参数，可在下载时自动删除被标记的赞助片段；或用 --sponsorblock-mark 将其保留但标记为章节，便于在播放器中快速跳过。

3.2 从浏览器导入 Cookie：访问受限内容

许多网站有年龄限制或私密内容，需要登录才能观看。yt-dlp 提供了优雅的解决方案：直接从浏览器读取 Cookie。

通过 --cookies-from-browser 参数并指定浏览器（如 chrome, firefox），yt-dlp 会自动读取该网站的登录凭证。只要你在浏览器里能看，yt-dlp 就能下。此操作为只读，不会修改或泄露你的登录信息（建议仅在个人设备上使用）。

3.3 下载视频的任意片段：精准裁剪

有时你只想保存视频的某个精彩部分。--download-sections 参数就是为此而生。

你可以通过时间戳指定片段，例如 --download-sections “*0:30-2:15” 表示下载每个章节中从30秒到2分15秒的部分。对于带章节标记的视频，还可以用 --split-chapters 参数将其自动分割成独立的文件。

3.4 实时直播的“时光机”

看直播最怕错过。yt-dlp 的 --live-from-start 参数允许你从直播开始的地方下载，而非当前时间点。即使直播已进行数小时，你也能下载完整内容。配合 --wait-for-video 参数，甚至可以提前设定命令，等待直播开始后自动执行下载。

3.5 元数据的艺术：让文件自己会说话

杂乱的文件名很快会淹没在硬盘中。yt-dlp 提供了强大的元数据处理能力。

通过 -o 参数，你可以使用变量组合出理想的文件名模板，例如 -o “%(upload_date)s_%(uploader)s_%(title)s.%(ext)s”，会生成“20250318_频道名_视频标题.mp4”这样的文件名。

更进一步，使用 --embed-metadata 参数，可以将标题、作者、日期等信息直接写入视频文件的元数据区域，方便 Plex、Jellyfin 等媒体库软件自动识别分类。对于音频文件，--embed-thumbnail 参数还能将视频封面嵌入为音频的专辑封面。

---

第四章：实战场景——yt-dlp 能为你做什么

4.1 场景一：建立个人视频资料库

假设你是一名研究者，需要系统收藏学术报告和教程视频。

# 下载整个播放列表，按顺序命名，嵌入元数据和英文字幕
yt-dlp -o “%(playlist_index)02d - %(title)s.%(ext)s” \
       -f “bestvideo[height<=1080]+bestaudio/best” \
       --embed-metadata --embed-subs --sub-langs en \
       “PLAYLIST_URL”

这条命令会：1) 下载列表所有视频；2) 以“01、02...”开头命名；3) 限制最高1080p以节省空间；4) 嵌入元数据和英文字幕。

4.2 场景二：音频播客订阅

将YouTube上的播客视频一键转换为高质量音频。

# 提取最佳音质音频并转换为MP3，嵌入封面和元数据
yt-dlp -x --audio-format mp3 --audio-quality 0 \
       --embed-thumbnail --embed-metadata \
       -o “%(uploader)s/%(title)s.%(ext)s” \
       “VIDEO_URL”

参数说明：

• -x：只提取音频。
• --audio-format mp3：转换为MP3格式。
• --audio-quality 0：最高音质（0最好，9最差）。
• --embed-thumbnail：嵌入视频封面作为音频封面。

4.3 场景三：字幕提取与翻译

方便地获取视频字幕。

# 下载所有可用字幕（包括自动生成），并转换为SRT格式
yt-dlp --write-subs --write-auto-subs --sub-langs “en,zh-CN” \
       --convert-subs srt \
       “VIDEO_URL”

若希望字幕直接嵌入视频文件（而非单独文件），可加上 --embed-subs 参数。

4.4 场景四：批量备份社交媒体内容

创作者备份自己发布的内容是个好习惯。

# 下载整个YouTube频道的所有视频（谨慎使用，数据量可能很大）
yt-dlp -f “bestvideo[height<=720]+bestaudio/best” \
       -o “%(upload_date)s - %(title)s.%(ext)s” \
       --download-archive archive.txt \
       “CHANNEL_URL”

--download-archive archive.txt 会记录已下载的视频ID，下次运行时自动跳过，避免重复。

4.5 场景五：代理与网络环境

在公司内网等受限环境下，可通过代理使用。

# 使用HTTP代理
yt-dlp --proxy http://代理地址:端口 “URL”
# 使用SOCKS5代理
yt-dlp --proxy socks5://代理地址:端口 “URL”

---

第五章：yt-dlp vs youtube-dl：为何选择前者

在当下，选择 yt-dlp 几乎是必然。以下是关键差异对比：

5.1 维护状态：活跃与停滞

youtube-dl 的最后实质性更新停留在2021年底，几乎不再合并社区修复。而 yt-dlp 保持每周甚至每天更新的节奏，能快速响应各大视频平台的改版。

5.2 功能对比

功能	youtube-dl	yt-dlp
SponsorBlock 支持	❌	✅
从浏览器提取 Cookie	❌	✅
多线程分段下载	❌	✅
下载视频片段	❌	✅
章节分割	❌	✅
直播从头下载	❌	✅
自动绕过YouTube节流	❌	✅
插件系统	❌	✅

5.3 更合理的默认行为

• 格式选择：yt-dlp 默认优先更高分辨率和更先进编码（如AV1）。
• 文件名：默认包含视频ID，方便追溯来源。
• 错误处理：默认遇到错误继续处理列表中的其他视频，而非直接终止。

5.4 迁移成本极低

两者命令行参数高度兼容，绝大多数 youtube-dl 命令可直接在 yt-dlp 中使用。yt-dlp 还提供了 --compat-options 参数来模拟 youtube-dl 的特定行为。

---

第六章：上手教程——从零开始

6.1 安装

macOS (推荐 Homebrew):

brew install yt-dlp ffmpeg

Windows (使用 winget):

winget install yt-dlp

Linux:

# Ubuntu/Debian
sudo apt install yt-dlp ffmpeg
# Arch Linux
sudo pacman -S yt-dlp ffmpeg
# 或使用 pip
pip install -U yt-dlp

注意：强烈建议同时安装 FFmpeg，它是视频合并、格式转换、元数据嵌入的必备工具。

6.2 第一条命令

最简单的用法，只需提供视频URL：

yt-dlp “https://www.youtube.com/watch?v=...”

yt-dlp 会自动选择最佳格式，以下载到当前目录。

6.3 常用参数速查表

参数	说明	示例
-F	列出所有可用格式	yt-dlp -F “URL”
-f	选择特定格式	yt-dlp -f 22 “URL”
-o	指定输出文件名模板	yt-dlp -o “%(title)s.%(ext)s” “URL”
-P	指定输出目录	yt-dlp -P ~/Downloads “URL”
-x	提取音频	yt-dlp -x “URL”
--write-subs	下载字幕	yt-dlp --write-subs “URL”
--cookies-from-browser	从浏览器获取Cookie	yt-dlp --cookies-from-browser chrome “URL”
-N	并发下载片段数	yt-dlp -N 4 “URL”
-U	更新到最新版本	yt-dlp -U

6.4 配置文件的妙用

将常用参数写入配置文件，避免重复输入。

配置文件位置：

• Linux/macOS: ~/.config/yt-dlp/config
• Windows: %APPDATA%/yt-dlp/config

示例配置内容：

# 总是限制最高1080p
-f bestvideo[height<=1080]+bestaudio/best
# 嵌入元数据和缩略图
--embed-metadata
--embed-thumbnail
# 下载中英字幕并嵌入
--write-subs
--sub-langs en,zh-CN
--embed-subs
# 输出文件名模板
-o ~/Downloads/%(uploader)s/%(title)s.%(ext)s

配置后，日常只需 yt-dlp “URL”，所有预设参数自动生效。

---

第七章：进阶玩法——脚本与API

7.1 脚本自动化

批量下载多个视频：

#!/bin/bash
while read url; do
    yt-dlp “$url”
done < video_list.txt

监控频道自动下载新视频（配合cron）：

#!/bin/bash
# 每天检查一次频道更新
yt-dlp --download-archive ~/archive.txt \
       -o “~/Videos/%(uploader)s/%(title)s.%(ext)s” \
       “CHANNEL_URL”

7.2 Python API 调用

yt-dlp 也是一个 Python 库，可在脚本中调用。

import yt_dlp

ydl_opts = {
    ‘format’: ‘bestaudio/best’,
    ‘postprocessors’: [{
        ‘key’: ‘FFmpegExtractAudio’,
        ‘preferredcodec’: ‘mp3’,
        ‘preferredquality’: ‘192’,
    }],
    ‘outtmpl’: ‘%(title)s.%(ext)s’,
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download([‘https://www.youtube.com/watch?v=…’])

---

第八章：从 yt-dlp 到 OpenClaw Skill——能力的工程化

认识到 yt-dlp 的强大后，核心问题浮现：如何将这个强大的CLI工具，转化为OpenClaw能稳定调用的能力模块？

这远不止是“套个壳”。真正的技能化，是将命令提炼成稳定、可交付、可运营的能力。

8.1 为何要技能化？

yt-dlp 参数繁多，对新手上手不友好。更重要的是：

• 输出不适合自动化消费（日志混杂）。
• 失败原因难以诊断（登录态、限流、格式问题混杂）。
• 调用方式不稳定，环境一变易出问题。

OpenClaw 的目标是让智能体、其他实例乃至未来的自己，都能以低心智负担反复完成同一类任务。

8.2 技能化的核心方法论

将 yt-dlp 封装成 yt-dlp-media Skill 的过程，可提炼为八句话：

1. 保留内核，不重造轮子 —— Skill 只负责包装 yt-dlp 强大的提取器能力。
2. 先做高频闭环，不做大而全 —— 优先解决80%的真实需求。
3. 尽快建立统一入口 —— 外部只与一个稳定的“门面”（facade）交互。
4. 用预设替代参数海 —— 提供如 best/balanced/mobile 等预设，降低使用门槛。
5. 失败要分类 —— 明确区分“环境缺失”、“URL不支持”、“需要登录”等错误，否则无法有效维护和运营。
6. 输出要结构化 —— 输出明确的结果文件路径、信息JSON等，便于下游自动化消费。
7. 长任务要有Job模型 —— 引入轻量级任务状态管理，不依赖前台命令长时间等待。
8. 文档和代码同等重要 —— 技能的可复用性，不仅看功能多少，更看约定和文档是否清晰。

8.3 OpenClaw Skill 的本质

不是把命令搬进智能体，而是把命令提炼成能力。

OpenClaw Skill 的价值在于：

• 将复杂工具收敛为稳定入口。
• 将易碎命令转化为结果清晰的能力。
• 将一次性脚本变成他人也能接手的工作流。

yt-dlp 本体负责“下载能力”，而 yt-dlp-media Skill 负责“交付能力”。二者缺一不可。

8.4 真实用例：视频内容处理流水线

一个完整的内容处理工作流可能如下：

1. 将社交媒体视频链接发给 OpenClaw。
2. 让 OpenClaw 调用技能下载视频。
3. 抽取视频音频。
4. 通过多模态大模型（如 Gemini）将音频转录为文字。
5. 对文本进行清洗、摘要、风格化改写或生成思维导图。

所有这些步骤的中间产物和状态，可以通过诸如“智能表格”等工具进行管理和中转，形成可追溯、可复现的完整流水线。

上图展示了一个可能的任务管理和记录界面。

第九章：安全、法律与道德

9.1 法律风险

下载视频的合法性因国家、地区和用途而异。一般而言：

• 个人学习、研究：多数国家版权法允许为个人使用而复制。
• 再次分发、商业用途：通常需要版权方授权。
• DRM破解：绕过数字版权管理在许多国家是违法的，yt-dlp 也不支持下载DRM保护的内容。

重要原则：yt-dlp 仅下载网站公开提供的内容。浏览器无需登录能看的，它通常也能下；需要付费或特殊权限的，它也无法绕过。

9.2 安全建议

1. 从官方渠道下载：仅从 GitHub yt-dlp 官方仓库 获取。
2. 谨慎使用Cookie功能：--cookies-from-browser 仅在个人可信设备上使用。
3. 防范命令注入：避免将不受信任的动态输入直接作为参数。

9.3 道德准则

即使合法，也应遵循基本道德：

• 尊重创作者：下载内容供个人使用，勿未经授权二次上传。
• 支持创作者：通过点赞、订阅等方式支持你喜爱的内容提供者。
• 不要滥用：避免大规模爬取，以免对服务器造成负担。

---

附录：相关资源

• 官方仓库：github.com/yt-dlp/yt-dlp
• 官方Wiki：github.com/yt-dlp/yt-dlp/wiki
• FFmpeg官网：ffmpeg.org
• SponsorBlock：sponsor.ajay.app
• 支持的网站列表：运行 yt-dlp --list-extractors 查看。

在探索这些强大工具和 开源实战 方法的同时，也欢迎来到云栈社区与更多开发者交流，共同构建高效、自动化的数字工作流。