核心用法
youtube-search 是一款专注于 YouTube 内容检索的 Agent Skill，通过 TranscriptAPI.com 提供的服务实现三大核心功能：全局视频/频道搜索、指定频道内精准检索，以及视频字幕转录获取。用户可通过自然语言触发搜索意图（如"查找关于 X 的视频""搜索某频道"），Skill 会自动调用 API 返回结构化数据，包括视频元数据（标题、时长、观看量、发布时间、缩略图）、频道信息（订阅数、认证状态、RSS 源）以及可下载的字幕文本。
使用流程分为两步：首次使用需通过邮箱注册获取 API Key（100 免费积分，无需绑卡），验证后密钥自动保存至本地配置；日常调用时直接发起搜索请求，按 1 积分/次计费，支持视频搜索、频道搜索、频道内搜索三种模式，并可链式调用字幕接口获取带时间戳的完整文本。
显著优点
精准检索能力：支持 @handle、频道 URL 或 UC... ID 三种格式定位频道，可在特定创作者内容库中深度搜索，解决 YouTube 原生搜索难以限定单一来源的痛点。结构化数据输出：返回包含 hasCaptions 标记、、channelVerified 认证状态、、rssUrl 订阅源等丰富字段，便于二次开发集成。零门槛试用：100 免费积分 + 无需信用卡的注册机制，降低体验成本。完善的本地配置管理：自动备份机制确保配置修改安全，API Key 本地存储减少泄露风险。
潜在缺点与局限性
付费依赖：免费额度有限（100 积分约支持 100 次搜索），高频使用需订阅付费计划，存在持续成本。第三方服务依赖：核心功能完全依赖 TranscriptAPI.com 的可用性，若服务中断或调整定价，Skill 将失效。YouTube 数据限制：频道内搜索最多返回约 30 条结果（YouTube 接口限制），大规模内容分析需多次分页调用。无原生视频播放：仅提供元数据和字幕，不直接嵌入视频播放或下载功能。地理与版权限制：部分视频因区域限制或创作者关闭字幕，无法获取转录文本。
适合的目标群体
内容研究者与学术用户：需要批量获取 YouTube 视频字幕进行文本分析、主题建模或引用标注。知识管理爱好者：构建个人视频知识库，将视频内容转化为可搜索的文本笔记。竞品分析与市场调研人员：追踪特定频道的内容策略，分析热门视频标题与发布规律。播客与内容创作者：快速检索行业相关视频素材，提取引用片段或研究竞品脚本。自动化工作流开发者：将 YouTube 搜索集成到 RAG 系统、内容监控机器人或自动摘要 pipeline 中。
使用风险
API 配额管理：免费额度消耗较快，生产环境需监控用量并设置预算告警，避免意外超额。网络稳定性：依赖外部 API 服务，超时（408 错误）或限流（402 错误）时需实现重试逻辑。数据隐私：搜索关键词和获取的字幕内容会经过 TranscriptAPI 服务器，敏感主题检索需注意合规性。配置权限：建议设置 ~/.openclaw// 目录为 600 权限，防止多用户环境下 API Key 被读取。服务连续性风险：TranscriptAPI 作为商业服务存在被收购、调价或终止的可能，关键业务建议保留替代方案。