Code Agent 是如何处理视频的
Codex · Claude Code · Pi · Grok Build 源码对比 · 2026-08-04
范围限于文中检查的客户端代码与一次本地 MP4 测试。
- 0 · 从 MP4 输入开始
- 1 · 检查范围
- 2 · 发给模型的数据里有没有视频
- 3 · 去读 mp4 时会发生什么
- 4 · 生成、播放与分析
- 5 · 任务是靠什么做好的
- 6 · 抽帧会损失什么
- 7 · 自己做产品时怎么定
- 附录 · 四家流程
把 MP4 交给 Agent 以后
把视频文件交给编程 Agent,任务有时能完成,但仅凭结果,看不出模型究竟收到过哪些画面。它可能读了字幕、检查了媒体参数,也可能运行脚本抽帧。
我先查 Codex 的输入定义和本地看图工具,再对照 Claude Code、Pi 与 Grok Build 的相应代码。检查的这几条路径接受文字和图片,没有把本地 MP4 直接作为视频内容块提交给模型的入口。
为了弄清任务怎样继续,我又用同一个 MP4 做了对照:直接交给 view_image 会失败,用 ffmpeg 导出 JPEG 后,同一工具可以读取画面。后文保留了文件参数、命令和结果。
这几步回答的是不同问题:客户端能接收什么,读文件工具如何处理 MP4,以及 Agent 能否借助其他工具取得画面。生成视频、播放视频也需要另看,不能从界面能播就推断模型看过内容。
检查到的输入范围
在本文检查的客户端路径中,模型获得画面信息要经过图片输入。Agent 可以先把 MP4 转成帧图,也可以只用文本和媒体参数完成某些任务。因此,“任务完成了”不足以证明整段视频进入过模型,更不能概括所有版本和产品入口。
| 顺序 | 检查对象 | 在问什么 | 为什么重要 |
| 请求格式 | 发给模型的数据 | 请求里能不能带「视频」? | 这里没有,后面补不回来 |
| 文件工具 | 去读文件时 | 对 .mp4 点读取,怎么反应? | 决定日常体感 |
| 产品入口 | 产品还提供了什么 | 会不会生成、播放?和理解混没混? | 决定会不会被宣传带偏 |
| 问题 | 结论(判定) | 补充 |
| Codex 会不会原生处理视频? |
不会 |
用户输入类型里没有视频 |
| 任务是靠什么做好的? |
靠「不看视频也能完成」的办法 |
例如:活本来就不用看画面;终端截帧再当图;你已经说明了内容/给了字幕;只改旁边的文本配置。不是模型看懂了 mp4。具体哪一种,要看那一次对话记录 |
| 四家大不相同吗? |
是,差在工具处理与产品入口 |
相同:都不会直接把视频交给模型。不同:拒绝响不响、有没有生成/播放 |
| Grok 会不会看视频? |
分析画面:不会 |
能生成、能播放;播放用的帧不会自动算「模型看过」 |
请求里有没有视频内容块
检查位置
我先检查发送给模型的数据结构。要把整段 MP4 交给模型,需要对应的内容类型、文件传递方式和服务端支持;依赖中出现一个 Video 类型名,并不能说明客户端已经接通这条路径。
下面列的是这次检查到的四套输入实现。结论限于这些代码,不涵盖同品牌的网页产品或其他 API。
2.1 Codex
Codex 的用户输入类型列有文字、图片、本地图片路径、Skill 和 Mention 等,没有本地视频类型。检查到的实时配置也没有启用视频输入。
要点
能提交:文字、图片、本地图片路径…
不能提交:视频路径 / 视频内容块
官方能「看」的入口:只有图
2.2 Pi
Pi 的这份协议把用户内容定义为文字和图片,提问时可以附带一组图片。会话树和分支摘要处理的是历史组织,不会增加视频输入类型。
2.3 Claude Code
Claude Code 的读文件结果包括文字、图片、笔记本和 PDF。图片分支识别常见静图格式;依赖 SDK 中的 Video 类型没有出现在这里检查的主请求路径上。
2.4 Grok Build
Grok Build 的这份对话协议包含文字和图片。代码中的视频地址主要用于接收生成结果和下载文件,不能据此认定请求端支持上传视频进行分析。
小结
这些客户端已经有图片入口,因此可以先抽帧再提交。这是后文实测采用的路径;调用其他视频服务也是可能的扩展方式,但本次没有验证。
读文件工具怎样处理 MP4
检查位置
接着看工具行为。支持读取图片,不代表工具会替 MP4 解码、采样并提交帧图。我在检查的默认路径中没有找到这套自动处理流程。
| 图片 | 视频 | 你的感觉 |
| Claude | 压缩后当图读 | 明确:二进制,不能读 | 明确返回二进制错误 |
| Codex | 看图工具 / 本地图 | 没有「读视频」工具 | 本次直接读取失败;可用终端自己绕 |
| Pi | 认静态图 | 不认 video | 不会当图给模型 |
| Grok | 粘贴图 / 读 image | 当二进制拒绝 | 挡文件;旁边能生成、能播 |
Claude:两张名单
Claude Code 对图片和二进制文件分别处理。png、jpg 等会进入图片分支;mp4、mov、webm 等在二进制名单中,读取时返回错误,不会在这条路径里逐帧解码。
Codex:看图工具只服务图片
Codex 的看图工具读取静态图片。Agent 仍能在终端运行 ffmpeg,再把导出的图片交给看图工具;转码、剪辑脚本和页面布局等任务,也可能只靠代码与媒体参数完成。
Pi / Grok
Pi 的默认输入中没有视频类型。Grok Build 需要另行区分读文件、视频生成和播放入口,后两者的存在不等于前者会提供视频画面。
小结
要判断某次任务有没有读取画面,查看工具调用和实际提交的内容即可。错误提示是否醒目、终端能否执行辅助程序,都不能代替这一步检查。
生成和播放不等于分析
检查位置
生成接口接收提示词并返回视频,播放器把文件展示给用户,内容分析则需要把视频或采样画面送进模型。这三种功能可以同时出现在一个产品里,但数据路径不同。
| 能力 | Codex | Claude | Pi | Grok | 模型算看过吗? |
| 直接分析视频 | 无 | 无 | 无 | 无 | — |
| 看图片 | 有 | 有 | 有 | 有 | 会 |
| 生成视频 | 无* | 无 | 无 | 有 | 产出文件,≠ 看懂 |
| 播放视频 | 无 | 无 | 无 | 有 | 不会(给人看) |
文档里出现 Sora 等名称,也需要找到实际的输入调用,才能确定该入口能做什么。
Grok Build 中相关功能可以按数据去向分开看:
- 分析——看图,模型算看过图;
- 生成——写出 mp4 文件;
- 播放——终端播给你看,模型不当作看过。
这份实现能生成和展示视频;本文检查的画面分析路径仍依赖图片输入。这个结论不延伸到 Grok 的其他产品或后来版本。
任务可能怎样完成
判定(结论)
接下来才是任务结果的问题。视频处理常包含剪辑、转码、提取字幕、生成代码或检查画面等不同要求,其中一部分可以在不把视频交给视觉模型的情况下完成。
几种可能路径,要用日志区分
下表列出可发生的处理方式,不是使用频率排名。判断一个案例属于哪种,需要查看当次会话的工具结果,尤其是有没有实际产生并提交帧图。
| 路径 | 靠什么 | 实际在干什么 | 怎么验证 |
| A | 任务本来就不用看画面 | 改脚本、修播放器、写配置、对接 API | 对话里几乎没读 mp4、也没截帧 |
| B | 自己截帧再当图看 | 终端 ffmpeg 导出图,再走看图 | 日志里有 ffmpeg,后面有看图 |
| C | 你已经把内容说明白了 | 口述、字幕、剧本、关键截图 | 用户消息里已有描述或图 |
| D | 只动旁边的文本 | srt / json / prompt | 读的是文本 |
| E | 缺少画面证据的描述 | 仅依据文件名推测 | 检查描述能否追溯到画面输入 |
同一个 MP4:直接读取失败,抽帧后可读
实测(事实)· 2026-08-04
测试先把本地 MP4 交给 Codex 的 view_image,再用 ffmpeg 抽帧,将 JPEG 交给同一入口。两次结果对应下表中的路径 B,输入文件和抽帧参数如下。
| 步骤 | 操作 | 本次测试结果 |
| 样本隔离 | 选择只有 source.mp4、没有同目录字幕或 JSON 的 15.069 秒视频;临时改名为 sample.mp4 | H.264 · 864×496 · 24 fps · AAC;SHA-256 67190c6532f5…72ae19 |
| 直接读取 | view_image(sample.mp4) | image content omitted because it could not be processed;没有画面进入视觉结果,也没有产生内容描述 |
| Shell 抽帧 | ffmpeg 在 0、2.5、5、7.5、10、12.5 秒取六帧,拼成 JPEG 联系表 | 成功生成 1296×496 静态图 |
| 图片读取 | view_image(contact-sheet.jpg) | 成功看到厨房内两名成年人,并能比较六帧中的人物表情和取景范围变化 |
本次实测的关键命令
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height,avg_frame_rate sample.mp4
ffmpeg -i sample.mp4 -vf "fps=1/2.5,scale=432:248:force_original_aspect_ratio=decrease,pad=432:248:(ow-iw)/2:(oh-ih)/2:black,tile=3x2" -frames:v 1 contact-sheet.jpg
这次会话的画面识别发生在 JPEG 进入 view_image 之后。直接读取 MP4 没有成功,Shell 抽帧为已有的图片工具提供了可用输入。
六张帧图只覆盖若干采样时刻,没有覆盖完整音轨和逐帧动作。一个样本也无法判断 A–E 哪条更常见,或代表所有 Codex 版本的行为。
| 你怎么做 | 更可能发生什么 |
| mp4 → Claude 读文件 | 明确报错 → 你立刻知道没看成 |
| mp4 → Codex | 官方不看;活能绕开画面就照样做成 → 容易误以为会处理视频 |
| Grok 生成/打开 mp4 | 能产、能播 → 「会视频」感觉更强;模型仍没按视频去理解 |
抽帧之后还会损失什么
抽帧间隔决定哪些时刻会被遗漏,缩放尺寸影响小字和局部细节,静图本身也不包含音轨。即便图片入口工作正常,仍要按任务补充字幕、音频转写或更密的采样,不能把几张图片当成完整时间轴。
做成产品时,需要补上的流程
这次对照暴露出的缺口可以直接落到产品设计上:说明输入能力,提供明确的预处理步骤,并在结果中保留模型实际看过的内容范围。
先声明支持的输入
- 对外只承诺:能处理文字和图片
- 用户上传视频时,不要写「模型将直接理解视频内容」
把预处理接成可检查的流程
做成固定流程:
流程
视频文件
→ 沙箱里 ffmpeg 截帧(关键画面 / 均匀取样,需要时抽字幕)
→ 压成各家都吃得下的静图
→ 走各家已有的「看图」
→ 输出带时间信息的说明
→ 截帧失败就明确失败,禁止假装分析过
界面区分生成、播放与分析
- 能力表强制三列:理解 | 生成 | 展示
- 验收:直接丢 mp4 → 应拒绝,或能看到自动截帧的证据
日志记录实际输入
- 截了哪些帧、哪些图进了对话、模型实际吃到几张图
- 是否生成了成片、是否播放了成片
- 「播过」和「模型看过」不要记成同一次成功
附录 · 四家流程(查阅)
简图
Codex 图片→看图工具→模型 │ 视频→官方无对等路径,终端可自助截帧
Claude 读图→压缩当图 │ 读 mp4→报错(二进制)
Pi 读静图→缩放→模型 │ 视频不是一等能力
Grok (A)看图 (B)生成mp4 (C)终端播放(给人看)│ 读 mp4→拒绝
这次对照说明了什么
给 Agent 一个 MP4 后,下一步应检查它拿到了什么。对这次 Codex 测试,答案是 ffmpeg 导出的六张 JPEG;对只改转码脚本的任务,模型可能根本不需要画面。
后续判断应依据实际提交的内容和工具结果。文件路径、视频播放器和一段听起来合理的描述,都不能单独证明模型看过整段视频。