OpenClaw🦞養蝦基建系列[1]：yt-dlp 可下載1700個網站視頻的瑞士軍刀

感謝國內大中小廠在過去一個月中的狂飆突進，OpenClaw🦞的安裝部署已不再如一個月前那樣困難，我也基本上把國內近半數🦞的安裝部署保姆教程寫了一遍...該進入下個階段了：養蝦🦞

養蝦養蝦，養的究竟是什麼？
給🦞配上實用高效的skills；
讓🦞不常忘事兒；
讓🦞可以持續自我提升；
讓多個🦞可以彼此協作；
等等等等...... 都是養蝦

沒有兩個人（或兩個組織）的工作流是完全相同，這或許就意味着沒有兩隻🦞會相同：

• • 它們要記的東西不一樣；
• • 它們擁有的skills不同（即便是從同一個source下載的同一個skill可能也會在很短時間內演化成不同的特異化skills）；
• • 它們進化的路徑不同；
• • 它們彼此協作的模式也互不相同~

養蝦🦞的最高境界，就是能養出每個組織（現在一個人OPC也是組織）裏可以完美fit in業務場景的Agents

雖然蝦各不同，但總是會存在一些非常重要基礎設施明顯優於絕大多數其他同類的。因此，從今天開始，我將啓動一個新“養蝦基建系列”，將一些在特定任務方向上你大概率躲不掉的養蝦基建介紹給你。

今天是該系列第1篇：給大家介紹視頻下載界的瑞士軍刀yt-dlp，它可以下載1700個網站的視頻；如果你的工作流經常圍繞視頻展開（下載視頻，提取音頻，抽取文本，二次加工等等），你必然不能錯過yt-dlp；它的歸宿是：被封裝成🦞的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 的更新速度跟不上網站變化的速度時，用戶開始感受到明顯的陣痛：今天還能用的命令明天就失效了，昨天剛修復的 bug 今天又以另一種形式出現了。

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 上已經積累了近 10 萬個 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等視頻網站、直播平台、社交媒體視頻、視頻分享網站等各類國際主流視頻平台（甚至一些在這裏不能提及名字的視頻網站）……這些都是基礎配置。

國內平台同樣覆蓋全面：小紅書、Bilibili（支持分P視頻、彈幕、收藏夾、頻道）、抖音、快手、西瓜視頻、優酷、愛奇藝（部分）、騰訊視頻（部分）、微博視頻……

新聞媒體和專業站點：全球各大電視台、新聞網站、學術平台、教育站點、技術分享社區等。

音樂平台也能搞定：SoundCloud、Bandcamp、Spotify（播客）、Apple Music（部分）……你可以直接從這些平台下載音頻文件。

更有趣的是，yt-dlp 採用了一種模塊化的"提取器"（Extractor）架構。每一個支持的網站都對應一個獨立的提取器模塊，負責處理該網站的頁面解析和連結提取。這意味着當某個網站改版時，只需要更新對應的提取器即可，不會影響到其他功能。同時，這種架構也讓社區貢獻新網站的變得相對容易——有經驗的開發者可以按照既定規範編寫新的提取器，提交合並請求，經過審核後就能讓 yt-dlp 支持新的平台。

2.2 下載速度：從龜速到火箭的蜕變

很多早期用過 youtube-dl 的用戶都有一個痛苦的記憶：下載速度奇慢無比。

這不是 youtube-dl 本身的問題，而是 YouTube 的"鍋"。大約從 2021 年開始，YouTube 引入了一種基於 "n-sig"（簽名）的節流機制。簡單來說，如果系統檢測到請求來自非瀏覽器環境（比如命令行工具），就會故意限制下載速度，從正常的幾 MB/s 驟降到幾十 KB/s。以這種速度下載一個 1GB 的視頻，可能需要好幾個小時。

yt-dlp 的團隊很快注意到了這個問題。經過深入分析，他們找到了繞過這種節流機制的方法，並在 yt-dlp 中實現了相應的修復。這一改進的效果是立竿見影的：同樣網絡環境下，yt-dlp 的下載速度可以達到 16-17 MB/s，而 youtube-dl 只有 50-60 KB/s——差距達到了兩三百倍。

但這還不是全部。yt-dlp 還引入了多線程分段下載（Multi-threaded Fragment Downloads）的功能。

現代視頻網站為了優化播放體驗，普遍採用 HLS（HTTP Live Streaming）或 DASH（Dynamic Adaptive Streaming over HTTP）技術。這些技術會把一個完整的視頻切割成無數個幾秒的片段（fragments），播放時根據網絡狀況動態選擇不同清晰度的片段。這種架構對下載工具提出了新的挑戰：你需要同時下載成百上千個片段，然後再把它們拼接起來。

yt-dlp 的解決方案是並行下載。通過 --concurrent-fragments（或簡寫 -N）參數，你可以指定同時下載多少個片段。比如設置為 4，就意味着有 4 個線程同時工作，理論上可以把下載速度提升到單線程的 4 倍。再配合 aria2c 這樣的外部下載器（yt-dlp 支持調用 aria2c 來處理 HLS/DASH 流），速度還能進一步提升。

2.3 音視頻質量：不做選擇題，全都要

早期的視頻下載工具往往面臨一個兩難選擇：要麼下載畫質最好的版本（但只有視頻沒有聲音），要麼下載帶聲音但畫質一般的版本。這是因為 YouTube 等平台從某個時間點開始，將視頻流和音頻流分離存儲——高清視頻單獨一個文件，音頻單獨一個文件，播放器在播放時才會把它們合併起來。

yt-dlp 徹底解決了這個問題。當你要求下載"最佳質量"時，它會自動分析可用的格式，分別選擇畫質最好的視頻流和音質最好的音頻流，下載完成後再調用 FFmpeg 自動合併成一個完整的文件。整個過程對用戶完全透明，你拿到手的永遠是一個音畫同步、質量最優的視頻文件。

更妙的是格式選擇功能。通過 -F 參數，yt-dlp 會列出目標視頻所有可用的格式（分辨率、編碼格式、文件大小等），每個格式對應一個數字 ID。然後你可以用 -f 參數指定想要的格式，比如只下載音頻、只下載 720p 以下視頻等。甚至可以用類似 -f "bestvideo[height<=1080]+bestaudio/best" 這樣的條件語句，讓 yt-dlp 自動選擇最佳組合。

第三章：那些讓人直呼"卧槽"的高級功能

3.1 SponsorBlock：自動跳過廣告的神器

如果你經常看 YouTube 上的技術教程、測評視頻或播客，一定對"本期視頻由 XX 贊助"這種開場白深惡痛絕。更煩人的是，這類贊助片段往往長達幾十秒，而且創作者通常會把它放在視頻最精彩的部分之前，讓你不得不看完。

SponsorBlock 是一個眾包項目，它讓用戶手動標記視頻中的各種片段類型：贊助商廣告、片頭片尾、訂閲提醒、自我宣傳、無關閒聊等。這些數據被整理成一個公開的數據庫，供各種工具調用。

yt-dlp 內置了對 SponsorBlock 的支持。你可以通過 --sponsorblock-remove 參數，在下載視頻時自動刪除被標記的贊助片段。或者使用 --sponsorblock-mark 把這些片段保留下來，但標記為章節（chapter），方便你在播放器裏快速跳過。

想象一下：下載一個一小時的編程教程，裏面的三個廣告片段被自動剔除，你拿到的就是一個純淨的教學視頻。這種體驗簡直不要太爽。

3.2 從瀏覽器導入 Cookie：訪問受限內容

很多視頻網站都有年齡限制內容，需要登錄並驗證年齡後才能觀看。還有些視頻是私人的，只有特定用戶或訂閲者才能訪問。傳統的下載工具面對這種情況往往束手無策，因為它們無法提供登錄憑證。

yt-dlp 提供了一個優雅的解決方案：直接從你的瀏覽器裏讀取 Cookie。

通過 --cookies-from-browser 參數，你可以指定 Chrome、Firefox、Safari、Edge、Brave、Opera 等主流瀏覽器。yt-dlp 會自動讀取瀏覽器存儲的 Cookie 文件，提取出目標網站需要的登錄憑證。這樣一來，只要你在瀏覽器裏能看的視頻，yt-dlp 就能下載。

更貼心的是，這個操作是隻讀的——yt-dlp 只是讀取 Cookie，不會修改或泄露你的登錄信息。當然，為了安全起見，建議只在個人電腦上使用這個功能。

3.3 下載視頻的任意片段：精準裁剪

有時候你不需要下載整個視頻，只想保存其中的某個精彩片段。yt-dlp 的 --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 提供了強大的元數據（Metadata）處理能力，讓下載的文件自帶"身份證"。

首先是指定輸出文件名的模板。通過 -o 參數，你可以使用各種變量來組合文件名，比如 %(title)s（標題）、%(uploader)s（上傳者）、%(upload_date)s（日期）等。

比如 -o "%(upload_date)s_%(uploader)s_%(title)s.%(ext)s"，下載的文件名就會是"20260318_頻道名_視頻標題.mp4"的格式。

更進一步，yt-dlp 可以把這些信息直接寫入視頻文件的元數據標籤中。通過 --embed-metadata 參數，標題、藝術家、日期、描述等信息會被嵌入到 MP4、MKV 等格式文件的元數據區域，方便媒體庫軟件（如 Plex、Emby、Jellyfin）自動識別和分類。

對於音頻文件，還可以用 --embed-thumbnail 把視頻的封面圖嵌入為音頻文件的專輯封面。想象一下，下載下來的播客 MP3 在播放器裏顯示着精美的封面，體驗提升不止一個檔次。

第四章：實戰場景——yt-dlp 能為你做什麼

4.1 場景一：建立個人視頻資料庫

假設你是一名深度學習研究者，經常需要觀看各種學術報告和教程視頻。YouTube 上有大量優質內容，比如 NeurIPS、ICML 等頂會的官方頻道，各種大學教授的課程錄像，還有像 "3Blue1Brown" 這樣優秀的數學可視化頻道。

用 yt-dlp，你可以建立一個自動化的資料收集流程：

# 下載整個播放列表，按順序命名
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. 1. 下載播放列表中的所有視頻
2. 2. 文件名以兩位數序號開頭（01、02、03……），方便按順序觀看
3. 3. 限制最高 1080p 分辨率（節省硬盤空間）
4. 4. 嵌入元數據和英文字幕
5. 5. 如果視頻本身沒有字幕，還會嘗試下載自動生成的字幕

4.2 場景二：音頻播客訂閲

很多優質的播客內容發佈在 YouTube 上，但你可能更習慣在通勤時用耳機聽音頻版。yt-dlp 可以把視頻一鍵轉換為音頻：

# 提取最佳音質音頻並轉換為 MP3
yt-dlp -x --audio-format mp3 --audio-quality 0 \
       --embed-thumbnail --embed-metadata \
       -o "%(uploader)s/%(title)s.%(ext)s" \
       "VIDEO_URL"

參數說明：

• • -x（或 --extract-audio）：只提取音頻
• • --audio-format mp3：轉換為 MP3 格式（還支持 aac、m4a、opus、vorbis、flac、wav）
• • --audio-quality 0：最高音質（0-10，0 是最好，9 是最差）
• • --embed-thumbnail：把視頻封面嵌入為音頻封面
• • --embed-metadata：寫入標題、藝術家等元數據

4.3 場景三：字幕提取與翻譯

看外語視頻時，字幕是剛需。yt-dlp 支持下載視頻的各種字幕：

# 下載所有可用字幕（包括自動生成）
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 場景五：代理與網絡環境

在某些網絡環境下（比如公司內網），直接訪問外部視頻平台可能會受限。yt-dlp 支持通過代理連接，具體配置方式如下：

# 使用 HTTP 代理
yt-dlp --proxy http://代理地址:端口 "URL"

# 使用 SOCKS5 代理
yt-dlp --proxy socks5://代理地址:端口 "URL"

此外，yt-dlp 還提供了一些處理地理限制內容的參數，具體可參考官方文檔。

第五章：yt-dlp vs youtube-dl：為什麼要"背叛"經典

雖然 youtube-dl 是 yt-dlp 的"父輩"，但在 2026 年的今天，選擇 yt-dlp 幾乎是毫無懸念的決定。以下是關鍵差異的詳細對比：

5.1 維護狀態：活人與殭屍的區別

youtube-dl 的最後一次實質性更新停留在 2021 年底。雖然項目沒有被正式放棄，但維護者幾乎不再合併社區提交的修復補丁。這意味着當 YouTube、TikTok 等平台調整頁面結構或 API 時，youtube-dl 無法及時響應，用戶只能面對各種報錯信息乾瞪眼。

相比之下，yt-dlp 保持着每週甚至每天更新的節奏。開發團隊和社區貢獻者們時刻關注着各大視頻平台的變化，一旦發現網站改版導致提取器失效，通常幾小時內就會有修復版本發佈。

5.2 功能對比：麻雀與鳳凰

5.3 默認行為的優化

yt-dlp 不僅在功能上更豐富，默認設置也更加合理：

• • 格式選擇策略：yt-dlp 默認優先選擇更高分辨率和更先進編碼格式（如 AV1、VP9）的視頻，而 youtube-dl 只看碼率
• • 文件名模板：yt-dlp 默認在文件名中包含視頻 ID（[%(id)s]），方便追溯來源；youtube-dl 不包含
• • 縮略圖嵌入：yt-dlp 使用 mutagen 庫處理 MP4 文件的縮略圖嵌入，速度更快且無需額外依賴；youtube-dl 依賴 AtomicParsley
• • 錯誤處理：yt-dlp 默認開啓 --no-abort-on-error，遇到錯誤會繼續處理列表中的其他視頻；youtube-dl 默認遇到錯誤就終止

5.4 Python 版本要求

yt-dlp 要求 Python 3.9 或更高版本（Python 3.8 已於 2024 年 11 月結束支持）。這讓它可以使用 Python 的現代特性，代碼更簡潔高效。

youtube-dl 為了兼容性，至今仍支持 Python 2.6+，這意味着大量過時的代碼包袱和無法使用新特性。

5.5 遷移成本

好消息是，從 youtube-dl 遷移到 yt-dlp 幾乎沒有學習成本。兩者命令行參數高度兼容，絕大多數 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 會自動選擇最佳格式，下載到當前目錄，文件名為"視頻標題 [視頻ID].webm/mp4"。

6.3 常用參數速查表

6.4 配置文件的妙用

如果你有一些每次都要用的參數（比如總是想嵌入元數據、總是限制 1080p 分辨率），可以把它們寫到配置文件中，避免每次手動輸入。

配置文件位置：

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

所有預設的參數會自動生效。

第七章：進階玩法——成為 yt-dlp 高手

7.1 腳本自動化

yt-dlp 的真正威力在於可以嵌入到自動化腳本中。以下是一些實用示例：

批量下載多個視頻：

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

提取視頻信息（不下載）：

# 獲取標題
yt-dlp --get-title "URL"

# 獲取時長
yt-dlp --get-duration "URL"

# 獲取所有信息（JSON 格式）
yt-dlp -j "URL" | jq .

7.2 Python API 調用

yt-dlp 不僅是命令行工具，還是一個 Python 庫。你可以在 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=...'])

這種方式特別適合集成到更大的應用程序中，或者進行更復雜的流程控制。

7.3 與 FFmpeg 的深度配合

yt-dlp 和 FFmpeg 的組合可以完成很多複雜的視頻處理任務。

僅下載特定時間段（精確裁剪）：

# 下載視頻的 30 秒到 90 秒部分
yt-dlp --external-downloader ffmpeg \
       --external-downloader-args "ffmpeg_i:-ss 00:00:30 -to 00:01:30" \
       "URL"

下載後自動壓縮視頻：

yt-dlp --postprocessor-args "FFmpegVideoConvertor:-c:v libx264 -crf 23 -preset fast" \
       "URL"

7.4 插件系統

yt-dlp 支持加載外部的提取器和後處理器插件。這意味着即使官方版本不支持某個網站，你也可以自己編寫或使用社區提供的插件來擴展功能。

插件通常放在特定的目錄中：

• • Linux/macOS：~config/yt-dlp/plugins
• • Windows：%APPDATA%/yt-dlp/plugins

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

如果你已經讀到這裏，應該對 yt-dlp 的強大功能有了充分的認識。但接下來的問題是：如何把這樣一個強大的 CLI 工具，變成 OpenClaw 能夠穩定調用的能力模塊？

這不僅僅是"套個殼"那麼簡單。真正的 Skill 化，是把命令提煉成穩定、可交付、可運營的能力。

8.1 為什麼要 Skill 化？

yt-dlp 的參數很多，高手嚮明顯。-f、--format-sort、--cookies-from-browser、--download-archive……新人一看很容易懵掉。

更重要的是：

• • 輸出並不天然適合自動化消費（有時視頻、有時音頻，stdout 一大坨日誌）
• • 失敗信息混在一起（登錄態、限流、網絡問題、格式問題），難以診斷
• • 調用方式不穩定，換個環境就忘了參數含義

OpenClaw 的目標不是讓你手搓命令，而是讓 Agent、其他實例、未來的自己，都能用低心智負擔反覆完成同一類任務。

8.2 Skill 化的九個階段

把 yt-dlp 封裝成 yt-dlp-media Skill 的過程，大致經歷了這九個階段：

重要提示：你並不需要手動完成後面的步驟，因此這裏僅總結了大致的步驟和階段。你可以跟🦞說：
請深刻理解yt-dlp項目的repo：https://github.com/yt-dlp/yt-dlp  然後請按照這篇文章中的方法（這篇文章的連結）將yt-dlp封裝為skill

第一階段：MVP 先行
不追求大全，只抓住最高頻的動作：下載視頻、提取音頻、下載字幕、獲取元數據、批量處理。先閉環，不先完美。

第二階段：統一入口
別讓腳本散落各處。建立 scripts/yt_dlp.sh 作為穩定 facade：

scripts/yt_dlp.sh video --url 'https://...'
scripts/yt_dlp.sh audio --url 'https://...'
scripts/yt_dlp.sh subtitles --url 'https://...'

外部只認這個入口，內部怎麼重構都不影響調用方。

第三階段：預設替代參數海
不要暴露底層參數，而是提供 preset：

• • 視頻：best / balanced / mobile
• • 音頻：audio_only

讓默認行為就能跑出大多數人滿意的結果。

第四階段：把失敗當成一等公民
媒體下載的失敗是主流程，不是邊緣情況。建立錯誤分類：

• • ERR_NO_YTDLP / ERR_NO_FFMPEG —— 環境缺失
• • ERR_UNSUPPORTED_URL —— URL 不支持
• • ERR_AUTH_REQUIRED —— 需要登錄
• • ERR_RATE_LIMITED —— 被限流
• • ERR_EXTRACTOR_BROKEN —— 提取器失效

這樣 Agent 才能決定下一步：重試、加 cookies、還是提示更新 yt-dlp。

第五階段：結果結構化
不只是"下載完成"，而是明確產出：

RESULT:file=...
RESULT:info_json=...
RESULT:thumbnail=...
RESULT:result_json=...

讓下游腳本和 Agent 都能穩定消費。

第六階段：輕量 Job 系統
下載可能持續很久，transcript 可能更久。引入基於目錄狀態機的 job 模型：

scripts/yt_dlp.sh job submit probe --url URL
scripts/yt_dlp.sh job status <job_id>
scripts/yt_dlp.sh job tail <job_id>

不依賴數據庫或消息隊列，簡單、易排障、適合 Agent 場景。

第七階段：輕量站點畫像
不同站點行為不同，但不要寫第二套 extractor。用 site profile 做"默認值偏置"：

• • YouTube / Bilibili 偏 balanced
• • 小紅書 / X 偏 mobile
• • 某些站點更可能需要 cookies

第八階段：打通完整任務鏈
不只是"多一個參數"，而是端到端的工作流。比如 transcript 流程：

1. 1. 下載源視頻（保留！）
2. 2. 抽取音頻 → mono 16kHz wav
3. 3. 送到 ASR 服務
4. 4. 生成 raw transcript → cleaned transcript

輸出完整產物鏈，讓用戶可以回看、校對、二次整理。

第九階段：文檔即交付物
真正的 Skill 不只是代碼，而是 代碼 + 約定 + 文檔：

• • SKILL.md —— 核心規則、推薦入口
• • setup-and-runtime.md —— 安裝、依賴、環境變量
• • end-to-end-examples.md —— 可複製的用例
• • troubleshooting.md —— 典型問題排查

8.3 核心方法論

整個過程可以壓縮成 8 句話：

1. 1. 保留內核，不要重造輪子 —— yt-dlp 的 extractor 能力很強，Skill 只負責包裝
2. 2. 先做高頻閉環，不先做大全 —— 解決 80% 的真實需求
3. 3. 儘快建立統一入口 —— 外部只認穩定 facade
4. 4. 用預設替代參數海 —— 降低使用門檻
5. 5. 失敗要分類 —— 否則無法維護和運營
6. 6. 輸出要結構化 —— 否則自動化很脆
7. 7. 長任務要有 Job 模型 —— 別全靠前台命令
8. 8. 文檔和代碼同等重要 —— 別人能不能複用，不看功能多少

8.4 OpenClaw Skill 的本質

不是把命令搬進 Agent，而是把命令提煉成能力。

OpenClaw Skill 真正有價值的地方，不是"我會調工具"，而是：

• • 能把複雜工具收斂成穩定入口
• • 能把易碎命令變成結果清晰的能力
• • 能把一次性腳本變成別人也能接手的工作流

yt-dlp 本體負責"下載能力"，yt-dlp-media Skill 負責"交付能力"。這兩者缺一不可。

8.5 一些真實case

• • 將小某書的視頻連結發給OpenClaw🦞
• • 讓🦞下載這條視頻
• • 讓🦞抽取音頻
• • 讓🦞抽取音頻中的文字（需要多模態大模型，性價比最高的可能是"google/gemini-3.1-flash-lite-preview",可以通過OpenRouter調用，需要配置OpenRouter的API Key）
• • 要求🦞對文本進行清洗，然後進行二次加工，例如：生成思維導圖、生成PPT、風格化改寫、等等
• • 以上所有內容通過企微“智能表格”來管理和中轉
  

  

第九章：安全與合法性——使用前必須知道的事

9.1 法律風險

下載視頻的合法性因國家和地區而異，也因用途而異。一般來說：

• • 個人學習、研究用途：大多數國家的版權法允許為個人使用而複製受版權保護的作品
• • 再次分發、商業用途：通常需要獲得版權持有者的授權
• • DRM 破解：繞過數字版權管理（DRM）保護在很多國家是違法的，yt-dlp 也不支持下載 DRM 保護的內容

重要原則：yt-dlp 只下載網站公開提供的內容。如果一個視頻在瀏覽器裏無需登錄就能觀看，yt-dlp 通常也能下載；如果需要付費訂閲或特殊權限，yt-dlp 也無法繞過。

9.2 安全風險

作為一個命令行工具，yt-dlp 本身沒有廣告軟件或惡意代碼。它是開源的，代碼託管在 GitHub 上，任何人都可以審計。

但需要注意以下幾點：

1. 只從官方渠道下載

• • 官方網站：https://github.com/yt-dlp/yt-dlp
• • 官方發佈的可執行文件在 GitHub Releases 頁面
• • 不要使用來路不明的第三方下載站點

2. Cookie 安全
使用 --cookies-from-browser 時，yt-dlp 會讀取瀏覽器的 Cookie 數據。雖然 yt-dlp 不會上傳或泄露這些數據，但建議只在個人電腦上使用此功能，不要在公共或共享電腦上使用。

3. 命令注入風險
在極少數情況下，如果在參數中使用了不受信任的輸入（比如從網頁直接複製視頻標題作為文件名），可能存在命令注入風險。建議對動態輸入進行適當的轉義或過濾。

9.3 道德準則

即使法律允許，下載視頻也應該遵循一些基本的道德準則：

• • 尊重創作者的勞動成果：下載的視頻僅供個人使用，不要未經授權再次上傳到其他地方
• • 支持你喜歡的創作者：如果某個創作者的內容對你有價值，考慮通過點贊、訂閲、打賞等方式支持他們
• • 不要濫用：不要大規模爬取網站內容，這可能會給服務器帶來負擔，甚至導致 IP 被封禁

附錄：相關資源

• • 官方倉庫：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 查看完整列表