企业官网建设流程全解析

DeepSeek-V4-Pro 接入 Codex 这件事，最近问的人很多。这个模型如果用来实际写代码，最常见的门槛不是“会不会写”，而是怎么把它接到 Codex 上，让 Codex 的对话、补全、批量改代码全部走到 DeepSeek 的 API。另一个高频需求是视觉：Codex 本身偏向编码智能体，不能直接说“帮我看看这张截图里的报错”，所以需要单独配一个识图 Skill 来补。这篇文章把接入流程、Skill 配置、安装包处理和几个典型报错整理成一份可以照着走的教程。适合正在折腾 Codex 接入第三方模型、或者想把 DeepSeek 模型变成日常编程助手的开发者。

我建议先花两分钟搞清楚自己属于哪种情况：如果只是想让 Codex 能连上 DeepSeek 模型，看前 3 章就够了；如果还要处理图片、截图、界面识别，重点看第 4 章；如果已经在接入过程中报错，直接跳到第 5 章按顺序排查。

1. 先理解 DeepSeek-V4-Pro 接入 Codex 到底改了什么

1.1 这个组合解决什么问题

DeepSeek-V4-Pro 从模型能力上说，更擅长代码生成、代码解释、长上下文理解和中文场景的指令跟随。Codex 则是一个把“模型能力”变成“开发动作”的智能体外壳，它负责规划任务、调用命令行、修改文件和运行验证。

把两者接在一起，你得到的不再是“一个聊天窗口”，而是一个能理解项目目录、能连续处理多文件改动、能自己跑命令看结果的编程助手，只不过底层大模型换成了 DeepSeek-V4-Pro。

这对两类人最有价值。第一类是开发团队，希望在不改变 Codex 工作流的前提下，把默认模型换成更符合自己场景或者成本更可控的模型。第二类是个人开发者，想在本地或者云服务器上有一个相对稳定的编码 agent，同时保留 DeepSeek 的中文表达和长上下文能力。

1.2 为什么不是装完 Codex 就能直接用

Codex 默认情况下只认它自己配套的模型。要接 DeepSeek-V4-Pro，你需要做的是在 Codex 的配置里新增一个模型提供方，把请求地址、API Key、模型名都指向 DeepSeek 的服务。

很多刚上手的人卡在这里，是因为把“配置模型”理解成了“改个名字”。实际上每次请求都会带上模型名、请求地址和鉴权信息，三者必须同时正确。如果只改了模型名，API 会返回 400；如果只改了地址，鉴权又会出问题。

从接口返回的信息来看，DeepSeek 这边支持的模型名包括 deepseek-v4-pro 和 deepseek-v4-flash。pro 更适合复杂编码任务，flash 更适合快速验证和轻量任务。具体差别以平台文档为准，但接入时模型名必须精确匹配，不能多空格，不能加中文引号。

1.3 先想清楚自己的运行方式

接入之前，先确定你是用 Codex CLI、桌面应用，还是其他让它跑起来的界面。不同方式只是入口不同，底层配置链路类似，但报错时的排查路径不一样。

• CLI 方式：启动快，适合脚本化和批量任务，配置文件在用户目录下。
• 桌面应用：界面直观，适合日常交互，但可能依赖 CLI 二进制路径。
• CI 或服务端：适合自动化任务，需要把 API Key 放在环境变量或密钥管理里。

我在实测时更建议先用 CLI 方式把链路打通。因为 CLI 日志更直接，报错信息更容易定位，等链路稳定了再决定要不要迁移到桌面应用。

1.4 它还解决不了什么问题

接入方案解决的是“模型通道”问题，不解决“图片理解”问题。DeepSeek-V4-Pro 本身能不能直接读图，要看当前版本有没有多模态能力。如果标题里强调“再配一个识图 Skill 补齐视觉”，那就说明默认链路里并不包含图片输入。

另外，它也不解决项目结构混乱的问题。Codex 再智能，也需要一个相对清晰的项目目录、合理的依赖环境和可执行的验证命令。如果项目本身缺少入口文件、报错信息不完整，任何模型接进来都只能靠猜。

2. Codex 安装与 DeepSeek API 环境准备

2.1 安装包怎么选

最新版 Codex 安装包一般从官方 Release 页面下载。下载前先看两件事：你的操作系统是 Windows、macOS 还是 Linux；你的机器是 Intel、Apple Silicon 还是 ARM 架构。

我见过不少安装失败，不是软件问题，而是下载了不匹配的包。比如在 Apple Silicon 的 Mac 上运行 x64 版本，启动时会提示二进制无法执行。Windows 上则要区分 exe 安装包和免安装压缩包。如果你只是个人使用，优先选择官方发布的稳定版本，而不是 nightly 或预览版。

下载完成后，先解压到一个固定目录，不要放在临时文件夹或桌面上。原因很简单：后面 Codex 桌面应用需要定位 CLI 二进制，如果路径不稳定，就会出现“unable to locate the codex cli binary”之类的问题。

2.2 把 CLI 加入系统 PATH

无论用哪种方式安装，最终目标都是让系统能找到 codex 命令。Linux 和 macOS 下，常见做法是把可执行文件目录加进.bashrc或.zshrc：

export PATH="$HOME/codex-bin:$PATH"

Windows 下，可以在“系统属性 - 环境变量”里把解压目录追加到 Path。加完之后，开一个新的终端窗口执行：

codex --version

能看到版本号，说明安装链路是通的。看不到版本号，先检查目录是否真实存在、环境变量是否生效，而不是重新下载安装包。

2.3 准备 DeepSeek API Key 和请求地址

接入 DeepSeek-V4-Pro 需要三个信息：API Key、请求地址（Base URL）、模型名。

API Key 从 DeepSeek 开放平台获取，创建后只会完整显示一次，建议立刻保存。请求地址就是 API 服务的根地址，不要加多余路径，也不要带引号。模型名使用 deepseek-v4-pro。

这三个信息建议通过环境变量传入，而不是写死在配置文件里。一方面避免把密钥提交到 Git，另一方面换环境时不用来回改文件。

export DEEPSEEK_API_KEY="你的key" export DEEPSEEK_BASE_URL="https://你的接口地址" export DEEPSEEK_MODEL="deepseek-v4-pro"

这里要注意，不同 Codex 版本对环境变量的名字可能不同。有的版本读OPENAI_API_KEY，有的版本读DEEPSEEK_API_KEY。如果 API 返回 401，第一个检查项就是环境变量名字是否被 Codex 正确读取。

2.4 网络条件先确认

接入第三方 API 本质上是一次普通的 HTTPS 请求。你需要确保运行 Codex 的机器能正常访问 DeepSeek 的 API 地址。

这里最容易出现的误判是：Codex 能启动，但一发起请求就超时。然后很多人开始怀疑模型问题，实际是网络出口根本没通。你可以先用 curl 单独验证一次接口连通性，确认能返回 HTTP 状态码，再回到 Codex 里继续测试。

如果是在公司内网环境，可能还需要配置合规的 API 网关或内网访问方式。这个由网络管理员提供，不属于 Codex 本身的配置范围。不要擅自绕过网络限制，你应该优先走正规的访问通路。

2.5 安装包的校验习惯

下载安装包后，除了确认文件名和大小，还可以留意官方是否提供了校验值。如果页面附了 SHA256，建议校验一下，避免文件损坏或从不可信渠道拿到被篡改的版本。

校验文件的命令在 macOS 和 Linux 上是shasum -a 256 文件名，Windows 上可以用certutil -hashfile 文件名 SHA256。这个步骤看起来多花几秒钟，但能省掉后面很多莫名其妙的启动报错。

3. 把模型名和地址写进 Codex 配置

3.1 配置文件长什么样

Codex 的配置文件一般位于用户目录下，不同版本可能叫config.toml、settings.json，也可能是通过命令行参数注入。我建议先运行帮助命令，确定当前版本读取哪个文件：

codex --help

看到输出里有 config、settings、provider 相关的参数，优先使用这些命令管理配置，而不是手动猜文件路径。如果确实需要手动编辑，配置项通常包括模型提供方、请求地址、API Key、模型名和上下文长度。

下面是一个参考格式，代表了一种常见的模型提供方配置思路：

[model_providers.deepseek] base_url = "https://你的接口地址" api_key_env_var = "DEEPSEEK_API_KEY" model = "deepseek-v4-pro"

不同版本字段名可能不完全一样，落地时以你当前版本为准。重点是理解结构：它声明了一个名为 deepseek 的提供方，告诉 Codex 到哪里发请求、用什么密钥、使用哪个模型名。

3.2 模型名的坑

deepseek-v4-pro 这个模型名看起来简单，实际配置时很容易多出隐藏字符。尤其是从网页复制配置内容时，引号会被改成中文引号，空格可能变成不间断空格，导致 API 返回模型不存在。

还有一点：有些版本会显示带后缀的模型名，比如 deepseek-v4-pro[1m]。如果平台不支持这个写法，你会看到类似“there's an issue with the selected model”的报错。这时候先去掉后缀，只保留 deepseek-v4-pro 试试。

如果 API 返回的提示里列出了支持模型名，直接照着返回信息抄一遍，通常能解决。

3.3 发起单条测试请求

配置完成后，先别急着打开复杂项目，先用最小对话验证一次。在 Codex 里输入一句简单的指令，比如“用 python 写一个读取 csv 文件的函数”。

成功的标准不是它一定写出完美代码，而是：

• 请求没有返回 400 或 401
• 模型返回了正常文本
• Codex 没有立刻中断
• 日志里能看出它确实走到了 DeepSeek 的地址

如果超过 10 秒没有任何响应，先看终端输出是卡在请求还是卡在解析。卡在请求，多半是网络或地址问题；卡在解析，可能返回格式不兼容。

3.4 资源占用怎么看

Codex CLI 本身不跑大模型，所以对显存没有直接要求。普通开发机能跑，关键在于你的任务大小和请求频率。如果你同时挂了很长的项目上下文，内存占用会上升，但通常不是主要瓶颈。

真正需要考虑资源的是后面要讲的识图 Skill。如果识图能力也走云端 API，本地压力小；如果走本地视觉模型，就要考虑显存和内存。这一点在第 4 章会展开。

3.5 参数的边界理解

默认配置适合入门，但不一定适合生产任务。比如上下文长度、超时时间和并发数，这些参数在不同版本里都有默认值。批量任务跑起来之后，如果频繁超时，你需要单独调大超时时间，而不是反复重试。

但不要一上来就开最大并发。很多 API 限流不是按请求数，而是按并发数或每分钟 token 数。先把单任务调稳，再逐步提高并发，观察错误率变化，才是更稳妥的路径。

4. 用识图 Skill 补上视觉能力

4.1 Skill 到底是什么

很多第一次接触 Skill 的人以为它是一个安装包，双击就能装好。实际不是。Skill 更像是一份“给智能体看的说明文档加执行脚本”。

它的基本逻辑是：在特定目录下放一个描述文件，告诉智能体“当用户提到图片、截图、报错画面时，你可以调用某个脚本”；脚本会去完成具体的图像识别，再把结果返回给智能体，由智能体整理成答案。

所以在配置识图 Skill 之前，先确认你的 Codex 版本是否支持 Skill 机制。支持的话，通常会有一个固定的 skills 目录，指向它即可。如果不支持，也不要硬套，改成自定义命令或者 MCP 工具也能实现类似效果。

4.2 识图 Skill 的目录结构

一个典型 Skill 包括两个部分：描述文件和脚本。描述文件一般叫SKILL.md，脚本可以是 Python、Shell 或 Node.js。

skills/ image-reader/ SKILL.md read_image.py

SKILL.md里要写清楚触发条件和使用方法。比如：当用户上传截图、图片路径、或者询问“图里是什么”时，使用read_image.py读取图片，并调用视觉模型 API 返回图片描述。描述要尽量具体，智能体才知道什么场景下调用它。

4.3 写一个识图脚本

脚本的核心工作只有几步：读图片、转成基础格式、发给视觉模型、拿到文字描述、输出给智能体。

下面是一个示例结构，实际使用时需要替换成你自己能访问的视觉模型接口：

import base64 import sys import requests image_path = sys.argv[1] with open(image_path, "rb") as f: image_data = base64.b64encode(f.read()).decode("utf-8") resp = requests.post( "https://你的视觉模型接口", headers={"Authorization": "Bearer 你的key"}, json={ "model": "你的视觉模型名", "image": image_data, "prompt": "请描述这张图片中的主要内容，尤其是报错信息、文字和界面状态。" } ) print(resp.json()["description"])

这段代码不是完整可用版本，但流程是对的。如果视觉模型要求图片大小有上限，可以先用 Pillow 压缩再上传。如果接口返回的是 OCR 文本，也要解析成纯文本后输出。

4.4 验证 Skill 是否生效

配置好之后，找一张测试图片，尽量选包含明显文字的截图，比如代码报错截图、控制台输出截图。然后在 Codex 里问一句：“这张图片里写了什么？”

判断标准有三个：

• Codex 是否主动调用了识图脚本
• 脚本是否成功返回图片文字描述
• Codex 是否基于描述给出了下一步建议

如果 Codex 完全没有调用 Skill，先检查目录位置是否正确，以及描述文件里的触发条件是否清晰。如果脚本报错，单独运行一次脚本，不要带着 Codex 一起调试。

4.5 没有视觉模型时怎么降级

如果你的环境里没有可用的视觉模型，识图 Skill 还可以退化成 OCR 方案。比如用本地的 OCR 库提取图片中的文字，再做格式整理。这样只能拿到文字，不能理解图像里没有文字的内容，但对于“看报错截图”这个场景通常够用。

如果你手头能用的视觉模型是一个本地多模态模型，就要关注显存和内存。低配置机器也能试，但要把图片分辨率降下来，或者一次只处理一张图。千万不要用本地视觉模型直接跑批量识图，很容易把整台机器拖垮。

另外要提示一点：不要拿 Skill 去处理未经授权的隐私图片。技术本身没有边界问题，但使用者要尊重数据来源和他人授权，这也是一个工程习惯。

4.6 多个 Skill 并存时的注意点

如果你不只是配识图 Skill，还想加其他能力，比如生成流程图、写测试用例、处理数学建模任务，那么每个 Skill 的触发描述必须尽量独立。否则智能体可能混淆，用户问“帮我画一个架构图”，它反而调用了识图脚本。

常见的做法是在SKILL.md里写清“适合什么场景”“不适合什么场景”。不要把所有能力都堆在一个脚本里。脚本职责单一，调试起来才方便。

5. 按报错顺序排查接入问题

5.1 模型名不被识别

如果你看到的报错是“deepseek-v4-pro is not a model this version of claude code recognizes”，说明你的模型名被用在了不支持自定义模型的工具里，或者写错了位置。

排查顺序是：

1. 先确认你用的是不是 Codex，而不是其他类似工具。
2. 再确认模型名是写在 Codex 配置里，而不是在通用聊天参数里。
3. 最后确认模型名没有多余空格和后缀。

这类问题 90% 是位置写错，剩下 10% 是模型名过期。

5.2 CLI 二进制找不到

“unable to locate the codex cli binary”是很常见的启动报错。它的意思是：Codex 界面或插件启动时，需要调用 codex 命令，但系统 PATH 里找不到它。

常见原因有三个：

• 安装后没有把可执行文件目录加入 PATH
• 改了安装目录，但旧配置还在找老路径
• Windows 下没有重开终端，环境变量没刷新

解决方法是直接在终端执行codex --version，确认命令行能用。然后回到报错的界面，在设置里指定 codex_cli_path，指向真实存在的二进制文件。

5.3 API 返回 400

API 返回 400 时，响应体里通常会写明支持的模型名。比如：

{"error":{"message":"the supported api model names are deepseek-v4-pro, deepseek-v4-flash, and de..."}}

这说明请求已经到达服务端，但模型名或请求格式不对。你不需要重新安装 Codex，只需要把模型名改成响应中列出的准确值。

5.4 请求成功但输出为空

如果模型返回了 200，但 Codex 输出是空，问题往往出在解析层。部分模型返回的内容格式和 Codex 预期不一致，比如没有标准的文本段，或者返回了流格式但 Codex 没正确处理。

这时候到日志里看原始响应，如果原始响应有内容但 Codex 没显示，大概率是兼容性配置问题，可以在配置里调整响应格式相关字段。如果原始响应就是空的，再去查请求参数。

5.5 识图 Skill 无输出

识图 Skill 没有输出，先别怀疑 Codex。单独在终端里执行脚本，把图片路径传进去，看脚本能不能正常返回文字。脚本能跑，问题在 Skill 配置；脚本不能跑，问题在脚本本身或者视觉 API。

还有一个容易忽略的点：图片路径。Codex 调用 Skill 时，如果传的是相对路径，脚本工作目录可能和想象的不一样。更稳妥的做法是在脚本里先判断路径是否存在，不存在时打印完整路径，方便定位。

5.6 报错排查快速对照

这张表可以当作固定排查清单，遇到问题先对号入座，不要反复卸载重装。

6. 接入稳定后的几个生产建议

6.1 先单任务，再批量

不要把高并发测试放在第一次接入时做。先跑单条任务，确认模型名、地址、鉴权、返回格式都是通的，再考虑批量任务。

批量任务和单任务不一样的地方在于：失败重试、输出命名、日志记录。模型偶尔一次返回异常是正常现象，如果没有重试机制，一个任务失败可能影响整条流水线。

6.2 日志和输出目录提前规划

长期使用 Codex 接入 DeepSeek-V4-Pro，建议把日志和输出目录固定下来。任务输出文件不要散落在桌面和临时目录，统一放在项目下的outputs或logs目录。排查问题时，先看日志再改参数，不要凭感觉反复重启。

6.3 模型版本更新时重新检查模型名

DeepSeek 的模型名可能随版本调整，比如新增 flash 版本或者增加上下文长度标识。升级前先看平台文档，确认 deepseek-v4-pro 和 deepseek-v4-flash 这些名字是否仍然有效。配置里的模型名一旦过期，API 会返回 400，而不是自动切换。

6.4 API Key 要单独管理

不要把 API Key 写在配置文件的明文里，也不要直接提交到代码仓库。用环境变量注入，或者放到密钥管理服务里。如果发现 Key 泄露，第一时间到平台吊销并重新生成。这个习惯和 Codex 本身无关，但接入任何第三方 API 都适用。

6.5 保留最小可用配置备份

我每次调通一个新的模型接入，都会把最小可用的配置内容单独存一份，不包含真实密钥，只保留字段结构和注释。换机器、换环境、或者是团队成员需要复现时，直接拿这份模板改，比重新翻文档快得多。

识图 Skill 的脚本也一样。保留一个最简单的可运行版本，再在上面扩展其他能力。这样即使后来的复杂功能坏了，也能快速回退到可用状态。

最后留几个我自己排查时会优先看的点：第一，先分清楚是网络问题、鉴权问题还是模型名问题；第二，先单独运行脚本，再让 Codex 调用；第三，批量任务不要一上来就开最大并发。很多接入问题都不是模型能力不够，而是前置环境、路径和参数没有处理干净。