最近不管刷哪个技术社区，都快被 Codex 刷屏了。有人拿它半小时重构一个遗留项目，有人让它把测试覆盖率补到 80%，也有人刚下载完就对着黑乎乎的窗口直接懵住。Codex 是 OpenAI 官方出品的 AI 编程助手，和网页聊天里那种“只会给建议”的工具不一样，它能直接读取你项目里的文件、在终端里执行命令，然后真正把代码改完。这篇实战课不跟你讲高深理论，我会从零开始，把安装、登录、接入 DeepSeek、跑通第一个需求、排查高频报错这几步完整走一遍。不管你是写了几年代码的老手，还是刚摸到键盘的小白，只要照着做，今天之内就能让它帮你干成第一件正经活。
1. Codex 到底是什么，小白该选 CLI 还是桌面版
1.1 先搞清楚你装的究竟是哪个 Codex
Codex 这个名字在圈子里出现过两次。最早它指 OpenAI 2021 年发布的代码生成模型，你给它注释，它给你补函数；现在大家讨论的 Codex，已经变成一个完整的 AI 编程智能体，官方同时提供了命令行工具 Codex CLI、桌面应用和云端沙箱。两代产品名字一样，能力差了一个量级。
我见过不少新人拿着旧教程来问，“我装的这个怎么不能直接跑？”其实大部分不是装错了，而是教程过时了。你只需要记住一个结论：2025 年之后的 Codex，核心是 agent，不是补全插件。它能自己读文件、搜代码、跑测试、根据报错修 bug，甚至自己执行 git 命令。把它理解成“一个坐在你电脑前面帮你写代码的实习生”，很多行为就解释得通了。
1.2 CLI、桌面版、云端版怎么选
很多教程一上来就让你npm install，小白很容易卡住。实际上官方目前主要有三种形态，适合的人群完全不同。
| 形态 | 安装方式 | 适合谁 | 特点 |
|---|---|---|---|
| Codex CLI | npm 全局安装，在终端里跑 | 有一定命令行基础的开发者 | 最灵活，能深入项目目录操作，适合脚本化和 CI 场景 |
| Codex 桌面版 | 官网下载安装包 | 不喜欢终端的小白 | 图形界面，左侧文件树、右侧对话，中间能看到改动 diff |
| Codex Cloud | 浏览器打开云端沙箱 | 想快速试验、本地环境不干净的人 | 不需要配本地环境，任务丢到云端跑，结果拿回来用 |
我自己的习惯是主力场景用 CLI，因为后续接第三方模型、写自动化脚本、配合 team 共享配置都绕不开它。桌面版更适合第一次体验，因为图形界面会把“它在改什么文件、打算怎么改”展示得很直观，对新手非常友好。
1.3 不同人群怎么选
如果你是第一次接触 Codex，我的建议很直接：先装桌面版，跑通一个完整任务之后，再决定要不要切到 CLI。桌面版把文件读写、终端执行、diff 展示这些能力都做进了界面里，你不需要理解“工作目录”“会话”这些概念也能上手。
如果你日常主力开发工具是 VS Code 或者 JetBrains 系，官方 IDE 扩展也可以考虑，它能让你在编辑器里直接唤起 Codex，不用来回切窗口。但我还是想提醒一句：网上很多第三方“增强工具”和“整合包”先不要碰，等官方原版跑明白了，你再判断自己缺什么。很多人一上来就装一堆乱七八糟的插件，最后连基本问题都分不清是谁造成的。
2. 装好 Codex：官方渠道、环境检查和登录验证
2.1 为什么我反复强调只走官方渠道
这里必须多说两句，因为踩坑的人实在太多。打开搜索页，你能看到各种“Codex 安装包”“Codex 中文版”“Codex 破甲版”之类的下载链接，我的态度非常明确：别用。这类来路不明的安装包和脚本，轻则被塞进广告和挖矿程序，重则直接窃取你电脑里的密钥、账号信息。Codex 本身要读写你的项目文件，你把它交给一个不明不白的“整合版”，等于把家门钥匙给了陌生人。
而且账号层面也有风险。非官方渠道改过的客户端很容易触发风控，轻则报错，重则封号。我见过不止一个朋友因为贪图所谓“汉化版”“绿色版”，最后连正版都登录不上去。安装这事没什么技术含量，花五分钟走官方流程，比之后花几个小时排查不明问题划算得多。
2.2 Windows 安装实测
Windows 上装 Codex CLI，核心步骤就三步。
第一步，确认 Node.js 环境。打开 PowerShell，输入node -v，如果能打印出版本号且大于等于 18，说明环境没问题；如果提示“node 不是内部或外部命令”，去 nodejs.org 下载 LTS 版本装好，重开一个终端再验证一次。
第二步，全局安装 Codex。在 PowerShell 里执行：
npm install -g @openai/codex如果终端里装了 yarn 或 pnpm，也可以对应替换，但 npm 是最通用的一种。安装完后验证一下：
codex --version第三步，如果 npm 下载速度很慢，或者频繁超时，我建议先把 npm 源切成国内镜像。这个操作很安全，只是换个下载源而已：
npm config set registry https://registry.npmmirror.com切完源再重新执行安装命令，速度会快很多。注意这只影响 npm 包的下载，不影响 Codex 后续的 API 请求地址。
桌面版就更简单了：去 OpenAI 官网找到 Codex 桌面版下载页，下载对应的.exe安装包，双击一路下一步。装完后首次启动可能需要系统授权，Windows Defender 弹窗时点允许就行。
2.3 macOS 安装实测
macOS 上我比较推荐用 Homebrew，命令干净：
brew install codex装完之后看一眼路径：
which codex如果刚装完提示找不到命令，多半是brew的 bin 目录没进 PATH。可以执行eval "$(/opt/homebrew/bin/brew shellenv)"，然后重开终端。
Apple Silicon 机器上，如果通过 npm 全局安装，偶尔会碰到 npm 全局目录不在 PATH 里的情况。这时候用npm config get prefix看一下全局目录，再把它加到~/.zshrc的 PATH 里就行。这条坑我踩过一次，当时折腾了十分钟，最后发现就是路径问题。
macOS 首次启动还会有“无法验证开发者”的提示，去“系统设置 - 隐私与安全性”里找到对应的条目，点“仍要打开”就好，这是所有命令行工具首次运行都会有的正常弹窗。
2.4 登录验证码收不到怎么办
装好之后，CLI 里执行codex login，桌面版在设置里点登录，这时候两个问题最常出现：一个是邮箱验证码一直收不到，一个是手机号验证码收不到。
先检查垃圾箱，这个概率比你想象得高。再检查是不是短时间内重复点击了“发送验证码”，很多平台对发送频率有限制，点太多次反而会触发频控，导致后面收不到。我的建议是：如果 5 分钟内没收到，就换一种登录方式。优先尝试用 Google、GitHub 这类第三方账号 OAuth 登录，比邮箱和手机验证码都要稳定。
如果手机号验证一直不通过，可以考虑换个邮箱注册，或者过一段时间再试。千万不要去搜索什么“代收验证码”的服务，把自己的注册信息交给第三方，账号安全就没有保障了。登录成功后，CLI 会在本地存一份凭证文件，日常使用不会再重复登录。
3. 把 Codex 接到 DeepSeek：模型供应商切换实战
3.1 为什么值得折腾一次
很多人刚接触 Codex 时都有一个疑问：官方默认模型挺好用的，为什么还要自己换供应商？原因很实际：成本、习惯和场景。
我自己是重度用户，日常会拿 Codex 处理很多琐碎任务，比如写迁移脚本、补单元测试、解释老项目里的逻辑。这些任务价值高但对模型能力要求没那么极致，用官方默认模型跑会有明显额度压力。这时候接入第三方模型，把不同类型的任务分给不同供应商，效率和成本都会好很多。
在第三方模型里，DeepSeek 是很多开发者选择入门的一个，因为它提供了兼容接口，配置方式不复杂，价格也比较亲民。下面这段配置不是黑科技，就是改一个文本文件而已，但能帮你省下不少后续折腾时间。
3.2 config.toml 配置逐行拆解
Codex CLI 的配置文件默认放在用户目录下的.codex文件夹里：
- Windows：
C:\Users\你的用户名\.codex\config.toml - macOS / Linux：
~/.codex/config.toml
如果你之前已经用官方默认方式登录过，这个文件可能还不存在，等第一次启动 Codex 后它会自动生成。用任意文本编辑器打开，加上下面这段：
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：默认使用的模型名。deepseek-chat对应 DeepSeek 的通用对话模型，如果要用推理增强版，可以填deepseek-reasoner。model_provider：告诉 Codex 使用下方哪一个供应商配置。[model_providers.deepseek]：定义一个供应商块，deepseek是这个供应商的 ID，可以自己起名，但要和上面的model_provider保持一致。base_url：API 的访问地址。DeepSeek 官方提供的是 OpenAI 兼容地址，所以这里填它的 v1 端点。env_key：Codex 读取 API Key 时对应的环境变量名。wire_api：指定接口协议格式，chat表示走 Chat Completions 兼容格式。
不同版本的 Codex 对字段支持略有差异，如果你发现保存后启动报“无法识别配置项”，大概率是版本字段名变了。这时候不要硬删配置，先codex --version确认版本，再去对应版本的官方文档里核对字段写法。网上很多教程的配置文件是几个月前的老版本，直接抄过来很可能不兼容。
3.3 环境变量设置与接入验证
配置写好之后，还需要把 API Key 放进环境变量，Codex 才会去读取。
Windows 下，如果你想永久生效，最好用setx：
setx DEEPSEEK_API_KEY "你的key"设置完后一定要重开一个终端窗口，否则当前会话读不到新变量。
macOS / Linux 下，写入 shell 配置文件：
echo 'export DEEPSEEK_API_KEY="你的key"' >> ~/.zshrc source ~/.zshrc如果不想永久写入环境变量，也可以直接在启动 Codex 的那个终端里临时导出：
export DEEPSEEK_API_KEY="你的key" codex这种方式的优点是只在当前终端生效，不污染全局环境，适合测试阶段。缺点是你很容易忘记自己没导出，换个终端窗口又启动 Codex，它又会报找不到 Key。
配置完之后，启动codex，先问一句“你现在用的是什么模型”，如果它回答里出现deepseek-chat相关的信息，说明接入成功。这里有个常见坑：环境变量名写错或者没导出，Codex 会提示找不到 API Key，或者要求你重新登录。遇到这种报错先别急，回看终端里echo $DEEPSEEK_API_KEY是否能正确打印出 Key。
另外还有一种接入方式，是直接用 DeepSeek 提供的 Anthropic 兼容接口。这种方式只需要在终端里设置几个环境变量：
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN=你的key export ANTHROPIC_MODEL=deepseek-chat然后正常启动codex。两条路线选一条就行，我个人更推荐配置文件的方式，因为所有设置都沉淀在config.toml里，不会因为换了终端就失效。
4. 跑通第一次实战：从一句话需求到文件改动
4.1 在项目目录里启动 Codex
配置好了模型，接下来才是真正好玩的部分。先进入一个真实项目目录，然后启动 Codex：
cd ~/work/my-todo-api codex首次进入会显示当前工作目录，并提示 Codex 已经获取了项目上下文。这里有个很多人都忽略的细节：启动位置非常关键。Codex 默认只对你启动它的那个目录及子目录有操作权，你如果把 Codex 启动在~，它能看的东西就很有限，行动起来也容易迷茫。所以每次使用前，先 cd 到目标项目根目录，再启动。
会话里第一句话，不要只说“帮我改一下接口”。好的描述至少包含三块信息：项目背景、要做什么、约束条件。比如：
“这是一个 FastAPI 项目，当前/todos接口会返回全部待办。我想把它改成支持分页，返回结构里加上total和items两个字段，保持现有测试用例不变。”
这句话给足了上下文，Codex 就能直接开干；如果你只丢一句“加分页”，它还得先花时间读代码猜测你想干什么，效果自然差很多。
4.2 从需求到文件改动：完整过程复盘
我拿一次真实改动来走一遍。项目是一个简单的待办事项 API，结构大概是：
app/ routes.py models.py main.py tests/ test_todos.py我在 Codex 里输入分页需求后，它做了这样几件事：
第一步，列出本次改动的计划。它先定位到app/routes.py，发现当前接口直接用Todo.query.all()返回全量数据，然后告诉我它打算改成查询总数、计算分页参数、只查询当前页数据。
第二步，等确认后再动手。Codex 默认不是“改完就跑”，而是先把 diff 展示给我看。我在会话里确认之后，它才真正写入文件。
第三步，自动补测试。它看了tests/test_todos.py里的既有写法，新增了一个分页场景的测试函数，然后自己跑了一遍测试命令，把结果贴在对话里。
整个过程最让我舒服的一点是：它每一步都会说清楚“我要改哪个文件、为什么这么改”。这不光是仪式感，而是让你有机会在错误发生之前拦截它。如果我看完 diff 发现它想到了数据库层改动方案，但我的需求只是想在前端做过滤，直接在会话里纠正就行，成本很低。
4.3 权限模式怎么选
Codex 会话里通常会提供几种操作模式，不同版本叫法有差异，但本质就三类：只读、每次确认、自动执行。
只读模式适合让它先做代码审查、解释逻辑、找 bug 线索，它不会改任何文件。每次确认模式是默认选项，也是我最推荐新手用的：它每次执行写文件或跑命令前，都会弹出 diff 或命令预览，等你点头。自动执行模式省心，但风险也最大，尤其当项目在 git 主分支上时，一个错误的git push --force就能让你后悔半天。
我的经验是：第一周先用默认确认模式，建立对 Codex 行为的直觉。等你看得懂它的 diff、知道哪些命令是安全的，再在低风险分支上尝试自动模式。生产分支永远不要开自动执行。
5. 高频报错排查实录
5.1 auth token is unavailable：完整排查链路
这个报错几乎能排进“Codex 用户最常见问题”前三。看到它先别慌，按顺序查：
第一步，重新登录。执行codex login，按提示走完一遍授权流程。很多 token 失效就是单纯过期了，重新登录就好使。
第二步，检查环境变量。如果你之前为了接第三方模型设置过类似AUTH_TOKEN的环境变量，它可能会覆盖 Codex 内部的凭证。Windows 下执行Get-ChildItem Env:AUTH_TOKEN，macOS / Linux 下执行echo $AUTH_TOKEN，确认有没有值。如果有，把它清掉再启动 Codex。
第三步，检查本地凭证文件。Codex 登录后会在~/.codex/auth.json（或对应平台路径）保存凭证。确认这个文件存在且非空。如果文件损坏，删掉它然后重新codex login就能解决。
第四步，确认系统时间。这个容易被忽略，但非常关键。token 的签发和校验依赖时间戳，如果系统时间偏差超过一定范围，服务端会直接判定凭证无效。Windows 右键任务栏时间调“自动同步”，macOS 在“日期与时间”里打开自动设置，同步完再试。
第五步，查看详细日志。Codex 通常有--debug或--verbose参数，打开后能看到具体是哪一步校验失败。这一步能看到确切的 HTTP 状态码和错误信息，再拿去搜索或提 issue，命中率会高很多。
5.2 装了一键切换工具后 Codex 端点请求失败
打开搜索页，“Codex 一键切换”“Codex 加速配置”这类工具非常热门，很多小白装了之后反而遇到新问题：Codex 莫名其妙报错，类似“本地服务切换失败导致端点请求异常”。我自己排查过好几个这样的 case，结论高度一致：问题就出在这些工具改写了 Codex 请求的本地服务地址。
这类工具的核心原理是拦截 Codex 的请求，把流量转到自定义的本地服务。听上去很省事，但它同时带来了至少三个风险：端口被占用时 Codex 启动失败；工具自带的证书不被系统信任，请求被拦截；配置残留污染了config.toml，导致官方版本也无法正常工作。
我的建议很简单：新用户不要碰这些工具，官方原版足够用了。如果你已经装了，处理方式也很直接：彻底卸载该工具，然后打开config.toml，把里面所有非官方供应商配置全部删掉，恢复成默认状态。必要时把.codex里工具生成的中间配置也清掉，再重启终端，重新登录一次。
需要注意的是，我不建议去研究这类工具的配置细节，也不建议反复尝试“让工具和 Codex 共存”。它解决的问题用官方配置或合法第三方 API 就能实现，没必要在本地维护一层额外服务。
5.3 模型不支持与 unrecognized configuration setting
这两个报错经常一起出现。一个是告诉你“你选的模型在当前条件下不被支持”，另一个是“配置里有无法识别的字段”。
模型不支持的情况，多半是config.toml里写了官方模型列表之外的模型名，比如网上某个版本流传出来的gpt-5.6-sol这类编号，在你当前版本里根本不存在。解决办法就是改回官方支持范围内的模型名，或改成你已正确接入的第三方模型，比如deepseek-chat。
unrecognized configuration setting的排查方向不太一样。先看报错提示里点名的字段名，把它和当前版本的官方配置文档对照。最常见原因是字段名拼写错误，或者这个字段在旧版本里存在、在新版本里被废弃了。这里我有个实用技巧：把原来的config.toml备份一份，然后用最小化配置重新启动 Codex，跑通之后，再一项一项把你的自定义配置加回去。哪一项加完报错，问题就在哪一项。
5.4 打不开、汉化风险与没有终端工具提示
桌面版打不开，常见原因有三个：安装包下载不完整、旧版本残留、系统权限不够。常规做法是彻底卸载后重新下载官方最新安装包，装到默认路径，不要贪方便装到奇怪的目录。
关于汉化，我要说两句可能得罪人的话：不要装第三方汉化补丁。Codex 的界面文字量本来就不大，核心菜单就那么几个，查词表十分钟就能习惯。第三方汉化补丁本质上是修改客户端资源或注入脚本，你不知道它除了翻译字符还做了什么。为了省这点阅读成本，把账号和项目代码暴露给不明来源的补丁，这笔交易不划算。
还有一个让我印象深刻的报错提醒：“没有终端和文件编辑工具”。遇到这个提示，新手很容易以为 Codex 坏了。实际上它通常是说 Codex 检测到当前会话缺少可用的终端环境或文件编辑能力，常见于你在一个不对的目录启动、或者集成终端没能初始化。重启终端，在目标项目根目录重新执行codex，大多数情况就恢复正常了。
6. 进阶玩法：Skills、配置约定与我的使用心得
6.1 用 SKILL.md 给 Codex 立规矩
跑通基本流程之后，Codex 还有一个很值得玩的能力：Skills。你可以把它理解成给 Codex 写“岗位说明书”。
Skills 的实现方式是在项目目录下放一个SKILL.md文件，里面写清楚某类任务应该怎么做。比如你想让 Codex 在改代码时强制遵循团队的 commit 规范，就在项目里建一个.codex/skills/git-commit/SKILL.md，内容大致是：
# Git Commit 规范 - 提交信息使用 Conventional Commits 格式 - 类型限定为 feat / fix / refactor / test / docs - 每次提交只包含一个逻辑改动 - 提交前必须运行对应模块的测试之后 Codex 在处理涉及 git 提交的任务时，会自动读取这份规范并按它执行。它不会每次都完美遵守，但整体偏差会明显减少，比你在会话里反复叮嘱要稳定得多。
6.2 团队共享配置的注意事项
如果你的团队有好几个人一起用 Codex，可以把config.toml里的公共部分抽出来放到项目仓库中共享，保证大家默认模型、权限策略、Skills 一致。注意两点：第一，配置文件里的 API Key 相关字段一定不要写死，统一走环境变量；第二，auth.json属于个人凭证文件，绝对不应该进入 git 仓库。
我见过团队因为有人把auth.json提交上去，导致全组人的登录状态互相顶掉，最后花了一上午排查。给.gitignore加上这两行就能避免：
.codex/auth.json .env另外团队共享配置建议配一份“最小权限”的默认模式，让所有人都从确认模式开始，而不是默认开自动执行权限。这看起来保守，但对新人尤其友好，能防止误操作把生产分支搞乱。
6.3 三个月用下来的几条私人心得
最后分享几条我实际操作中沉淀下来的心得，供你参考。
第一，描述需求时，“不要动什么”往往比“要做什么”更重要。我在会话里加一句“不要动数据库表结构”“不要碰登录逻辑”，Codex 的改动范围立刻收敛很多。
第二，改完代码后一定要看 diff，并跑一遍测试。我见过不少次它给出的修改方案是对的，但漏掉了边界条件，比如空列表分页、超长字符串截断。你负责 review，它负责执行，这个分工模式效率最高。
第三，长任务拆成短任务。让 Codex 一次性完成“重构整个模块 + 补全测试 + 更新文档”，成功率远低于“先重构核心函数、再补测试、最后更新文档”这个顺序。上下文窗口再大也有极限，任务一长，它就容易忘掉早先的约定。
第四，学会用会话重置。当 Codex 开始重复犯同一个错误，或者回复里明显带着之前某段对话的混乱记忆时，用一个/reset清空上下文，重新描述任务，往往比在旧会话里硬掰效率高得多。
Codex 目前还不是一个能完全放手不管的“自动驾驶”，它更像一个执行力很强的搭档：你需要告诉它边界、检查它的输出、在关键时刻踩刹车。把这套使用节奏建立起来之后，你会发现它的价值远超“帮你写代码”这件事——它还会逼着你把需求想得更清楚，把项目结构整理得更规整。这大概也是这段时间里我用它最大的收获。
