★ FEATURED ARTICLE 最近这半年AI 编程圈子里热度涨得最快的名字除了 Claude Code就是 Codex。我后台收到的私信里一大半都在问Codex 到底怎么装、怎么登录、怎么接入 DeepSeek、为什么一跑就报错。正好 VideCoding 这个系列第一期就把 Codex 的基础一次讲透——从它是什么、能做什么到安装、配置、第一次跑通任务再到现在大家问得最多的高频报错一步不落全部按我实际踩过来的经验来写。先说结论Codex 不是又一个“聊天窗口里写代码”的工具而是一个能自己在终端里读代码、改代码、跑命令的 AI 编程智能体Agent。装好之后你会多一个“能听懂人话的实习生”它替你查文件、写代码、执行测试做完之后把改动摆在 diff 里等你看。市面上教你“装个插件就能用”的教程很多但真正决定能不能用顺手的是登录方式、模型配置和任务拆解这三件事。这篇内容适合三类人第一次听说 Codex、想从零开始安装的新手已经在用但经常被登录和报错卡住的普通开发者以及想把它接到 DeepSeek 这类第三方模型上省钱的进阶用户。全程不涉及任何账号之外的骚操作保证安全落地。1. Codex 到底是什么先别急着装1.1 从“帮你补全”到“替你把活干了”把 AI 编程工具的发展简单分成三个阶段你就明白 Codex 处在哪个位置了。第一阶段是“补全型”典型代表是各家的代码补全插件。它们根据你正在敲的代码预测下一行或下一个函数。你还在负责写AI 只是输入法。第二阶段是“对话型”典型代表是各种集成在 IDE 里的聊天窗口。你可以问“这段代码哪里有问题”AI 给你解释、贴出修改建议但改文件这件事还是你自己来改完还要负责复制粘贴。第三阶段才是“智能体型”。这类工具在英文里有个通用名词叫 Agent意思是 AI 拿到你的需求后自己去读项目结构、定位相关代码、动手修改、运行测试再把结果交给你确认。Codex 就属于这一类。它直接跑在你的终端里有权限读取工作目录、执行命令甚至在一个受限的沙箱环境里自动运行脚本。如果说前面两种像“陪练”Codex 更像是“替你上场打球但每步动作都先给你看的球员”。这也就是为什么很多人刚用 Codex 会不适应它不给你长篇大论的解释而是直接给你看它改了什么文件、跑了什么命令。你要做的不是跟着它敲代码而是审核它的动作。1.2 Codex 的核心能力终端原生、沙箱执行、记忆规则Codex 最早为人所知的是它在云端沙箱里“能连续干活几小时”的 Agent 能力后来命令行版本把同样的能力搬到了本地。我认为本地 CLI 版本有四个核心点值得你重点理解。第一终端原生。Codex CLI 不是一个 IDE 插件而是一个命令行程序。你在任何项目目录里敲 codex它就把当前这个目录当成项目上下文。这意味着它不挑编辑器无论你用 VS Code、JetBrains 还是纯 vim都能在同一个终端里调用。第二沙箱执行。Codex 默认会在受限环境里执行命令防止 AI 瞎跑破坏你的系统。管理员权限、危险命令都需要你确认。如果你明确知道自己要做什么也可以切换到全自动模式。这个设计非常重要后面我会专门讲沙箱的取舍。第三记忆规则。你可以在项目根目录放一个 AGENTS.md 文件里面写上“代码风格、禁止事项、测试命令”。Codex 每次启动都会先读这个文件把里面的规矩当作自己的行为准则。这相当于把团队约定固化进了 AI 的工作流程。第四技能Skill扩展。Codex 支持把自己常用的操作流程写成 Skill比如“提交 Git 时按什么格式写消息”“新增接口时自动补充哪几类测试”。写一次以后一句话就能触发。这听起来复杂其实就是一个 Markdown 文件后面我会给模板。1.3 Codex 与同类工具怎么选我知道很多人是冲着“Claude Code 和 Codex 选哪个”点进来的。这里不做拉踩只给一张我实测后的对照表方便你按自己的情况选。对比项CodexClaude CodeCursor Agent传统补全插件运行形态终端 CLI / 桌面版终端 CLIIDE 内 AgentIDE 内补全账号要求ChatGPT 账号或 API KeyAnthropic 账号或 API Key订阅账号订阅账号第三方模型接入配置灵活可接 DeepSeek 等同样可改接口但文档较杂基本锁定官方模型基本锁定官方模型记忆机制AGENTS.md SkillCLAUDE.md 为主项目规则文件无上手难度中等需要懂一点命令行中等偏高低按钮即用最低我的建议很简单如果你重度使用 VS Code、习惯图形界面Cursor 是最轻松的如果你想要一个不挑编辑器的终端 AgentCodex 和 Claude Code 都值得装。它们共用终端用途不同。Codex 对 OpenAI 模型的调用链路最顺畅Claude Code 在长文本理解和复杂重构上各有拥趸。别被圈子里的争论带偏工具而已跑通一个再说。2. 安装前的三个准备账号、命令行环境、目录习惯2.1 账号和订阅先搞清楚你用什么身份跑 Codex这是所有新手踩坑的第一站也是最容易被忽略的。Codex 的登录身份有两大类它们的报错方式和适用场景完全不同。第一类是 ChatGPT 账号需要是 Plus、Pro、Team 或 Business 套餐。用codex login会打开浏览器让你登录 ChatGPT 账号登录成功后 Codex 会拿到一个授权凭证全程不需要你手动填模型 Key。这种方式的好处是开箱即用坏处是流量和模型选择受账号套餐限制而且登录状态过期后会出现 “auth token is unavailable” 这类报错。第二类是 OpenAI API Key适合你已经开通了 API 计费、想精确控制模型和额度的用户。CLI 支持通过环境变量传入 API Key也可以把 Key 写进配置文件。另外提醒一句注册和手机号验证这类操作都走官方渠道按流程填就行。不要去买那种来路不明的“共享账号”风控一来轻则登录不掉线重则账号连带服务一起被冻结省下的钱不够折腾的。2.2 安装 CLInpm 与 Homebrew 两条路Codex CLI 是一个开源项目官方仓库维护得很勤安装方式也在持续更新。目前最通用的方式是 npm 安装npm install -g openai/codex codex --versionmacOS 用户如果有 Homebrew也可以直接查官方仓库里的安装说明用 brew 来装。npm 装的是 stable 版brew 装的更新更频繁。我个人的习惯是主力机装 npm 版测试机装 brew 版两边互不干扰。安装完成后先跑codex --version确认版本号。如果提示“codex 不是内部或外部命令”八成是 Node.js 没装或者 npm 的全局安装目录不在系统 PATH 里。Windows 用户在 PowerShell 里装完后建议重开一个终端窗口再试PATH 环境变量要重启终端才生效。CLI 装好之后不要急着用先在命令行里执行codex --help把常用子命令扫一遍。基础期你只需要记住两个codex进入交互模式codex exec执行一次性任务其他都是锦上添花。2.3 Windows 桌面版安装与常见“打不开”问题如果你不想碰命令行或者只是想在图形界面里试试水官网提供了 Windows 和 macOS 的桌面版安装包。Windows 桌面版下载后直接运行安装程序首次启动需要登录 ChatGPT 账号登录成功后会在界面里显示当前工作目录和聊天面板。关于“桌面版打不开”的问题我收集到的原因大致有三类一是系统版本过旧桌面版对 Windows 版本有要求老版本系统装上后可能白屏或闪退二是安装包未下载完整尤其是从非官网渠道下载的离线安装包体积不对、签名不对都会导致安装失败三是登录环节卡住网页授权窗口被浏览器拦截授权完成后桌面端没收到回跳。“求汉化包”也是个高频话题。我的建议是别折腾汉化Codex 的界面语言跟随系统而且这些工具的核心使用场景本来就在终端和提示词里。你真想让它用中文干活直接在项目根目录的 AGENTS.md 里写一句“所有回复请使用简体中文”比任何汉化包都可靠。汉化包这种东西来源不明还可能被塞私货不值得冒账号风险。2.4 登录与鉴权auth token 到底是怎么来的很多人一看到 “auth token is unavailable” 就懵其实搞清楚凭证的来源就一点都不慌。当你执行codex loginCLI 会启动一个本地服务并打开浏览器引导你登录 ChatGPT 账号。登录成功后服务端把授权凭证通过本地回调写进~/.codex/auth.json。之后每次调用 Codex它都会带着这个凭证访问服务。凭证失效的原因通常是三种账号密码变更、凭证过期、本地时间不准。遇到 “auth token is unavailable” 或 “unauthorized”第一件事不是改配置而是重新执行一次codex login八成问题都能解决。如果你走 API Key 路线auth.json 就不需要了。你要做的是把你的 Key 设置成对应环境变量并确保终端会话里能看到这个变量。注意不要把 Key 写进项目里的代码文件这是账号安全问题不是技术问题。3. 基础配置config 文件与第三方模型接入3.1 一份能跑起来的 config.toml 长什么样Codex 的基础配置集中在一个 TOML 文件里全局路径是~/.codex/config.toml。在项目根目录下也可以放.codex/config.toml它是覆盖全局配置的“本地优先级”配置。理解了这个覆盖关系你就能做到“全局统一、项目微调”。一份最基本的配置长这样model gpt-5.2-sol model_provider openai model_reasoning medium [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY逐行解释一下model是主模型名直接决定了 Codex 的思考质量model_provider指向下面[model_providers.xxx]这个区块的 ID用来定位到具体的服务商model_reasoning是思考强度低中高三档档位越高推理越细、耗时越长、花销也越大[model_providers.openai]里定义了服务商的显示名、接口地址和读取 Key 的环境变量名。这套结构最大的好处是“服务商可插拔”。你想换模型不需要改一堆代码只要在配置里新增一个 provider 区块再切换model和model_provider即可。3.2 把 Codex 接到 DeepSeek一份真实可用的配置模板“Codex 接入 DeepSeek”是最近搜索量最大的词之一原因也很直观DeepSeek 的 API 便宜而且接口兼容 OpenAI 的调用格式理论上 Codex 可以直接用。我实测下来的配置方案如下model deepseek-chat model_provider deepseek model_reasoning medium [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY然后把 DeepSeek 的 API Key 设置到环境变量export DEEPSEEK_API_KEYsk-你的key之后在项目目录里执行codex它就会通过 DeepSeek 的接口跑任务。如果你用的是 DeepSeek 的推理模型比如deepseek-reasoner把第一行的model改成对应模型名model_reasoning可以降一档因为推理模型本身就在做深度思考再叠加高推理档位会明显拖慢响应。这里补充三点实测教训第一不同版本的 Codex 对模型名的校验严格度不同改完配置最好先跑一个小任务验证连通性第二base_url末尾的/v1别漏漏了会返回 404第三用第三方模型时部分沙箱行为和模型自身能力有关如果发现它频繁提示权限不足优先检查 AGENTS.md 里的规则是否把它的手脚绑得太死。至于“所在地区能不能用”这类问题我的看法是先看你的账号能否正常走官方登录流程。能走就按官方流程用不能走与其在网络层面折腾各种方案不如直接用 API Key 加兼容服务商的方式来跑 CLI。后者在社区里被验证得最多也是最不容易出问题的替代路径。3.3 VS Code 插件接入与中文使用习惯很多人问“vscode 怎么接入 codex”其实有两个层面。第一层是安装官方插件在 VS Code 扩展市场里搜 OpenAI Codex安装后打开侧边栏按提示登录 ChatGPT 账号就能在 IDE 里直接对话、让 Codex 改当前项目。第二层是用配置文件把 Codex CLI 的规则带进 VS Code 项目也就是在项目根目录放.codex/config.toml和 AGENTS.md这样你在 IDE 终端里启动 codex 时行为规则自动生效。中文使用这块经常有朋友吐槽“Codex 回复全是英文看得头疼。”实际上这和模型本身有关和界面没关系。最有效的解决办法是在 AGENTS.md 里明确要求中文回复因为 Codex 每次启动都会读这个文件你的偏好会被持续遵循。这比在每条 prompt 里重复一遍“用中文回答”省心得多。3.4 配置切换工具ccswitch 这类怎么用才安全社区里流传着一类小工具叫“CC Switch”也好、叫“Provider Switcher”也罢作用都差不多在多个模型服务商配置之间快速切换免得你每次手动改 config.toml。对于同时接 OpenAI、Anthropic、DeepSeek 多套配置的人来说确实省事。但这类工具有一个天然的坑它生成的配置字段未必匹配当前 Codex 版本的格式而且有些版本会写入额外的网络相关配置项。很多人切换完再启动 codex就遇到连接失败类的报错多半就是这个原因。我的安全用法是三步第一切换前先备份当前的~/.codex/config.toml第二切换后不要急着跑大任务先跑一个简单请求验证连通性第三如果报错把配置恢复成备份再排查具体是哪个字段导致的。永远不要在没备份的情况下让工具帮你覆写配置。4. 第一次让 Codex 干活从最小任务跑通完整流程4.1 用一个最小任务跑通闭环理论和配置讲再多不如亲手跑一次。找一个空目录我带你做一个最小任务写一个 Python 脚本统计当前目录下所有 .py 文件的行数。第一步新建目录并进入mkdir codex-demo cd codex-demo第二步在目录里创建一个 AGENTS.md先只写一句话“你是一个严谨的 Python 工程师所有代码先解释思路再动手。”这是为了让 Codex 一进来就知道边界。第三步执行codex进入交互模式输入需求“写一个 Python 脚本统计当前目录下所有 .py 文件的行数并在终端里输出结果。”接下来你会看到它的行动过程先列出目录文件然后创建脚本再尝试运行最后把输出给你看。其中涉及执行命令的部分会弹出确认请求这是沙箱在保护你。第一次用建议每一步都看清楚再放行别闭着眼按“全部允许”。脚本跑成功之后退出 Codex手动检查一下它生成的文件。这一步非常关键AI 写的代码你必须亲自读一遍确认没写入危险命令、没引入莫名其妙依赖。Codex 的定位是帮你提速不是替你做责任背书。4.2 多文件改造时如何拆解需求跑通最小任务之后大多数人会立刻想拿它干大活比如“帮我给整个项目加权限系统”。我的建议是大活可以干但前提是你会拆。Codex 的上下文窗口再大也没法在一个超长对话里把所有细节都照顾到超长任务还容易触发限流后面会讲 429 报错。比较好的拆法是把需求拆成一串可验证的小步骤每步一个目标。比如改造一个模块拆成第一步梳理现有结构和数据流第二步新增数据模型第三步补接口第四步写测试。每完成一步让 Codex 暂停你检查 diff确认无误再继续下一步。我常用的提示词模板是这样背景这个模块负责用户注册当前逻辑在 auth_service.py。 任务新增一个密码强度校验函数要求最少 8 位、包含大小写和数字。 约束不要改文件结构复用已有工具函数补一个单元测试。 验收运行 pytest 能通过。背景、任务、约束、验收四段式足够让 Codex 在大多数场景下少说废话、少跑偏。4.3 AGENTS.md 与 Skill把团队规矩写进项目Codex 的长期记忆能力是我们把它当成正式工作流的一部分的重要基础。项目根目录的 AGENTS.md 就是它的“员工手册”。你可以写的东西包括项目技术栈、目录结构说明、测试命令、代码风格约定、禁止事项比如“不要修改 API 文档”“不要删除迁移文件”。写 AGENTS.md 有一个技巧别写成论文写成检查清单。Codex 是概率模型太长的规则它记不住重点。每条规则尽量一句话能用否定句说明禁止事项的就明确写“禁止 xx”比“建议谨慎处理 xx”效果好得多。Skill 是更上层的复用机制。拿“提交信息”举例你可以建一个文件.codex/skills/git-commit/SKILL.md里面用固定格式写清触发场景和操作步骤。之后你只对 Codex 说“用 git-commit 技能帮我提交”它就会按你写好的规范操作。这本质上是在给 AI 造“脚本”日常重复性动作都值得沉淀成 Skill。4.4 真实操作中的三个习惯第一永远是独立分支。我见过太多人让 Codex 直接在 main 分支上跑大改造然后回滚时欲哭无泪。让 Codex 干活之前先git checkout -b feature/xxx这是成本最低的安全垫。第二小步提交频繁查看 diff。Codex 每次改完用git diff看一遍。看不懂的改动宁可让它重写也不要带着疑问继续。一旦你连续跳过几个 diff后面它会越来越“自由发挥”。第三给足上下文但别倒垃圾。项目背景、涉及文件、验收标准这些要写清楚历史对话、无关日志这些别粘进去。Codex 不是搜索引擎给它干净的输入它才有干净的输出。5. 高频报错与排查实录5.1 429 too many requests限流没那么吓人“codex exceeded retry limit, last status: 429” 这个报错常见到什么程度我在群里几乎每天都能看到一次。429 表示服务端限流了不是你的配置坏了也不是账号被封。常见触发场景有三种短时间内连续发起大量任务同一账号多个终端同时在使用低套餐的额度被跑完。遇到 429 的正确姿势是停一停不要立刻疯狂重试那样只会把限流窗口延长。等几分钟再试通常能恢复。如果频繁复现就把大任务拆成多个小任务中间留出间隔。另外检查一下你的账号套餐额度低套餐的并发和每日额度都有限制这是正常的商业逻辑不是故障。5.2 model is not supported模型名和套餐对不上这个报错很典型报错信息里通常会带上具体的模型名比如“the gpt-5.x-sol model is not supported when using codex with a chatgpt account”。意思是说你当前用的是 ChatGPT 账号登录方式但配置里指定的模型在这个账号套餐的后端并不支持。解决办法很简单要么把你的model改成账号套餐真正支持的那个模型名要么改用 API Key 登录并在服务商支持列表里确认模型名的拼写。这里要特别提醒模型名大小写、连字符、后缀都得和官方文档一致差一个字符就是 not supported。5.3 auth token is unavailable八成是登录状态失效这个报错我在第二节讲过原理这里只说排查顺序。第一步重新执行codex login看能否完成整个授权闭环。第二步检查~/.codex/auth.json是否存在、文件内容是否为空。第三步确认系统时间准确时间偏差过大会导致凭证校验失败。如果以上三步都做了还是报错考虑是不是环境变量里同时设置了 API Key导致 CLI 在两种鉴权方式之间发生了冲突。把 API Key 的环境变量临时清掉再走一遍账号登录往往就好了。5.4 配置切换工具导致的连接失败问题使用 ccswitch 这类配置切换工具后最常见的症状是一切看着正常但 codex 一启动就连接失败或者请求发出去直接超时。根据社区反馈和我自己的复现问题基本都出在工具自动生成的配置上——它可能写入了当前环境不可用的网络相关配置项或者 base_url 指向了不可达的地址。排查思路分四步第一步恢复备份的 config.toml观察问题是否消失第二步如果问题消失就手动新写一个 provider而不是依赖工具生成第三步确认 base_url 在当前网络环境下能正常访问第四步确认环境变量里的 Key 已正确加载。这四步走完九成的切换问题都能定位到具体字段。这里也多说一句任何社区工具都不值得你把账号凭证直接交给它。配置切换工具只负责写文本文件不负责保管密钥。密钥在你自己的环境变量里这才是底线。5.5 其他常见问题速查现象可能原因处理建议提示 codex 不是内部或外部命令npm 全局目录不在 PATH重装 Node.js 或手动配置 PATH重开终端登录页面一直转圈浏览器拦截、网络环境不通检查官方登录入口重试或换浏览器桌面版安装后闪退系统版本过旧或安装包损坏从官网重新下载确认系统要求终端输出中文乱码Windows 终端编码问题把终端编码切到 UTF-8调用第三方模型返回 404base_url 漏了 /v1 或后缀不对对照服务商文档逐字符核对地址任务执行到一半中止单次上下文过长或超时拆任务、精简 AGENTS.md、换更强模型6. 从基础到顺手我的几点真实体会6.1 把它当实习生而不是搜索引擎把 Codex 从“能跑通”用到“顺手”我最大的体会是别把它当搜索引擎要把它当实习生。刚入门的用户最容易犯的错是给一个模糊的请求然后期待它一次做对而用得好的人都在反复训练自己把需求拆成背景、任务、约束、验收四段。需求越清楚Codex 的返工率越低你的时间节省才真正成立。另一个经常会忽略的事情是Codex 给出的答案不一定对但它给出答案的速度足够快这就给了你反复验证的空间。你应该像审实习生代码一样审它的 diff而不是像查词典一样查它的输出。心态一旦转过来这些 AI 编程工具的效率优势才能真正兑现。6.2 沙箱、确认与配置管理沙箱和确认机制不是麻烦是保护。刚开始我也嫌每次执行命令都弹确认很烦后来把沙箱关掉跑了几次AI 一个误操作差点把本地数据库文件清了从那以后我再也没嫌弃过确认弹窗。真的需要全自动跑长任务时再单独开一个隔离环境去用别拿日常开发的机器赌运气。最后分享一个小技巧把~/.codex/config.toml和项目里的 AGENTS.md 纳入你自己的配置仓库统一管理。换新电脑时一条命令就能恢复全套环境。Codex 的能力上限由模型决定但你的使用下限完全由你的配置和习惯决定。
阅读完成 · 觉得有帮助？
