企业官网建设流程全解析

很多用 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 在主流程里发现任务涉及图片，就会调用 Skill，Skill 内部请求视觉模型，再把结果返回给主模型继续编码。这种组合方式让文本模型和视觉模型各司其职，不用为了“能看图”而牺牲代码能力。

3. 环境准备与前置条件

开始之前，先把环境梳理清楚。下面的清单以通用情况为例，具体版本以你本机为准。

3.1 基础环境要求

版本检查命令：

node --version npm --version git --version

如果提示command not found，先安装对应工具，再继续。

3.2 安装 Codex CLI

Codex 的官方安装方式是通过 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.toml

4.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_url：DeepSeek API 的基础地址，末尾/v1一般不能漏。
• env_key：Codex 会读取这个环境变量名来获得 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 连通后，启动 Codex：

codex

进入交互界面后，先给一个简单任务，比如：

“请用 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) == 3

5.2 启动 Codex 执行任务

在项目目录下启动 Codex：

codex

输入任务：

“阅读 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_key=api_key, base_url=base_url) base64_image = encode_image(image_path) response = client.chat.completions.create( model=model, messages=[ { "role": "user", "content": [ {"type": "text", "text": "请描述这张图片的内容，提取所有文字信息，并总结界面结构。"}, {"type": "image_url", "image_url": {"url": f"data: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 判断成功与失败

7. 常见问题与排查思路

群里很多朋友问的第一个问题，其实是“为什么我的 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 工程化能力最快的路径。