之前在使用 Codex CLI 做 AI 编程辅助时，默认接的是 OpenAI 模型，接口成本高，而且密钥管理、网络连通性都让团队协作变得很麻烦。后来发现 DeepSeek 完全兼容 OpenAI 的接口协议，只需要改 Codex 的模型供应商配置，就能把底层模型切换成 DeepSeek，顺便还能通过多模态模型链路实现“识图”类需求。整个过程比想象中简单，但也踩了不少坑，比如 wire_api 选错、base_url 拼接不对、Codex CLI 二进制路径找不到等等。
这篇文章就来整理一套完整的 DeepSeek 一键接入 Codex CLI 的速通方案，覆盖环境准备、配置编写、识图能力说明、高频报错排查和工程化建议。不管你是第一次接触 Codex，还是已经用了一段时间想切换到 DeepSeek，都可以直接按步骤操作。
1. 核心概念：Codex 与 DeepSeek 为什么能组合
1.1 Codex CLI 是什么
Codex CLI 是 OpenAI 推出的开源命令行 AI 编程助手，官方项目名通常写作codex，通过 npm 包@openai/codex分发。它运行在终端里，可以读取当前项目的文件结构、执行命令、修改代码，并且支持交互式会话和自动化脚本两种使用方式。
很多开发者会把它理解为终端里的“AI 结对程序员”。你可以在终端输入自然语言需求，比如“给这个模块补充单元测试”，Codex 会自动分析上下文、生成代码片段，甚至直接修改文件。它和 ChatGPT 网页版的区别在于，Codex 更贴近本地开发环境，能直接操作仓库内容，也更容易接入自定义模型供应商。
Codex CLI 本身并不只绑定 OpenAI 官方模型。它的设计里有一个model_providers配置概念，允许使用者自定义模型服务地址、鉴权方式和接口协议。这就为接入 DeepSeek 留下了空间。
1.2 DeepSeek API 为什么可以用
DeepSeek 是深度求索推出的大语言模型服务，它的开放平台提供了 OpenAI 兼容的 API 接口。也就是说，凡是支持 OpenAI SDK 的工具，通常都可以通过修改base_url和 API Key 来对接 DeepSeek，Codex CLI 自然也属于这一类。
DeepSeek 开放平台目前提供的主要模型名称通常是deepseek-chat和deepseek-reasoner，分别面向通用对话和推理任务。具体模型版本会跟随官方迭代调整，所以本文不会写死某个具体版本号。重点是，在 Codex 配置里只要把模型提供方指向 DeepSeek 的接口地址，并把模型名改成 DeepSeek 支持的模型名，就能让 Codex 使用 DeepSeek 的能力。
接入后的最大好处是成本和灵活性。DeepSeek 的定价通常比部分国外大模型更具竞争力，同时接口部署在国内，访问延迟和稳定性对国内开发者更友好。对于需要把 AI 编程助手推广到团队内部使用的场景，这种替换方案非常实用。
1.3 接入后的能力边界，尤其是“识图”
标题里提到的“支持识图”，这里需要提前说清楚能力边界。Codex CLI 在较新版本里支持在对话上下文中附加图片附件，这是客户端能力。但最终模型能不能理解图片，取决于你接入的模型是否是多模态模型，也就是是否支持视觉输入。
DeepSeek API 是否开放视觉输入能力，需要以 DeepSeek 开放平台的最新文档为准。如果某个模型版本只支持文本，即使 Codex 上传了图片，后端也会返回错误或忽略图片内容。因此，本文在实战部分会给出两种处理思路：一种是确认当前模型支持视觉后直接传图；另一种是通过接入其他 OpenAI 兼容视觉模型，来实现真正的“识图”。
简单总结：Codex 相当于一个支持自定义模型的车架子，DeepSeek 是发动机，而识图能力则是发动机的一个选装功能，不是所有发动机都带。
2. 环境准备与安装
2.1 检查本地环境
在开始之前，先确认本地环境是否满足 Codex CLI 的基本运行条件。
Codex CLI 依赖 Node.js 运行时，建议使用 Node.js 18 或更高版本。如果你通过 npm 安装，需要确保 npm 可用。操作系统方面，Windows、macOS、Linux 都可以运行，但不同系统在环境变量配置上略有差异。本文示例以 macOS 和 Linux 常用命令为主，Windows 用户可以把export换成set或在 PowerShell 中使用$env:NAME="value"。
检查环境的命令如下：
node -v npm -v git --version如果node或npm没有安装，需要先安装 Node.js 环境。安装方式有 nvm、Node 官方安装包、包管理器等，这里不做展开。git不是强制依赖，但 Codex 在分析项目时常常会读取 Git 状态，建议安装。
2.2 安装 Codex CLI
Codex CLI 最常用的安装方式是通过 npm 全局安装，命令如下：
npm install -g @openai/codex安装完成后，运行以下命令验证是否安装成功：
codex --version如果终端能输出版本号，说明 Codex CLI 已经安装成功。此时还不需要登录 OpenAI 账号，因为我们接下来会通过配置把模型供应商指向 DeepSeek。
如果你已经尝试运行过codex，可能会发现它默认会要求登录 OpenAI。这个环节可以通过自定义配置跳过，后面会详细说明。
2.3 获取 DeepSeek API Key
要去 DeepSeek 开放平台获取 API Key，需要先注册账号并登录控制台。在控制台的“API Keys”或类似页面，点击创建新的 API Key，复制保存。
API Key 通常以sk-开头，是访问 DeepSeek 接口的唯一凭证。它属于敏感信息，不要提交到 Git 仓库，也不要直接写死在代码里。后面配置 Codex 时，我们会通过环境变量来传递 API Key。
拿到 Key 后，在终端设置环境变量：
export DEEPSEEK_API_KEY="你的API Key"为了验证 Key 是否有效，可以用 curl 直接请求 DeepSeek 接口。这一步也能确认当前环境能否正常访问 DeepSeek 的 API 地址。
curl https://api.deepseek.com/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -d '{ "model": "deepseek-chat", "messages": [{"role": "user", "content": "你好，请回复 OK"}] }'如果返回结果中包含choices字段，说明 API Key 有效，网络连接也正常。如果返回401或invalid api key，请检查 Key 是否复制完整，是否有多余空格。
3. 编写 Codex 配置，接入 DeepSeek
3.1 config.toml 完整配置
Codex CLI 的全局配置位于用户目录下的~/.codex/config.toml。如果这个文件不存在，需要手动创建。默认配置里没有 DeepSeek 供应商信息，所以我们要新增一个模型供应商并把它设为默认模型。
下面是一份可以直接使用的完整配置示例：
# 文件路径：~/.codex/config.toml model = "deepseek/deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"保存文件后，重新打开终端并运行codex，Codex 就会尝试使用deepseek/deepseek-chat对应的供应商配置发起请求。环境变量DEEPSEEK_API_KEY会自动被读取作为鉴权凭证。
3.2 关键参数解析
上面这段配置虽然短，但每个参数都值得仔细理解。
model字段的写法是“供应商名称/模型名称”。Codex 会根据这个字段去[model_providers.xxx]段落里查找对应的供应商标识。这里的deepseek是我们自定义的供应商 id，不是官方内置值，所以一定要保证model里的前缀和模型供应商段落名称一致。
base_url是模型服务的根地址。Codex 在发起请求时，会根据wire_api来决定在根地址后面拼接什么路径。如果wire_api = "chat"，最终请求地址就是https://api.deepseek.com/chat/completions；如果wire_api = "responses"，最终请求地址就是https://api.deepseek.com/responses。
env_key指定读取哪个环境变量作为 API Key。这里配置成DEEPSEEK_API_KEY，就对应我们在终端里设置的export DEEPSEEK_API_KEY="..."。Codex 会在运行时读取这个环境变量的值，并放入 HTTP 请求的 Authorization 头中。
wire_api是最容易踩坑的配置项。DeepSeek 开放平台兼容的是 OpenAI Chat Completions 协议，对应的就是chat。如果错误设置成responses，Codex 会请求/responses路径，DeepSeek 接口通常不提供这个路径，结果就是 404 或接口无法识别。
3.3 验证 DeepSeek API 的 OpenAI 兼容性
在正式配置 Codex 之前，先用 Python 脚本验证一次调用，可以更直观地确认 DeepSeek 接受的请求格式。安装 OpenAI Python SDK 后，写一个最小脚本：
pip install openai# 文件路径：test_deepseek.py from openai import OpenAI client = OpenAI( api_key="你的API Key", base_url="https://api.deepseek.com" ) response = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": "你是一个简洁的助手。"}, {"role": "user", "content": "用一句话介绍你自己。"} ] ) print(response.choices[0].message.content)运行脚本：
python test_deepseek.py如果输出正常，说明 DeepSeek 的接口协议与 OpenAI SDK 完全兼容。此时再回到 Codex 配置层面，基本上不会出现协议层面的问题。
3.4 启动 Codex 验证接入
配置完成后，直接在终端运行：
codex如果 Codex 成功连上 DeepSeek，它会进入交互式对话界面。此时可以输入一个问题测试：
请列出当前目录下的文件，并说明每个文件可能的作用。Codex 会先读取目录结构，然后调用模型生成回答。如果模型正常返回内容，说明 DeepSeek 接入成功。
如果希望非交互式运行，可以用exec子命令。例如：
codex exec "用 Python 写一个快速排序函数，并附带测试用例"这种模式适合脚本化调用，也可以在 CI 流程里集成。
4. 识图能力支持：图片输入、模型限制与替代方案
4.1 Codex 端如何传图片
Codex CLI 的交互式环境中，可以通过粘贴或拖拽方式将图片附加到对话中。具体操作方式可能随版本迭代而有所不同，建议先查看当前版本的帮助信息：
codex --help在支持图片附件的版本中，Codex 会把图片转换成模型可识别的多模态消息格式发送给后端。但这里有一个关键前提：后端模型必须支持视觉输入。如果模型不支持视觉，图片消息要么被忽略，要么直接报错。
4.2 DeepSeek 是否支持图片输入
截至本文写作时，DeepSeek 开放平台的主要模型以文本模型为主，但 DeepSeek 也有视觉方向的开源模型工作。具体哪个模型支持图片输入、API 是否开放多模态请求，需要以 DeepSeek 开放平台的最新文档和模型列表为准。
一个可靠的检查方法，是直接构造一个带图片的 OpenAI 兼容请求，看看 API 是否报错。示例代码如下：
# 文件路径：test_image.py from openai import OpenAI client = OpenAI( api_key="你的API Key", base_url="https://api.deepseek.com" ) response = client.chat.completions.create( model="deepseek-chat", messages=[ { "role": "user", "content": [ {"type": "text", "text": "这张图片里有哪些物体？"}, { "type": "image_url", "image_url": { "url": "https://example.com/test.png" } } ] } ] ) print(response.choices[0].message.content)如果返回结果正常，说明当前模型支持视觉输入。如果返回400之类的错误，说明图片输入不被支持。这时就需要换用其他支持视觉的模型，或者通过识图 skill 的方式间接实现。
4.3 识图 skill 的本质
社区里提到的“识图 skill”或“识图插件”，本质上并不是给文本模型增加眼睛，而是通过工具调用机制，把图片交给外部视觉识别服务处理，再把识别结果返回给模型。常见实现方式有两种。
第一种是基于 OCR 的文本提取。图片经过 OCR 服务识别出文字内容，然后作为文本上下文交给大模型。这种方式适合截图、文档扫描件等以文字为主的图片。
第二种是基于视觉语言模型的调用。在 Codex 工具链中，可以编写一个 skill 或插件，让模型调用另一个支持视觉的模型接口，比如 Qwen-VL、GLM-4V 或本地部署的视觉模型，由视觉模型输出图片描述，再交给主模型进行推理。
所以，如果你需要的是“上传一张产品截图，让 AI 描述界面布局”这类能力，通过 DeepSeek 文本模型加外部视觉模型组合，完全可以实现。
4.4 使用支持视觉的 OpenAI 兼容模型
如果 DeepSeek API 当前的模型不支持图片输入，而你的业务又确实需要识图，最务实的方案是切换到一个支持视觉且兼容 OpenAI 协议的模型。
操作上只需要修改 Codex 的config.toml，增加另一个模型供应商，并把默认模型切换过去。例如：
# 文件路径：~/.codex/config.toml model = "vision/qwen-vl-plus" model_provider = "vision" [model_providers.vision] name = "VisionModel" base_url = "https://你的接口地址" env_key = "VISION_API_KEY" wire_api = "chat"这里的base_url可以是云服务商的 OpenAI 兼容地址，也可以是本地部署的视觉模型网关地址。需要注意，不同的视觉模型对图片 URL 和图片 base64 编码的支持程度不同，实际使用时可能需要先做一次基础连通性测试。
5. 高频报错排查
5.1 unable to locate the codex cli binary
这个报错经常出现在桌面端工具或 IDE 插件中，提示信息类似：
unable to locate the codex cli binary. set codex cli path or ensure the executable is available in PATH意思是当前工具找不到 Codex CLI 的可执行文件。常见原因是 Codex CLI 没有安装，或者安装位置不在工具的搜索路径中。
排查步骤：
which codex如果命令没有输出，说明 Codex CLI 未正确安装，重新执行：
npm install -g @openai/codex如果命令有输出，比如/usr/local/bin/codex，需要在 IDE 插件或桌面端工具的设置中，把 Codex CLI Path 手动设置为这个路径。设置完成后重启工具即可。
5.2 cc switch 本地代理转发 /responses 失败
有读者在使用cc switch或类似本地代理工具时遇到报错：
cc switch local proxy failed while handling codex endpoint /responses这个问题的根源通常是本地代理工具把 Codex 的请求转发到了后端服务，但后端服务不识别/responses路径。Codex 默认的 wire_api 是responses，而 DeepSeek 等 OpenAI 兼容接口使用的是/chat/completions路径。
解决思路是在 Codex 配置里显式设置：
wire_api = "chat"同时确认base_url没有拼错。如果本地代理工具本身提供了接口类型选择，也要把类型改成 Chat Completions 或 OpenAI 兼容模式。
5.3 其他常见报错汇总
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 401 Unauthorized | API Key 无效、缺失或环境变量未生效 | 检查DEEPSEEK_API_KEY是否正确，重新 export 后重启终端 |
| 404 Not Found | base_url 拼接错误，或 wire_api 选成 responses | 检查 base_url，设置 wire_api = "chat" |
| model not found | 模型名写错，或模型不可用 | 在 DeepSeek 开放平台确认模型名，如deepseek-chat |
| 请求超时 | 网络无法访问 api.deepseek.com，或代理设置异常 | 检查网络连通性，确认系统代理配置不影响 API 请求 |
| 返回内容为空 | 上下文过长，或模型未理解指令 | 简化问题，调整 temperature 等参数 |
| 图片请求返回 400 | 当前模型不支持视觉输入 | 换用支持视觉的多模态模型 |
排查这类问题，建议按照“网络-鉴权-协议-模型名”的顺序逐层检查。先用 curl 验证 API 连通性，再确认 Codex 配置，最后检查模型能力边界。
6. 最佳实践与工程建议
6.1 配置与密钥管理
API Key 属于高敏感凭证，建议在开发环境中使用.env文件配合 direnv 或 dotenv 管理，避免把 Key 写进 shell 历史记录。在团队协作中，可以引入密钥管理服务，或者在 CI 中使用 Runner Secrets，而不是把 Key 放在代码仓库里。
Codex 的config.toml中不要直接写入 Key，而是通过env_key指定环境变量名称。这样即便配置文件被同步到其他机器，也不会泄露密钥内容。
6.2 针对 DeepSeek 的配置建议
DeepSeek 的 OpenAI 兼容接口并不等同于 OpenAI 官方接口。两者在模型命名、上下文长度、速率限制、费用计算上都存在差异。接入 DeepSeek 后，建议先做一轮小流量验证，确认代码生成质量、响应速度符合预期，再逐步推广到团队日常开发。
如果同时使用多个模型供应商，可以在config.toml中维护多个模型供应商段落，按项目或任务类型手动切换默认模型。不同供应商使用不同env_key，避免密钥互相覆盖。
6.3 本地代理工具的使用建议
社区中出现了一些本地代理工具，比如cc switch、ccgui等，用来在多个模型厂商之间切换。这类工具本质上是一个本地 HTTP 服务，接收 Codex 的请求，再转发到目标模型后端。
使用本地代理时，最容易出问题的地方是协议转换。Codex 的responses协议和 DeepSeek 的chat/completions协议并不完全等价，代理工具如果只做简单的路径转发，很容易出现 404 或请求格式错误。建议在本地代理工具中，优先选择支持“OpenAI Chat Completions”模式的配置，或者直接不使用代理，让 Codex 直连 DeepSeek。这样可以减少中间层带来的故障点。
6.4 成本、隐私与安全
把代码上下文发送给第三方模型服务，本质上存在数据隐私风险。在接入 DeepSeek 或任何云模型之前，建议先和团队确认数据合规要求。涉及客户隐私、未公开业务逻辑、密钥文件等内容，不要直接上传到模型接口。必要时可以考虑本地部署模型，或者使用脱敏后的数据集进行测试。
成本控制方面，可以关注 DeepSeek 开放平台提供的用量统计和计费明细。Codex 交互式会话可能会发送大量上下文，尤其是大型项目场景下，建议合理控制会话长度，定期清理无用会话，避免 token 消耗激增。
7. 最后的几点提醒
这套 DeepSeek 接入 Codex 的方案，核心就三个步骤：安装 Codex CLI，配置model_providers，设置环境变量。真正容易踩坑的地方不在接入本身，而在wire_api和模型能力边界。只要记住 DeepSeek 走的是 Chat Completions 协议，绝大多数报错都能迎刃而解。
识图功能能否生效，取决于你最终接入的模型是否支持视觉输入。如果 DeepSeek 当前模型不支持，完全可以通过外部视觉模型或识图 skill 组合实现，并不需要放弃 Codex 的工作流。建议动手写一个带图片的测试脚本，实测一次，比看多少文档都管用。
如果你想继续深入，下一步可以研究 Codex 的自定义 skill 机制、批量任务脚本，以及如何把 Codex 集成到 Git 提交前检查或 CI 流水线中。把这些能力组合起来，AI 编程助手才能真正融入日常开发流程。
