基于OpenClaw与本地LLM网关，构建AI驱动的YouTube视频智能分析工具-平芜编程栈

1. 项目概述：基于OpenClaw的AI技能库

最近在折腾一个挺有意思的项目，叫OpenClaw-Skills。简单来说，它是一个建立在OpenClaw LLM网关之上的、由AI驱动的命令行工具集合。你可以把它理解为一个“技能库”，每个技能都是一个独立的、能完成特定任务的CLI工具。目前这个库里最成熟的一个技能，就是YouTube视频总结器。这个工具能干的事儿挺多，不只是生成摘要，还能进行基于字幕的问答、深度分析，甚至提取视频里的行动要点，而且最棒的是它支持多语言——视频是什么语言，它就能用什么语言来分析和回复，完全不用你手动切换。

我之所以花时间研究并部署这套东西，是因为每天要看的视频和资料实在太多了。无论是技术教程、行业访谈还是产品发布会，动辄一小时的长度，想快速抓住核心内容非常耗时。市面上虽然有一些摘要工具，但要么是纯云端服务有隐私顾虑，要么功能单一（比如只给个摘要，没法追问细节），要么对非英语内容支持得很差。OpenClaw-Skills的YouTube技能正好解决了这几个痛点：它在本地通过多种方式获取字幕，利用本地的OpenClaw网关调用大模型，整个过程数据可控；它提供了摘要、问答、深度分析、行动提取四种模式，能满足不同深度的信息消化需求；最关键的是它的语言自适应能力，处理日语、西班牙语、印地语的内容和英语一样流畅。

这个项目非常适合那些需要高效处理视频信息的内容创作者、研究者、学生，或者任何想从海量视频内容中快速提炼价值的开发者。它不是一个庞大的全功能应用，而是一个个轻量、专注、可组合的“技能”，你可以按需使用，甚至基于它的框架快速开发自己的新技能。接下来，我就结合自己的实操经验，带你从零开始把它跑起来，并深入聊聊每个环节的设计思路和避坑指南。

2. 核心架构与设计思路拆解

2.1 整体项目结构：模块化与技能独立性的权衡

刚拿到这个项目源码时，我第一眼关注的是它的目录结构。它没有采用传统的、把所有逻辑堆在一个文件里的方式，而是清晰地体现了“技能即插件”的思想。

openclaw-skills/ ├── index.ts ├── package.json └── src/ └── youtube/ ├── cli.ts ├── config.ts ├── types.ts ├── client.ts ├── youtube.ts ├── transcript.ts ├── cache.ts ├── chunks.ts ├── llm.ts └── qa.ts

index.ts是整个项目的入口，但它的角色更像一个“路由器”或“加载器”。它的核心逻辑是动态导入当前激活技能的cli.ts中的main函数并执行。这种设计意味着，未来增加新技能（比如src/twitter/或src/podcast/）时，只需要修改index.ts中的导入路径，或者通过更动态的配置来指定当前要运行的技能，项目的主体架构完全不用动。这为技能库的扩展打下了非常好的基础。

src/youtube/目录是第一个也是目前唯一的技能实现。里面的文件分工非常明确，体现了单一职责原则。我特别喜欢这种分法：

cli.ts：负责命令行参数的解析（使用commander或类似库）和整个技能执行流程的编排。它是用户交互的边界。
config.ts：集中存放所有常量、提示词模板和大模型调用参数。把提示词这种经常需要调整的内容独立出来，修改时不用去业务逻辑里翻找，非常方便。
types.ts：定义了整个技能用到的 TypeScript 接口。比如视频元数据、字幕块、缓存项、LLM请求/响应体的结构。这不仅是类型安全的需要，更是项目的一份“数据字典”，让人一眼就能看懂核心数据结构。
client.ts：管理youtubei.js（一个优秀的非官方YouTube API库）客户端的单例。确保整个应用生命周期内只创建一个客户端实例，避免重复登录和资源浪费。
youtube.ts：封装了与YouTube数据相关的操作，主要是根据频道ID或URL获取视频列表，以及获取视频的基本元数据（标题、时长、频道名等）。
transcript.ts：这是整个技能的“心脏”之一，实现了三层递进的字幕获取管道。它的健壮性直接决定了技能的上限。
cache.ts：实现基于磁盘文件的JSON缓存。对于字幕这种获取成本较高（可能触发反爬）且不常变的数据，缓存能极大提升重复查询的速度和成功率。
chunks.ts：负责将长字幕文本切割成有意义的块，并为后续的问答模式实现基于TF-IDF等算法的检索，确保答案“有据可查”。
llm.ts：封装了对OpenClaw网关的调用，针对不同的模式（摘要、深度分析、行动提取）构造不同的提示词并发起请求。
qa.ts：问答模式的核心，它协调chunks.ts进行检索，从找到的相关字幕块中提取信息，并调用llm.ts生成最终答案，同时会标记答案是否“有据可依”。

这种架构的好处是高内聚、低耦合。每个文件职责清晰，测试和调试时可以单独针对某个模块。比如你想优化字幕获取成功率，就专注改transcript.ts；想调整摘要的格式和深度，就去config.ts里改提示词。这种设计思路非常值得我们在开发自己的自动化工具时借鉴。

2.2 核心依赖选型：为什么是它们？

项目的技术选型也经过了一番考量，不是随便抓几个流行的库就来用。

Bun 作为运行时：项目要求 Bun >= 1.3。Bun 不仅仅是一个像 Node.js 或 Deno 的 JavaScript 运行时，它内置了打包器、转译器和 npm 客户端，速度非常快。对于这种 CLI 工具，启动速度和依赖安装的便捷性很重要。使用 Bun 可以bun install一键安装所有依赖，并且运行 TypeScript 文件无需预先编译，开发体验很流畅。不过在实际部署时需要注意，如果生产环境没有 Bun，可能需要用bun build编译成可执行的单一文件。
OpenClaw 作为 LLM 网关：这是项目的核心前提。OpenClaw 是一个统一的大语言模型网关，它可以对接后端不同的 LLM 服务（如 OpenAI API、本地部署的 Ollama、Claude 等）。这样做的好处是将业务逻辑与具体的大模型提供商解耦。你的代码里只需要向http://localhost:3000发送标准格式的请求，而具体由哪个模型处理、密钥如何管理，都在 OpenClaw 网关层面配置。这带来了巨大的灵活性和安全性，切换模型只需改网关配置，而不需要修改技能代码。
youtubei.js 作为首选 API：获取 YouTube 数据，尤其是官方字幕，有很多方法。项目首选了youtubei.js这个库。它是一个对 YouTube 内部 API (Innertube) 的反向工程实现，能模拟官方客户端的请求。相比于直接爬取网页，它的优势是结构化程度高、稳定性相对更好，能直接获取到 JSON 格式的字幕轨道信息，包括每个字幕片段的起止时间和文本。这是获取字幕最“干净”的方式。
yt-dlp 作为保底方案：yt-dlp是youtube-dl的一个强大分支，几乎是处理 YouTube 视频下载和相关信息提取的“瑞士军刀”。在这个项目里，它扮演了“最后一道防线”的角色。当前两种方法都失败时（比如视频没有官方字幕，且网页上也没有可抓取的隐藏字幕），yt-dlp可以尝试下载自动生成的字幕。这里有一个关键细节：项目会优先检测视频的原始语言，然后只请求该语言的自动字幕，避免了去请求可能不存在的翻译轨道，从而减少无效请求和触发风控的概率。
TypeScript 保障代码质量：整个项目用 TypeScript 编写，这为这种涉及多个步骤、多种数据流转的复杂 CLI 工具提供了坚实的类型安全基础。它能有效避免很多低级错误，比如字段名拼写错误、错误的数据类型传递等，尤其是在频繁修改提示词和数据结构时，类型检查能提供即时反馈。

这样的技术栈组合，体现了一个务实的选择：用最适合、最专业的工具解决特定问题，并通过清晰的架构将它们组合起来，而不是追求一个“全能”但可能臃肿的解决方案。

3. 环境准备与详细配置指南

3.1 基础运行环境搭建

要让这个技能跑起来，你需要准备好以下四样东西：Bun 运行时、yt-dlp 工具、一个运行中的 OpenClaw 网关实例，以及对应的认证文件。下面我一步步带你操作，并说明每个环节的注意事项。

第一步：安装 Bun如果你的系统还没安装 Bun，官方的一键安装脚本是最快的方式。打开你的终端，执行以下命令：

curl -fsSL https://bun.sh/install | bash

安装完成后，重启你的终端，或者运行source ~/.bashrc（或~/.zshrc）来让 bun 命令生效。用bun --version检查是否安装成功，确保版本至少是 1.3。

注意：如果你在公司的网络环境下，可能会因为网络策略问题导致 curl 下载失败。这时可以尝试使用包管理器安装，比如在 macOS 上用 Homebrew (brew install oven-sh/bun/bun)，或者在 Ubuntu 上参考官方文档添加 apt 源。Windows 用户可以通过 Windows Subsystem for Linux (WSL) 来获得最好的体验。

第二步：安装 yt-dlpyt-dlp的安装方式也很多。我推荐直接用 curl 下载可执行文件，这样最干净，不依赖系统的 Python 环境。

sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp sudo chmod +x /usr/local/bin/yt-dlp

这两条命令的作用是：从 GitHub 发布页下载最新的 yt-dlp 二进制文件，放到/usr/local/bin目录下（这个目录通常已经在系统的 PATH 环境变量里），然后赋予它可执行权限。安装后，在终端输入yt-dlp --version应该能看到版本号。

踩坑提示：有些 Linux 发行版或 macOS 系统可能对/usr/local/bin的写入权限管理很严格。如果遇到权限错误，可以尝试不加sudo下载到用户目录，比如~/bin/yt-dlp，然后确保~/bin目录在你的 PATH 中 (export PATH="$HOME/bin:$PATH")。Windows 用户可以去发布页面直接下载yt-dlp.exe，然后将其所在目录添加到系统环境变量 PATH 中。

第三步：部署与配置 OpenClaw 网关这是整个项目的大脑。OpenClaw 网关需要单独部署。通常，你可以克隆它的仓库，然后根据其 README 在本地运行。假设你已经在http://localhost:3000跑起来了一个 OpenClaw 服务，并且配置好了后端的大模型（比如接入了 OpenAI 的 API 或者本地运行的 Llama 模型）。

接下来是最关键的一步：获取并配置认证令牌。OpenClaw 网关需要 token 来验证请求。这个 token 的获取方式取决于你的 OpenClaw 配置。通常，在 OpenClaw 的配置文件或管理界面中，你可以生成一个长期有效的 token。

第四步：创建认证文件项目要求你在~/.openclaw/目录下创建一个名为openclaw.json的配置文件。注意，~代表你的用户家目录。

mkdir -p ~/.openclaw # 如果目录不存在则创建

然后，用你喜欢的文本编辑器创建并编辑这个文件：

nano ~/.openclaw/openclaw.json # 或者用 vim, code 等

文件内容如下，将YOUR_TOKEN_HERE替换成你从 OpenClaw 网关获取的真实 token：

{ "gateway": { "auth": { "token": "YOUR_ACTUAL_TOKEN_HERE" } } }

保存并退出。这个文件是高度敏感的，务必确保其权限安全，不要将其提交到任何公开的版本控制系统。

重要检查点：完成以上四步后，我建议做一个简单的连通性测试。你可以尝试用 curl 命令测试 OpenClaw 网关是否正常工作：
curl -X POST http://localhost:3000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACTUAL_TOKEN_HERE" \ -d '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello"}]}'
如果返回一个包含 AI 回复的 JSON，说明网关配置正确。如果遇到连接拒绝或认证错误，需要回头检查 OpenClaw 服务是否真的在 3000 端口运行，以及 token 是否正确。

3.2 项目初始化与技能安装

环境准备好后，就可以把技能库本身拉下来了。

git clone https://github.com/Celestial-0/OpenClaw-Skills.git cd OpenClaw-Skills bun install

bun install会读取package.json，安装所有必要的 Node.js/TypeScript 依赖包，比如commander（命令行解析）、youtubei.js等。这个过程通常很快。

安装完成后，项目根目录下的package.json里已经定义好了脚本。你可以通过bun run youtube来执行 YouTube 技能。但为了确保一切就绪，我们先运行一个最简单的命令来测试整个链路是否打通：

bun run youtube --help

这个命令会打印出 YouTube 技能所有可用的参数和选项说明。如果你能看到详细的帮助信息，恭喜你，基础环境已经搭建成功。如果出现“命令未找到”或模块加载错误，请检查bun install的日志，看是否有依赖安装失败。

4. YouTube技能深度解析与实操

4.1 字幕获取管道：三层递进的稳健策略

字幕是这一切分析的基石。如果拿不到字幕，后面的LLM分析就成了无米之炊。transcript.ts文件实现的三层获取策略，是该项目设计中最精妙、最体现工程思维的部分。

第一层：Innertube 官方API（首选）这是通过youtubei.js库来模拟手机或网页客户端，直接调用YouTube的内部API获取字幕。这种方法的好处是：

数据最规范：拿到的是结构化的JSON数据，包含精确的时间戳和纯文本，没有HTML标签污染。
可靠性高：只要该视频有官方提供的字幕（包括创作者上传的.srt文件或YouTube生成的自动字幕），且你的请求模拟得足够像真实客户端，成功率就很高。
速度快：直接获取数据，无需下载和解析整个视频页面。

它的实现核心是创建一个Innertube客户端实例，然后通过video.getInfo()获取视频信息，其中就包含了captions（字幕）列表。代码会遍历这个列表，寻找语言代码（如en,zh-Hans）匹配的视频原始语言的字幕轨道。找到后，调用track.getCaptions()即可获取字幕片段数组。

第二层：youtube-transcript 网页抓取（备选）当第一层失败时（比如API结构发生变化，或者请求被风控），系统会回退到第二层：使用youtube-transcript这类库，通过HTTP请求获取视频页面HTML，然后从中解析出字幕信息。YouTube有时会把字幕数据以JSON格式内嵌在页面HTML中。

优点：不依赖非官方API，只进行普通的网页抓取，行为更“低调”。
缺点：受网页结构变化影响大，如果YouTube前端改版，解析逻辑可能失效。而且需要下载和解析整个页面，效率稍低。

第三层：yt-dlp 下载自动字幕（保底）当前两层都失败时（常见于一些没有提供任何官方字幕，且页面内也无嵌入字幕信息的视频），第三层保底方案启动：使用yt-dlp。

语言检测：首先，yt-dlp会获取视频的元信息，从中判断视频的原始语言是什么（比如ja代表日语）。
定向下载：然后，它尝试下载该语言对应的“自动生成字幕”。这里的关键是只请求原始语言。如果你请求--sub-lang en而视频是日语的，YouTube可能会尝试返回机器翻译的英文字幕，这个翻译质量往往很差，且更容易触发“字幕不可用”的错误。直接请求原始语言 (--sub-lang ja) 的成功率最高。
格式转换：yt-dlp默认下载的字幕可能是多种格式（SRT, VTT, TTML等）。代码需要将这些格式解析、清洗，转换成统一的内部数据结构（包含text,start,duration的数组）。

为什么需要三层？这是一种典型的“优雅降级”策略。核心目标是最大化获取字幕的成功率。没有任何一种方法能保证100%成功。官方API可能被封；网页抓取可能因改版失效；有些视频可能根本没有自动字幕。三层策略环环相扣，确保只要视频存在任何形式的可获取字幕，我们就有很大机会拿到它。在实际使用中，我观察到大约85%的视频可以通过第一层获取，10%通过第二层，剩下5%可能通过第三层获取或最终失败。

实操心得：你可以通过设置环境变量或修改代码日志级别，来观察具体某个视频走了哪一层管道。这对于调试和了解YouTube的反爬现状很有帮助。如果发现大量视频都 fallback 到 yt-dlp，可能意味着youtubei.js需要更新了。

4.2 缓存机制：提升效率与避免风控

频繁地对同一个视频请求字幕，不仅慢，而且很容易触发YouTube的速率限制。cache.ts实现的磁盘缓存机制巧妙地解决了这个问题。

缓存键的设计：缓存不是简单地用视频URL作为键，而是使用video_id。因为同一个视频可能有不同的URL形式（比如包含追踪参数的分享链接）。提取出标准的11位视频ID（如dQw4w9WgXcQ）作为键，保证了唯一性。

缓存内容：缓存的文件是一个JSON，里面不仅存储了最终清洗好的字幕数组，通常还会存储一些元数据，比如获取时间、使用的获取方法、视频语言等。这样下次请求时，可以直接从缓存加载，完全跳过网络请求。

缓存目录：默认的缓存目录是~/.openclaw/cache/youtube。你可以通过--cache-dir参数自定义。我建议将这个目录放在一个读写速度快的位置（比如SSD），并且考虑定期清理，虽然单个缓存文件很小，但数量多了也会占用空间。

缓存失效策略：当前的实现是“永久缓存”，即一旦获取成功就永远使用缓存。这对于静态内容（如已上传的视频）是合理的。但你需要知道，如果视频作者后来更新了字幕，你的缓存就不会更新。一个更完善的策略可以加入“缓存有效期”（例如7天），或者提供一个--no-cache或--force-refresh参数来跳过缓存。

缓存带来的好处：

极速响应：第二次分析同一个视频时，几乎是瞬间完成。
降低风控风险：避免了重复的、不必要的网络请求。
离线工作：只要分析过的视频，即使在没有网络的环境下，你仍然可以对其进行新的问答或分析（因为字幕已在本地）。

4.3 四大使用模式详解与示例

YouTube技能提供了四种核心模式，分别对应不同的信息处理需求。下面我用具体的命令示例和输出来展示它们的威力。

模式一：结构化摘要 (Summary) - 默认模式这是最常用的功能，旨在用最少的文字呈现视频的核心内容。

bun run youtube --url "https://www.youtube.com/watch?v=VIDEO_ID"

输出特点：它会生成一个包含5个部分的Markdown格式摘要：

概述：一两句话点明视频主题。
核心要点：分条列出3-5个最重要的观点或结论。
关键时间戳：标记出视频中讨论核心话题的具体时间点，方便你快速跳转。
详细总结：对视频内容进行更连贯、更详细的段落式总结。
最终收获：提炼出观众看完本视频最应该记住的一两个启示。

语言自适应：如果你不指定--lang，它会自动检测字幕语言并用同种语言输出摘要。例如，一个日语视频，你会得到日语的摘要。如果你想强制用中文输出，可以加--lang zh。

模式二：基于字幕的问答 (QA)当你对视频的某个具体细节有疑问时，这个模式就派上用场了。它不是让大模型凭空想象，而是严格基于获取到的字幕文本来回答。

bun run youtube --url "https://www.youtube.com/watch?v=VIDEO_ID" --mode qa --question "演讲者在第15分钟左右提到的那个实验的具体步骤是什么？"

工作原理：

检索：chunks.ts会将整个字幕文本切割成较小的片段（例如按句子或按固定token数）。当收到问题时，它会使用TF-IDF或类似的向量检索技术，快速找出与问题最相关的几个字幕片段。
** grounding**：qa.ts将找到的相关片段和问题一起发送给LLM，并给出严格的指令：“请仅基于以下提供的上下文来回答问题。如果上下文没有提供足够信息，请回答‘根据提供的字幕，无法找到相关信息’。”
生成：LLM基于提供的“证据”（字幕片段）生成答案。

这样生成的答案可信度非常高，因为它有据可查。输出JSON中会有一个"grounded": true的字段来表明这一点。

模式三：深度分析 (Deep Dive)这个模式适合用于分析讲座、辩论、深度访谈等内容，旨在解构视频的深层逻辑。

bun run youtube --url "https://www.youtube.com/watch?v=VIDEO_ID" --mode deepdive

它会生成一个6部分的分析报告：

背景与上下文：视频讨论的问题是在什么背景下产生的？
核心论点与论据：讲者提出了哪些主要观点？他用什么证据（数据、案例、逻辑）来支撑？
论证结构与逻辑：讲者是如何组织这些论据的？论证过程是否严密？
潜在影响与启示：如果讲者的观点成立，会带来哪些影响？
未解答的问题与局限：视频中有哪些问题被回避了？论证存在哪些弱点或假设？
目标受众与说服策略：这个视频是针对谁的？采用了哪些说服技巧（情感、权威、逻辑）？

这种分析能帮你从“看热闹”进阶到“看门道”，特别适合学习和研究。

模式四：行动要点提取 (Action Points)从教程、产品发布会、方法论分享等视频中，直接提取出可操作的步骤。

bun run youtube --url "https://www.youtube.com/watch?v=VIDEO_ID" --mode actionpoints

输出会将行动分为三类：

立即行动：现在就可以开始做的事情（例如，“访问XX网站下载模板”）。
短期计划：接下来几天或几周内需要规划的事情（例如，“研究一下A工具和B工具的对比”）。
长期战略：从视频中获得的、可能影响长期决策的启示（例如，“考虑将XX方法论引入团队工作流程”）。

这对于将知识转化为实践非常有帮助。

4.4 批量处理与频道监控

手动一个个输入URL太麻烦。技能提供了两种批量处理方式。

方式一：扫描频道最新视频

bun run youtube --channel "@TechLinked" --hours 48

这个命令会去抓取@TechLinked这个频道在过去48小时内发布的所有视频，然后依次对每个视频执行默认的摘要模式。--channel参数支持频道ID、@开头的句柄，或者完整的频道URL。--hours参数控制回溯的时间窗口。这对于跟踪你订阅的频道、制作每日简报非常有用。

方式二：基于配置文件的每日批处理这是更自动化的工作流。首先，复制示例配置文件：

cp config/channels.example.json config/channels.json

然后编辑config/channels.json，添加你关注的频道列表：

{ "channels": [ { "name": "AI Explained", "id": "UCmG-7A2IzDEsg-7xjeLx7cQ" }, { "name": "Fireship", "url": "https://www.youtube.com/@Fireship" }, { "name": "3Blue1Brown", "id": "UCYO_jab_esuFRV4b17AJtAw" } ], "hours_lookback": 24, "max_videos_per_channel": 3 }

运行批处理命令：

bun run youtube --config ./config/channels.json --daily

这个命令会读取配置文件，遍历每个频道，获取过去24小时（由hours_lookback控制）内发布的视频，但每个频道最多只处理3个（由max_videos_per_channel控制）。所有结果会分别生成JSON文件，保存在output/目录下。你可以将此命令设置为系统的定时任务（如Cron），实现真正的无人值守每日摘要。

重要提醒：批量处理会发起大量的网络请求。务必合理设置hours_lookback和max_videos_per_channel，并在网络请求间添加适当的延迟（代码中可能需要自己添加sleep），以免对YouTube服务器造成过大压力或被封禁IP。建议从保守的参数开始测试。

5. 高级配置、问题排查与性能调优

5.1 输出定制与结果处理

默认情况下，技能的输出是一个JSON文件，保存在./output/youtube_summary.json。你可以通过--output参数指定任何路径和文件名。JSON格式便于被其他程序（比如你自己的笔记系统、数据库或前端展示页面）进一步处理。

如果你希望直接在终端看到美观的Markdown格式摘要，可以写一个简单的Shell脚本来解析JSON并格式化输出。例如，使用jq工具：

bun run youtube --url "YOUR_URL" --output /tmp/result.json cat /tmp/result.json | jq -r '.output' | glow - # 使用glow来渲染markdown

或者，你也可以直接修改cli.ts文件，在写入JSON文件的同时，也将output字段的内容漂亮地打印到控制台。

对于批量处理，output/目录下可能会生成很多文件。一个良好的实践是按照日期或频道名建立子目录来组织这些文件，例如output/2023-10-27/@ChannelName/。这需要你稍微修改一下批量处理的逻辑，在写入文件前动态创建目录。

5.2 应对速率限制与网络问题

在频繁使用，尤其是批量处理时，你几乎一定会遇到YouTube的速率限制或网络错误。

症状：请求失败，错误信息可能包含429 Too Many Requests、403 Forbidden，或者连接超时。

解决方案1：使用代理项目文档提到了一个可选的环境变量YOUTUBE_CF_PROXY。你可以将其设置为一个代理服务器的URL，让所有对youtube.com或其子域的请求都通过这个代理转发。这可以帮你更换出口IP，绕过基于IP的限流。

YOUTUBE_CF_PROXY="https://your-proxy-service.com/?url=" bun run youtube --url "YOUR_URL"

你需要自己搭建或寻找可靠的代理服务。注意，将流量经过第三方代理存在隐私风险，请谨慎评估。

解决方案2：增加请求间隔最根本、最有效的方法是慢下来。在代码的请求逻辑中（比如在youtube.ts的频道视频获取循环，或transcript.ts的连续处理中），主动添加延迟。例如，在处理每个视频之间休眠2-5秒。

// 在循环内添加 import { sleep } from 'bun'; // Bun 内置了 sleep 函数 for (const video of videos) { // ... 处理视频 ... await sleep(3000); // 休眠3秒 }

对于频道扫描，这个间隔可能需要更长。模拟人类浏览器的行为是避免风控的关键。

解决方案3：利用缓存，避免重复请求如前所述，充分利用缓存机制。在批量处理前，可以先检查缓存中是否已有该视频的字幕。如果有，直接使用，这能减少绝大部分对外请求。

解决方案4：备用User-Agent和Cookie有时问题出在youtubei.js的请求头或Cookie上。你可以尝试更新youtubei.js库到最新版本，因为它会持续跟进YouTube内部API的变化。在极端情况下，可以考虑在代码中配置轮换的User-Agent字符串，或者尝试导入一个有效的浏览器Cookie（但这比较复杂且有安全风险）。

5.3 字幕获取失败常见问题排查

即使有三层管道，字幕获取仍可能失败。以下是一些常见场景和排查思路：

视频没有字幕：这是最根本的原因。有些视频（尤其是音乐MV、纯演示视频）可能既没有创作者上传的字幕，也没有自动生成的字幕（可能因为语言冷门或背景音乐太吵）。排查：手动在YouTube网页上打开该视频，查看播放器控件下方是否有“CC”字幕按钮。如果没有，则技能也无法获取。
Innertube API 失效：youtubei.js是一个逆向工程库，当YouTube更新其内部API时，它可能会暂时失效。排查：查看技能运行的日志或错误信息。如果第一层失败并迅速回退到第二层，这可能是原因。解决：升级youtubei.js到最新版本 (bun update youtubei.js)。
地域或版权限制：某些视频的字幕信息可能因地域或版权原因被限制访问。排查：尝试用你的浏览器（最好是无痕模式，且未登录账号）访问该视频，看是否能显示字幕。如果不能，技能也无法获取。
yt-dlp 路径或权限问题：第三层保底方案依赖系统能找到并执行yt-dlp。排查：在终端直接运行which yt-dlp，确认命令是否存在且路径正确。同时，运行yt-dlp --list-subs VIDEO_ID测试一下该命令是否能正常获取字幕列表。
视频过短：项目代码中有一个逻辑，会自动跳过时长小于5分钟的视频（通常是YouTube Shorts）。因为短视频往往信息密度低，且自动字幕可能不准确。这不是错误，而是设计上的过滤。

当字幕获取失败时，技能的输出JSON中has_transcript字段会是false，并且output字段会包含错误信息或说明。你可以根据这个来判断是单个视频问题还是普遍问题。

5.4 扩展思路：开发你自己的新技能

OpenClaw-Skills 的架构鼓励扩展。假设你想开发一个“播客摘要”技能，可以遵循以下步骤：

创建技能目录：在src/下新建一个目录，例如src/podcast/。
定义核心文件：
- cli.ts: 定义命令行参数，如--rss-feed、--episode-url。实现main()函数作为入口。
- config.ts: 定义播客摘要的提示词模板、LLM参数。
- types.ts: 定义播客剧集、音频/文字稿等数据的接口。
- fetcher.ts: 实现从RSS feed或特定平台获取播客元数据和文字稿的逻辑（可能需要用到rss-parser、node-fetch等库）。
- transcript.ts(可选): 如果播客没有现成文稿，你可能需要集成语音转文字服务（如Whisper API）。
- llm.ts: 封装调用OpenClaw进行摘要、分析的逻辑。
修改项目入口：更新根目录的index.ts文件，暂时将导入指向你的新技能（例如import { main } from './src/podcast/cli';），或者设计一个更动态的机制（如通过命令行参数选择技能）。
更新 package.json：在scripts部分添加一个新命令，比如"podcast": "bun run index.ts"。
安装依赖：在项目根目录运行bun add rss-parser等来添加你需要的包。