DeepSeek Vision接入Codex与Harness：给编程智能体装上眼睛

DeepSeek的Vision能力接入Codex和Harness这事，最近在开发圈里讨论度一下子高了起来。说白了，以前大家在终端里跑Codex这种编程智能体，它只能“读文字”，代码报错信息、终端日志这些纯文本没问题，可一旦涉及截图、UI原型、设计稿、图表这些视觉内容，它立刻就抓瞎了。现在Vision进来了，相当于给终端里的编程智能体装上了眼睛，这个变化对日常开发流程的影响其实比想象中大得多。

加上Harness这边的接入，意味着不光能在交互式工具里用上视觉能力，还能批量跑评测、做自动化验证。这篇文章我就把完整的接入过程和实测结果整理出来，覆盖Codex CLI和Harness两条链路，从安装配置到真实任务的效果对比，踩过的坑也会一并列出来，给想上手的人一个可以直接照着操作的参考。

1. 这次“长眼睛”到底意味着什么

1.1 Codex和Harness在整条链路里的角色

先把两个工具定位弄清楚，后面配置起来才不会云里雾里。

Codex很多人已经比较熟了，它是OpenAI推出的终端编程智能体，跑在命令行里，可以读取项目代码、执行命令、修改文件，把“理解需求-改代码-跑测试-修Bug”这个循环自动化。它本身支持配置自定义模型提供商，也就是说不一定非要用OpenAI自家模型，只要能兼容对应的API协议，就可以把其他模型接进来。这也是DeepSeek能接入Codex的基础。

Harness这个词稍微绕一点。在AI工程语境里，Harness指的是“评估脚手架”或“测试框架”，它的职责不是像Agent那样帮你写代码，而是把模型放在一个标准化的环境里，喂给它一批测试任务，统一收集输出、计算指标、对比不同模型的表现。常见的lm-evaluation-harness就是干这个的。这次DeepSeek Vision接进Harness，意味着视觉模型可以在标准benchmark上批量跑评测，而不是只能靠人工一张张看图判断效果。

两者定位差异可以概括成：Codex是“干活的”，Harness是“打分的”。干活的不长眼睛，很多任务做不了；打分的不长眼睛，评测就测不准。Vision同时补上了这两块短板。

1.2 DeepSeek Vision带来了哪几类新能力

DeepSeek的Vision模型（VL系列）是视觉-语言多模态模型，核心能力在于能同时理解图像和文本，再基于两者生成输出。具体到实际开发场景，以下几类能力最常用，也最容易直接产生价值。

第一类是截图与UI理解。给模型一张页面截图，它能描述页面结构、识别按钮位置、提取界面上的文字信息，甚至能判断布局是否符合某个设计规范。这在自动化测试、页面还原、UI走查里非常有用。

第二类是文档与图表解析。论文里的公式截图、数据表格、折线图柱状图，模型能提取出结构化信息，转换成Markdown表格或者JSON数据。对经常处理技术文档和数据分析的人来说，这个能力能省掉大量手工录入时间。

第三类是视觉驱动的代码生成。结合截图或设计稿描述，模型生成对应前端代码。虽然离“设计稿一键变网页”还有距离，但作为初稿生成器已经能派上用场，尤其是配合Codex这样的智能体做后续迭代。

第四类是图文混合的推理。比如“根据这张架构图，解释这个系统有哪些模块”“看这个报错截图，判断问题可能出在哪一步”。这类能力把视觉理解和逻辑推理结合起来，实用性很强。

1.3 这套方案适合谁

我梳理了一下，下面几类人从这套方案里获益最大。

正在用Codex做自动化开发的工程师。如果你已经在终端里用Codex跑任务，但经常因为“看不清图片”而卡住，接上DeepSeek Vision后，工作流会顺很多。

需要批量评测多模态模型的算法工程师。以前测视觉模型要么用官方脚本，要么自己写评测流程，接入Harness后可以直接用统一框架跑，省不少事。

经常处理截图、文档、图表类信息的内容开发者。比如要定期把报表截图整理成结构化数据，或者根据UI图写前端代码，这类重复劳动很适合交给带视觉能力的智能体干。

刚接触多模态模型、想低成本试水的个人开发者。DeepSeek的API价格比主流闭源视觉模型便宜不少，用来学习、验证想法、做个人项目都很合适。

2. 接入前的准备和方案选型

2.1 需要准备的四样东西

动手之前先把东西备齐了，免得配到一半发现缺这缺那。

第一，一个DeepSeek开放平台的API Key。这是调用所有DeepSeek模型的基础凭证。去开放平台注册账号，在控制台里创建API Key，创建时它会提示你保存，这个Key只会完整显示一次，一定要先复制下来存好。DeepSeek目前多模态接口走的是OpenAI兼容协议，基础地址是https://api.deepseek.com，这点后面配置Codex和Harness都要用到。

第二，本机装好Python 3.10以上环境。Codex CLI本身是Rust写的，不依赖Python，但Harness那一套是基于Python的，很多依赖库需要Python环境来装。建议用python3 -m venv开个独立虚拟环境，别和系统Python混在一起，后面踩依赖冲突坑的概率会小很多。

第三，Node.js和npm。Codex CLI虽然可以直接用安装脚本装，但有些扩展和辅助工具走npm更方便。版本建议Node 18 LTS以上，太老的版本在拉取依赖时会遇到兼容性问题。

第四，一个可以跑命令行工具的终端环境。macOS上用自带Terminal或者iTerm2都行，Linux下随便哪个终端模拟器都可以，Windows用户建议用Windows Terminal配合WSL，纯PowerShell环境跑起来会遇到一些路径和权限问题，折腾成本高。

2.2 方案选型：为什么选Codex加Harness这条组合路线

市面上能接DeepSeek Vision的工具不少，为什么不选其他的，偏偏是Codex和Harness的组合？这个选型逻辑值得掰开说一下。

先看Codex这边。目前主流的终端AI编程工具有好几款，有的更像“聊天机器人”，有的更像是“代码补全插件”。Codex的核心差异在于它被设计成一个真正的Agent——有工作区读写权限，能自己执行命令，能根据错误反馈自动修正，而且配置文件支持细粒度控制模型提供商。这意味着我可以把DeepSeek Vision作为它的“视觉大脑”，让它在一个已经验证过的Agent框架里干活，没必要从零造轮子。

Harness这边就更明确了。要做视觉能力的评测，要么用模型厂商自己提供的测试脚本，要么用社区通用的评测框架。厂商自带脚本的问题是只测自家的，没法横向对比；社区通用的评测框架则提供了统一的数据集加载、采样、指标计算和结果导出能力，不管是横向对比还是回归测试都方便得多。EleutherAI的lm-evaluation-harness是目前社区生态最完整的，支持的数据集覆盖了语言、推理、多模态多个方向，选它作为评测底座是顺理成章的。

组合起来的效果就是：Codex负责“用”，Harness负责“测”。一套能力两条链路，产出和验证都能闭环。

2.3 关于API兼容性和模型命名的几个细节

接DeepSeek Vision之前，有几个易混淆的细节必须搞清楚，不然会在这个环节浪费不少时间。

DeepSeek开放平台目前有多种模型可用。纯文本对话模型、推理模型、以及这次要用到的视觉-语言模型，它们的接口地址和请求格式大体一致，但模型名称不同。配置Codex的时候，模型名要填对，填错会直接报“model not found”。

API的base_url也有讲究。DeepSeek兼容OpenAI格式，基础地址一般是https://api.deepseek.com或https://api.deepseek.com/v1，大部分情况下两种写法都兼容，但在某些工具里必须用带/v1的路径才能正确解析。Codex这边我建议直接用带/v1的地址，少踩一个坑。

还有一个点是鉴权方式。DeepSeek的API Key通过Authorization: Bearer <key>头传递，凡是支持OpenAI格式的工具都认这个。配置环境变量时统一用DEEPSEEK_API_KEY这个名字，既清晰又能避免和OpenAI的Key混淆。

提示：环境变量里的Key千万别写进仓库或配置文件提交到代码库。我这边的做法是单独放一个.env文件然后加进.gitignore，配置工具时通过$DEEPSEEK_API_KEY引用。

3. Codex接入DeepSeek Vision实操

3.1 安装Codex CLI并完成初始化

Codex CLI的安装方式取决于你的操作系统。macOS用户用Homebrew最省事：

brew install codex

Linux用户一般用官方安装脚本：

curl -fsSL https://codex.openai.com/install.sh | bash

Windows用户建议先装好WSL，然后在WSL的Linux环境里执行上面的脚本，体验和原生Linux基本一致。

装完后先执行一次初始化：

codex init

初始化过程会问你几个问题，包括是否登录ChatGPT账号、API Key从哪里来等。因为我们后面要自定义配置DeepSeek，这一步可以跳过登录，直接按提示生成默认配置之后再手动改。

初始化完成后，Codex会在~/.codex/目录下生成配置文件，核心是config.toml。这个文件就是我们接下来要动的地方。

3.2 配置自定义模型提供商，把DeepSeek Vision挂进去

打开~/.codex/config.toml，你会看到一段默认配置。我们需要在model_providers下面注册DeepSeek，然后把默认模型切到DeepSeek Vision。参考配置如下：

model = "deepseek-vl2" model_provider = "deepseek" model_providers = { deepseek = { name = "DeepSeek" base_url = "https://api.deepseek.com/v1" wire_api = "chat" env_key = "DEEPSEEK_API_KEY" http_headers = [ "Authorization: Bearer ${DEEPSEEK_API_KEY}" ] request_max_retries = 4 request_timeout = 600 } }

逐项说一下每个字段的含义。

model和model_provider是顶层配置，分别指定默认模型和默认提供商。deepseek-vl2是DeepSeek视觉-语言模型的名称，具体以你API账户里可用的模型名为准，可以通过查模型列表接口确认。

model_providers是一个映射表，里面每个key代表一个提供商。base_url是API服务地址，这里填https://api.deepseek.com/v1，Codex会在这个地址后面拼接实际的接口路径。

wire_api指定通信协议格式。这里填chat表示走OpenAI的/chat/completions协议，Codex对DeepSeek这类兼容OpenAI格式的第三方模型基本都用这个。如果你的工具支持responses协议，也可以填responses，但就我实测来看，DeepSeek的/v1/responses支持情况还不稳定，用chat最稳。

env_key告诉Codex去哪个环境变量读取API Key。http_headers这里也可以直接硬编码Key，但那样不安全，还是建议通过环境变量引用。

request_max_retries和request_timeout是容错参数。前者控制失败重试次数，后者控制单次请求超时时间，涉及视觉任务时图片上传和推理耗时会变长，超时时间建议给足，600秒是个保险值。

改完配置后，设置环境变量：

export DEEPSEEK_API_KEY="sk-你的key"

然后就可以启动Codex了：

codex

启动后如果在交互界面里正常响应，说明Codex已经成功接到DeepSeek上了。但这只验证了文本能力，Vision验没验还需要进一步确认。

3.3 验证视觉链路是否真正打通

光能聊不行，必须验证图片能不能传进去、能不能被正确理解。我找了个最直接的办法：让Codex读一张本地截图。

在Codex会话里执行：

请你查看当前目录下的screenshot.png，告诉我这个页面的标题和主要按钮分别是什么

然后看Codex的返回。如果它能准确描述出截图里的文字内容和界面结构，说明视觉链路已通；如果它回复“我看不到图片”或者“无法访问该文件”，说明图片读取环节有问题，需要检查路径以及当前模型是否真的支持视觉输入。

这里有个容易踩的坑：Codex默认会把文件内容塞进上下文，但如果文件太大或者格式不被支持，处理方式会不一样。对截图类任务，建议先把图片压缩到2MB以内，分辨率也不要太夸张，否则可能触发长度限制或者被降采样。

我实测下来，一个1920×1080的普通网页截图，压缩到1MB左右，DeepSeek Vision能准确识别出页面标题、导航栏文字和主要按钮。一旦这一步过了，后面所有依赖视觉的任务就都能跑了。

4. Harness接入DeepSeek Vision实操

4.1 Harness和Agent到底差在哪

很多人搞不清Harness和Agent的区别，这里多说两句，因为这直接关系到配置思路。

Agent是“干活的”。它有目标、有工具、能自主决策，比如Codex就是一个Agent。你给它一个任务，它会自己规划、执行、检查结果，整个流程是动态的。

Harness是“打分的”。它不决策，不干活，它做的事情是把一批测试输入喂给模型，收集输出，然后和标准答案比对算出分数。整个过程是静态的、批量的、可重复的。用生活化的话说，Agent是运动员，Harness是裁判和计时器。

为什么要分这么清楚？因为评测这件事必须标准化。如果你让Agent自由发挥去解一个题目，它可能用了工具、查了资料、推理了十步，那它得到的分数到底算模型的能力还是算Agent框架的能力？说不清楚。Harness解决了这个问题——它对所有模型一视同仁，同样的输入、同样的约束、同样的评分标准，才能横向对比。

这次DeepSeek Vision接入Harness，本质上是把视觉模型放入一个标准评测框架，跑指定的视觉任务集，得到可对比的量化结果，而不是让人肉眼看效果。

4.2 安装并初始化评估框架

我这边用的是社区生态最完整的lm-evaluation-harness框架，它对多模态模型的支持已经比较成熟。安装方式推荐通过pip装进虚拟环境：

python3 -m venv eval-env source eval-env/bin/activate pip install lm-eval

装完后先跑个自检命令，确认框架能正常工作：

lm-eval --model_list

这个命令会列出当前框架支持的所有模型接口类型，包括openai-completions、local-completions、vllm等。我们要用的就是openai-completions这个接口，因为DeepSeek的API是OpenAI兼容格式，通过这个接口类型可以直接喂给它评测数据。

接下来验证API连通性。用下面这个命令跑一个最简单的任务：

lm-eval \ --model openai-completions \ --model_args model=deepseek-vl2,base_url=https://api.deepseek.com/v1,api_key=$DEEPSEEK_API_KEY \ --tasks winogrande \ --num_fewshot 0 \ --limit 5

winogrande是偏向常识推理的数据集，只跑5条做连通性验证。如果能看到类似“acc”的指标输出，说明Harness到DeepSeek的链路已经通了。

4.3 配置视觉评测任务并跑起来

连通性验证之后，就可以配置真正和视觉相关的评测任务了。lm-evaluation-harness对多模态任务的支持方式是通过image选项传图片路径，配合文字问题形成“图文对”输入。下面是一个实用的评测配置示例：

lm-eval \ --model openai-completions \ --model_args model=deepseek-vl2,base_url=https://api.deepseek.com/v1,api_key=$DEEPSEEK_API_KEY \ --tasks mmmu_validation \ --num_fewshot 0 \ --batch_size 1 \ --output_path results/deepseek-vl2-mmmu.jsonl

MMMU是一个综合性的多模态理解评测集，覆盖图表、示意图、OCR等多种视觉理解任务，非常适合作为视觉能力的基准测试。

跑评测时需要注意batch_size参数。多模态评测和纯文本不一样，每条样本都包含图片，内存和显存开销比纯文本大得多。即使是走API调用，并发太高也容易被限流。我实测下来batch_size设为1最稳，虽然慢一点但不容易出错。

评测结果会输出到指定的JSONL文件，里面包含每条样本的输入、模型输出和得分。用Harness的价值就在于：这批结果是可以沉淀的，跑十次模型更新，十次的结果都在，随时可以做回归对比。

5. 实测：三组有代表性的视觉任务

5.1 任务一：网页截图理解与结构化提取

第一个实测任务是网页截图理解。我从一个数据后台截了张图，包含顶部导航、左侧菜单、中间的数据报表表格。然后让Codex里的DeepSeek Vision完成三件事：描述页面整体布局、提取表格中的数据、判断页面是否有告警信息。

结果是：页面布局描述准确率很高，能正确说出“顶部蓝色导航栏包含三个入口，左侧是折叠菜单，中间区域是数据报表”这样的结构化描述。表格数据提取方面，数字和列名都能正确识别，但有一处把“同比下降8.3%”识别成了“同比下降8.2%”，百分号后面小数位出错，这个误差在涉及具体数据的场景下要留个心眼。告警信息判断正确，能识别出右上角的红色告警图标并给出相应说明。

总体表现是可用级别——做UI走查和页面结构梳理完全够用，但涉及精确数值提取时还是需要人工复核。

5.2 任务二：技术文档中的图表内容解析

第二个任务更贴近技术场景：给模型一张系统架构图，里面包含模块名称、箭头指向、标注文字，要求它用Markdown格式输出架构层次和模块关系。

这个任务考验的不只是OCR，还有对图示关系的理解能力。实测下来，模块名称的OCR识别率很高，架构图的层级关系描述也基本准确，能正确说出“数据层包括三个模块，分别对外提供两类接口”。但有一个细节问题：当箭头交叉较多时，模型偶尔会把模块间的依赖方向搞反，把A依赖B说成B依赖A。这类关系型错误在复杂架构图上尤其容易出现，用它生成初稿可以，但最终还是要人工确认一遍逻辑关系。

5.3 任务三：视觉驱动的代码生成

第三个任务直接用它干活：给一张简单的登录页面设计稿，要求生成对应的HTML和CSS。

生成的代码结构是完整的，包含用户名输入框、密码输入框和登录按钮，样式上还原了设计稿的大致配色和布局。但离像素级还原还有差距，比如设计稿里的圆角大小、阴影效果、按钮的悬停态这些细节，模型生成的版本都比较朴素。

不过注意，这只是一个初始版本。把生成结果交给Codex继续迭代修改的时候，模型可以看懂我在终端里贴出的新截图和调整意见，这种“看得见”能力让整个开发循环顺畅了很多——以前做不到的UI任务，现在至少能从零到一搭起个能看的东西。

5.4 实测表现的两个关键发现

三组任务跑下来，有两个比较重要的观察。

第一个发现是：DeepSeek Vision在“理解型”任务上的表现明显好于“生成型”任务。让模型描述一张图、提取信息、判断关系，它完成得相当不错；但让它根据图片生成复杂代码或高精度还原设计稿，能力还有明显天花板。这和很多多模态模型的共性表现一致——理解容易、生成难。

第二个发现是：图片质量对结果的影响比想象中大。清晰度不足、文字过小、背景杂乱这三类情况会让识别准确率明显下降。实际操作中，我建议在喂图之前先做预处理：裁剪掉无关区域、放大关键部分、适当提高对比度。这个操作对比实测下来，识别准确率能提升一到两成。

6. 常见问题与排查技巧实录

6.1 Codex接入时的报错清单

接入Codex的过程中有几个高频报错，基本每个都能对号入座找到原因。

客户端缓存的坑也要提一下。改动config.toml之后，如果Codex好像一点反应都没有，先杀掉所有codex进程重新启动。我遇到过两次改完配置不生效的情况，都是因为旧进程还在跑着旧配置。

6.2 Harness接入时的报错清单

Harness这边的报错类型更集中，但也更隐蔽。

跑评测时最常遇到的是Connection error，多半是并发请求太高被API限流了，把batch_size降到1基本能解决。其次是json decode error，这通常是API返回了非JSON格式的错误信息，比如限流提示或网络中间层的不标准返回，处理办法是查看原始响应文本而不是只看解析后的报错。还有一个是No module named 'torch'，这是Harness依赖的大模型推理库没装全，虽然走API不需要本地推理，但有些数据加载组件仍然依赖torch，补个pip install torch就好。

跑长任务还有一个隐藏风险：评测中断。批量任务跑到一半网络抖动导致中断，前面的结果就全丢了。我的习惯是加--output_path参数边跑边写结果，同时开个tmux会话，这样即使终端断了任务还在后台继续，回来接着看进度就行。

6.3 几条容易被忽略的实操经验

最后分享几条实际摸索出来的经验，都是文档里不会写的东西。

第一，图片预处理永远值得做。别指望模型能处理任意质量的图片，裁剪、缩放、降噪这三步预处理几乎不加成本，却能明显提升识别准确率。尤其是截图类任务，把不相关的浏览器工具栏、状态栏裁掉，让模型专注核心区域，效果提升非常明显。

第二，视觉模型的上下文开销比文本大得多。一张普通截图的token消耗可能相当于几千个文本token，所以在配置Codex时，如果任务不涉及视觉，就不要把图片塞进去。Codex默认会把工作区文件加入上下文，要留意哪些文件被自动带上了，不然很容易触发上下文超限。

第三，评测结果的横向对比比绝对值更有价值。单看一次评测的准确率，意义有限；真正有价值的做法是用同一套Harness配置，分别跑不同版本的模型或者不同模型，放在一起对比。这样模型一更新迭代，你立刻知道哪些能力变强了、哪些变弱了，回归测试的意义就在这里。

第四，API调用费用要心里有数。视觉模型的成本一般高于纯文本模型，批量评测时尤其明显。建议先用--limit参数跑小样本验证流程，确认没问题再全量跑，避免重复扣费。

我自己的习惯是：Codex日常开发任务里接DeepSeek Vision处理视觉输入，Harness的评测任务固定在每周跑一次，跑完把结果存下来形成历史记录。这一套流程用熟了以后，视觉能力就不再是偶尔玩一下的新鲜功能，而是日常工作流里一个稳定的组成部分了。