claude-video 实战教程：用 Agent Skill 让 Claude 看懂任意视频

1. 为什么 Claude 看视频这件事值得折腾你可能遇到过这种场景同事甩来一段 40 分钟的屏幕录制说“你帮我看看哪里点错了”或者老板发来一个竞品发布会链接让你“总结下真正的新功能”。把链接丢给 Claude它只能根据标题和残缺字幕猜画面里到底发生了什么模型完全不知道。这就是 claude-video 这个 Agent Skill 想解决的问题——让 Claude 真正“看”视频而不是靠标题脑补。claude-video 本质上是「一段 Python 脚本 一份 SKILL.md 说明文件」的组合它补上了 AI 编程助手长期缺失的一项能力直接读取视频内容。工作链路很清晰先用 yt-dlp 把视频拉下来或者直接读本地文件再用 ffmpeg 按场景切换抽帧音频部分走字幕或 Whisper 转录最后把带时间戳的帧图片路径和转录文本一起交给 Claude 阅读。Claude 拿到的是“看到的画面 听到的音频”回答自然有依据。它适合谁三类人最刚需一是做内容拆解的运营需要分析爆款视频的钩子结构二是排查 Bug 的开发者同事发来的录屏要快速定位出错帧三是需要给长视频做摘要的知识工作者不想花 40 分钟逐帧看完。项目在 GitHub Trending Python 榜上单周涨星超过 4000说明“给 AI 一双眼睛”这个需求是真实存在的。这篇教程不会只讲概念。我会带你从零把 claude-video 跑起来包括 ffmpeg 抽帧、音频转写、Skill 配置、Python 调用脚本以及如何通过 TaoToken 统一 Key 和 API 通道接入最后给一次完整的验证流程和常见报错排查。全程可复制跟着做就行。2. 前置准备ffmpeg、yt-dlp 与 TaoToken 通道在装 claude-video 之前先把底层依赖理清楚。这个 Skill 本身不复杂但它依赖两个外部工具ffmpeg 负责抽帧和音频截取yt-dlp 负责下载视频。这两个装不好后面 /watch 命令会直接报错。macOS 上最省事一条命令搞定brew install ffmpeg yt-dlpLinuxDebian/Ubuntu 系sudo apt update sudo apt install -y ffmpeg pip install -U yt-dlpWindows 用 wingetwinget install Gyan.FFmpeg winget install yt-dlp.yt-dlp装完验证一下版本确保 ffmpeg 在 PATH 里ffmpeg -version yt-dlp --version如果 ffmpeg 报 “command not found”八成是没加进环境变量。Windows 上手动把 ffmpeg 的 bin 目录加到系统 PATHLinux/macOS 检查~/.bashrc或~/.zshrc里有没有 export。接下来是模型通道。claude-video 抽完帧和转录文本后最终要交给 Claude 阅读这一步需要一个能稳定调用的 API 通道。我实测下来用 TaoToken 统一管理 Key 和 Base URL 比较省心不用在多个平台之间来回切换配置。TaoToken 提供兼容 OpenAI 风格的接口Claude 系列模型也能通过它统一接入。你需要先去官网注册并拿到 API Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 后在控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Key 管理页面在这里可以随时新建或吊销https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址统一用https://taotoken.net/api注意这个地址后面不加 UTM 参数直接作为 Base URL 填进配置即可。模型 ID 方面Claude 系列可以填claude-sonnet-4-20250514这类具体版本号具体以你账号下可用的模型列表为准。这三件套——Base URL、API Key、Model ID——后面在 Skill 配置和 Python 脚本里都会用到先记好。提示如果你只是想让 Claude 读带字幕的视频其实不需要 Whisper也就不需要额外的转录 API Key。只有视频没有字幕、需要音频转写时才要配 Whisper。Groq 的 whisper-large-v3 便宜且快OpenAI 的 whisper-1 也行二选一即可。3. 可复制配置Skill 安装与 settings 片段依赖装好后开始装 claude-video 这个 Skill。它支持 50 多种 Agent 宿主环境不同宿主安装方式略有差异。如果你用的是 Claude Code推荐走 plugin marketplace支持自动更新/plugin marketplace add bradautomates/claude-video /plugin install watchclaude-video如果你用的是 Codex、Cursor、Copilot、Gemini CLI 等环境用 npx 全局安装npx skills add bradautomates/claude-video -g-g表示全局安装装到用户级目录比如~/.codex/skills跨项目都能用去掉这个参数则只装到当前项目。装完后你的宿主环境里会多出一个/watch命令。接下来配置 Whisper 的 API Key可选但建议配上。配置文件写在~/.config/watch/.env内容格式如下# ~/.config/watch/.env WHISPER_PROVIDERgroq GROQ_API_KEYgsk_你的GroqKey # 或者用 OpenAI # WHISPER_PROVIDERopenai # OPENAI_API_KEYsk_你的OpenAIKey如果你希望 claude-video 在处理完抽帧后把多模态输入统一走 TaoToken 通道交给 Claude可以在宿主环境的模型配置里指定 Base URL。以 Codex 的auth.json为例路径通常在~/.codex/auth.json配置片段如下{ base_url: https://taotoken.net/api, api_key: 你的TaoTokenKey, model: claude-sonnet-4-20250514 }如果你用的是 Cline 或带 MCP 配置的宿主可以在 MCP 的 settings 里加一段{ mcpServers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: 你的TaoTokenKey, model: claude-sonnet-4-20250514 } } }这里三件套必须齐全Base URL 填https://taotoken.net/apiAPI Key 填你在控制台创建的 KeyModel ID 填具体模型版本。少任何一个调用都会失败。claude-video 的--detail参数控制抽帧精细度本质是在速度、token 成本和视觉还原度之间做权衡。四种档位对照如下档位引擎帧数上限适用场景transcript无仅字幕0只关心讲了什么不看画面efficient关键帧抽取50快速浏览抽取最快balanced场景切换检测100兼顾覆盖度和 token 成本token-burner场景切换检测不限需要完整还原每次画面切换官方给过一组实测数据一段 49 分 08 秒的 720p 视频efficient 档抽帧约 0.5 秒、产出约 9800 image tokensbalanced 约 20.9 秒、约 19700 tokenstoken-burner 保留全部 116 次场景切换约 21 秒、约 22800 tokens。日常排查问题或看长视频摘要efficient 或 balanced 通常够用。帧去重逻辑默认开启这点很关键。屏幕录制里一张幻灯片可能停留 90 秒如果每帧都单独计费token 消耗会非常离谱。claude-video 的做法是用一次 ffmpeg 调用把每帧缩成 16×16 灰度缩略图计算当前帧与“上一张被保留的帧”之间的平均像素亮度差异低于阈值默认 2.0就判定为近重复帧直接丢弃。注意比较对象是“上一张被保留的帧”而非“上一帧”这样才能捕捉缓慢渐变但逐帧差异很小的画面变化。需要关闭时加--no-dedup。4. 验证请求Python 调用脚本与成功结果配置就绪后先做一次最小验证确认整条链路能跑通。最直接的方式是用/watch命令/watch https://youtu.be/dQw4w9WgXcQ 30秒的地方发生了什么如果只想看某个时间段更省 token/watch https://youtu.be/abc --start 2:15 --end 2:45本地文件同样支持/watch ~/Movies/screen-recording.mp4 界面是从哪里开始出问题的但很多时候你需要把 claude-video 的能力嵌进自己的 Python 脚本里比如批量处理一批录屏或者把抽帧结果接到自己的分析流程。下面给一个可复制的调用脚本思路是先用 ffmpeg 抽帧再把帧图片和转录文本组织成多模态消息通过 TaoToken 通道发给 Claude。import base64 import subprocess from pathlib import Path from openai import OpenAI # 1. 用 ffmpeg 按场景切换抽帧 video_path screen-recording.mp4 frames_dir Path(frames) frames_dir.mkdir(exist_okTrue) subprocess.run([ ffmpeg, -i, video_path, -vf, selectgt(scene,0.3),scale640:-1, -vsync, vfr, str(frames_dir / frame_%03d.jpg) ], checkTrue) # 2. 收集帧文件并转 base64 frame_files sorted(frames_dir.glob(frame_*.jpg))[:50] image_contents [] for f in frame_files: b64 base64.b64encode(f.read_bytes()).decode() image_contents.append({ type: image_url, image_url: {url: fdata:image/jpeg;base64,{b64}} }) # 3. 通过 TaoToken 通道调用 Claude client OpenAI( base_urlhttps://taotoken.net/api, api_key你的TaoTokenKey ) messages [{ role: user, content: [ {type: text, text: 这些是视频的关键帧请描述界面是从哪里开始出问题的。}, *image_contents ] }] resp client.chat.completions.create( modelclaude-sonnet-4-20250514, messagesmessages, max_tokens2000 ) print(resp.choices[0].message.content)跑通后你会看到类似这样的输出Claude 会指出“第 12 帧开始设置面板的保存按钮变成了灰色且控制台出现红色报错”而不是泛泛地说“视频里有个界面”。这就是“看到画面”和“猜标题”的区别。如果你只关心音频内容可以跳过抽帧直接走转录import subprocess # 截取音频单声道 16kHz 64kbps约 480KB/分钟 subprocess.run([ ffmpeg, -i, video_path, -vn, -ac, 1, -ar, 16000, -b:a, 64k, audio.mp3 ], checkTrue)然后把audio.mp3送进 Whisper 转录拿到带时间戳的文本再和帧一起交给 Claude。转录文本里带上时间戳很重要Claude 才能把“第 2 分 15 秒说的话”和“第 2 分 15 秒的画面”对应起来。验证成功的标志有三个一是/watch命令能返回带画面依据的回答二是 Python 脚本能打印出 Claude 对帧的描述三是日志里没有 401 或连接超时。三个都满足说明整条链路通了。5. 常见报错排查401、local proxy failed 与 reading choices实际跑的时候报错基本集中在几个地方。我踩过的坑里最常见的是下面这几类对照着排查能省不少时间。401 Unauthorized这个最直接就是 Key 不对或没带上。检查三处一是~/.config/watch/.env里的 Whisper Key 是否正确二是宿主环境配置里的 TaoToken Key 有没有填三是 Python 脚本里api_key是不是写成了占位符。如果 Key 刚创建确认没有多余空格。TaoToken 的 Key 在控制台可以随时重新生成怀疑泄露就直接吊销重建。local proxy failed / connection refused这类报错通常是 Base URL 写错了或者本地网络环境有干扰。确认 Base URL 是https://taotoken.net/api注意结尾不要多加/v1或斜杠。如果你在脚本里用了http://localhost之类的本地代理地址检查代理服务是否真的在运行。另外某些宿主环境会读取系统代理设置如果之前配过其他代理记得清掉避免请求被劫持到不存在的端口。Error reading choices / choices 字段为空这个报错说明请求发出去了但返回结构不对。常见原因是模型 ID 填错比如填了一个账号下不存在的模型名接口返回了错误对象而不是正常的 choices 数组。解决方法是去 TaoToken 控制台确认可用模型列表把 Model ID 换成实际存在的版本。另一个可能是max_tokens设得太大超过了模型上限调小一点再试。OAuth / 认证失败如果你用的是 Codex 或 Claude Code 这类带 OAuth 流程的宿主报 OAuth 错误通常是因为auth.json里的配置和宿主自身的登录态冲突。解决办法是优先用 API Key 方式而不是 OAuth在auth.json里明确写base_url、api_key、model三件套让宿主走 Key 认证而不是走 OAuth 回调。ffmpeg 抽帧为空/watch跑完但 Claude 说“没有收到图片”检查 ffmpeg 的selectgt(scene,0.3)阈值是不是太高导致没有帧被选中。把阈值降到 0.1 试试或者换成efficient档位的关键帧抽取。另外确认视频路径没有中文或空格必要时用引号包起来。Whisper 转录超时长视频的音频文件可能几十 MB转录时间较长。如果用的是 Groq确认音频格式是它支持的mp3、m4a、wav 等。如果一直超时先用--start和--end截取一小段测试确认链路通了再处理完整视频。排查时有个通用技巧先把--detail transcript跑一遍跳过抽帧只走文本确认模型通道没问题再逐步加上抽帧定位是 ffmpeg 的问题还是 API 的问题。这样能把问题范围缩小到具体环节。6. 把 claude-video 接进你的日常工作流跑通之后claude-video 能嵌进的工作流比想象中多。做内容拆解时我会用/watch 视频链接 开头用了什么钩子分析同行的开场手法排查 Bug 时同事发来的录屏直接/watch bug-repro.mov 哪里出问题了Claude 能定位到出错的那一帧并描述现象看长视频时/watch 长视频 总结一下跳过逐帧看完的时间成本过滤营销话术时/watch 发布会视频 真正的新功能是什么把十分钟的“划时代”“颠覆性”压缩成几条实质更新。如果你需要长期、批量地做这类视频理解任务可以考虑用 Coding Plan 来管理调用额度避免每次手动配 Keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想先在线验证模型对多模态输入的理解效果可以直接在模型对话页面测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content完整的接入文档和参数说明在这里遇到配置问题可以对照查阅https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你用的是 Claude Code 并且想走 Anthropic 原生协议接入参考这个页面https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后说个实用技巧处理长视频时先用--detail efficient快速过一遍拿到大致结论如果发现某个时间段有问题再用--start和--end聚焦那一段用balanced或token-burner重跑。这样既省 token又能拿到细节。帧去重默认开着静态画面不会重复计费但如果你发现 Claude 漏掉了缓慢变化的画面可以临时加--no-dedup对比一下效果。项目还在快速迭代帧预算算法和画质档位的具体参数可能随版本更新调整实际使用前以仓库最新 README 为准。