YouTube Skills for AI Agents 详细部署教程

项目概述

YouTube Skills for AI Agents 是一个专为 AI 代理设计的技能包，让你的 AI 代理能够即时访问 YouTube 字幕提取、视频搜索、频道数据和播放列表提取功能。

核心优势：

  • 无需 yt-dlp：YouTube 会屏蔽所有主要云 IP，而此方案通过 API 调用绕过此限制
  • 无需无头浏览器：不需要运行 Chrome/Firefox 等浏览器
  • 无需二进制文件：纯 API 调用，可在任何环境运行
  • 基于 TranscriptAPI：由 YouTubeToTranscript.com 背后的同一后端提供支持

兼容的 AI 代理：

  • 🦞 OpenClaw (ClawdBot/Moltbot)
  • Hermes Agent
  • Claude Code
  • Cursor
  • Antigravity
  • Cline
  • Codex
  • 其他支持 Agent Skills 格式的代理

免费额度：注册即送 100 credits，无需信用卡。

部署前准备

系统要求

项目 要求
Node.js 18+（用于运行 npx skills 命令）
操作系统 Windows / macOS / Linux
网络 需能访问 TranscriptAPI.com

环境检查

1
2
node --version
npx --version

获取 API Key（可选）

虽然安装后代理会自动引导你获取 API Key，但你也可以提前手动准备：

  1. 访问 transcriptapi.com 注册账户（免费，无需信用卡）
  2. 从仪表板复制 API Key（以 sk_ 开头）
  3. 保存备用

方案一：为 OpenClaw 安装（推荐）

如果你使用 OpenClaw（ClawdBot/Moltbot），这是最简单的安装方式。

步骤 1：执行安装命令

1
npx clawhub@latest install youtube-full

步骤 2：验证安装

安装完成后，你的 OpenClaw 代理即可使用 YouTube 相关功能。

步骤 3：首次使用

首次运行时，代理会自动引导你完成 API Key 设置：

  1. 代理会询问你的电子邮件地址并在 TranscriptAPI 注册
  2. 你会收到一封包含 OTP 验证码的邮件——代理会要求你输入
  3. 验证完成后，代理会自动将 API Key 保存到你的 shell 和代理配置中

方案二：为 Hermes Agent 安装

步骤 1：执行安装命令

1
hermes skills install skills-sh/ZeroPointRepo/youtube-skills/skills/youtube-full

步骤 2：API Key 存储位置

Hermes Agent 会将 API Key 存储在 Hermes secret store 中（通过技能 frontmatter 中的 required_environment_variables 声明 TRANSCRIPT_API_KEY）。

方案三：为 Claude Code / Cursor / Antigravity / Cline / Codex 安装

步骤 1：执行安装命令

1
npx skills add ZeroPointRepo/youtube-skills --skill youtube-full

步骤 2：选择目标代理

执行命令时，CLI 会提示你选择要安装到的代理（可多选）。

步骤 3：安装所有 12 个技能（可选）

如果你希望一次性安装全部技能：

1
npx skills add ZeroPointRepo/youtube-skills

方案四：手动安装（Git Clone）

如果你需要完全控制安装过程：

步骤 1：克隆仓库

1
git clone https://github.com/ZeroPointRepo/youtube-skills.git

步骤 2：复制技能目录

1
2
3
4
5
6
7
# Claude Code
cp -r youtube-skills/skills/youtube-full ~/.claude/skills/

# Codex
cp -r youtube-skills/skills/youtube-full ~/.codex/skills/

# 其他代理类似，复制到对应的 skills 目录

步骤 3：配置 API Key（手动方式）

如果你不想让代理自动获取，可以手动配置：

1
export TRANSCRIPT_API_KEY="sk_your_key_here"

API Key 保存位置（由代理自动存储）：

运行时 文件位置
OpenClaw/Moltbot ~/.openclaw/openclaw.json 或 ~/.clawdbot/moltbot.json
Hermes Agent Hermes secret store
macOS shell ~/.zshenv、~/.zprofile
Linux shell ~/.profile、~/.bashrc、~/.zshenv
Fish shell ~/.config/fish/config.fish
回退方案 ~/.transcriptapi（权限 600）

非开发者快速上手

如果你不是开发者，只需将以下提示粘贴到你的 AI 代理（OpenClaw、Hermes Agent、Claude、ChatGPT 等）：

text

1
2
3
Install the youtube skills from this GitHub repo: https://github.com/ZeroPointRepo/youtube-skills
I want to be able to get YouTube transcripts, search YouTube, and browse channel videos from my agent.
Set everything up for me.

代理会自动处理其余所有事项。

技能选择指南

youtube-full 是推荐给大多数用户的技能，包含所有功能。如果你需要更小的、专注的技能（更小的上下文 = 特定任务更好的代理性能），可以按需选择：

技能 功能 安装命令
youtube-full 全部功能——字幕、搜索、频道、播放列表 --skill youtube-full
transcript 获取带时间戳的视频字幕 --skill transcript
youtube-search 搜索 YouTube 视频和频道 --skill youtube-search
youtube-channels 浏览上传、获取最新视频、解析 @handle --skill youtube-channels
youtube-playlist 提取播放列表中的所有视频 --skill youtube-playlist

安装特定技能

1
2
3
4
5
# 安装特定技能
npx skills add ZeroPointRepo/youtube-skills --skill transcript

# 安装多个特定技能
npx skills add ZeroPointRepo/youtube-skills --skill transcript --skill youtube-search

全部 12 个技能

技能 描述
youtube-full 完整的 YouTube 工具包——字幕 + 搜索 + 频道 + 播放列表
transcript 从任何 YouTube 视频提取带时间戳的字幕
captions 获取 YouTube 视频的隐藏字幕/CC
subtitles 提取 YouTube 视频的字幕
youtube-search 搜索 YouTube 视频和频道
youtube-channels 浏览频道上传、获取最新视频、解析 @handle
youtube-playlist 从 YouTube 播放列表获取所有视频
youtube-data 获取 YouTube 视频和频道数据（Google API 的轻量替代）
youtube-api 供 AI 代理使用的 YouTube API——无需 Google 配额麻烦
transcriptapi 完整的 TranscriptAPI 访问权限，包含所有端点
video-transcript 将 YouTube 视频转换为文本字幕
yt 快速 YouTube 工具，用于快速查询

使用示例

安装完成后，直接向你的代理提出请求即可，无需配置或代码：

任务 示例提示
获取 YouTube 字幕 “总结这个视频：[URL]”
搜索 YouTube “查找关于机器学习的视频”
浏览频道 “TED 这周发布了什么？”
获取播放列表内容 “列出这个播放列表中的所有视频”
提取视频字幕 “获取这个视频的西班牙语字幕”
批量字幕 “获取这个频道每个视频的字幕”
研究主题 “查找并总结关于量子计算的前 5 个视频”
获取最新上传 “给我看 NASA 最近的视频”
在频道内搜索 “在 TED 频道搜索’人工智能’”

定价方案

方案 价格 Credits 速率限制
免费 $0 注册送 100 credits 300 req/min
Starter $5/月 1,000 credits/月 300 req/min
Starter 年付 $54/年（$4.50/月） 1,000 credits/月 300 req/min

说明：

  • 大多数操作花费 1 credit
  • 频道解析和最新视频免费
  • 免费层无需信用卡

常见问题排查

症状 可能原因 解决方案
401 Unauthorized API Key 缺失、输入错误或未加载到环境 确认 TRANSCRIPT_API_KEY 已在代理运行的 shell 中设置，且 Key 以 sk_ 开头
402 Payment Required 账户 credits 用尽 在 transcriptapi.com/billing 检查余额
403 带 Cloudflare 代码 1010 请求未发送 User-Agent 头 发送你的代理名称作为 User-Agent，例如 HermesAgent/0.11.0
404 Not Found 视频没有字幕、非公开或 ID 错误 验证 URL 在浏览器中打开且播放器显示字幕
408 Request Timeout 视频上游临时压力 临时性问题：等待几秒后重试一次
422 Validation Error 参数格式错误，如错误的频道或播放列表引用 频道接受 @handle、频道 URL 或 UC ID；播放列表接受 PL、UU、LL、FL 和 OL 前缀
429 Too Many Requests 达到速率限制 等待并遵守 Retry-After 头

其他注意事项

  • Key 已保存但代理看不到：Shell 配置文件按 shell 类型加载，检查”Key 保存位置”表格，确保文件匹配代理实际运行的 shell。保存 Key 后重启代理可解决大多数情况
  • 直播和首播：字幕在直播结束且字幕处理完成后才可用，直播期间不可用
  • 字幕语言不符合预期：许多视频仅携带原始语言的字幕。使用首选语言参数请求字幕，或让代理翻译结果

常见问题 FAQ

如何获取 YouTube 字幕？

安装 youtube-full（或 transcript），然后询问代理：

“获取这个视频的字幕：https://youtube.com/watch?v=VIDEO_ID“

代理会获取带时间戳的完整字幕，然后你可以让它总结、翻译、引用或分析内容。

如何从代理搜索 YouTube？

安装 youtube-full（或 youtube-search），然后询问：

“查找关于机器学习的视频”

返回最多 50 个结果，包含标题、缩略图、观看次数和发布日期。

需要 Google YouTube Data API Key 吗？

不需要。 TranscriptAPI 替代了 Google YouTube Data API 的字幕提取、搜索和频道/播放列表操作。无需 Google Cloud 项目、无配额限制、无需 OAuth 设置。

需要 API Key 吗？

需要，但注册免费且即时——100 credits，无需信用卡。你的代理会在首次运行时自动处理设置。

更新与维护

更新技能

1
2
3
4
5
# OpenClaw
npx clawhub@latest update youtube-full

# 其他代理
npx skills add ZeroPointRepo/youtube-skills --skill youtube-full

查看当前版本

1
npx skills list

总结

部署方式 适用场景 难度 推荐度
OpenClaw 安装 OpenClaw 用户 ⭐ ⭐⭐⭐⭐⭐
Hermes Agent 安装 Hermes 用户 ⭐ ⭐⭐⭐⭐⭐
Skills CLI 安装 Claude Code/Cursor 等 ⭐ ⭐⭐⭐⭐⭐
手动 Git Clone 需要完全控制 ⭐⭐ ⭐⭐⭐

对于大多数用户，根据你使用的代理选择对应的安装方式即可：

1
2
3
4
5
6
7
8
# OpenClaw
npx clawhub@latest install youtube-full

# Claude Code / Cursor / Codex 等
npx skills add ZeroPointRepo/youtube-skills --skill youtube-full

# Hermes Agent
hermes skills install skills-sh/ZeroPointRepo/youtube-skills/skills/youtube-full

安装完成后，首次运行时代理会引导你完成免费的 API Key 设置。之后，你可以直接用自然语言向代理请求 YouTube 相关操作，例如获取字幕、搜索视频、浏览频道或提取播放列表。