很多用 Codex 写代码的开发者第一反应是“装好就能用”。真正上手后你会发现环境搭好只是开始模型选型、接口兼容、多模态扩展每一步都可能卡住你半天。尤其是想用 DeepSeek 这类高效模型替换默认模型时很多人会在配置层反复试错最后发现 Codex 的接入协议和模型能力边界才是关键。这篇教程要解决的就是这件事把 DeepSeek-V4-Pro 原生接入 Codex跑通一个真实的编码任务再配一个识图 Skill 补齐视觉理解能力。整个过程我会按“概念 → 环境 → 配置 → 代码 → 验证 → 排错 → 建议”的顺序拆开讲最后附上一些容易踩坑的细节。无论你是刚接触 AI 编程助手的新手还是已经在用 Codex 但想换成更顺手的模型这篇文章都能给你一份可以直接照做的路径。1. 为什么要折腾“换模型”这件事Codex 作为编程助手底层模型决定了它理解代码、生成代码、执行命令的上限。默认模型虽然综合表现不错但开发者在实际项目中往往有更具体的诉求有的希望降低调用成本有的希望中文理解更自然有的希望代码风格更贴近国内团队规范。这时候把模型替换成 DeepSeek-V4-Pro 就是一种很自然的解法。不过这里要先给一个判断Codex 和 DeepSeek 的对接核心不在 Codex 本身而在“它们之间使用什么协议沟通”。Codex 官方支持 OpenAI 兼容的接口协议DeepSeek 对外提供的 API 同样兼容这一协议。所以表面上是“换模型”实际上是在 Codex 的配置层指定一个新的模型提供方。这意味着你不需要修改 Codex 的源码也不需要写复杂的适配层只需要在配置文件里告诉 Codex“去哪个地址、用哪个 Key、调哪个模型”。这个思路一旦建立后续不管是接 DeepSeek 还是接其他模型你都能快速迁移。还有一类开发者的需求是“视觉”。DeepSeek-V4-Pro 作为文本模型本身不直接处理图片输入。但在真实开发里你经常需要给 AI 看设计图、截图、报错界面、手绘图让 AI 理解后生成代码。这个能力不能靠模型凭空变出来要靠一个额外的 Skill 来补位。所以这篇文章真正的价值是帮你建立一套可组合的 AI 编程环境主模型负责理解和生成代码Skill 负责扩展模型不具备的能力。两者配合Codex 才不是“一个聊天框”而是“一个能看图、能写代码、能执行命令的工程助手”。2. DeepSeek-V4-Pro 与 Codex 的核心概念2.1 DeepSeek-V4-Pro 是什么DeepSeek 系列模型来自深度求索特点是代码能力强、中文理解好、性价比高。V4-Pro 这个版本在标题里被标记为“正式发布”如果你想验证它的实际表现核心不是听宣传而是跑一组你自己的测试任务。比如让它读一段仓库代码、改一个 bug、写一个单元测试观察它的生成质量和速度。这里要特别提醒不同版本模型在 API 里的名称可能不同比如模型 ID 可能是deepseek-chat或类似名称。配置时必须以你实际拿到的 API 文档为准不要照搬别人文章里的模型名。2.2 Codex 是什么Codex 是 OpenAI 推出的编程智能体它不是在网页里对话的助手而是跑在终端里的工程工具。它能做这些事情读取你本地项目里的代码文件理解你提出的编码任务生成代码补丁执行 shell 命令运行测试并读取结果根据测试失败信息反复修正代码它的工作流非常接近一个真实工程师先看代码再改代码然后跑测试验证最后交付改动。Codex 的可配置性来自“模型提供方”model provider机制。它可以调用 OpenAI 默认模型也可以通过配置切换到其他兼容服务。这个机制就是 DeepSeek 接入的依据。2.3 Skill 机制是什么Skill 是 Codex 生态里的扩展机制可以理解成给 AI 编程助手加“职业技能”。Codex 默认的文本模型不会直接“看”图片但如果你给它挂一个“识图 Skill”它就能在需要的时候调用这个工具完成图像理解。Skill 一般包含两部分描述信息告诉模型什么时候该使用这个技能执行逻辑实际调用视觉模型把图片变成文本描述从架构上看这非常像函数调用function calling。Codex 在主流程里发现任务涉及图片就会调用 SkillSkill 内部请求视觉模型再把结果返回给主模型继续编码。这种组合方式让文本模型和视觉模型各司其职不用为了“能看图”而牺牲代码能力。3. 环境准备与前置条件开始之前先把环境梳理清楚。下面的清单以通用情况为例具体版本以你本机为准。3.1 基础环境要求项目推荐要求说明操作系统macOS / Linux / WindowsWindows 建议使用 PowerShell 或 WSLNode.js较新稳定版本Codex CLI 基于 Node.js 构建npm随 Node.js 安装用于安装 Codex CLIGit建议安装便于管理项目代码和补丁API KeyDeepSeek 平台申请用于调用 DeepSeek 模型接口版本检查命令node --version npm --version git --version如果提示command not found先安装对应工具再继续。3.2 安装 Codex CLICodex 的官方安装方式是通过 npm。打开终端执行npm install -g codex安装完成后验证codex --version如果这一步输出版本号说明 Codex CLI 已经装好。这里需要说明版本号会持续更新你本地拿到的最新版本即为当前可用版本不需要刻意追求教程里的某个数字。3.3 准备 DeepSeek API Key想要在 Codex 里调用 DeepSeek你需要一个有效的 DeepSeek API Key。这个 Key 一般是在 DeepSeek 开放平台上创建创建时需要实名认证并充值少量金额。拿到 Key 后先保存好下一步配置时要用。从安全角度出发不要把 Key 写死在项目代码里更不要提交到 Git 仓库。推荐使用环境变量或 Codex 提供的配置管理机制来保存。4. 核心流程拆解DeepSeek-V4-Pro 接入 Codex 的完整流程可以分为六个步骤。4.1 明确接入协议DeepSeek 的 API 兼容 OpenAI 接口格式这意味着 Codex 不需要额外插件只需要把请求的 base_url 指向 DeepSeek 的 API 地址把模型名称改成 DeepSeek 对应的模型 ID。这一步是整个接入的架构基础。4.2 初始化 Codex 配置Codex CLI 安装后会自动创建配置文件目录。配置文件一般位于用户目录下的.codex文件夹中常见文件名是config.toml。如果你的电脑上没有这个文件可以通过codex init命令生成。codex init执行后检查配置文件是否存在ls ~/.codex/config.toml4.3 配置模型提供方在config.toml中你需要声明一个模型提供方并指定 base_url 和 API Key 对应的环境变量名。下面是一份参考配置。# 文件路径~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY配置说明model实际调用的模型 ID。请以 DeepSeek 官方文档为准如果文档里的模型名不是deepseek-chat替换成真实名称即可。model_provider指定使用哪个提供方对应下方[model_providers.deepseek]配置块。base_urlDeepSeek API 的基础地址末尾/v1一般不能漏。env_keyCodex 会读取这个环境变量名来获得 API Key。也就是说你需要在系统环境变量里设置DEEPSEEK_API_KEY。然后设置环境变量export DEEPSEEK_API_KEY你的DeepSeek API Key为了让环境变量长期生效可以把它写入 shell 的配置文件中例如~/.bashrc或~/.zshrc。生产环境或团队协作时推荐使用密钥管理工具。4.4 验证 API 连通性配置完成后先不急着启动 Codex先用 curl 验证 API 能否连通。这一步能快速定位问题在网络层还是配置层。curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY如果返回一段 JSON里面包含模型列表说明 Key 有效、网络连通、地址正确。如果返回 401说明 Key 无效或鉴权头不对如果返回超时说明网络不通或者地址错误。4.5 启动 Codex 并测试基础对话确认 API 连通后启动 Codexcodex进入交互界面后先给一个简单任务比如“请用 Python 写一个函数判断一个字符串是否是回文。”这一步的目的是验证 Codex 能否成功请求 DeepSeek 模型。如果模型返回结果并且速度正常说明接入成功。4.6 跑一个真实编码任务基础验证通过后再跑一个贴近实际的任务。建议在你自己的项目里操作这样 Codex 能读取真实代码上下文。比如让它修复一个测试失败或者新增一个接口。这类任务能验证三件事模型是否能理解项目结构、是否能修改正确文件、是否能运行测试验证结果。5. 完整示例与代码实现下面给出一套可以完整跑通的示例流程。为了演示清晰我们创建一个临时项目目录里面放一个简单的 Python 文件和一个测试文件。5.1 创建测试项目mkdir -p ~/codex-demo cd ~/codex-demo创建calculator.py# 文件路径~/codex-demo/calculator.py def add(a, b): return a b def subtract(a, b): return a - b创建test_calculator.py# 文件路径~/codex-demo/test_calculator.py from calculator import add, subtract def test_add(): assert add(2, 3) 5 def test_subtract(): assert subtract(5, 2) 35.2 启动 Codex 执行任务在项目目录下启动 Codexcodex输入任务“阅读 calculator.py 和 test_calculator.py运行测试然后新增一个 multiply 函数和对应测试。”Codex 会读取文件、修改代码、执行测试。你需要观察的是它是否自动完成了“改代码 → 跑测试 → 根据结果修正”的完整循环。5.3 识图 Skill 的代码实现现在来写识图 Skill。这个 Skill 的目标是Codex 遇到需要理解图片内容的任务时调用一个视觉模型把图片转换成文本描述再交给主模型处理。我们先创建一个 Skill 目录mkdir -p ~/.codex/skills/image-ocr在目录下创建SKILL.md# 文件路径~/.codex/skills/image-ocr/SKILL.md name: image-ocr description: 当用户需要理解图片内容、截图、设计图、OCR文字识别时使用此技能。再创建一个执行脚本run.py# 文件路径~/.codex/skills/image-ocr/run.py import os import sys import base64 from openai import OpenAI def encode_image(image_path): with open(image_path, rb) as image_file: return base64.b64encode(image_file.read()).decode(utf-8) def analyze_image(image_path): api_key os.environ.get(VISION_API_KEY) base_url os.environ.get(VISION_BASE_URL, https://api.openai.com/v1) model os.environ.get(VISION_MODEL, gpt-4o-mini) client OpenAI(api_keyapi_key, base_urlbase_url) base64_image encode_image(image_path) response client.chat.completions.create( modelmodel, messages[ { role: user, content: [ {type: text, text: 请描述这张图片的内容提取所有文字信息并总结界面结构。}, {type: image_url, image_url: {url: fdata:image/png;base64,{base64_image}}} ] } ] ) return response.choices[0].message.content if __name__ __main__: image_path sys.argv[1] result analyze_image(image_path) print(result)这段代码的用途是调用视觉模型。如果你选择其他支持视觉的模型只需要改环境变量VISION_MODEL和VISION_BASE_URL核心逻辑不变。5.4 在 Codex 中调用识图 Skill实际使用时你不需要手动运行run.py。更好的方式是在 Codex 对话中描述任务让它自动判断是否需要识图。比如“请查看 design.png 这张设计图然后根据图中的布局生成一个 HTML 页面。”Codex 检测到任务涉及图片理解会通过 Skill 机制执行run.py把图片描述结果拿回来再生成代码。如果 Codex 没有自动调用你可以显式说明“请使用 image-ocr 技能处理这张图片”。5.5 模型配置的完整参考整合 DeepSeek 主模型和识图 Skill 之后完整配置如下# 文件路径~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY注意视觉模型的配置是通过环境变量在 Skill 脚本中独立管理的和 Codex 主模型配置互不干扰。这就保持了架构上的解耦。6. 运行结果与效果验证配置完成后用下面几个命令验证整个链路是否正常。6.1 验证 Codex 主模型运行codex对话中输入“请写一句话说明你是通过什么模型运行的。”如果返回结果正常说明 DeepSeek 已经作为 Codex 的主模型生效。6.2 验证识图 Skill准备一张测试图片test.png然后在 Codex 中输入“请使用 image-ocr 技能查看 test.png描述图片内容。”观察是否输出图片的文字和结构信息。如果上一步 Codex 不会自动调用 Skill可以手动在终端验证脚本本身python ~/.codex/skills/image-ocr/run.py test.png如果脚本能正确输出图片描述说明视觉链路是通的问题只在于 Codex 是否识别到了这个 Skill。6.3 判断成功与失败现象判断Codex 能正常对话且回复有代码风格主模型接入成功Codex 报错权限或 401API Key 无效或环境变量未设置Codex 能对话但回复很慢检查网络延迟或模型负载Skill 脚本单独运行正常但 Codex 不调用检查 SKILL.md 描述是否足够清晰图片生成代码时完全忽略图片可能没有触发 Skill需要显式指定7. 常见问题与排查思路问题现象可能原因排查方式解决方案启动 Codex 提示找不到模型model 名称配置错误查看 DeepSeek 官方模型列表替换为正确的模型 ID请求返回 401API Key 错误或环境变量未加载执行echo $DEEPSEEK_API_KEY重新导出环境变量检查 shell 配置文件请求返回 404base_url 地址错误用 curl 手动请求验证确认/v1路径是否完整Codex 不执行 shell 命令权限或安全策略限制查看 Codex 配置的权限项调整命令执行权限注意合规识图 Skill 无法触发SKILL.md 描述不够明确检查 Skill 目录位置和格式重写 description明确触发条件视觉模型返回结果为空图片过大或格式不支持检查图片格式和大小压缩图片或转换格式Codex 生成的代码无法运行模型上下文不足或需求描述不清查看生成代码的错误信息细化任务描述分步执行群里很多朋友问的第一个问题其实是“为什么我的 Codex 一直用默认模型”。这种时候我一般会让他们先跑一次codex --version再检查config.toml是否存在。大多数情况是配置文件根本没有生效或者环境变量没有写入当前 shell。还有一种很常见的情况是配置文件改了但 Codex 没有重启。配置文件的改动必须重启 Codex 进程才会重新加载这个细节容易忽略。8. 最佳实践与工程建议8.1 API Key 不落盘不要把 Key 写在config.toml里也不要把 Key 提交到 Git 仓库。使用环境变量或专业的密钥管理服务能显著降低泄露风险。如果怀疑 Key 泄露第一时间在平台后台轮换。8.2 配置文件纳入版本管理~/.codex/config.toml这种配置文件适合保存一份模板到 Git 仓库但模板中不要包含真实 Key。团队协作时新人拉取模板后只需要配置自己的环境变量就能快速接入。8.3 Skill 拆分原则识图 Skill 的脚本不应该绑定某一个具体视觉模型。通过环境变量传入模型名称和地址能让你在后续换模型时不需要修改脚本代码。这个原则叫“配置与代码分离”在 AI 工程化中很重要。8.4 任务描述要具体Codex 生成代码的质量很大程度上取决于任务描述的清晰度。不要只写“优化这段代码”要写清楚“这个函数在并发场景下偶发死锁请分析可能原因并修复”。模型能理解的信息越多输出越靠谱。8.5 先小步验证再批量执行在生产项目中使用 Codex 改代码时建议每次只让它处理一个小任务检查生成的 diff再决定是否采纳。不要让它一次改动十几个文件否则一旦出现问题回滚成本很高。8.6 定期检查模型更新DeepSeek 模型版本更新后API 模型名称和参数可能变化。升级版本前先阅读官方文档确认模型名、上下文长度、计费方式的变化再决定是否切换。8.7 理解 Skill 的边界Skill 不是万能插件它只是让 Codex 多了一项工具调用能力。识图 Skill 的准确度取决于底层视觉模型如果视觉模型本身识别不了复杂图表Skill 再完善也无济于事。选视觉模型时建议在真实任务中测试不要只看宣传。9. 总结与后续学习方向这篇教程主要解决了三个问题。第一DeepSeek-V4-Pro 接入 Codex 的原理是协议兼容不是源码改造。理解这一层你就不会被各种花哨的接入教程迷惑。第二完整跑通了一个编码项目从创建文件到让 Codex 自动改代码、跑测试、生成补丁让你感受到真实工作流下的 Codex。第三通过识图 Skill 补齐了文本模型的视觉短板。这个能力组合的思路比单纯“会安装”重要得多它能帮你应对更多真实开发场景。接下来可以继续深入的方向包括研究 Codex 的命令执行权限管理学习如何编写更复杂的 Skill了解多模型路由与按任务自动选择模型的架构。建议你新建一个专门测试 Codex 的仓库把常用任务整理成任务清单逐步验证不同模型的代码能力差异。实践是检验模型能力最有效的方式也是提升 AI 工程化能力最快的路径。