不知道你有没有过这种体验跟 AI 聊天时它把代码写得头头是道可真把你粘进项目里跑起来全是错。我过去大半年折腾了各种 AI 编程工具直到换上 Codex才意识到工具和工具之间的差距可以是“给建议”和“帮你把活干完”这么大的区别。这篇教程不打算讲什么高深原理就是把我从零下载安装、登录、接 DeepSeek、改 Bug、踩坑排错的全过程拆开给你看适合完全没碰过命令行的小白直接照做。先说清楚一件事Codex 不是普通聊天机器人它更像一个能读懂项目、会自己改文件、自己执行命令的 AI 工程师。你把需求告诉它它会自动去看代码、定位问题、修改文件、跑测试出错了还能自己看日志继续修。正因为它“干活”而不是“聊天”安装和配置环节也就比普通插件多一点讲究。这篇文章会把每一步的命令都写出来解释每一步为什么要这么干争取让你照着敲就能跑起来。1. 先搞清楚 Codex 是替你写代码还是替你“干活”1.1 从“聊天式补全”到“自主干活”的转变传统 AI 编程工具大多停留在“你提问、它给代码”的模式。你复制粘贴它的输出自己负责跑、负责错、负责改。Codex 不一样它的核心是一个 agent 工作流你给它一个目标比如“帮我修复登录页报错并确保测试通过”它会自己读项目结构、找相关文件、修改代码、运行测试、看失败原因再继续改直到完成或确认自己做不到为止。我第一次用 Codex 修一个 JavaScript 定时器 Bug场景特别直观它打开文件发现 setTimeout 里用了旧的变量引用自动改成了闭包写法然后顺手跑了一遍单元测试确认绿了才停。整个过程我没打一行命令只说了一句话。这种体验和“它给我一段代码让我自己处理”是完全两个量级的事。1.2 Codex 常见的三种使用方式Codex CLI 是官方开源工具也是当前最核心的形态。它通过命令行运行适用于所有平台能直接操作你本地的项目文件。第二种是 IDE 扩展最典型的是 VS Code 里的 Codex 插件给你一个图形界面适合不习惯命令行的人。第三种是第三方封装的“桌面版”这类包五花八门官方本身并没有发布一个独立的 Windows 桌面安装包所以如果你看到“Codex 桌面版安装包下载”一定多个心眼优先从 npm 和官方插件市场拿货。我给小白的建议是先学 CLI。因为 CLI 能暴露所有配置细节你通过它搞懂了 Codex 的工作原理再去用 IDE 插件就会很顺手。反过来直接跳进图形界面遇到问题反而无从排查。1.3 为什么说“小白也能学会”Codex 的门槛不在于编程基础而在于能不能耐心把环境配好。一旦装好、登好、配置好模型日常使用就是说话而已。你不需要背参数、不了解 git 也能让它干活但最好懂一点基本命令否则它问你要不要执行 git push 时你会发懵。后面几章我会逐个带你过这些环节。2. 小白安装 Codex从环境检查到跑起第一个命令2.1 安装前的环境检查安装 Codex 之前先确认三样东西Node.js、npm、git。Node.js 是 Codex 的运行环境npm 是它的安装器git 则是 Codex 做文件改动时用来生成 diff 和回退的关键工具。打开终端Windows 用户建议直接装 Windows Terminal比老版 CMD 好用太多依次输入以下命令检查node -v npm -v git --version如果提示找不到命令先去对应官网下载安装。Node.js 建议装 20 及以上的长期支持版本太老的版本容易踩兼容坑。Windows 用户还需要注意npm 全局安装需要权限如果一会儿安装时报 EPERM 或 EACCES 错误就在管理员权限的终端里重试。这里有个常见误区很多人以为 Codex 只能在 macOS 或 Linux 上用实际上 Windows 也能正常跑只是有些网络相关配置上的差异。后面第 3 章会单独讲登录这类网络敏感环节。2.2 通过 npm 安装官方 Codex环境确认没问题后执行npm install -g openai/codex这条命令会把 Codex CLI 安装到全局目录之后你在任意终端里输入codex都能调用它。安装过程如果长时间卡住通常是 npm 源下载慢的问题。这时可以先切换镜像源再重新安装npm config set registry https://registry.npmmirror.com npm install -g openai/codex镜像源只是把下载仓库换到国内节点不会影响 Codex 本身的功能。装完使用npm config get registry可以查看当前源想换回官方源就执行npm config set registry https://registry.npmjs.org/。如果你更习惯图形界面去 VS Code 扩展市场搜索 Codex 官方插件安装后侧边栏会多一个 Codex 面板也能实现同样的功能。但请注意官方没有发布独立的“Codex Windows 桌面版安装包”网上搜到的很多“安装包”是非官方套壳轻则功能残缺、重则夹带私货优先用 npm 和官方扩展市场才安全。2.3 验证安装是否成功安装完成后先跑一个最简单的命令确认可用性codex --version能正常输出版本号说明安装成功。再试codex --help你会看到它支持的命令列表。到这一步Codex 已经装好了但离真正使用还差最关键的一步登录认证。3. 登录环节为什么总卡住认证逻辑和常见报错3.1 Codex 登录到底做了什么第一次运行codex时它会提示你登录。流程大致是终端弹出登录链接自动打开浏览器你登录账号并授权Codex 再把访问令牌写到你本地用户目录下的.codex配置文件里。这个令牌就是你之后每次请求模型服务的“通行证”。很多新手会卡在手机号验证这一步。手机号验证属于账号层面的安全验证跟着官方页面走就行。如果页面迟迟收不到验证码先检查你填的号码和网络请求是否正常。另外Codex 的登录状态和浏览器登录状态是两回事不是说你在网页上登录了 OpenAI 账号CLI 就自动生效必须单独执行过授权流程才算绑定。3.2 auth token is unavailable 的排查思路auth token is unavailable是最常见的登录报错之一。它的意思是 Codex 尝试获取访问令牌时失败了也就是本地没有拿到有效凭证。通常有四种原因第一登录流程根本没走完。你需要在终端里执行登录命令并完成浏览器授权不能跳过。第二本地保存的令牌过期或被清掉了。这时可以删除本地配置里的认证文件重新登录。第三系统时间不对。令牌校验依赖时间戳如果你的电脑时间偏离太多服务器会直接拒掉。第四网络无法正常访问认证服务导致令牌请求始终超时。清理重新登录可以这样操作codex login如果始终提示报错找到本地 Codex 配置目录。Windows 一般在C:\Users\你的用户名\.codexmacOS/Linux 在~/.codex。把里面的认证相关文件备份后删除再重新执行codex login。3.3 登录不上、打不开时的通用排查顺序很多人问“Codex 国内能用吗”我的回答是它本身是一个软件工具能不能正常登录和调用取决于你的网络能不能顺利访问到它所依赖的海外服务。如果终端一直卡在“等待浏览器完成授权”或者授权后页面转圈第一步先确认网络连通性换一个网络环境试试、关掉本地安全软件试试、等几分钟再试。这些属于最基础的连通性排查。如果网络本身不通任何工具层面的配置都救不了这是需要先解决的底层问题而不是 Codex 的 Bug。别急着重装先把网络这段打通再回来登录通常一次就能成功。4. 把 Codex 接到 DeepSeek第三方模型接入实例4.1 为什么要接入第三方模型我现在日常使用 Codex 时大部分请求其实走的是 DeepSeek 的模型而不是 Codex 默认绑定的官方模型。原因很简单成本更可控、账号限制更少、国内访问体验也通常更好。Codex 本身支持配置 model provider你可以把它理解成“给 Codex 换个大脑”本地还是那个会改文件会跑命令的 agent只是背后回答问题的模型换成了 DeepSeek、通义或者其他兼容 OpenAI 接口的服务。有一个很热的搜索词叫“Codex 接入 DeepSeek”要实现它本质上就是修改 Codex 的配置文件把模型服务地址指向 DeepSeek 的 API 地址再配上对应的 API Key。4.2 配置文件写法和具体步骤找到 Codex 的配置文件位置Windows 端一般在C:\Users\你的用户名\.codex\config.tomlmacOS/Linux 在~/.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 wire_api chat然后设置环境变量。Windows PowerShell 执行$env:DEEPSEEK_API_KEY 你的DeepSeek API KeymacOS/Linux 执行export DEEPSEEK_API_KEY你的DeepSeek API Key建议把 API Key 配置到环境变量而不是写进配置文件避免配置不小心分享出去导致密钥泄露。这个env_key的意思是Codex 启动时会去环境变量里找DEEPSEEK_API_KEY这个值把它作为请求头里的认证信息。配置完成后随便进入一个项目文件夹执行codex 帮我看看这个项目是干什么的如果回答来自 DeepSeek 模型说明接入成功。4.3 接入第三方的常见坑最容易踩的坑有三个。第一个是base_url写错了有些服务商给的是不带/v1的地址要么连不上要么返回 404一般补上/v1就能通。第二个是模型名写错比如把deepseek-chat写成deepseek-chat-v3服务端会直接返回模型不存在。第三个是wire_api用错DeepSeek 这类 OpenAI 兼容服务要用chat而不是responses因为后者是 OpenAI 新版接口协议的格式很多第三方服务没有实现。我个人还建议你注册一个 DeepSeek 的官方 API 账户花几块钱充值测试。用量不大时成本很低但能让你彻底搞懂整个链路之后再切换到其他第三方服务也就大同小异了。5. 第一次上手让 Codex 修一个真实的小 Bug5.1 进入项目目录并启动会话安装登录配置都完成后进入实战。第一步是进入你的项目目录。终端执行cd 你的项目目录然后直接说需求。比如这个项目里有个按钮点击没反应你就执行codex 帮我看看为什么按钮点击后没有任何反应修复并运行测试验证Codex 会先读取目录结构、搜索相关代码、逐文件排查然后告诉你它的计划并开始改代码。整个过程会在终端里实时输出你能看到它读了什么文件、改了哪些行、执行了什么命令非常透明。这里有一个关键前提项目最好已经初始化过 git。因为 Codex 的每一次修改都是建立在你当前代码之上的有 git 才能生成清晰 diff万一改砸了还能一键回退。如果项目还没有 git先执行git init再让 Codex 开工。5.2 权限模式谨慎型、半自动型和全自动型Codex 在执行命令前会问你要不要允许。比如它想运行npm test会弹出一个确认提示。这对小白来说是安全兜底避免 AI 随意执行危险命令。实际使用中Codex 提供三种操作策略suggest、auto、full-auto对应着“每次都问我”“非破坏性命令自动执行”“全部自动执行”。我建议新手先保持默认的 suggest 模式。等你对它的行为熟悉了再慢慢放开到 auto。full-auto 听起来省事但风险也最大尤其是 AI 执行 git push、删除文件这类操作时你必须对项目有足够掌控力才敢放手。安全第一永远是第一原则。5.3 小白最容易忽略的三件事第一件事任务越小越具体效果越好。“帮我重构整个项目”这种需求它大概率会陷入混乱“把 utils/format.js 里的日期格式化函数改成统一输出 YYYY-MM-DD”这种需求它能又快又准地完成。第二件事改完代码一定要验收。你可以看它生成的 diff可以用codex 总结一下你改了哪些内容让它自己汇报也可以手动跑一遍测试别默认它改完就一定对。第三件事注意 Token 消耗。Codex 每跑一次任务都会消耗模型配额上下文越长消耗越大所以无关文件能删就删需求能精简就精简。我要特别强调一下项目上下文。Codex 的能力上限很大程度上取决于它能看到的信息质量。你可以在项目根目录放一个AGENTS.md文件用普通人语言写下项目架构、常用命令、编码约定Codex 每次开工前都会读这个文件相当于提前给 AI 培训了一下项目背景。这个习惯一旦养成效果立竿见影。6. 我不想踩的坑高频报错的排查链路6.1 CC Switch 切换配置导致本地转发链路报错很多用户喜欢用 CC Switch 这类配置切换工具在多个模型服务之间一键切换省去手动改配置文件的麻烦。但这类工具的原理是改写本地配置并把请求转发到本地某个端口再中转出去。于是就会出现类似“切到 Codex 后请求 /responses 报错”的现场。遇到这种问题我的排查顺序非常固定第一步暂时绕开 CC Switch直接运行codex如果正常说明问题出在切换工具上如果也报错说明问题出在 Codex 自身配置。第二步打开 CC Switch 当前生成的配置文件看它的转发地址是不是指向本地某个端口再确认那个服务是否启动。第三步把配置还原成直连模式按第 4 章的手动配置方式重新写一遍确认能跑通后再重新开启 CC Switch。这类工具本身不坏但它是套在 Codex 外面的一层壳一旦发生问题就成了疑难点。你手动直连能跑通再逐步把壳加回来逻辑上就很容易定位到底是谁的责任。6.2 模型不支持与 unrecognized configuration setting有一个报错长这样某个gpt-5.6-sol模型在当前 Codex 连接方式下不受支持。说人话就是你当前配置里指定的模型名在你指定的服务商那边根本不存在。这种情况最常见于从网上复制别人的配置但没注意别人用的是特定账号或特定中转服务。解决方案很简单把模型名改成实际存在的比如 DeepSeek 就用deepseek-chat官方订阅用户就保持默认。还有一个高频警告是codex is ignoring 1 unrecognized configuration setting。意思是配置文件里有个键名它不认识直接忽略了。这通常是拼写错误或者从老版本配置里复制了过时的字段。处理办法是逐行核对配置节把不认识的键删掉即可。这种问题虽然没有致命影响但会让 Codex 按默认设置运行可能不符合你的预期。6.3 invalid input 与“没有终端和文件编辑工具”invalid input这类报错可以出现在模型端也可以出现在本地端。一种典型情况是请求上下文过长把输入内容截断或格式搞乱了。解决方案是缩小任务范围、清理无关文件或者直接新开一个会话不要在一个会话里堆一大堆无关对话。另一种情况是第三方服务的接口格式和 Codex 期望的不完全一致这时把wire_api换成chat再试。“没有终端和文件编辑工具”的报错则比较特殊Codex 运行需要它内部的工具链如果安装过程中缺失了某些依赖或者你使用的是一个残缺的非官方版本就可能出现。先执行重装npm uninstall -g openai/codex npm install -g openai/codex大多数情况下就能恢复。如果重装后还不行就把本地.codex目录里的配置文件彻底重置再重新登录。7. 用配置文件把 Codex 调成“顺手”的样子7.1 固定模型和审批策略既然已经掌握了config.toml不如顺手把默认模型和审批策略也写进去。比如我突然想让 Codex 默认使用 DeepSeek并且非破坏性操作自动执行就可以在配置文件里这样写model deepseek-chat model_provider deepseek approval_policy auto注意审批策略一旦写成autoCodex 对你的文件修改和命令执行会更加主动。新手刚上手时我依然建议用suggest等充分信任后再改。7.2 让 Codex 用中文回复很多人一开始用 Codex 都会问“它怎么不说中文”。其实 Codex 本身没有界面语言设置它说什么语言完全取决于你怎么要求它。最简单的办法是在提问时带上指令“请用中文回答我”。但更聪明的做法是在项目的AGENTS.md里写一句所有面向用户的回复一律使用中文。Codex 每次进来都会读这个文件之后自然就用中文跟你交流了。你甚至可以在配置文件里设置系统提示词让它始终保持某种工作习惯比如“切到完整代码搜索模式之前先列计划”“修改文件前先输出 diff。这些配置做到位之后Codex 会越来越像一个懂你项目、懂你习惯的搭子。7.3 我自己沉淀下来的几个使用习惯最后分享几个我实际用下来确实管用的习惯给 Codex 派活之前先在本地把分支切干净只保留和任务相关的代码减少干扰一次会话只做一个任务做完就开新会话避免上下文里塞满历史垃圾影响判断大改之前习惯性 git commit这样 Codex 改错了能随时后悔回滚。我用了 Codex 大半年最大的感受是它把“写代码”这件事的门槛又压低了一截但真正决定上限的还是使用者的表达能力和掌控习惯。你现在已经完全具备独立安装、登录、接入第三方模型、跑通修复流程、排查常见报错的能力了剩下的就是拿真实项目去喂它让它多跑、多错、多修你和它磨合出来的工作流会越来越顺手。
Codex完整上手指南：从安装配置到接入DeepSeek的实战教程
不知道你有没有过这种体验跟 AI 聊天时它把代码写得头头是道可真把你粘进项目里跑起来全是错。我过去大半年折腾了各种 AI 编程工具直到换上 Codex才意识到工具和工具之间的差距可以是“给建议”和“帮你把活干完”这么大的区别。这篇教程不打算讲什么高深原理就是把我从零下载安装、登录、接 DeepSeek、改 Bug、踩坑排错的全过程拆开给你看适合完全没碰过命令行的小白直接照做。先说清楚一件事Codex 不是普通聊天机器人它更像一个能读懂项目、会自己改文件、自己执行命令的 AI 工程师。你把需求告诉它它会自动去看代码、定位问题、修改文件、跑测试出错了还能自己看日志继续修。正因为它“干活”而不是“聊天”安装和配置环节也就比普通插件多一点讲究。这篇文章会把每一步的命令都写出来解释每一步为什么要这么干争取让你照着敲就能跑起来。1. 先搞清楚 Codex 是替你写代码还是替你“干活”1.1 从“聊天式补全”到“自主干活”的转变传统 AI 编程工具大多停留在“你提问、它给代码”的模式。你复制粘贴它的输出自己负责跑、负责错、负责改。Codex 不一样它的核心是一个 agent 工作流你给它一个目标比如“帮我修复登录页报错并确保测试通过”它会自己读项目结构、找相关文件、修改代码、运行测试、看失败原因再继续改直到完成或确认自己做不到为止。我第一次用 Codex 修一个 JavaScript 定时器 Bug场景特别直观它打开文件发现 setTimeout 里用了旧的变量引用自动改成了闭包写法然后顺手跑了一遍单元测试确认绿了才停。整个过程我没打一行命令只说了一句话。这种体验和“它给我一段代码让我自己处理”是完全两个量级的事。1.2 Codex 常见的三种使用方式Codex CLI 是官方开源工具也是当前最核心的形态。它通过命令行运行适用于所有平台能直接操作你本地的项目文件。第二种是 IDE 扩展最典型的是 VS Code 里的 Codex 插件给你一个图形界面适合不习惯命令行的人。第三种是第三方封装的“桌面版”这类包五花八门官方本身并没有发布一个独立的 Windows 桌面安装包所以如果你看到“Codex 桌面版安装包下载”一定多个心眼优先从 npm 和官方插件市场拿货。我给小白的建议是先学 CLI。因为 CLI 能暴露所有配置细节你通过它搞懂了 Codex 的工作原理再去用 IDE 插件就会很顺手。反过来直接跳进图形界面遇到问题反而无从排查。1.3 为什么说“小白也能学会”Codex 的门槛不在于编程基础而在于能不能耐心把环境配好。一旦装好、登好、配置好模型日常使用就是说话而已。你不需要背参数、不了解 git 也能让它干活但最好懂一点基本命令否则它问你要不要执行 git push 时你会发懵。后面几章我会逐个带你过这些环节。2. 小白安装 Codex从环境检查到跑起第一个命令2.1 安装前的环境检查安装 Codex 之前先确认三样东西Node.js、npm、git。Node.js 是 Codex 的运行环境npm 是它的安装器git 则是 Codex 做文件改动时用来生成 diff 和回退的关键工具。打开终端Windows 用户建议直接装 Windows Terminal比老版 CMD 好用太多依次输入以下命令检查node -v npm -v git --version如果提示找不到命令先去对应官网下载安装。Node.js 建议装 20 及以上的长期支持版本太老的版本容易踩兼容坑。Windows 用户还需要注意npm 全局安装需要权限如果一会儿安装时报 EPERM 或 EACCES 错误就在管理员权限的终端里重试。这里有个常见误区很多人以为 Codex 只能在 macOS 或 Linux 上用实际上 Windows 也能正常跑只是有些网络相关配置上的差异。后面第 3 章会单独讲登录这类网络敏感环节。2.2 通过 npm 安装官方 Codex环境确认没问题后执行npm install -g openai/codex这条命令会把 Codex CLI 安装到全局目录之后你在任意终端里输入codex都能调用它。安装过程如果长时间卡住通常是 npm 源下载慢的问题。这时可以先切换镜像源再重新安装npm config set registry https://registry.npmmirror.com npm install -g openai/codex镜像源只是把下载仓库换到国内节点不会影响 Codex 本身的功能。装完使用npm config get registry可以查看当前源想换回官方源就执行npm config set registry https://registry.npmjs.org/。如果你更习惯图形界面去 VS Code 扩展市场搜索 Codex 官方插件安装后侧边栏会多一个 Codex 面板也能实现同样的功能。但请注意官方没有发布独立的“Codex Windows 桌面版安装包”网上搜到的很多“安装包”是非官方套壳轻则功能残缺、重则夹带私货优先用 npm 和官方扩展市场才安全。2.3 验证安装是否成功安装完成后先跑一个最简单的命令确认可用性codex --version能正常输出版本号说明安装成功。再试codex --help你会看到它支持的命令列表。到这一步Codex 已经装好了但离真正使用还差最关键的一步登录认证。3. 登录环节为什么总卡住认证逻辑和常见报错3.1 Codex 登录到底做了什么第一次运行codex时它会提示你登录。流程大致是终端弹出登录链接自动打开浏览器你登录账号并授权Codex 再把访问令牌写到你本地用户目录下的.codex配置文件里。这个令牌就是你之后每次请求模型服务的“通行证”。很多新手会卡在手机号验证这一步。手机号验证属于账号层面的安全验证跟着官方页面走就行。如果页面迟迟收不到验证码先检查你填的号码和网络请求是否正常。另外Codex 的登录状态和浏览器登录状态是两回事不是说你在网页上登录了 OpenAI 账号CLI 就自动生效必须单独执行过授权流程才算绑定。3.2 auth token is unavailable 的排查思路auth token is unavailable是最常见的登录报错之一。它的意思是 Codex 尝试获取访问令牌时失败了也就是本地没有拿到有效凭证。通常有四种原因第一登录流程根本没走完。你需要在终端里执行登录命令并完成浏览器授权不能跳过。第二本地保存的令牌过期或被清掉了。这时可以删除本地配置里的认证文件重新登录。第三系统时间不对。令牌校验依赖时间戳如果你的电脑时间偏离太多服务器会直接拒掉。第四网络无法正常访问认证服务导致令牌请求始终超时。清理重新登录可以这样操作codex login如果始终提示报错找到本地 Codex 配置目录。Windows 一般在C:\Users\你的用户名\.codexmacOS/Linux 在~/.codex。把里面的认证相关文件备份后删除再重新执行codex login。3.3 登录不上、打不开时的通用排查顺序很多人问“Codex 国内能用吗”我的回答是它本身是一个软件工具能不能正常登录和调用取决于你的网络能不能顺利访问到它所依赖的海外服务。如果终端一直卡在“等待浏览器完成授权”或者授权后页面转圈第一步先确认网络连通性换一个网络环境试试、关掉本地安全软件试试、等几分钟再试。这些属于最基础的连通性排查。如果网络本身不通任何工具层面的配置都救不了这是需要先解决的底层问题而不是 Codex 的 Bug。别急着重装先把网络这段打通再回来登录通常一次就能成功。4. 把 Codex 接到 DeepSeek第三方模型接入实例4.1 为什么要接入第三方模型我现在日常使用 Codex 时大部分请求其实走的是 DeepSeek 的模型而不是 Codex 默认绑定的官方模型。原因很简单成本更可控、账号限制更少、国内访问体验也通常更好。Codex 本身支持配置 model provider你可以把它理解成“给 Codex 换个大脑”本地还是那个会改文件会跑命令的 agent只是背后回答问题的模型换成了 DeepSeek、通义或者其他兼容 OpenAI 接口的服务。有一个很热的搜索词叫“Codex 接入 DeepSeek”要实现它本质上就是修改 Codex 的配置文件把模型服务地址指向 DeepSeek 的 API 地址再配上对应的 API Key。4.2 配置文件写法和具体步骤找到 Codex 的配置文件位置Windows 端一般在C:\Users\你的用户名\.codex\config.tomlmacOS/Linux 在~/.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 wire_api chat然后设置环境变量。Windows PowerShell 执行$env:DEEPSEEK_API_KEY 你的DeepSeek API KeymacOS/Linux 执行export DEEPSEEK_API_KEY你的DeepSeek API Key建议把 API Key 配置到环境变量而不是写进配置文件避免配置不小心分享出去导致密钥泄露。这个env_key的意思是Codex 启动时会去环境变量里找DEEPSEEK_API_KEY这个值把它作为请求头里的认证信息。配置完成后随便进入一个项目文件夹执行codex 帮我看看这个项目是干什么的如果回答来自 DeepSeek 模型说明接入成功。4.3 接入第三方的常见坑最容易踩的坑有三个。第一个是base_url写错了有些服务商给的是不带/v1的地址要么连不上要么返回 404一般补上/v1就能通。第二个是模型名写错比如把deepseek-chat写成deepseek-chat-v3服务端会直接返回模型不存在。第三个是wire_api用错DeepSeek 这类 OpenAI 兼容服务要用chat而不是responses因为后者是 OpenAI 新版接口协议的格式很多第三方服务没有实现。我个人还建议你注册一个 DeepSeek 的官方 API 账户花几块钱充值测试。用量不大时成本很低但能让你彻底搞懂整个链路之后再切换到其他第三方服务也就大同小异了。5. 第一次上手让 Codex 修一个真实的小 Bug5.1 进入项目目录并启动会话安装登录配置都完成后进入实战。第一步是进入你的项目目录。终端执行cd 你的项目目录然后直接说需求。比如这个项目里有个按钮点击没反应你就执行codex 帮我看看为什么按钮点击后没有任何反应修复并运行测试验证Codex 会先读取目录结构、搜索相关代码、逐文件排查然后告诉你它的计划并开始改代码。整个过程会在终端里实时输出你能看到它读了什么文件、改了哪些行、执行了什么命令非常透明。这里有一个关键前提项目最好已经初始化过 git。因为 Codex 的每一次修改都是建立在你当前代码之上的有 git 才能生成清晰 diff万一改砸了还能一键回退。如果项目还没有 git先执行git init再让 Codex 开工。5.2 权限模式谨慎型、半自动型和全自动型Codex 在执行命令前会问你要不要允许。比如它想运行npm test会弹出一个确认提示。这对小白来说是安全兜底避免 AI 随意执行危险命令。实际使用中Codex 提供三种操作策略suggest、auto、full-auto对应着“每次都问我”“非破坏性命令自动执行”“全部自动执行”。我建议新手先保持默认的 suggest 模式。等你对它的行为熟悉了再慢慢放开到 auto。full-auto 听起来省事但风险也最大尤其是 AI 执行 git push、删除文件这类操作时你必须对项目有足够掌控力才敢放手。安全第一永远是第一原则。5.3 小白最容易忽略的三件事第一件事任务越小越具体效果越好。“帮我重构整个项目”这种需求它大概率会陷入混乱“把 utils/format.js 里的日期格式化函数改成统一输出 YYYY-MM-DD”这种需求它能又快又准地完成。第二件事改完代码一定要验收。你可以看它生成的 diff可以用codex 总结一下你改了哪些内容让它自己汇报也可以手动跑一遍测试别默认它改完就一定对。第三件事注意 Token 消耗。Codex 每跑一次任务都会消耗模型配额上下文越长消耗越大所以无关文件能删就删需求能精简就精简。我要特别强调一下项目上下文。Codex 的能力上限很大程度上取决于它能看到的信息质量。你可以在项目根目录放一个AGENTS.md文件用普通人语言写下项目架构、常用命令、编码约定Codex 每次开工前都会读这个文件相当于提前给 AI 培训了一下项目背景。这个习惯一旦养成效果立竿见影。6. 我不想踩的坑高频报错的排查链路6.1 CC Switch 切换配置导致本地转发链路报错很多用户喜欢用 CC Switch 这类配置切换工具在多个模型服务之间一键切换省去手动改配置文件的麻烦。但这类工具的原理是改写本地配置并把请求转发到本地某个端口再中转出去。于是就会出现类似“切到 Codex 后请求 /responses 报错”的现场。遇到这种问题我的排查顺序非常固定第一步暂时绕开 CC Switch直接运行codex如果正常说明问题出在切换工具上如果也报错说明问题出在 Codex 自身配置。第二步打开 CC Switch 当前生成的配置文件看它的转发地址是不是指向本地某个端口再确认那个服务是否启动。第三步把配置还原成直连模式按第 4 章的手动配置方式重新写一遍确认能跑通后再重新开启 CC Switch。这类工具本身不坏但它是套在 Codex 外面的一层壳一旦发生问题就成了疑难点。你手动直连能跑通再逐步把壳加回来逻辑上就很容易定位到底是谁的责任。6.2 模型不支持与 unrecognized configuration setting有一个报错长这样某个gpt-5.6-sol模型在当前 Codex 连接方式下不受支持。说人话就是你当前配置里指定的模型名在你指定的服务商那边根本不存在。这种情况最常见于从网上复制别人的配置但没注意别人用的是特定账号或特定中转服务。解决方案很简单把模型名改成实际存在的比如 DeepSeek 就用deepseek-chat官方订阅用户就保持默认。还有一个高频警告是codex is ignoring 1 unrecognized configuration setting。意思是配置文件里有个键名它不认识直接忽略了。这通常是拼写错误或者从老版本配置里复制了过时的字段。处理办法是逐行核对配置节把不认识的键删掉即可。这种问题虽然没有致命影响但会让 Codex 按默认设置运行可能不符合你的预期。6.3 invalid input 与“没有终端和文件编辑工具”invalid input这类报错可以出现在模型端也可以出现在本地端。一种典型情况是请求上下文过长把输入内容截断或格式搞乱了。解决方案是缩小任务范围、清理无关文件或者直接新开一个会话不要在一个会话里堆一大堆无关对话。另一种情况是第三方服务的接口格式和 Codex 期望的不完全一致这时把wire_api换成chat再试。“没有终端和文件编辑工具”的报错则比较特殊Codex 运行需要它内部的工具链如果安装过程中缺失了某些依赖或者你使用的是一个残缺的非官方版本就可能出现。先执行重装npm uninstall -g openai/codex npm install -g openai/codex大多数情况下就能恢复。如果重装后还不行就把本地.codex目录里的配置文件彻底重置再重新登录。7. 用配置文件把 Codex 调成“顺手”的样子7.1 固定模型和审批策略既然已经掌握了config.toml不如顺手把默认模型和审批策略也写进去。比如我突然想让 Codex 默认使用 DeepSeek并且非破坏性操作自动执行就可以在配置文件里这样写model deepseek-chat model_provider deepseek approval_policy auto注意审批策略一旦写成autoCodex 对你的文件修改和命令执行会更加主动。新手刚上手时我依然建议用suggest等充分信任后再改。7.2 让 Codex 用中文回复很多人一开始用 Codex 都会问“它怎么不说中文”。其实 Codex 本身没有界面语言设置它说什么语言完全取决于你怎么要求它。最简单的办法是在提问时带上指令“请用中文回答我”。但更聪明的做法是在项目的AGENTS.md里写一句所有面向用户的回复一律使用中文。Codex 每次进来都会读这个文件之后自然就用中文跟你交流了。你甚至可以在配置文件里设置系统提示词让它始终保持某种工作习惯比如“切到完整代码搜索模式之前先列计划”“修改文件前先输出 diff。这些配置做到位之后Codex 会越来越像一个懂你项目、懂你习惯的搭子。7.3 我自己沉淀下来的几个使用习惯最后分享几个我实际用下来确实管用的习惯给 Codex 派活之前先在本地把分支切干净只保留和任务相关的代码减少干扰一次会话只做一个任务做完就开新会话避免上下文里塞满历史垃圾影响判断大改之前习惯性 git commit这样 Codex 改错了能随时后悔回滚。我用了 Codex 大半年最大的感受是它把“写代码”这件事的门槛又压低了一截但真正决定上限的还是使用者的表达能力和掌控习惯。你现在已经完全具备独立安装、登录、接入第三方模型、跑通修复流程、排查常见报错的能力了剩下的就是拿真实项目去喂它让它多跑、多错、多修你和它磨合出来的工作流会越来越顺手。
