1. 为什么 Claude Code 需要 Video /watch 插件Claude 本身的多模态能力集中在图片和文本上视频这块一直是短板。你直接丢一个视频链接给它它只能靠标题、简介或者平台自动生成的字幕去猜内容画面里发生了什么、UI 在哪一帧崩的、PPT 上那行小字写的什么它一概看不到。做竞品分析、录屏排障、课程笔记整理的时候这个缺口特别明显。claude-video 这个开源插件就是来补这个缺口的。它注册了一个/watch指令底层串起 yt-dlp 下载、ffmpeg 抽帧、Whisper 转写三件套把视频拆成「带时间戳的画面帧 带时间轴的字幕」再喂给 Claude让模型真正同时读到画面和声音。支持 YouTube、TikTok、Loom、Instagram 以及本地 MP4/MOV/MKV 等几百种来源装完就能用。这篇聚焦一件事在 Claude Code 里把/watch插件完整接起来并且让它走统一的 Key/API 通道。很多人卡在两步——插件装上了但模型调用报鉴权错或者 settings.json 骨架写错导致插件根本没加载。下面从配置骨架到验证动作一步步来配置片段可以直接复制。2. 前置准备统一 Key 与 API 通道插件本身负责视频解析但解析完的帧和字幕最终要送给 Claude 模型去理解这一步需要模型 API 通道。如果你本地已经有一堆零散的 Key管理起来很烦我建议统一走一个兼容 Anthropic 协议的入口把模型调用收敛到一处。TaoToken 提供的就是这样一个统一通道官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。它的作用是让你用一套 Key 就能调用 Claude 系列模型Claude Code 这类客户端只要把 base_url 指过来即可不用在每个工具里重复配 Key。你需要先拿到一个 API Key。登录后进入控制台在 API Keys 页面创建一个控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentKey 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建时建议给 Key 起个能认出来的名字比如claude-code-watch方便后面区分是哪个客户端在用。Key 只在创建时完整显示一次复制好先存到安全的地方。注意Key 属于敏感凭据不要写进会提交到 Git 的配置文件里。下面配置里我用环境变量引用的方式避免明文硬编码。如果你还没决定用哪个模型可以先去模型对话页面试一下调用是否通模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content3. 安装 watch 插件并写 settings.json 骨架Claude Code 装插件走的是插件市场机制两条命令搞定# 添加插件市场 /plugin marketplace add bradautomates/claude-video # 安装 watch 指令 /plugin install watchclaude-video装完之后插件目录会落在~/.claude/skills/watch下。接下来是关键的 settings.json 配置。Claude Code 的配置文件通常在~/.claude/settings.json你需要把模型通道和插件相关的环境变量写进去。下面是一份可以直接改的骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的_TaoToken_API_Key, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 }, permissions: { allow: [ Bash(ffmpeg:*), Bash(yt-dlp:*), Bash(python3:*) ] } }几个字段说明一下。ANTHROPIC_BASE_URL指向统一通道的 API 基址注意这里不要带 UTM 参数纯 API 地址即可。ANTHROPIC_AUTH_TOKEN填你刚才创建的 Key。ANTHROPIC_MODEL按你实际要用的模型名填不确定的话可以先留空让客户端用默认值。permissions.allow这一段容易被忽略。/watch执行时会调用 ffmpeg、yt-dlp 和 python 脚本如果 Claude Code 的权限策略拦住了这些命令插件会在中途静默失败表现就是「指令跑了但没结果」。把这三条加进白名单能省掉很多排查时间。如果你更习惯用环境变量而不是写进 settings.json也可以在 shell 里导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKEN你的_TaoToken_API_Key两种方式选一种就行同时配可能互相覆盖反而乱。4. 首次运行的环境自检与依赖安装第一次执行/watch时插件会跑一个setup.py做环境检测缺什么会提示你装什么。手动提前装好更省事# macOS brew install ffmpeg yt-dlp # Ubuntu / Debian sudo apt install ffmpeg pipx install yt-dlp # Windows winget install ffmpeg winget install yt-dlp语音转写这块插件支持 Groq 和 OpenAI 两个后端。如果你要解析没有自带字幕的视频需要配一个 Whisper 后端 Key。配置文件在~/.config/watch/.env首次运行会自动生成占位符# ~/.config/watch/.env GROQ_API_KEY你的_groq_key OPENAI_API_KEY你的_openai_key能力对照可以看这张表按需决定配哪个场景需要的 Key说明视频自带字幕无需 Key直接抓字幕零成本无字幕转写推荐Groq API Keywhisper-large-v3速度快无字幕转写备选OpenAI API Key官方 Whisper标准计费只看画面不转写无需 Key加--no-whisper参数依赖装完、Key 配好环境这块就齐了。5. 验证请求确认视频解析能力生效配置对不对跑一条命令就知道。先拿一个短视频试水用最省的模式/watch https://www.youtube.com/watch?vdQw4w9WgXcQ --detail transcript--detail transcript只抓字幕不抽帧速度最快用来验证「插件加载 模型通道」这条链路是否通。如果返回了带时间戳的文字总结说明插件和 API 通道都正常。接着验证画面解析能力换成本地录屏文件/watch ~/Movies/bug-repro.mov --start 0:10 --end 0:40 when does the UI break?这条命令限定解析 10 秒到 40 秒的片段让 Claude 定位 UI 出错的时间点。如果它能说出具体画面内容比如「第 23 秒按钮变成灰色」说明抽帧、去重、多模态输入整条链路都生效了。再验证一下分段解析这是长视频的常用姿势/watch https://youtu.be/abc --start 2:15 --end 2:45成功的话你会看到类似这样的返回结构先列出提取到的关键帧时间点再给出基于画面和字幕的回答。如果只返回了字幕没有画面描述多半是--detail模式选成了 transcript或者 ffmpeg 没装好。6. 本篇常见错误排查报鉴权错误 401 / invalid api key八成是ANTHROPIC_AUTH_TOKEN填错或者 Key 前后带了空格。重新从 API Keys 页面复制一次注意别把 UTM 参数误粘进 base_url。base_url 必须是https://taotoken.net/api多一个斜杠或参数都可能出问题。插件装了但/watch指令不识别检查插件是否真的装到了~/.claude/skills/watch。有时候市场添加成功但 install 步骤被跳过重新跑一次/plugin install watchclaude-video。装完重启一下 Claude Code 会话。指令跑了但没结果日志里也没报错大概率是权限拦截。回到 settings.json确认permissions.allow里有 ffmpeg、yt-dlp、python3 三条。这是最隐蔽的坑因为拦截发生在命令执行层插件本身不会报错。视频下载失败先单独测 yt-dlp 能不能下yt-dlp -F url看格式列表。如果 yt-dlp 本身报错是网络或视频源的问题跟插件无关。本地文件路径注意用绝对路径~在某些 shell 下不展开。转写一直转圈或超时检查~/.config/watch/.env里的 Whisper Key 是否有效。Groq 后端偶尔会限流可以加--whisper openai切到 OpenAI 后端试试。如果视频本身有字幕直接用--detail transcript跳过转写。Token 消耗异常高默认 balanced 模式对长视频会抽到 100 帧单帧约 197 Token加起来不小。长视频务必用--start/--end分段或者加--max-frames 30手动压上限。文字密集的录屏用--resolution 1024提升可读性但要知道分辨率翻倍 Token 是四倍增长。7. 按场景选对通道与后续接入配置跑通之后日常用起来其实就三件事选对解析模式、控制帧预算、把模型调用收敛到统一通道。快速预览用--detail efficient几秒出结果课程和发布会这种长视频分段截取代码和幻灯片录屏开--resolution 1024批量短视频分析用默认 balanced 就行。如果你只是偶尔解析几个视频现有的 API Key 通道够用。但如果你打算把/watch接进长期的编码工作流或者做批量视频分析这类持续消耗模型调用的任务建议看一下 Coding Plan按长期用量规划会更划算Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入细节和参数说明都在文档里遇到协议层面的问题可以对照查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后提醒一句/watch的临时缓存文件解析完会自动清理但如果你用--out-dir自定义了目录记得定期手动清不然帧图片会越堆越多。
