Codex CLI接入DeepSeek V4 Flash：新手10分钟配置与使用指南

新手小白速通 Codex接入 DeepSeek V4 Flash从安装到使用 10 分钟搞定之前折腾 Codex CLI 的时候最头疼的就是默认配置下它要绑定 ChatGPT 账号或 OpenAI API Key门槛高不说额度也比较麻烦。后来我仔细翻了一下 Codex CLI 的配置文档发现它完全支持自定义模型提供方也就是说我们可以把模型后端切成 DeepSeek通过 DeepSeek 的 OpenAI 兼容接口直接跑起来。这样既不需要 ChatGPT 订阅也不用登录 OpenAI只要有一个 DeepSeek 开放平台的 API Key 就能用。本文就把这套流程完整拆开讲一遍包括 Codex 安装、DeepSeek API Key 申请、config.toml 配置、命令行实战和常见报错排查。照着做10 分钟基本能跑通。先说明一下“免登录”的含义这里说的免登录是指使用 Codex 时不需要登录 ChatGPT也不需要 OpenAI 订阅但 DeepSeek 开放平台本身仍然需要注册账号并创建 API Key这是调用任何商业模型服务的基本前提。至于 V4 Flash 这类具体模型DeepSeek 平台会不定期更新模型列表接入配置的思路是一样的。1. Codex 接入 DeepSeek V4 Flash为什么值得试1.1 Codex CLI 是什么Codex CLI 是 OpenAI 开源的一个终端版 AI 编程助手。它运行在本地命令行里能够读懂自然语言指令然后结合当前项目目录下的文件内容生成代码、修改文件甚至执行 shell 命令。和 ChatGPT 网页版不同Codex CLI 更像是一个“长在项目里的开发工具”它知道你当前目录下有哪些文件可以直接操作文件系统也支持多轮对话式的连续修改。举个例子你可以在终端里输入“帮我把这个 Python 脚本改成异步版本”Codex 会先扫描脚本内容分析哪些函数适合改成异步然后生成修改后的完整代码再给出一段变更说明。这种工作方式非常适合日常脚本维护、算法练习、快速原型开发以及在已有项目里完成局部重构。对于刚入门的开发者来说它也能起到“陪练”的作用帮助你理解代码结构。1.2 DeepSeek V4 Flash 是什么DeepSeek 是深度求索推出的大语言模型系列DeepSeek V4 Flash 是其中面向高并发、轻量级场景的模型版本主打响应速度快、成本相对可控同时在代码生成和理解上保持了不错的表现。对开发者最友好的点是DeepSeek 开放平台提供了 OpenAI 兼容的 API 接口也就是说凡是支持 OpenAI API 协议的客户端工具都可以通过修改 base_url 来切换到 DeepSeek。不过这里要提醒大家模型的具体版本名、价格和调用额度会随着平台迭代而调整。所以本文不会把某个具体模型名写死而是采用相对通用的模型标识作为示例实际使用时请打开 DeepSeek 开放平台控制台查看你账号下可用的模型列表然后把配置里的 model 值替换成对应的模型 ID 即可。1.3 这组搭配解决什么问题把 Codex CLI 和 DeepSeek 组合起来解决的核心问题有三个第一是订阅门槛问题。Codex 默认的认证方式要么是 ChatGPT 登录要么是 OpenAI API Key对国内用户来说成本不低。而 DeepSeek 开放平台注册即可创建 API Key按量计费不需要包月订阅。第二是网络可达性问题。DeepSeek 的 API 服务在国内可以正常访问不需要额外网络配置这对不想折腾网络环境的人来说非常省心。第三是生态复用问题。Codex 的交互体验、文件操作能力和工具链设计是它的优势DeepSeek 只需要提供 OpenAI 兼容接口就能把模型能力“无缝注入”到 Codex 里。我们不需要放弃好用的终端工具也不用改变使用习惯。2. 环境准备与版本说明2.1 操作系统与终端要求Codex CLI 是跨平台工具覆盖 macOS、Linux、Windows 三大主流环境。本文示例主要以 macOS 搭配 zsh、Ubuntu 搭配 bash 为主Windows 用户可以在 PowerShell 或 Windows Terminal 中执行同样的命令只是环境变量设置语法有一些差异。Node.js 建议使用 20 或更高版本太旧的版本在安装 Codex 依赖时可能会出现兼容性问题。开始之前可以先打开终端确认 Node.js 和 npm 是否已经存在node -v npm -v如果输出类似v20.x.x和10.x.x说明基础环境没有问题。如果提示找不到 node需要先安装 Node.js。Windows 可以从 Node.js 官网下载 LTS 安装包macOS 可以用 Homebrew 安装Linux 用户建议使用 nvm 管理版本避免直接用 apt 装到过老版本。2.2 注册 DeepSeek 开放平台并获取 API Key接下来准备 DeepSeek API Key。打开 DeepSeek 开放平台注册账号后进入控制台找到 API Keys 页面创建一个新的 Key。创建时系统会完整显示一次 Key 内容建议立刻复制保存到本地密码管理工具中。如果关掉页面就看不到了只能重新创建。在创建 Key 之前顺带看一眼“模型”或“服务”相关页面确认你当前账号下有哪些模型可用。通常平台会显示类似deepseek-chat、deepseek-reasoner或新版 Flash 系列模型 ID。这个 ID 后面会写进 Codex 的配置文件里。2.3 设置 DEEPSEEK_API_KEY 环境变量拿到 API Key 后先把它设置成环境变量。macOS / Linux 的 bash 或 zsh 终端可以执行export DEEPSEEK_API_KEYsk-你的keyWindows PowerShell 可以执行$env:DEEPSEEK_API_KEYsk-你的key设置完成后验证一下变量是否存在echo $DEEPSEEK_API_KEY这个变量名和后面 Codex 配置文件里的env_key是对应的。如果你习惯把 Key 写在其他环境变量里也可以改但要保证config.toml里的env_key和实际环境变量名一致。3. 安装 Codex CLI3.1 使用 npm 安装npm 是 Codex CLI 最常见的安装方式。执行下面这条命令即可全局安装npm install -g openai/codex安装过程会下载 Codex 主程序及其依赖。如果在 macOS 或 Linux 上遇到权限不足的报错通常是因为 npm 全局目录不在当前用户可写范围内可以在命令前加sudo但更推荐的做法是通过 nvm 重新安装 Node.js让 npm 全局目录落在用户目录下避免使用管理员权限。3.2 验证安装安装完成后先做一次基本验证codex --version如果输出版本号说明 Codex 已经成功安装并能被终端找到。如果提示command not found说明 npm 的全局 bin 目录没有加入系统 PATH下一步来处理这个问题。3.3 安装后找不到 codex 命令的处理很多同学安装完 Codex 后在终端里执行codex却提示找不到命令。最直接的原因就是 npm 全局可执行文件目录不在 PATH 里。可以先查看 npm 的全局前缀目录npm config get prefix这个命令会输出一个路径比如/usr/local或/Users/你的用户名/.nvm/versions/node/v20.x.x。Codex 可执行文件一般会在prefix/bin目录下也就是/usr/local/bin/codex或对应的 bin 目录。如果发现bin目录不在 PATH 中可以在 shell 配置文件里追加export PATH/你的npm全局目录/bin:$PATHWindows 用户则需要检查系统环境变量中是否包含%APPDATA%\npm没有的话手动添加然后重新打开终端。3.4 macOS 用户可选Homebrew 安装如果你习惯使用 Homebrew也可以直接通过 brew 安装 Codexbrew install codexHomebrew 安装的好处是会统一处理 PATH 和依赖适合已经深度使用 Homebrew 的开发者。不过 brew 仓库里的版本可能比 npm 官方渠道慢一点介意版本更新速度的话还是推荐 npm 安装。4. 配置 Codex 接入 DeepSeek V4 Flash4.1 创建 ~/.codex/config.tomlCodex CLI 启动时会读取用户目录下的配置文件~/.codex/config.toml。如果这个文件不存在就手动创建mkdir -p ~/.codex touch ~/.codex/config.toml这个文件是 TOML 格式用来控制模型、认证方式、模型提供方等核心行为。编辑它时要注意缩进和键值格式不要随意使用 Tab 或多余空格否则容易出现解析错误。4.2 完整配置示例把下面内容写入~/.codex/config.toml# 默认使用的模型 model deepseek-chat # 默认使用的模型提供方 model_provider deepseek # 自定义模型提供方deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat这段配置就是整个接入过程的核心。把它保存后Codex 启动时就会通过 DeepSeek 的 API 来驱动对话和代码生成。如果你在 DeepSeek 控制台看到的模型 ID 不是deepseek-chat而是类似 V4 Flash 的具体版本名把第一行的model值替换成那个 ID 就行。4.3 配置项逐行解释先看几个顶层配置modelCodex 默认使用的模型名。这里示例用deepseek-chat实际以 DeepSeek 平台模型列表为准。model_provider默认使用的模型提供方名称对应下面定义的[model_providers.deepseek]代码块。再看[model_providers.deepseek]块name模型提供方的展示名称可以任意填写例如 “DeepSeek”。base_urlDeepSeek API 的 OpenAI 兼容接口根地址。注意结尾一定要带/v1因为 Codex 会在这个地址后面拼接具体的 API 路径。env_key指定 API Key 从哪个环境变量读取这里对应DEEPSEEK_API_KEY。wire_api指定 Codex 使用哪种协议格式。设置为chat后Codex 会调用 DeepSeek 支持的/chat/completions接口而不是 OpenAI 默认的/responses接口。这一项最容易漏掉如果漏配Codex 可能会去请求一个 DeepSeek 不支持的端点从而报错。4.4 多模型提供方配置可选如果你希望保留 OpenAI 官方配置同时加入 DeepSeek可以同时定义两个 provider例如model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses这样之后想切换模型只需要修改顶层model和model_provider两个字段不需要反复改动整个文件。如果你同时使用多个模型这种配置方式会比直接改文件内容更安全、更省事。4.5 环境变量持久化第 2 节里的环境变量设置只对当前终端会话有效。为了让每次打开终端都能自动加载 Key建议把export写入 shell 配置文件。macOS 的 zsh 用户执行echo export DEEPSEEK_API_KEYsk-你的key ~/.zshrc source ~/.zshrcLinux 的 bash 用户执行echo export DEEPSEEK_API_KEYsk-你的key ~/.bashrc source ~/.bashrcWindows 用户可以在“系统属性 - 环境变量”中新增DEEPSEEK_API_KEY这样 PowerShell、CMD 以及 IDE 插件都能读取到。5. 实战在 Codex 中让 DeepSeek 干活5.1 准备测试项目为了验证整个链路是否打通先创建一个干净的测试目录mkdir -p ~/codex-demo cd ~/codex-demo建议在这个空目录中做第一次测试避免 Codex 读取到大量无关文件导致上下文过长或生成结果不准确。等确认基本功能没问题后再在真实项目中使用。5.2 交互式会话写一个快速排序在测试目录下启动 Codexcodex正常启动后终端会进入类似 REPL 的交互界面。输入下面这条指令写一个 Python 快速排序函数要求带注释和测试用例Codex 会基于 DeepSeek 模型的理解生成对应代码。下面是我整理的一份简化输出示例实际返回可能略有差异def quick_sort(arr): if len(arr) 1: return arr pivot arr[len(arr) // 2] left [x for x in arr if x pivot] middle [x for x in arr if x pivot] right [x for x in arr if x pivot] return quick_sort(left) middle quick_sort(right) if __name__ __main__: test_data [5, 3, 6, 2, 1] print(quick_sort(test_data))对新手来说这里有一个很友好的设计Codex 默认不会直接把文件写入磁盘而是先展示修改方案经过你确认后才落盘。所以即使模型生成的内容不完全符合预期也不用担心项目文件被莫名其妙地覆盖。5.3 多轮对话与代码修改Codex 的交互式会话支持继续对话。比如你可以接着输入把上面排序函数的 middle 逻辑去掉改成原地排序并且不要递归实现模型会结合对话上下文重新生成一份新代码。这种连续迭代能力很适合做代码重构练习先让模型生成一个基础版本再逐步提出限制条件观察它如何调整实现。如果得到的代码有问题你可以直接描述报错信息例如“运行时报错 IndexError请修复”Codex 会尝试定位问题并给出修改。此时建议把报错信息完整贴给模型信息越完整修复效果越好。5.4 非交互式执行如果只是想快速完成某个一次性任务不需要进入交互界面可以使用codex execcodex exec 写一个 Python 脚本读取当前目录下的 data.csv输出每一列的平均值codex exec适合在脚本、CI 流程或者自动化任务中调用。它会把指令直接交给模型执行并输出结果。具体参数可以通过帮助命令查看codex exec --help不同 Codex 版本对子命令的支持可能略有差异遇到参数不识别的情况优先查看当前版本的帮助信息不要照搬网上的配置。5.5 调试与日志查看如果你怀疑请求没有发到 DeepSeek或者 API Key 认证失败可以打开调试日志查看请求过程。Codex 通常提供了调试模式参数不同版本写法不同常见的包括codex --debug codex exec --verbose 你的指令观察日志时重点关注两个信息一个是请求的 base_url 是不是https://api.deepseek.com/v1另一个是请求路径是不是/chat/completions。如果路径是/responses说明wire_api chat没有生效需要回去检查配置文件。6. 常见问题和排查思路6.1 报错信息对照表问题现象常见原因解决思路安装后提示 codex: command not foundnpm 全局 bin 目录不在 PATH 中找到 npm 全局 bin 并加入 PATHunable to locate the codex cli binary安装不完整或外部工具找不到 codex 路径重新安装并在工具设置中指定 codex 路径提示无法加载 config.tomlTOML 格式错误或 model 参数非法检查文件格式对照示例修复 model 字段the ‘xxx’ model is not supported when using codex with a chatgpt account当前账号或密钥不支持该模型改用 DeepSeek API 配置或更换模型 ID401 UnauthorizedAPI Key 错误或环境变量未设置确认 DEEPSEEK_API_KEY 是否正确404 Not Foundbase_url 路径错误确认 base_url 以 /v1 结尾请求路径是 /responseswire_api 配置缺失或错误设置 wire_api “chat”6.2 unable to locate the codex cli binary 详解unable to locate the codex cli binary这个报错经常出现在 IDE 插件、Electron 类桌面工具或自动化脚本中。它的意思是外部程序试图启动 codex但在指定位置找不到可执行文件。排查顺序可以这样来which codex如果这个命令能输出路径说明终端可以找到 codex。但如果报错来自 IDE 插件或桌面工具它们可能不会继承终端 shell 的 PATH 环境变量所以仍然找不到。此时需要在工具设置里手动指定 Codex CLI 路径通常指向which codex输出的路径。如果which codex没有输出说明全局安装确实有问题。用 npm 重装一次然后再次验证npm