1. 先想清楚为什么换条路比拆门更靠谱前两天宿舍夜聊一个大二的学弟问我听说 Codex 写代码很强但他卡在注册环节好几天了验证码收不到、提示号码被占用越试越烦躁。这种场景我见得太多了——很多人把用上 AI 编程工具这件事默认等同于必须先搞定某个账号于是大量时间被消耗在跟注册流程较劲上真正想学的东西一点没碰。我的建议向来很直接别在那扇门上耗着。Codex CLI 本身是开源的命令行工具它最容易被忽略的一个能力就是可以换模型后端。也就是说你完全可以让它把请求发给 DeepSeek而 DeepSeek 的 API 走的是标准的密钥鉴权压根不存在注册时要不要手机验证这一环。这不是钻空子而是换了一个功能等价、链路更短的技术方案。手机验证这个东西本质上是账号体系的风控手段我们没必须去研究它、更没必要去绕它只需要选一条本来就不依赖它的路径。这篇文章想解决的问题很具体让一个刚接触命令行、甚至没写过几行配置文件的在校生能在半小时左右跑通 Codex 加 DeepSeek 的组合并且知道每一步为什么这么配。全文不讲虚的配置、命令、报错对照表都给全看完你可以直接抄。适合谁看有三类人——想用 AI 辅助写课程作业和课设的本科生、刚入行的初级开发者、以及带学生做项目的老师。只要你会复制粘贴、会开终端窗口剩下的交给下面的步骤。1.1 Codex CLI 到底是个什么工具先把概念理清楚不然容易被各种名词带偏。Codex 现在有两层含义一层是云端的代码托管与协作服务另一层是开源的本地命令行工具 Codex CLI。我们这里全程聊后者。它是一个跑在你本机终端里的智能体Agent能读你当前项目的文件、理解目录结构、按你的自然语言指令去改代码、跑命令、修 bug然后把改动直接落到磁盘上。它和在网页对话框里问问题再手动复制粘贴完全是两个量级的体验。举个例子你说把这个 Flask 项目里的同步数据库查询全部改成异步它会先扫描项目里所有相关文件列出它打算改哪几个、每个改什么等你确认后逐个文件写入最后还可能跑一遍测试。这种能动手的能力来自它内置的文件读写、Shell 执行、以及一套叫 MCP 的扩展协议。Codex CLI 用 Rust 写性能上比同类工具更利索启动快、流式输出顺滑。它默认对接着 OpenAI 自家的模型服务但配置系统是开放的——配置文件里可以声明任意多个模型提供商每个提供商只要满足 OpenAI 兼容接口规范就能接进来。这一点是整篇文章的技术地基理解了它后面所有配置都是顺理成章的。提示Codex CLI 的配置文件默认位于用户主目录下的.codex文件夹里核心文件是config.toml和auth.json。这两个文件的路径在 Windows、macOS、Linux 上略有差别后面会分开讲。1.2 手机验证这类环节为什么会反复卡人很多人一上来就想搞清楚手机验证为什么会失败提示次数过多怎么办其实这个方向本身就是个坑。账号验证是服务方的风控策略受地区、号码归属、使用频次、设备指纹等一堆因素影响个人用户既看不到规则也改不了规则。你在上面花的时间收益是零。我见过最典型的三种内耗一种是反复换号码试试到最后连自己都记不清哪个号注册过一种是在网上搜各种技巧结果搜到的全是过时的、互相矛盾的说法还有一种是账号好不容易弄好了登录时又要过二次校验心态直接崩。这三种情况有个共同点——你把注意力放在了不可控的环节上。换个视角就通了。你要的是用 AI 帮我写代码不是拥有某个账号。命令行工具加第三方 API 的组合恰好能满足前者而不要求后者。API 的鉴权方式是一串密钥字符串你在服务商后台生成一次之后本地环境变量里配好工具就能一直用。没有验证码没有二次校验没有设备绑定。这条路是官方的、公开的、写在文档里的不是什么偏门操作。1.3 为什么我推荐 DeepSeek 作为后端选后端模型我最看重的三个指标是中文理解、代码能力、价格。DeepSeek 在这三点上都很能打。中文语境下它比其他一些模型更少出现翻译腔和答非所问写代码时对国内常见框架比如各种国产 ORM、前端组件库的熟悉度也更高。价格更是它的强项百万 token 的输入成本通常只有一些国际主流模型的十分之一量级学生做课设这种跑法一个月花不了几块钱。还有个容易被忽视的优势它的接口是 OpenAI 兼容的这意味着所有为 OpenAI 生态写的工具、SDK、示例代码把base_url一改就能用。对 Codex CLI 来说这就是开箱即用级别的好消息不需要任何适配层、不需要本地起代理、不需要额外的中间件。它提供两类模型可以选一类是通用对话模型响应快、适合日常改代码另一类是推理模型遇到复杂算法题或者需要仔细推导的逻辑时切过去思考更深但会慢一些。日常写业务代码用前者遇到帮我分析这段递归为什么栈溢出这类问题切后者这个组合我用下来性价比最高。2. 动手前的准备密钥、环境与安装准备工作分三块拿到 DeepSeek 的 API 密钥装好 Node.js 运行环境把 Codex CLI 装到全局。这三件事的顺序不能乱因为 Codex CLI 是通过 npm 分发的没有 Node 环境装不上。2.1 API 密钥的申请与充值策略打开 DeepSeek 的开放平台首页用手机号或者邮箱注册一个开发者账号进控制台左侧的API Keys页面点创建新密钥。系统会生成一串以sk-开头的字符串这串东西只显示一次务必立刻复制到安全的地方——建议直接存进密码管理器或者至少粘到一个临时文本文件里并记好你把它放哪了。充值环节有个经验值得说别一上来就充一大笔。先充最小额度把整条链路跑通、确认工具能正常收发请求、观察几天用量曲线再决定要不要加。原因是很多人第一次配置会踩坑比如配置写错导致请求失败后工具自动重试短时间内产生一堆无效调用。小额起步试错成本低心里也踏实。关于密钥的安全我要多说两句。密钥等同于你账户里的钱任何情况下都不要把它写进config.toml也别提交到 Git 仓库。正确的做法是放进环境变量配置文件里只写去哪个环境变量里取。这个设计不是多余的它让你能放心地把配置文件同步到多台设备而不用担心里面的敏感信息泄露。注意如果你不小心把密钥贴到了聊天记录、公开仓库或者论坛里立刻去控制台把它删掉重新生成一个。密钥一旦泄露别人用你的额度跑请求账单是记在你头上的。2.2 Node.js 与 Codex CLI 的安装先确认本机有没有 Node。打开终端Windows 上是 PowerShell 或 Windows TerminalmacOS 和 Linux 上是自带的终端输入node -v。如果显示版本号且主版本号不低于 20可以跳过安装如果提示命令未找到就去 Node.js 官网下载 LTS 版本的安装包一路下一步即可。Windows 用户记得在安装向导里勾选自动配置环境变量那一项不勾的话装完还是用不了。我强烈建议用 LTS 版本而不是最新版。最新版偶尔会有一些依赖兼容问题尤其是一些原生模块的编译。LTS 版本经过大量项目验证稳。装完之后再跑一次node -v和npm -v两个都有输出说明环境就绪。接着装 Codex CLI。官方推荐的安装方式有三种我按推荐度排一下npm 全局安装跨平台通用最省心npm install -g openai/codexHomebrew仅 macOS 和 Linux如果你已经装了 brewbrew install codex下载二进制包适合完全不想装 Node 的人从项目的 Release 页面下载对应系统的压缩包解压后把可执行文件放进 PATH 里的目录第一种方式适合 95% 的人我下面也全部按这种方式来写。安装完成后在终端输入codex --version有版本号输出就说明装好了。Windows 用户这里有个高频问题装完提示找不到命令。八成是 npm 的全局 bin 目录没进 PATH。解决办法是先跑npm config get prefix看全局目录在哪然后手动把这个目录加到系统环境变量的 Path 里重启终端生效。这个坑我帮人排查过不下十次基本每次都是这个原因。2.3 环境变量怎么设三套系统分别说环境变量的作用是让 Codex 在不接触配置文件明文的情况下拿到密钥。设置方式各系统不同我分开列你对照自己系统操作。WindowsPowerShell临时生效只对当前窗口有效$env:DEEPSEEK_API_KEYsk-你的密钥想永久生效用setx命令注意它是写入注册表设置完必须新开一个终端窗口才读得到setx DEEPSEEK_API_KEY sk-你的密钥macOS 和 Linuxbash 或 zsh写在 shell 的配置文件里echo export DEEPSEEK_API_KEYsk-你的密钥 ~/.zshrc source ~/.zshrc如果你用的是 bash把.zshrc换成.bashrc。source那一步是让配置立刻生效不执行的话当前窗口读不到。验证是否设置成功三个系统命令一样# Windows PowerShell echo $env:DEEPSEEK_API_KEY # macOS / Linux echo $DEEPSEEK_API_KEY能原样打印出你的密钥或者至少能看出前缀是sk-就对了。这一步千万别跳过后面报认证错误时九成是因为环境变量名写错或者没生效。有个细节提醒环境变量名必须和配置文件里写的完全一致包括大小写。我习惯统一写成DEEPSEEK_API_KEY你如果改成别的名字配置文件里也要同步改。3. 核心配置把 Codex 接到 DeepSeek 上这一节是全文的技术核心。配置文件写对了一切顺滑写错一个字段可能就是半小时的排查。我把完整配置拆成逐行解读再专门讲那个最容易出问题的参数。3.1 config.toml 的完整配置与逐行解读配置文件位置WindowsC:\Users\你的用户名\.codex\config.tomlmacOS / Linux~/.codex/config.toml如果.codex目录不存在手动建一个。文件内容如下# 指定默认使用哪个提供商的哪个模型 model_provider deepseek model deepseek-chat # 鉴权方式固定为 API 密钥不走账号登录那套流程 preferred_auth_method apikey # 沙箱模式允许模型在工作区内读写文件但不能碰工作区之外的东西 sandbox_mode workspace-write # 审批策略涉及敏感操作时先问一句 approval_policy on-request # 自定义模型提供商 [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat逐行说清楚每个字段在干什么model_provider是告诉 Codex 默认用哪家值要和下面[model_providers.xxx]的 xxx 对应。model是默认模型名我填的是通用对话模型你可以换成推理模型的那个名字。preferred_auth_method设成apikey是关键一步。Codex 默认优先走账号登录那套流程如果我们用 API 密钥却不在配置里明确声明工具可能还会尝试去读登录态导致认证失败。写上这一行它就老老实实用密钥鉴权。sandbox_mode和approval_policy是安全阀下一节展开讲。[model_providers.deepseek]是我们自己新增的一个提供商块。name只是显示用的标签随便起。base_url指向 DeepSeek 的 OpenAI 兼容端点注意结尾的/v1要带上。env_key写的是环境变量的名字不是密钥本身——这就是前面强调的安全设计。3.2 wire_api 这个参数为什么决定了成败wire_api是整个配置里最容易踩坑、也最值得单独讲的一个字段。它的取值只有两个chat和responses。前者对应 OpenAI 的 Chat Completions 接口后者对应更新的 Responses 接口。两者的请求体和响应体结构不一样端点路径也不一样。Codex 这个工具自己更偏好responses因为它能更好地支持工具调用和多轮推理。但问题是绝大多数第三方兼容服务只实现了 Chat Completions根本没做 Responses 接口。于是你会看到一个非常典型的报错请求发出去返回 404日志里出现/responses这样的路径然后工具反复重连、最后报一串endpoint 处理失败。很多人看到这个报错的第一反应是是不是我的密钥不对是不是服务挂了其实压根不是——是接口协议对不上。解决办法就是显式写wire_api chat。这一行让 Codex 改用 Chat Completions 协议去构造请求DeepSeek 那边就能正常解析了。记住这个因果关系报错里出现/responses路径几乎必然是这个参数没设对。这条经验能帮你省下大量搜索时间。顺带一提有些服务商自己提供了本地代理层来转换协议如果你在用这类方案那wire_api保持默认可能也能跑通。但既然 DeepSeek 原生就支持 Chat Completions直接对接、不加中间层链路更短、故障点更少我个人更推荐这种干净的做法。3.3 先用底层接口验一遍通路在打开 Codex 之前我建议先用最原始的方式测一次接口通不通。这样做的好处是如果后面 Codex 报错你能立刻判断问题出在接口本身还是Codex 配置上排查范围直接砍一半。最简单的验证是 curl 命令。macOS 和 Linux 终端直接能用Windows 的 PowerShell 里curl是Invoke-WebRequest的别名行为不太一样建议用 Git Bash 或者换成下面的 Python 方式。curl https://api.deepseek.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: 用一句话说明什么是递归}], stream: false }正常的话你会收到一段 JSON里面的choices[0].message.content就是模型的回答。如果返回401说明密钥有问题返回404说明base_url写错了返回402或带有余额相关提示说明账户欠费了。这三个状态码基本能覆盖所有鉴权和路径问题。如果你更习惯 Python也可以用官方 SDK 测代码更直观from openai import OpenAI client OpenAI( api_keysk-你的密钥, # 实际使用建议从环境变量读取 base_urlhttps://api.deepseek.com/v1 ) resp client.chat.completions.create( modeldeepseek-chat, messages[{role: user, content: 用一句话说明什么是递归}] ) print(resp.choices[0].message.content)这段代码要能跑需要先pip install openai。注意 SDK 虽然叫 openai但它只是遵守协议可以指向任何兼容服务这是业界很普遍的做法。底层接口通了再进下一节心里就有底了。4. 上手实操从第一次对话到项目级改代码配置跑通之后剩下的就是怎么把它用顺手。这一节讲交互模式、非交互模式、项目规则文件、以及安全策略这几件事都是日常高频用到的。4.1 第一次跑通两种使用模式在任意项目目录下打开终端输入codex回车就进入了交互式界面。这是一个终端里的对话界面你可以像聊天一样描述需求它会边思考边给出计划需要动文件时会请求你确认。第一次跑起来时我建议先问一个跟当前项目相关的小问题比如这个项目的入口文件是哪个帮我梳理一下目录结构看它能不能正确读取文件并给出合理回答。另一种是非交互模式适合脚本化或者快速提问codex exec 解释一下当前目录下 requirements.txt 里每个包的用途exec模式下它执行完就退出不进入对话界面。我经常在写文档或者做代码审查时用这个模式把结果重定向到文件里存着。刚上手时有个心理预期要建立它对项目的理解是基于你给它的文件和上下文窗口的不是你肚子里的蛔虫。所以描述需求时越具体越好。优化一下代码这种指令它只能瞎猜把utils.py里的parse_config函数改成支持传入字典作为默认值并补上类型注解这种指令它能一次改对。这个差别我体会很深前期多花三十秒描述清楚后期省十分钟返工。还有个实用技巧在交互界面里输入/会弹出可用命令列表比如切换模型的/model、查看用量的命令、清空上下文的命令等。上下文越攒越长的时候记得清理一下不然既费钱又容易让它分心。4.2 用 AGENTS.md 给项目立规矩这是我觉得 Codex 最好用的功能之一。你在项目根目录放一个叫AGENTS.md的 Markdown 文件写清楚这个项目的技术栈、代码规范、目录约定、常用命令Codex 每次启动时会自动读取它相当于给 AI 一份项目说明书不用每次重复交代。我自己的AGENTS.md模板大概是这个结构# 项目说明 ## 技术栈 - 后端Python 3.11 FastAPI - 数据库PostgreSQLORM 用 SQLAlchemy 2.0 - 前端Vue 3 Vite ## 代码规范 - 所有函数必须有类型注解 - 数据库操作一律用异步写法 - 提交前必须跑 ruff check . 和 pytest ## 目录约定 - app/api/ 放路由 - app/models/ 放 ORM 模型 - app/services/ 放业务逻辑路由里不写业务代码 ## 注意事项 - 不要修改 alembic/versions/ 下的已有迁移文件 - 环境变量统一从 app/core/config.py 读取不要在业务代码里直接读 os.environ有了这个文件之后它生成的代码风格会明显统一也不会再往路由文件里塞业务逻辑了。这个投入产出比非常高花二十分钟写一次后面每次对话都受益。提示AGENTS.md也可以放在子目录里Codex 会按层级合并规则。比如你可以在frontend/AGENTS.md里写前端专属的规范在根目录的写全局的。4.3 沙箱与审批别让 AI 直接动你的磁盘回到配置里那两个安全字段这里展开讲讲它们为什么重要以及怎么调。sandbox_mode控制文件系统的访问边界。read-only是只读它只能看不能改workspace-write允许它在当前工作目录内读写但工作目录之外的路径碰不了还有一个权限最大档能访问全盘除非你非常清楚自己在干什么否则不建议长期开着。日常开发用workspace-write就够了。approval_policy控制什么时候需要你点头。untrusted最保守几乎所有操作都要确认on-request是折中方案它自己判断哪些操作有风险再问on-failure是出了错才问never是全程不问高风险。我个人的习惯是日常用on-request做重复性的批量重构时临时切到更宽松的档位提升效率做完再切回来。这里有个真实的教训。我有一次在跑一个批量重命名的重构任务嫌确认弹窗太烦临时开到了最宽松的档位。结果它理解偏了需求把几个不该动的配置文件也一起改了。幸好项目在 Git 里、改动没提交git diff一看就回滚了。从那以后我给自己定了条规矩凡是要它动多个文件的任务动手前先git status确认工作区干净或者先打个 commit。有了这个前提任何误改都能一键还原你才敢放心让它干活。4.4 多套配置的管理思路如果你既要接 DeepSeek又想保留其他后端的配置可以准备多个配置文件用命令行参数指定codex --config ~/.codex/deepseek.toml或者在同一个config.toml里声明多个提供商临时切换时用--config覆盖模型名codex --config model_provider另一个提供商名 --config model对应的模型名网上也有专门的配置切换工具思路是在多个配置文件之间快速切换。这类工具的原理不复杂本质上就是软链接或者文件复制。你要是嫌装工具麻烦自己写个十几行的 shell 脚本也能实现同样的效果。我个人更倾向于手写脚本因为它透明、可控、出问题好排查。5. 常见报错与排错实录前面铺垫了这么多这一节是实打实的排错手册。我把踩过的坑按报错现象整理成表方便你遇到问题时直接对照。5.1 高频报错速查表报错现象大概率原因解决动作日志里出现/responses路径请求反复重连wire_api没设成chat协议对不上在提供商配置块里加wire_api chat返回 401 未授权环境变量名和env_key不一致或密钥已删除用 echo 检查变量是否读得到名字逐字对比返回 404 找不到路径base_url写错常见是漏了/v1或多加了斜杠改成https://api.deepseek.com/v1提示余额不足账户欠费去控制台充值先充小额日志中出现模型不支持的字样model字段填了该服务不存在的模型名改成服务商文档里列出的可用模型名运行中提示上下文空间不足单次任务灌入的文件太多超出模型上下文长度缩小任务范围或先清理对话上下文再继续命令找不到全局 bin 目录没进 PATHWindows 高发把 npm 全局目录加进系统 Path 并重启终端环境变量设置了但读不到没重启终端或改错了配置文件新开窗口重试确认改的是当前 shell 对应的文件流式输出到一半卡住网络波动或超时参数偏紧适当放宽超时时间或换网络环境重试这张表我建议截图存手机里。绝大多数情况下问题就出在前四行。5.2 三个我反复帮人排查的坑第一个坑配置写在了错误的目录。Codex 只读用户主目录下的.codex你在项目目录里新建一个.codex文件夹是无效的。Windows 上尤其容易搞混因为主目录是C:\Users\用户名\很多人会误以为在项目里建就行。判断方法很简单如果改了配置但行为一点没变先确认改的是不是主目录那份。第二个坑环境变量的作用域。Windows 上如果你用的是$env:语法设置的它只在当前这个终端窗口有效。关掉窗口再开一个新的变量就没了于是出现昨天还能用今天就不行的诡异现象。要持久化必须用setx并且新开窗口才生效。macOS 和 Linux 上则是要注意echo追加到的是哪个文件——用 zsh 的人往.bashrc里写是不会生效的。第三个坑以为模型名可以随便填。有些教程里写的模型名可能是旧版本的服务商更新后名字变了。遇到模型不支持的报错别猜直接去服务商的文档页查当前可用的模型名列表以文档为准。这个动作花不了一分钟比试错快得多。注意排错时养成看日志的习惯。Codex 的详细日志里会打印出实际的请求路径、状态码、重试次数。把日志从头到尾读一遍很多问题不用搜就能自己定位。我见过太多人一看到报错就截图发群里问其实日志里已经写清楚原因了。5.3 用量与成本怎么控制住最后聊聊钱的事这是很多人关心的。API 计费按 token 算输入和输出分开计价输出通常比输入贵几倍。学生做课设一天的用量可能也就几毛钱到一两块钱。但如果不注意也有烧得快的场景。第一是上下文膨胀。对话轮次多了以后每次请求都会把历史对话重新发一遍token 消耗是滚雪球式的。所以做完一个任务就清理一次上下文别一直在一个超长会话里连续干活。第二是让它读大文件。如果你让它分析一个几千行的日志文件光输入就上万 token。这种情况先用命令行工具把日志过滤压缩一下再喂给它。第三是反复重试。前面说的wire_api配错导致的无限重连是典型的不产出任何价值但持续扣费的场景所以一定要先测通再长时间运行。控制成本的实操建议先去控制台把每日用量提醒打开设一个你能接受的阈值养成定期看用量曲线的习惯发现异常波动及时查原因做批量任务前先拿一个小样本试跑确认行为和成本都可接受再放大规模。6. 一些实际用下来攒的经验配置这东西稳定之后就别频繁动了。我见过一些同学看到网上新的配置写法就忍不住改一改结果好好的环境被改崩又回头花时间恢复。我的习惯是一份能用的配置就固定下来改动前先备份一份改完如果没解决问题立刻回滚。另一条经验是关于任务拆分的。刚开始用的时候我总想一口气把大需求丢给它比如帮我实现一个完整的用户登录模块。结果它给出来的东西经常要在细节上返工。后来我改成拆成小步走先让它设计数据库表结构我确认再让它写模型层我跑通再写路由层我测接口。每一步都小、都可验证出问题能立刻定位在哪一步。整体效率反而比自己一口气写完再调试更高。还有一点别指望它替你做技术决策。它很擅长把已经想清楚的事情快速落地比如按这个接口文档生成对应的请求封装、把这段代码改成异步、给这个函数补单元测试。但这个项目该用哪种架构这种问题它给的建议只能当参考最终拍板还得你自己。把这个工具的定位摆正——它是个执行力极强的助手不是替你思考的大脑——用起来就不会有落差。如果你按上面的步骤一路走下来最后卡在某一步我的建议是从后往前倒推先确认底层接口能不能通再确认环境变量读不读得到再确认配置文件里的wire_api和base_url最后才怀疑工具本身。这个顺序是我排过无数次故障之后总结出来的它能保证你每次排查都在缩小范围而不是在几个可能的原因之间来回乱撞。