如果你在 2026 年还只把 Codex 当作一个网页聊天框那很可能错过了它真正重要的变化。Codex 不是一个“给你出主意”的对话助手而是一个能在终端里直接读你的仓库、修改代码、执行命令、甚至把多步任务跑完的 AI 智能体。对普通开发者来说它带来的最大改变不是“回答得更准”而是“真的动手干活”。这篇文章面向的是第一次接触 Codex 的开发者尤其是被安装、登录、模型配置这几步劝退的小白。我会把完整链路拆开讲Codex 是什么、安装前要准备什么、如何安装、如何登录、如何接入 DeepSeek 等第三方模型、如何用命令行完成实际任务以及最常遇到的报错和排查思路。读完之后你能独立把 Codex 跑起来并且知道在真实项目里怎么用它、不该怎么用它。先给出一个明确判断Codex 最有价值的地方是它把 AI 编程从“对话式问答”推进到了“任务式执行”。这个差异决定了它的安装和使用方式也决定了你要用新的思路去驾驭它。1. Codex 是什么——它解决的是什么问题Codex 是 OpenAI 推出的编程智能体面向开发者的命令行工具。它和你在网页端打开的 ChatGPT 是两种形态也和 IDE 里的自动补全插件不一样。Codex 的运行场景是终端你给它一个任务描述它会自己规划步骤、读取项目文件、修改代码、执行测试命令然后给你一个结果。用一句话概括它是一个“能在你的电脑里真正干活的 AI 程序员”。要理解 Codex 的价值可以看一个典型场景。以前你写一个功能流程是在编辑器里写代码、切到终端跑测试、看到报错、回到编辑器继续改。每一步都需要你亲自操作。有了 Codex 之后你可以把“帮我实现一个用户注册接口包含参数校验、数据库存储和单元测试”这样一整条任务扔给它它会自己去创建文件、写代码、跑测试然后告诉你结果。你从“执行者”变成了“验收者”。从技术原理上看Codex 的核心能力来自两个方面。第一它能感知当前项目的工作区读取项目结构和文件内容而不是只靠你粘贴的代码片段。第二它具备工具调用能力可以在终端里执行命令、修改文件相当于把大模型的语言理解能力和操作系统的执行能力打通了。这两点加在一起才让“AI 自动完成开发任务”成为可能。这里有一个容易误解的地方Codex 并不只是“代码生成器”。它真正解决的是开发流程里的重复劳动和上下文切换成本。换句话说它降低的不是“写代码”的门槛而是“把代码跑通”的沟通成本。理解了这一点你就知道为什么它是一个命令行工具而不是又一个网页编辑器。2. Codex CLI 与传统 AI 编程工具的区别很多刚接触 Codex 的开发者会拿它和 GitHub Copilot、Cursor、ChatGPT 网页版做比较。为了帮你快速建立认知我用一张表来说明差异。工具运行形态核心能力适合场景GitHub CopilotIDE 插件代码补全、行内建议写代码时的即时辅助Cursor编辑器对话式代码修改、多文件编辑在图形界面里做 AI 编程ChatGPT 网页版网页问答、代码解释、代码生成学习、讨论、获取片段Codex CLI终端命令行读取仓库、执行命令、多步任务自动完成把 AI 接入工程流程让 AI 独立执行任务从上表能看出Codex 和 Copilot 不是同类工具。Copilot 更像你写代码时的一个“输入法”你写到哪里它补到哪里Codex 更像一个“结对程序员”你把任务交给它它自己去完成。两者的价值主张完全不同。Codex 和 Cursor 相比差异在交互层。Cursor 把所有能力封装在图形界面里优点是上手直观缺点是自动化程度和脚本化能力有限。Codex 在终端里运行天然适合和 Git、测试框架、CI/CD 流程配合也更容易嵌入到自动化脚本中。如果你有“用命令行完成任务”的习惯Codex 会更顺手。Codex 与 ChatGPT 网页版的区别就更明显了。网页版是“你问我答”你需要自己把代码复制来复制去Codex 直接操作你的本地文件系统不需要复制粘贴也不依赖打开浏览器。它解决的核心痛点是AI 给的代码片段和你的项目环境脱节。Codex 直接在你的项目里工作代码和上下文天然一致。不过我对 Codex 的判断不是“它一定比所有工具都好”。准确地说它是“AI 编程工具演进到智能体阶段的代表”。如果你的工作流高度依赖 IDE 的可视化操作Cursor 可能更适合你如果你想构建一个能自动完成工程的开发流程Codex CLI 才是更贴近未来方向的选择。3. 安装前的环境准备在安装 Codex 之前先确认你的电脑环境是否满足基本条件。Codex CLI 是一个 Node.js 命令行工具因此最核心的前置依赖是 Node.js 和 npm。先检查两个命令是否可以正常执行node -v npm -v如果两个命令都能输出版本号说明 Node.js 环境已经就绪。如果提示找不到命令需要先安装 Node.js。建议安装较新的 LTS 版本比如 Node.js 18 及以上因为较旧版本可能无法满足最新 Codex 的依赖要求。版本细节以你安装时的官方发布信息为准不要盲目追求最新的大版本LTS 版本在稳定性上更有保障。除了 Node.js 和 npm我还建议你提前准备好 Git。虽然 Codex 本身不强制依赖 Git但实际开发中你通常会在一个 Git 仓库里使用它。Codex 修改代码后你需要通过 Git 查看变更、对比差异、回滚操作。如果你还不熟悉 Git可以先用最简单的几条命令git init初始化仓库git diff查看改动git checkout .撤销改动。这些操作会在后面用到。另一个重要的准备项是账号。使用 Codex 需要有一个 ChatGPT 账号并且这个账号需要具备使用 Codex 的权限。这里需要特别说明从当前信息看Codex 面向的是付费订阅用户免费账号通常无法正常使用。具体的订阅档位和权限范围以 OpenAI 官方页面为准。提前准备好账号能让后面的登录步骤更顺畅。最后Codex 官方推荐在 macOS 和 Linux 系统上运行Windows 用户可以通过 WSL 获得更好的体验。这不是说 Windows 原生环境完全不行但 WSL 能减少很多文件路径和权限相关的兼容性问题。如果你在 Windows 上安装时遇到奇怪的问题先考虑切换 WSL 环境。环境准备完成后建议在终端里执行一次检查清单确认node -v、npm -v、git --version都能正常输出再确认自己已经拥有一个可以登录的 ChatGPT 账号。这样进入下一步时就不会被环境问题打断。4. Codex 安装完整步骤Codex CLI 的安装方式非常直接核心命令只有一条。在终端中执行npm install -g openai/codex这里使用了 npm 的全局安装参数-g意思是把 Codex 安装到系统全局环境中这样你在任何目录下都能直接执行codex命令。安装过程中npm 会自动下载 Codex 及其依赖包需要保持网络连接稳定。安装完成后验证是否成功codex --version如果能看到类似版本号的输出说明安装成功。如果提示codex不是内部或外部命令可能是全局安装路径没有被加入系统的 PATH 环境变量。在 macOS 和 Linux 上可以尝试重新加载终端配置比如执行source ~/.zshrc或source ~/.bashrc在 Windows WSL 中重启终端通常就能解决。接下来是更新 Codex 的命令。Codex 迭代速度很快新功能和新模型支持都会随版本更新发布。定期更新是一个好习惯npm update -g openai/codex这里提醒一下权限问题。在 Linux 或 macOS 上如果你使用系统自带的 Node.js全局安装有时会报 EACCES 权限错误。一个稳妥的解决方案是使用 Node 版本管理工具如 nvm来安装 Node.js这样全局安装路径就在你的用户目录下不需要 sudo 权限。从工程实践看用 nvm 管理 Node 环境比直接修改全局目录权限更安全也能避免后续出现其他权限问题。如果在安装过程中出现网络超时或下载失败多数情况是网络波动导致的。可以先执行npm cache clean --force清理缓存然后重试安装。如果仍然失败可以换一个 npm 镜像源。需要说明的是镜像源配置因地区和网络环境差异很大这里不展开具体镜像地址你可以根据实际网络情况选择可用的 npm 镜像。5. 登录与基础命令行用法安装完成之后还不能直接使用需要先登录你的 OpenAI 账号。在终端中执行codex login执行之后终端会显示一个授权链接并等待你在浏览器中完成登录和授权确认。整个过程和常见的“通过浏览器授权 CLI 工具”的流程一致。登录成功后Codex 会把凭据保存在本机之后一段时间内无需重复登录。如果你需要退出登录执行codex logout登录只是第一步真正要掌握的是 Codex 的命令行用法。下面几个命令是最常用的。第一是交互模式。直接运行codex会进入一个交互式终端界面你可以像聊天一样连续给 Codex 发指令它会根据对话上下文和你的项目文件执行任务。这个模式适合需要反复调整和确认的开发任务。第二是单次执行模式。使用codex exec后面跟上任务描述Codex 会执行一次任务后退出。例如codex exec 帮我写一个 Python 脚本输出 1 到 10 的平方这个模式适合明确、独立的任务也适合写进自动化脚本。第三是恢复会话模式。使用codex resume可以恢复上一次的交互会话。当你退出交互模式后Codex 会记住之前的对话状态你可以回到原来的上下文继续工作。如果你同时在多个项目里使用 Codex建议用codex resume -c 会话编号精确恢复指定会话避免加载错误上下文。第四是查看帮助。执行codex --help你会看到完整的命令列表和可用参数。花几分钟浏览一下帮助信息比直接搜索教程更能帮助你了解当前版本的实际能力因为不同版本的命令细节可能有差异。初次使用时我建议先在一个空白测试目录里运行codex随便给它一个简单任务比如“创建一个 README.md 文件并写一段欢迎文字”。这样能快速验证环境是否完全跑通同时让你熟悉 Codex 的工作流程而不必担心它误改你的真实项目。这里有一个关键认知Codex 会在你的工作区内执行命令和修改文件。它的能力不只是生成文本还涉及真实操作所以在执行任何任务前你都要清楚它“能干什么”和“你允许它干什么”。这个边界意识会在后面的最佳实践部分详细讲。6. Codex 接入 DeepSeek 等第三方模型很多开发者在安装完 Codex 后会遇到一个问题账号权限有限或者觉得官方模型的使用成本偏高。于是“Codex 接入 DeepSeek”成了搜索热度非常高的需求。好消息是Codex 支持配置第三方模型提供商你可以通过修改配置文件把底层模型切换为 DeepSeek 等 OpenAI 兼容接口的模型。先解释一下配置原理。Codex 的配置文件位于用户主目录下的~/.codex/config.toml。如果没有这个文件可以手动创建。配置文件中可以定义默认模型、模型提供商、API 请求地址和密钥环境变量。Codex 启动时会读取这些配置决定它调用哪个模型服务。一个常见的 DeepSeek 接入配置如下# 文件路径~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat在这份配置里model指定默认使用的模型名称model_provider指定使用哪个提供商配置。[model_providers.deepseek]下面的base_url是 DeepSeek 的 API 地址env_key告诉 Codex 从哪个环境变量读取 API Keywire_api表示接口协议类型。需要说明的是不同 Codex 版本对配置文件的支持程度可能有差异以上配置是最常见的写法。你在实际配置时应以当前版本的官方文档和社区资料为准。配置中引用了环境变量DEEPSEEK_API_KEY所以你要先获取 DeepSeek 的 API Key并把密钥设置到环境变量中。在 macOS 和 Linux 终端中可以临时设置export DEEPSEEK_API_KEY你的 API Key如果你希望配置持久生效可以把这行命令写入~/.zshrc或~/.bashrc。注意不要把 API Key 直接写进config.toml因为配置文件可能被同步到代码仓库存在泄露风险。使用环境变量是更安全的方式。配置完成后在终端中运行codex exec 你好请简单介绍一下你自己如果 Codex 能正常返回 DeepSeek 模型的回复说明接入成功。这里要提醒三点。第一DeepSeek 属于第三方模型服务具体能力和稳定性和官方模型有差异生产环境使用前一定要充分测试。第二使用第三方模型时Codex 的 API 调用方式和模型能力边界可能与官方模型不同某些高级功能不一定完全兼容。第三不要把你自己的 API Key 提交到公开仓库也不要在团队代码中明文展示密钥。正确做法是把密钥放在本机环境变量或密钥管理服务中按最小权限原则分配。7. 实战示例用 Codex 完成一个完整任务现在进入最关键的实操环节。我们用一个完整示例演示 Codex 从接收任务到交付结果的全过程。7.1 示例一创建 Python 脚本先创建一个测试目录并进入mkdir codex-demo cd codex-demo执行以下任务codex exec 在 Python 中写一个函数计算 Fibonacci 数列的第 n 项并为它写一个简单的单元测试Codex 会在这个目录中创建文件、编写函数和测试代码。任务结束后你可以查看目录结构ls -la你会发现目录中多出了 Python 脚本文件和测试文件。然后运行测试验证python -m pytest test_fibonacci.py如果看到测试通过的结果说明 Codex 完成的任务真实可用。7.2 示例二在交互模式中迭代修改单次执行适合一次性任务但真实的开发流程通常是多轮迭代的。这时可以使用交互模式codex进入交互模式后输入给 fibonacci 函数添加一个参数允许调用方指定起始值并更新测试Codex 会在当前对话上下文中理解之前的代码结构修改文件并更新测试。你可以继续追加指令再为这个函数补充类型注解并确认测试仍然全部通过这种交互式的迭代方式是 Codex 最有价值的使用形态。它像一个能记住上下文的结对程序员你可以不断提出新需求它会在已有代码基础上持续修改。7.3 示例三查看会话历史与恢复在交互模式中你可以使用/exit退出。之后之前的会话会被保存。查看会话历史codex resume --list恢复最近一次会话codex resume如果你在多个项目间切换记得使用-c参数指定会话编号避免在错误的项目里恢复错误上下文。运行到这里你已经完成了 Codex 从安装到实际使用的完整闭环。接下来要做的是在自己的真实项目中逐步增加使用场景写脚本、修 bug、补测试、重构代码。每次使用后用 Git 查看代码变更是否符合预期。8. 常见问题与排查思路在使用 Codex 的过程中报错是最容易劝退新手的一环。我把常见问题整理成排查表格你可以直接对照处理。问题现象可能原因排查方式解决方案codex命令找不到npm 全局目录未加入 PATH执行echo $PATH查看路径将 npm 全局目录加入 PATH或使用 nvm 管理 Node.js安装时提示 EACCES 权限错误当前用户对系统全局目录无写权限检查错误信息中的目录路径使用 nvm 安装 Node.js避免使用 sudo登录时提示认证失败或无法访问登录链接网络环境受限、登录链接打不开检查网络连通性换一个网络环境再试确保能正常访问 OpenAI 服务重新执行codex login提示 “model is not supported”当前账号没有权限使用该模型或模型名称拼写错误核对config.toml中的模型名检查账号订阅权限更换为当前账号支持且官方兼容的模型名称或检查订阅状态任务执行时输出与预期差异很大上下文不清晰、缺少 AGENTS.md 指引查看 Codex 读取了哪些文件、是否理解项目结构在项目根目录添加 AGENTS.md写清楚编码规范和约束提示本地网络相关错误例如cc switch local proxy failed while handling codex endpoint /responses终端无法正常访问 API 服务或本地网络中间设置有异常先检查能否正常访问目标 API 服务确认基础网络连通性排查本地网络环境和受限状态必要时切换网络环境再重新执行任务交互模式下回复卡顿或超时网络不稳定、任务过于复杂按 CtrlC 终止当前请求重新发起分拆任务缩小单次指令范围或在网络环境更稳定的情况下使用修改了错的文件工作区中没有锁定的修改范围用git status查看变更清单养成每次任务后检查 Git 变更的习惯必要时使用git checkout回滚这里我想重点展开一下“模型 is not supported”这个报错。出现这种情况有两种常见原因一种是账号权限不够也就是你当前的订阅档位不支持你指定的模型另一种是模型名称在配置中写错Codex 无法识别。排查时先检查config.toml中的model字段是否准确再确认账号权限。从社区反馈看很多新手在配置第三方模型时会把模型名写错少一个符号或多一个空格都会导致这个报错。另一个值得关注的是本地网络相关报错。这类报错信息中可能出现/responses之类的 endpoint 路径容易让人误以为是 Codex 配置错误。实际上这类报错的触发点通常在终端到 API 服务的链路。排查时先做一个基础检查确认你的网络能正常访问 API 服务。如果公司网络或本地网络有额外的限制你可以先切换网络环境测试确认是不是网络因素导致的。注意排查这类问题时不要擅自修改系统级网络配置首先要确认是否在自己的可控范围内再谨慎操作。最后补充一个容易被忽略的问题Codex 在交互模式中的历史会话会占用磁盘空间。如果你长时间高频使用可以定期执行codex resume --list查看会话列表删除不再需要的旧会话避免无意义的磁盘占用。9. 最佳实践与工程建议安装和跑通只是第一步真正让 Codex 在项目中发挥价值需要建立一套工程实践规范。9.1 用 AGENTS.md 约束 Codex 的行为Codex 支持读取项目根目录下的AGENTS.md文件把它当作项目的“行为准则”。你可以在这个文件里写清楚项目使用的技术栈、代码风格、测试命令、禁止修改的目录等信息。这样每次 Codex 进入项目都会自动读取这些规则行为会稳定很多。一个最小示例# 文件路径/项目根目录/AGENTS.md ## 项目说明 这是一个 Python FastAPI 项目使用 pytest 进行测试。 ## 编码规范 - 使用中文注释 - 遵循 PEP 8 风格 - 所有新增函数必须有类型注解 ## 常见命令 - 运行测试python -m pytest - 启动服务uvicorn main:app --reload ## 禁止事项 - 不要修改 config 目录下的生产配置 - 不要执行数据库迁移命令有了 AGENTS.mdCodex 的回答质量和任务完成度会显著提升因为它不再靠猜而是有明确的项目上下文。9.2 让 Codex 在独立分支上工作Codex 会修改代码、执行命令这就意味着它有破坏性操作的能力。最稳妥的做法是每次让 Codex 工作前先创建一个新的 Git 分支。这样如果 Codex 完成的任务不满意你可以删除分支重新开始完全不影响主分支代码。推荐流程git checkout -b feature/codex-task codex exec 实现用户注册接口 git diff检查git diff输出了哪些变更确认无误后再合并到主分支。这个习惯看似简单但能帮你避免大量因 AI 误改代码导致的问题。9.3 明确安全边界Codex 能够执行终端命令这意味着它有可能执行删除文件、安装依赖、修改配置等操作。在真实项目中你必须明确告诉它哪些操作不能做而且最好在 AGENTS.md 里写清楚。更稳妥的方式是把 Codex 的运行环境限定在隔离的测试环境中尤其是当你准备让它修改数据库结构、运行迁移、处理敏感数据时。API Key、数据库密码、云服务密钥这类敏感信息绝对不要出现在 Codex 的输入提示词中也不要让它读取包含密钥的文件。你要意识到AI 工具的便利性和它的权限边界是一体两面的越是能帮你做事的工具越要谨慎控制它的权限。9.4 控制单次任务粒度前面实战示例中我把任务拆分成了“写函数—改参数—补注解”三个步骤这是有意为之。Codex 虽然在多步任务上表现不错但任务粒度越粗偏差风险越大。从工程经验看一次对话中让它完成一个相对独立的子任务然后马上验证结果效率和可靠性最高。9.5 团队协作时的约定如果你们团队多人使用 Codex建议统一AGENTS.md规范并在仓库中维护一份公共的 prompt 模板。这样可以避免不同成员对 Codex 的指令风格差异导致的项目风格分裂。同时凡是 Codex 生成的代码都要经过 review 再合入不要因为“AI 写的”就放松检查标准。10. 总结这篇文章从 Codex 的定位讲起解释了它为什么不是又一个聊天机器人而是一个能在终端执行任务的 AI 智能体。然后一步步完成了环境准备、安装、登录、接入第三方模型、实战示例和问题排查的完整闭环。到这里你已经具备了独立使用 Codex 的基础能力。我最后想强调一个观点Codex 这类工具的真正门槛不在安装命令而在于你能否建立一套和 AI 协同工作的工程规范。会用codex exec只是起点懂得用 AGENTS.md 约束它、用 Git 分支隔离它、用最小权限保护项目安全才是让 AI 编程助手真正融入开发流程的关键。建议你按顺序完成三个实践先在一个临时目录里跑通最简单的示例然后把它应用到你的个人项目中最后再尝试接入第三方模型和团队工作流。每一步验证通过后再进入下一步。这样即使遇到问题你也能清楚知道是环境问题、配置问题还是任务描述问题。Codex 还在快速迭代新的模型、新的命令、新的配置项会不断出现。所以保持看官方文档和更新日志的习惯比收藏任何教程都更可靠。希望这篇文章能帮你迈过最开始的这道坎真正开始体验 AI 智能体编程的干活方式。
如果你在 2026 年还只把 Codex 当作一个网页聊天框那很可能错过了它真正重要的变化。Codex 不是一个“给你出主意”的对话助手而是一个能在终端里直接读你的仓库、修改代码、执行命令、甚至把多步任务跑完的 AI 智能体。对普通开发者来说它带来的最大改变不是“回答得更准”而是“真的动手干活”。这篇文章面向的是第一次接触 Codex 的开发者尤其是被安装、登录、模型配置这几步劝退的小白。我会把完整链路拆开讲Codex 是什么、安装前要准备什么、如何安装、如何登录、如何接入 DeepSeek 等第三方模型、如何用命令行完成实际任务以及最常遇到的报错和排查思路。读完之后你能独立把 Codex 跑起来并且知道在真实项目里怎么用它、不该怎么用它。先给出一个明确判断Codex 最有价值的地方是它把 AI 编程从“对话式问答”推进到了“任务式执行”。这个差异决定了它的安装和使用方式也决定了你要用新的思路去驾驭它。1. Codex 是什么——它解决的是什么问题Codex 是 OpenAI 推出的编程智能体面向开发者的命令行工具。它和你在网页端打开的 ChatGPT 是两种形态也和 IDE 里的自动补全插件不一样。Codex 的运行场景是终端你给它一个任务描述它会自己规划步骤、读取项目文件、修改代码、执行测试命令然后给你一个结果。用一句话概括它是一个“能在你的电脑里真正干活的 AI 程序员”。要理解 Codex 的价值可以看一个典型场景。以前你写一个功能流程是在编辑器里写代码、切到终端跑测试、看到报错、回到编辑器继续改。每一步都需要你亲自操作。有了 Codex 之后你可以把“帮我实现一个用户注册接口包含参数校验、数据库存储和单元测试”这样一整条任务扔给它它会自己去创建文件、写代码、跑测试然后告诉你结果。你从“执行者”变成了“验收者”。从技术原理上看Codex 的核心能力来自两个方面。第一它能感知当前项目的工作区读取项目结构和文件内容而不是只靠你粘贴的代码片段。第二它具备工具调用能力可以在终端里执行命令、修改文件相当于把大模型的语言理解能力和操作系统的执行能力打通了。这两点加在一起才让“AI 自动完成开发任务”成为可能。这里有一个容易误解的地方Codex 并不只是“代码生成器”。它真正解决的是开发流程里的重复劳动和上下文切换成本。换句话说它降低的不是“写代码”的门槛而是“把代码跑通”的沟通成本。理解了这一点你就知道为什么它是一个命令行工具而不是又一个网页编辑器。2. Codex CLI 与传统 AI 编程工具的区别很多刚接触 Codex 的开发者会拿它和 GitHub Copilot、Cursor、ChatGPT 网页版做比较。为了帮你快速建立认知我用一张表来说明差异。工具运行形态核心能力适合场景GitHub CopilotIDE 插件代码补全、行内建议写代码时的即时辅助Cursor编辑器对话式代码修改、多文件编辑在图形界面里做 AI 编程ChatGPT 网页版网页问答、代码解释、代码生成学习、讨论、获取片段Codex CLI终端命令行读取仓库、执行命令、多步任务自动完成把 AI 接入工程流程让 AI 独立执行任务从上表能看出Codex 和 Copilot 不是同类工具。Copilot 更像你写代码时的一个“输入法”你写到哪里它补到哪里Codex 更像一个“结对程序员”你把任务交给它它自己去完成。两者的价值主张完全不同。Codex 和 Cursor 相比差异在交互层。Cursor 把所有能力封装在图形界面里优点是上手直观缺点是自动化程度和脚本化能力有限。Codex 在终端里运行天然适合和 Git、测试框架、CI/CD 流程配合也更容易嵌入到自动化脚本中。如果你有“用命令行完成任务”的习惯Codex 会更顺手。Codex 与 ChatGPT 网页版的区别就更明显了。网页版是“你问我答”你需要自己把代码复制来复制去Codex 直接操作你的本地文件系统不需要复制粘贴也不依赖打开浏览器。它解决的核心痛点是AI 给的代码片段和你的项目环境脱节。Codex 直接在你的项目里工作代码和上下文天然一致。不过我对 Codex 的判断不是“它一定比所有工具都好”。准确地说它是“AI 编程工具演进到智能体阶段的代表”。如果你的工作流高度依赖 IDE 的可视化操作Cursor 可能更适合你如果你想构建一个能自动完成工程的开发流程Codex CLI 才是更贴近未来方向的选择。3. 安装前的环境准备在安装 Codex 之前先确认你的电脑环境是否满足基本条件。Codex CLI 是一个 Node.js 命令行工具因此最核心的前置依赖是 Node.js 和 npm。先检查两个命令是否可以正常执行node -v npm -v如果两个命令都能输出版本号说明 Node.js 环境已经就绪。如果提示找不到命令需要先安装 Node.js。建议安装较新的 LTS 版本比如 Node.js 18 及以上因为较旧版本可能无法满足最新 Codex 的依赖要求。版本细节以你安装时的官方发布信息为准不要盲目追求最新的大版本LTS 版本在稳定性上更有保障。除了 Node.js 和 npm我还建议你提前准备好 Git。虽然 Codex 本身不强制依赖 Git但实际开发中你通常会在一个 Git 仓库里使用它。Codex 修改代码后你需要通过 Git 查看变更、对比差异、回滚操作。如果你还不熟悉 Git可以先用最简单的几条命令git init初始化仓库git diff查看改动git checkout .撤销改动。这些操作会在后面用到。另一个重要的准备项是账号。使用 Codex 需要有一个 ChatGPT 账号并且这个账号需要具备使用 Codex 的权限。这里需要特别说明从当前信息看Codex 面向的是付费订阅用户免费账号通常无法正常使用。具体的订阅档位和权限范围以 OpenAI 官方页面为准。提前准备好账号能让后面的登录步骤更顺畅。最后Codex 官方推荐在 macOS 和 Linux 系统上运行Windows 用户可以通过 WSL 获得更好的体验。这不是说 Windows 原生环境完全不行但 WSL 能减少很多文件路径和权限相关的兼容性问题。如果你在 Windows 上安装时遇到奇怪的问题先考虑切换 WSL 环境。环境准备完成后建议在终端里执行一次检查清单确认node -v、npm -v、git --version都能正常输出再确认自己已经拥有一个可以登录的 ChatGPT 账号。这样进入下一步时就不会被环境问题打断。4. Codex 安装完整步骤Codex CLI 的安装方式非常直接核心命令只有一条。在终端中执行npm install -g openai/codex这里使用了 npm 的全局安装参数-g意思是把 Codex 安装到系统全局环境中这样你在任何目录下都能直接执行codex命令。安装过程中npm 会自动下载 Codex 及其依赖包需要保持网络连接稳定。安装完成后验证是否成功codex --version如果能看到类似版本号的输出说明安装成功。如果提示codex不是内部或外部命令可能是全局安装路径没有被加入系统的 PATH 环境变量。在 macOS 和 Linux 上可以尝试重新加载终端配置比如执行source ~/.zshrc或source ~/.bashrc在 Windows WSL 中重启终端通常就能解决。接下来是更新 Codex 的命令。Codex 迭代速度很快新功能和新模型支持都会随版本更新发布。定期更新是一个好习惯npm update -g openai/codex这里提醒一下权限问题。在 Linux 或 macOS 上如果你使用系统自带的 Node.js全局安装有时会报 EACCES 权限错误。一个稳妥的解决方案是使用 Node 版本管理工具如 nvm来安装 Node.js这样全局安装路径就在你的用户目录下不需要 sudo 权限。从工程实践看用 nvm 管理 Node 环境比直接修改全局目录权限更安全也能避免后续出现其他权限问题。如果在安装过程中出现网络超时或下载失败多数情况是网络波动导致的。可以先执行npm cache clean --force清理缓存然后重试安装。如果仍然失败可以换一个 npm 镜像源。需要说明的是镜像源配置因地区和网络环境差异很大这里不展开具体镜像地址你可以根据实际网络情况选择可用的 npm 镜像。5. 登录与基础命令行用法安装完成之后还不能直接使用需要先登录你的 OpenAI 账号。在终端中执行codex login执行之后终端会显示一个授权链接并等待你在浏览器中完成登录和授权确认。整个过程和常见的“通过浏览器授权 CLI 工具”的流程一致。登录成功后Codex 会把凭据保存在本机之后一段时间内无需重复登录。如果你需要退出登录执行codex logout登录只是第一步真正要掌握的是 Codex 的命令行用法。下面几个命令是最常用的。第一是交互模式。直接运行codex会进入一个交互式终端界面你可以像聊天一样连续给 Codex 发指令它会根据对话上下文和你的项目文件执行任务。这个模式适合需要反复调整和确认的开发任务。第二是单次执行模式。使用codex exec后面跟上任务描述Codex 会执行一次任务后退出。例如codex exec 帮我写一个 Python 脚本输出 1 到 10 的平方这个模式适合明确、独立的任务也适合写进自动化脚本。第三是恢复会话模式。使用codex resume可以恢复上一次的交互会话。当你退出交互模式后Codex 会记住之前的对话状态你可以回到原来的上下文继续工作。如果你同时在多个项目里使用 Codex建议用codex resume -c 会话编号精确恢复指定会话避免加载错误上下文。第四是查看帮助。执行codex --help你会看到完整的命令列表和可用参数。花几分钟浏览一下帮助信息比直接搜索教程更能帮助你了解当前版本的实际能力因为不同版本的命令细节可能有差异。初次使用时我建议先在一个空白测试目录里运行codex随便给它一个简单任务比如“创建一个 README.md 文件并写一段欢迎文字”。这样能快速验证环境是否完全跑通同时让你熟悉 Codex 的工作流程而不必担心它误改你的真实项目。这里有一个关键认知Codex 会在你的工作区内执行命令和修改文件。它的能力不只是生成文本还涉及真实操作所以在执行任何任务前你都要清楚它“能干什么”和“你允许它干什么”。这个边界意识会在后面的最佳实践部分详细讲。6. Codex 接入 DeepSeek 等第三方模型很多开发者在安装完 Codex 后会遇到一个问题账号权限有限或者觉得官方模型的使用成本偏高。于是“Codex 接入 DeepSeek”成了搜索热度非常高的需求。好消息是Codex 支持配置第三方模型提供商你可以通过修改配置文件把底层模型切换为 DeepSeek 等 OpenAI 兼容接口的模型。先解释一下配置原理。Codex 的配置文件位于用户主目录下的~/.codex/config.toml。如果没有这个文件可以手动创建。配置文件中可以定义默认模型、模型提供商、API 请求地址和密钥环境变量。Codex 启动时会读取这些配置决定它调用哪个模型服务。一个常见的 DeepSeek 接入配置如下# 文件路径~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat在这份配置里model指定默认使用的模型名称model_provider指定使用哪个提供商配置。[model_providers.deepseek]下面的base_url是 DeepSeek 的 API 地址env_key告诉 Codex 从哪个环境变量读取 API Keywire_api表示接口协议类型。需要说明的是不同 Codex 版本对配置文件的支持程度可能有差异以上配置是最常见的写法。你在实际配置时应以当前版本的官方文档和社区资料为准。配置中引用了环境变量DEEPSEEK_API_KEY所以你要先获取 DeepSeek 的 API Key并把密钥设置到环境变量中。在 macOS 和 Linux 终端中可以临时设置export DEEPSEEK_API_KEY你的 API Key如果你希望配置持久生效可以把这行命令写入~/.zshrc或~/.bashrc。注意不要把 API Key 直接写进config.toml因为配置文件可能被同步到代码仓库存在泄露风险。使用环境变量是更安全的方式。配置完成后在终端中运行codex exec 你好请简单介绍一下你自己如果 Codex 能正常返回 DeepSeek 模型的回复说明接入成功。这里要提醒三点。第一DeepSeek 属于第三方模型服务具体能力和稳定性和官方模型有差异生产环境使用前一定要充分测试。第二使用第三方模型时Codex 的 API 调用方式和模型能力边界可能与官方模型不同某些高级功能不一定完全兼容。第三不要把你自己的 API Key 提交到公开仓库也不要在团队代码中明文展示密钥。正确做法是把密钥放在本机环境变量或密钥管理服务中按最小权限原则分配。7. 实战示例用 Codex 完成一个完整任务现在进入最关键的实操环节。我们用一个完整示例演示 Codex 从接收任务到交付结果的全过程。7.1 示例一创建 Python 脚本先创建一个测试目录并进入mkdir codex-demo cd codex-demo执行以下任务codex exec 在 Python 中写一个函数计算 Fibonacci 数列的第 n 项并为它写一个简单的单元测试Codex 会在这个目录中创建文件、编写函数和测试代码。任务结束后你可以查看目录结构ls -la你会发现目录中多出了 Python 脚本文件和测试文件。然后运行测试验证python -m pytest test_fibonacci.py如果看到测试通过的结果说明 Codex 完成的任务真实可用。7.2 示例二在交互模式中迭代修改单次执行适合一次性任务但真实的开发流程通常是多轮迭代的。这时可以使用交互模式codex进入交互模式后输入给 fibonacci 函数添加一个参数允许调用方指定起始值并更新测试Codex 会在当前对话上下文中理解之前的代码结构修改文件并更新测试。你可以继续追加指令再为这个函数补充类型注解并确认测试仍然全部通过这种交互式的迭代方式是 Codex 最有价值的使用形态。它像一个能记住上下文的结对程序员你可以不断提出新需求它会在已有代码基础上持续修改。7.3 示例三查看会话历史与恢复在交互模式中你可以使用/exit退出。之后之前的会话会被保存。查看会话历史codex resume --list恢复最近一次会话codex resume如果你在多个项目间切换记得使用-c参数指定会话编号避免在错误的项目里恢复错误上下文。运行到这里你已经完成了 Codex 从安装到实际使用的完整闭环。接下来要做的是在自己的真实项目中逐步增加使用场景写脚本、修 bug、补测试、重构代码。每次使用后用 Git 查看代码变更是否符合预期。8. 常见问题与排查思路在使用 Codex 的过程中报错是最容易劝退新手的一环。我把常见问题整理成排查表格你可以直接对照处理。问题现象可能原因排查方式解决方案codex命令找不到npm 全局目录未加入 PATH执行echo $PATH查看路径将 npm 全局目录加入 PATH或使用 nvm 管理 Node.js安装时提示 EACCES 权限错误当前用户对系统全局目录无写权限检查错误信息中的目录路径使用 nvm 安装 Node.js避免使用 sudo登录时提示认证失败或无法访问登录链接网络环境受限、登录链接打不开检查网络连通性换一个网络环境再试确保能正常访问 OpenAI 服务重新执行codex login提示 “model is not supported”当前账号没有权限使用该模型或模型名称拼写错误核对config.toml中的模型名检查账号订阅权限更换为当前账号支持且官方兼容的模型名称或检查订阅状态任务执行时输出与预期差异很大上下文不清晰、缺少 AGENTS.md 指引查看 Codex 读取了哪些文件、是否理解项目结构在项目根目录添加 AGENTS.md写清楚编码规范和约束提示本地网络相关错误例如cc switch local proxy failed while handling codex endpoint /responses终端无法正常访问 API 服务或本地网络中间设置有异常先检查能否正常访问目标 API 服务确认基础网络连通性排查本地网络环境和受限状态必要时切换网络环境再重新执行任务交互模式下回复卡顿或超时网络不稳定、任务过于复杂按 CtrlC 终止当前请求重新发起分拆任务缩小单次指令范围或在网络环境更稳定的情况下使用修改了错的文件工作区中没有锁定的修改范围用git status查看变更清单养成每次任务后检查 Git 变更的习惯必要时使用git checkout回滚这里我想重点展开一下“模型 is not supported”这个报错。出现这种情况有两种常见原因一种是账号权限不够也就是你当前的订阅档位不支持你指定的模型另一种是模型名称在配置中写错Codex 无法识别。排查时先检查config.toml中的model字段是否准确再确认账号权限。从社区反馈看很多新手在配置第三方模型时会把模型名写错少一个符号或多一个空格都会导致这个报错。另一个值得关注的是本地网络相关报错。这类报错信息中可能出现/responses之类的 endpoint 路径容易让人误以为是 Codex 配置错误。实际上这类报错的触发点通常在终端到 API 服务的链路。排查时先做一个基础检查确认你的网络能正常访问 API 服务。如果公司网络或本地网络有额外的限制你可以先切换网络环境测试确认是不是网络因素导致的。注意排查这类问题时不要擅自修改系统级网络配置首先要确认是否在自己的可控范围内再谨慎操作。最后补充一个容易被忽略的问题Codex 在交互模式中的历史会话会占用磁盘空间。如果你长时间高频使用可以定期执行codex resume --list查看会话列表删除不再需要的旧会话避免无意义的磁盘占用。9. 最佳实践与工程建议安装和跑通只是第一步真正让 Codex 在项目中发挥价值需要建立一套工程实践规范。9.1 用 AGENTS.md 约束 Codex 的行为Codex 支持读取项目根目录下的AGENTS.md文件把它当作项目的“行为准则”。你可以在这个文件里写清楚项目使用的技术栈、代码风格、测试命令、禁止修改的目录等信息。这样每次 Codex 进入项目都会自动读取这些规则行为会稳定很多。一个最小示例# 文件路径/项目根目录/AGENTS.md ## 项目说明 这是一个 Python FastAPI 项目使用 pytest 进行测试。 ## 编码规范 - 使用中文注释 - 遵循 PEP 8 风格 - 所有新增函数必须有类型注解 ## 常见命令 - 运行测试python -m pytest - 启动服务uvicorn main:app --reload ## 禁止事项 - 不要修改 config 目录下的生产配置 - 不要执行数据库迁移命令有了 AGENTS.mdCodex 的回答质量和任务完成度会显著提升因为它不再靠猜而是有明确的项目上下文。9.2 让 Codex 在独立分支上工作Codex 会修改代码、执行命令这就意味着它有破坏性操作的能力。最稳妥的做法是每次让 Codex 工作前先创建一个新的 Git 分支。这样如果 Codex 完成的任务不满意你可以删除分支重新开始完全不影响主分支代码。推荐流程git checkout -b feature/codex-task codex exec 实现用户注册接口 git diff检查git diff输出了哪些变更确认无误后再合并到主分支。这个习惯看似简单但能帮你避免大量因 AI 误改代码导致的问题。9.3 明确安全边界Codex 能够执行终端命令这意味着它有可能执行删除文件、安装依赖、修改配置等操作。在真实项目中你必须明确告诉它哪些操作不能做而且最好在 AGENTS.md 里写清楚。更稳妥的方式是把 Codex 的运行环境限定在隔离的测试环境中尤其是当你准备让它修改数据库结构、运行迁移、处理敏感数据时。API Key、数据库密码、云服务密钥这类敏感信息绝对不要出现在 Codex 的输入提示词中也不要让它读取包含密钥的文件。你要意识到AI 工具的便利性和它的权限边界是一体两面的越是能帮你做事的工具越要谨慎控制它的权限。9.4 控制单次任务粒度前面实战示例中我把任务拆分成了“写函数—改参数—补注解”三个步骤这是有意为之。Codex 虽然在多步任务上表现不错但任务粒度越粗偏差风险越大。从工程经验看一次对话中让它完成一个相对独立的子任务然后马上验证结果效率和可靠性最高。9.5 团队协作时的约定如果你们团队多人使用 Codex建议统一AGENTS.md规范并在仓库中维护一份公共的 prompt 模板。这样可以避免不同成员对 Codex 的指令风格差异导致的项目风格分裂。同时凡是 Codex 生成的代码都要经过 review 再合入不要因为“AI 写的”就放松检查标准。10. 总结这篇文章从 Codex 的定位讲起解释了它为什么不是又一个聊天机器人而是一个能在终端执行任务的 AI 智能体。然后一步步完成了环境准备、安装、登录、接入第三方模型、实战示例和问题排查的完整闭环。到这里你已经具备了独立使用 Codex 的基础能力。我最后想强调一个观点Codex 这类工具的真正门槛不在安装命令而在于你能否建立一套和 AI 协同工作的工程规范。会用codex exec只是起点懂得用 AGENTS.md 约束它、用 Git 分支隔离它、用最小权限保护项目安全才是让 AI 编程助手真正融入开发流程的关键。建议你按顺序完成三个实践先在一个临时目录里跑通最简单的示例然后把它应用到你的个人项目中最后再尝试接入第三方模型和团队工作流。每一步验证通过后再进入下一步。这样即使遇到问题你也能清楚知道是环境问题、配置问题还是任务描述问题。Codex 还在快速迭代新的模型、新的命令、新的配置项会不断出现。所以保持看官方文档和更新日志的习惯比收藏任何教程都更可靠。希望这篇文章能帮你迈过最开始的这道坎真正开始体验 AI 智能体编程的干活方式。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
