企业官网建设流程全解析

1. 为什么 Claude 看不了视频，以及 claude-video /watch 到底做了什么

你给 Claude 丢一个视频链接，它只能从标题猜内容，或者拿一份残缺的字幕。屏幕上发生了什么、图表长什么样、操作流程怎么走，它一概不知。这不是 Claude 笨，而是它的输入通道里压根没有"视频"这个类型——它能读网页、跑代码、浏览仓库，但视频对它来说是一团黑盒。

claude-video /watch 解决的就是这件事。它的本质是一条预处理管道：用 yt-dlp 把视频拉下来，用 ffmpeg 抽帧和切音频，用 Whisper 把音频转成带时间戳的文字稿，最后把"帧序列 + 时间戳文字稿"拼装成 Claude 能读的多模态输入。Claude 拿到的不是视频文件，而是一组图片加一份对齐了时间的文本，然后靠它自己的图像理解能力去推理。

这套东西适合谁？三类人最直接受益：一是想让 Claude Code 帮忙分析录屏 bug 的开发者，二是需要快速消化技术讲座、会议录像的工程师，三是想把视频内容接进现有 Agent 工作流的人。它没有发明任何新的 AI 能力，而是把 yt-dlp、ffmpeg、Whisper、Claude 的图像理解串成了一条能跑的链路，填补了一个明显的工具链空白。

真正值得仔细看的设计有两个：帧预算和去重。视频理解的成本由图像 token 主导，按 Anthropic 的公式(width × height) / 750，一帧 512×288 的 JPEG 大约消耗 197 个 token。一个 50 分钟的视频如果不加限制地抽帧，token 成本会直接打穿上下文窗口。所以工具的设计哲学是用信息密度换覆盖率，而不是暴力把所有帧都塞进去。去重则是把每帧缩小到 16×16 灰度图，计算与上一张被保留帧的平均绝对差值，阈值故意设得很低（2.0/255），保证一行代码变化、终端滚动一行这类微小变化都能被保留。

下面我把这条链路完整拆开，给出可复制的命令和配置，并演示一次端到端验证：输入视频链接，确认抽帧、转写、Claude 调用三段都返回预期结果，同时标注时长、分辨率与 token 消耗的边界。

2. 前置准备：TaoToken 接入与 claude-video 环境搭建

在动手之前，先把两件事准备好：一个是 Claude 的调用通道，一个是本地工具链。我这边用的是 TaoToken 作为模型接入层，它兼容 Anthropic 的接口格式，配置起来比较省事。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数。

先去控制台拿一个 API Key，地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。拿到 Key 之后，你需要把它写进环境变量，claude-video 和 Claude Code 都会读这个变量。我习惯用ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL两个变量，前者放 Key，后者指向 TaoToken 的 API 地址。

export ANTHROPIC_API_KEY="sk-你的TaoToken密钥" export ANTHROPIC_BASE_URL="https://taotoken.net/api"

如果你用的是 Claude Code，它默认会读这两个变量。想确认配置是否生效，可以跑一次模型对话验证，地址是 https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，在里面发一条消息看能不能正常返回。这一步别跳过，后面 claude-video 调用失败，十有八九是这里没配对。

本地工具链需要三样东西：yt-dlp、ffmpeg、以及一个能跑 Whisper 的环境。yt-dlp 负责下载视频，ffmpeg 负责抽帧和音频切分，Whisper 负责转写。安装命令如下：

# macOS brew install yt-dlp ffmpeg # Ubuntu / Debian sudo apt install yt-dlp ffmpeg # Whisper 用 pip 装，建议单独建虚拟环境 python3 -m venv whisper-env source whisper-env/bin/activate pip install openai-whisper

Whisper 的模型有 tiny、base、small、medium、large 几档，模型越大越准但越慢。第一次跑会下载模型权重，large-v3 大概 3GB 左右。如果你只是做技术讲座转写，medium 通常够用，速度也快不少。装完之后用whisper --help确认一下命令可用。

claude-video 本身是一个 skill 形式的工具，安装方式取决于你用的客户端。Claude Code 用户可以直接把 skill 文件放到对应目录，Codex、Cursor、Copilot、Gemini CLI 也都有各自的接入方式。核心是让它能读到你的 API 配置，并且能调用本地的 yt-dlp 和 ffmpeg。装好之后，/watch命令就能用了。

这里有个容易踩的坑：yt-dlp 和 ffmpeg 必须在 PATH 里能被找到。如果你在虚拟环境里跑，确认一下which yt-dlp和which ffmpeg都有输出。另外 Whisper 的转写是 CPU 密集型的，长视频转写会吃满一个核，建议在有空闲算力的时候跑。

3. 可复制配置：抽帧、音频切分与 Whisper 转写参数

这一节给出可以直接抄的配置片段。claude-video 的核心参数集中在帧预算、detail 模式和音频处理上，我按实际使用场景拆开讲。

先看帧预算。工具会根据视频时长自动决定抽帧密度，规则大致是这样：

超过 10 分钟的视频，100 帧就是字面意义上的稀疏扫描。工具会给出警告，并建议用--start/--end聚焦片段。这个警告不是摆设，后面排障章节会讲为什么。

detail 模式有四种，取舍如下：

有个反直觉的结论值得记住：efficient 模式在低运动素材上可能产生比 balanced 更多的帧。因为关键帧数量由编码器决定，静态视频的关键帧可能比场景切换点还多。"efficient"指的是提取速度快，不是帧少。

如果你要手动控制抽帧，ffmpeg 的命令是这样的：

# 按固定间隔抽帧，每 2 秒一帧，缩放到 512 宽 ffmpeg -i input.mp4 -vf "fps=1/2,scale=512:-1" -q:v 3 frames/frame_%04d.jpg # 按场景切换抽帧，阈值 0.3 ffmpeg -i input.mp4 -vf "select='gt(scene,0.3)',scale=512:-1" -vsync vfr -q:v 3 frames/scene_%04d.jpg

音频切分和转写用 Whisper 一条命令搞定：

# 从视频提取音频并转写，输出带时间戳的 srt ffmpeg -i input.mp4 -ar 16000 -ac 1 -c:a pcm_s16le audio.wav whisper audio.wav --model medium --language zh --output_format srt --output_dir ./transcript

-ar 16000 -ac 1是把音频重采样到 16kHz 单声道，这是 Whisper 推荐的输入格式，能减少不必要的计算。--output_format srt会生成带时间戳的字幕文件，方便后面和帧对齐。

如果你用 Claude Code 的 settings 配置，可以这样写：

{ "env": { "ANTHROPIC_API_KEY": "sk-你的TaoToken密钥", "ANTHROPIC_BASE_URL": "https://taotoken.net/api" }, "skills": { "claude-video": { "enabled": true, "defaultDetail": "balanced", "maxFrames": 100 } } }

这段配置放在~/.claude/settings.json里，Claude Code 启动时会读取。注意ANTHROPIC_BASE_URL不要带 UTM 参数，只写https://taotoken.net/api。

如果你用的是 Codex，配置写在~/.codex/auth.json里，格式略有不同：

{ "api_key": "sk-你的TaoToken密钥", "base_url": "https://taotoken.net/api", "model": "claude-sonnet-4-20250514" }

三件套要写全：Base URL、Key、Model ID。少任何一个都会在调用时报错。Model ID 按你实际用的模型填，别照抄。

4. 端到端验证：从视频链接到 Claude 返回结果

配置好之后，跑一次完整链路验证。我拿一个 12 分钟的技术讲座视频做测试，分辨率 1920×1080，内容是讲某个框架的架构设计。

第一步，用 transcript 模式先探一下字幕质量：

/watch https://example.com/video --detail transcript

返回结果里会包含字幕文本和时长信息。如果平台有自动字幕，这一步零下载零帧，几秒钟就出结果。我这次测试的视频有自动字幕，但技术术语错得比较多，比如把某个库名识别成了另一个词，所以决定走完整链路。

第二步，用 balanced 模式跑完整抽帧加转写：

/watch https://example.com/video --detail balanced --start 0:00 --end 12:00

这一步耗时约 21 秒抽帧，加上 Whisper medium 模型转写 12 分钟音频，总共花了大概 3 分钟。返回结果里包含帧序列、时间戳文字稿，以及 Claude 的分析结论。

抽帧结果：12 分钟视频，balanced 模式检测到 47 个场景切换点，去重后保留 38 帧。每帧 512×288，按公式(512 × 288) / 750 ≈ 197token，38 帧约 7486 图像 token。加上文字稿约 3200 token，总输入约 10700 token。

Claude 返回的分析结论里，准确识别出了架构图里的三个核心模块，并且把讲师在第 4 分 20 秒提到的"这个模块负责路由"和对应帧里的架构图关联了起来。这说明时间戳对齐是有效的，Claude 能把文字和帧按时间近似匹配。

第三步，验证 token 消耗边界。我故意用一个 49 分钟的视频跑 token-burner 模式，结果如下：

/watch https://example.com/long-video --detail token-burner

返回警告：视频时长 49 分钟，帧预算上限 100 帧，平均每 30 秒才一帧。实际抽帧 100 帧，图像 token 约 19700，文字稿约 12000 token，总输入约 31700 token。Claude 的分析结论明显比短视频粗糙，讲师在第 22 分钟讲的一个关键细节，因为落在两帧之间，Claude 完全没提到。

这个对比说明一个事：帧预算不是可选项，是硬约束。长视频要么用--start/--end聚焦，要么接受稀疏扫描的代价。

验证成功的标志有三个：抽帧目录里有 JPEG 文件且数量符合预期，转写目录里有 srt 文件且时间戳连续，Claude 返回结果里能引用到具体时间点的内容。三个都满足，链路就是通的。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

这一节对照真实报错，给出排查路径。我踩过的坑基本都在这了。

401 Unauthorized：最常见。原因通常是 API Key 没配对，或者ANTHROPIC_BASE_URL写错了。检查两件事：一是echo $ANTHROPIC_API_KEY有没有输出，二是echo $ANTHROPIC_BASE_URL是不是https://taotoken.net/api。如果 Key 是从控制台复制的，注意别把前后空格带进去。还有一种情况是 Key 过期了，去 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 重新生成一个。

local proxy failed：这个报错通常出现在 Claude Code 里，意思是本地代理连接失败。先确认你的网络能正常访问https://taotoken.net/api，用curl -I https://taotoken.net/api看返回码。如果返回 200 或 401 都说明网络通，问题在配置；如果超时，检查一下本地防火墙或者 DNS。另外确认没有多余的代理环境变量干扰，unset HTTP_PROXY HTTPS_PROXY之后再试。

reading choices 报错：这个一般出现在模型返回格式不符合预期的时候。claude-video 期望 Claude 返回结构化的分析结果，如果模型返回了非预期格式，解析就会失败。排查方法是先单独跑一次模型对话，确认模型本身能正常返回。如果模型对话正常但 /watch 报这个错，可能是帧数太多导致上下文超限，试试降低 detail 模式或者用--start/--end缩小范围。

OAuth 相关报错：如果你用的是 Claude Code 的 OAuth 登录方式，而不是 API Key，可能会遇到 token 刷新失败。这种情况建议切到 API Key 方式，配置更稳定。在 settings.json 里显式写ANTHROPIC_API_KEY，不要依赖 OAuth 缓存。

yt-dlp 下载失败：报错通常是Unable to download webpage或者HTTP Error 403。先升级 yt-dlp，pip install -U yt-dlp，很多平台的反爬策略更新很快。如果升级后还不行，试试加--cookies-from-browser chrome参数，从浏览器读 cookie。注意这个操作只用于你自己有权限访问的内容。

Whisper 转写卡住：如果转写长时间没输出，可能是模型太大或者音频太长。先用--model tiny跑一遍确认链路通，再换大模型。另外确认音频文件格式是 16kHz 单声道，格式不对 Whisper 会报错或者转写质量很差。

ffmpeg 抽帧为空：检查输入视频路径是否正确，以及 ffmpeg 是否有解码器。用ffmpeg -i input.mp4看能不能正常输出视频信息。如果视频是特殊编码，可能需要额外装解码器。

排查顺序建议：先确认 API 配置（401 类），再确认网络（proxy 类），再确认模型返回（choices 类），最后确认本地工具链（yt-dlp/ffmpeg/Whisper 类）。大部分问题在前两步就能定位。

6. 把视频接进 Claude 工作流：从验证到日常使用

链路跑通之后，日常使用有几个实用技巧。

定向查询比总结视频更有价值。"总结整个视频"在帧稀疏时效果一般，因为 Claude 可能根本没看到关键帧。真正发挥工具价值的场景是已知时间点的精确查询，比如/watch bug.mov --start 0:45 --end 1:10 what's on screen?，这种聚焦查询在稠密帧下效果显著。我实测下来，聚焦 25 秒片段的查询准确率比总结 50 分钟视频高得多。

字幕充分的长讲座直接用 transcript 模式，零帧、零 API 费用、全文内容，性价比最高。只有当你需要看屏幕上的图表、代码、操作流程时，才需要走完整抽帧链路。

诊断录屏类问题时，屏幕录制帧变化稳定、去重效果好，实际帧数比预算数字少很多，成本可控。这类场景是 claude-video 最舒服的用法。

如果你需要长期做视频分析，可以考虑 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合高频调用的场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有完整的接口说明和参数列表。

最后说一个边界：这套工具链目前完全依赖外部 API 做语音转文字，没有本地推理选项。数据隐私敏感的场景不要用。另外它不适合帧级精确的专业视频分析，比如视频剪辑、逐帧校色，因为抽帧是统计采样，不是全帧保留。yt-dlp 本身也不能绕过版权保护或付费墙，这是工具的限制，不是配置问题。

把视频拆成帧加文字稿再交给 Claude，本质是一种信息压缩。100 帧稀疏扫描一个 50 分钟视频，和人类快进看视频差不多，能抓大概，但容易漏细节。当分析任务需要"没有任何遗漏"时，这套架构会系统性地失败。知道这个边界，比知道怎么配置更重要。