如果你最近在看 AI 编程工具大概率已经被 Codex 刷屏过。但打开各种教程你会看到两种完全相反的叙事一边说它是“最强 AI 助手”一边又说它不过是个终端聊天框。真实情况是什么我的判断是Codex 不是又一个帮你生成代码片的补全工具而是一个真正站在终端里的 AI 工程师。它能读你的项目修改文件执行命令跑测试然后把结果直接落地到工作区。这个变化看起来只是“多写点代码”实际上把 AI 编程从“你问我答”推向了“你派活、它干活、你验收”的新阶段。这篇文章是一份面向新手的保姆级教程规划了从零开始的完整路径环境准备、安装登录、第一次跑通任务、进阶配置、常见故障排查和工程建议。就算你之前没怎么用过命令行 AI 工具也可以照着做。我会尽量把原理讲清楚因为只抄命令不理解原因遇到问题还是不会排查。文中有大量代码和配置示例建议先收藏再照着操作。1. Codex 到底解决了什么问题先回到一个最基础的问题为什么有了 ChatGPT、Copilot还需要 Codex传统 AI 编程助手的典型工作流是你把需求发给 AI它给你一段代码你复制回编辑器然后自己执行、自己调试、自己看报错。这个过程其实没有把 AI 放进真实的工程闭环里它更像一个“高级搜索框”。遇到简单的函数生成没问题但遇到跨文件修改、需要跑测试确认、要搜索代码库理解上下文的任务时体验就很割裂。Codex 把重点放在了“任务执行”上。它不只是生成代码而是在一个受限环境中替你完成一个完整的开发动作读取项目文件、定位问题、修改代码、执行命令、根据命令行输出决定下一步操作。它真正降低的是三类成本上下文切换成本不用反复在聊天窗口、编辑器、终端之间复制粘贴。流程熟悉成本构建命令、测试命令、格式化命令这些项目细节它能从项目文件和指令文档中自己学习。重复劳动成本批量重命名、补测试、修报错信息这类机械任务可以直接交给它。但这不意味着 Codex 适合所有人。它最适合的场景是你了解自己的项目能看懂它改了什么能判断它做的事是否符合预期。如果你完全看不懂代码或者不愿意做代码审查那任何 AI 编程工具都救不了你反而可能把项目弄得更乱。换句话说Codex 给你提效但不替你背锅。它适合“会验收”的工程师不适合“撒手不管”的甩手掌柜。2. Codex 的核心概念模型、沙箱、审批、AGENTS.md在安装之前有几个概念必须提前建立认知。很多时候排查问题卡住不是因为命令写错而是没理解这些机制的设计意图。2.1 终端 AgentCodex 的完整形态是一个运行在终端里的 AI Agent。“Agent”这个词听起来玄乎实际含义是AI 不只是回答你它会按你给的最终目标自己规划步骤调用工具观察结果再决定下一步。在 Codex 里它能做的操作包括读取项目目录中的文件。创建、修改、删除文件。执行 shell 命令。运行测试并读取结果。在遇到需要用户判断的问题时停下来询问。这种“能操作真实环境”的能力和普通聊天工具完全不同也是风险所在。所以 Codex 设计了两道安全机制沙箱和审批。2.2 沙箱与审批机制沙箱Sandbox是 Codex 的运行环境边界。你可以把它理解成给 AI 划了一个“活动范围”。常见沙箱模式包括只读模式AI 可以读文件、看代码但不能修改任何文件。工作区写模式AI 可以修改当前项目范围内的文件但不能随便碰项目之外的系统文件。完全访问模式AI 能执行的范围更广适合需要安装依赖、修改全局配置等任务但风险也更高。审批Approval则是你给 AI 上的一道“人工确认阀门”。Codex 在执行关键操作前会先告诉它打算做什么等你点头后继续。审批策略可以设置为全部需要确认、失败时确认、从不确认。我把这两个机制理解为“自动驾驶的 L2/L3”AI 可以自己开但你必须保留方向盘控制权出事时你负责。2.3 AGENTS.md给 AI 的项目说明书AGENTS.md 是 Codex 会自动读取的项目级指令文件通常放在项目根目录。它的作用类似“入职手册”告诉新来的 AI 工程师这个项目的结构是什么、构建命令是什么、代码规范是什么、有哪些需要注意的坑。以前你用 AI 辅助编程每次都要在对话里重复“这是一个 Spring Boot 项目”“测试用 Maven 跑”“代码风格是 xxx”。有了 AGENTS.md这些上下文可以沉淀成文件每次启动 Codex 它都能自动读取。这不是 Codex 独有的概念很多 Agent 工具都有类似的设计。但它的重要性经常被新手低估不写 AGENTS.mdCodex 也能用但效果随机写完它Codex 像是熟悉你项目的“老同事”。2.4 交互会话与非交互执行Codex 有两种主流使用方式交互式会话在项目目录运行codex进入一个终端对话界面你一句它一步适合边聊边改。非交互执行用codex exec 任务描述让它一次性完成指定任务适合脚本化、批处理、CI 场景。后面实操部分我会先带你跑通交互式会话再介绍非交互执行。3. 环境准备与前置条件开始安装前先检查你的环境是否满足基本条件。越早发现问题后面越少折腾。3.1 操作系统与终端Codex CLI 是跨平台的Windows、macOS、Linux 都可以使用。Windows 用户建议使用 PowerShell 或 Windows Terminal。如果你想获得更接近 Linux 的体验也可以使用 WSL但这不是必须的。无论用哪种终端请确保你能熟练执行普通命令。3.2 Node.js 与 npmCodex 官方推荐通过 Node.js 生态的包管理器安装。因此你需要先安装 Node.js 和 npm。建议安装 Node.js 18 或更高版本。具体版本要求以官方 README 和当时的最新版本为准但一般来说保持 Node.js 在 LTS 版本不会错。打开终端执行下面命令验证node -v npm -v如果两个命令都能输出版本号说明环境就绪。如果提示“node 不是内部或外部命令”或“command not found”说明 Node.js 没有装好或没有加入系统 PATH。3.3 账号与 API Key使用 Codex 需要你有合法的 OpenAI 账号。登录方式通常有两种ChatGPT 账号登录适合个人日常使用流程简单。OpenAI API Key适合脚本化调用或企业级场景。无论用哪种都请确保你使用的是自己的账号和合法的接入方式并且已经了解账号对应的服务条款。3.4 网络环境Codex 在登录和请求模型服务时需要能够正常访问 OpenAI 官方服务。如果你的网络环境无法访问官方域名安装后也会在登录或请求阶段报错。这里要特别提醒不要在来路不明的第三方渠道下载所谓的“Codex 安装包”或“配置一键包”。这类文件无法保证安全性轻则配置被篡改重则账号信息泄露。官方工具链完全可以通过正规包管理器安装没必要冒这个风险。3.5 Git 仓库强烈建议你在一个 Git 仓库中做首次实验。原因有两个Codex 会利用 Git 状态判断项目内容和变更。如果 Codex 改坏了代码你可以直接git checkout回滚。这应该是所有 AI Agent 实验的第一原则永远给它一块可以重置的试验田。4. 安装 Codex 与登录配置环境准备好之后接下来就是正式安装了。4.1 通过 npm 安装全局安装命令很简单npm install -g openai/codex安装完成后验证版本codex --version如果输出版本号说明安装成功。Linux 或 macOS 上如果遇到权限问题优先考虑使用 nvm 管理 Node.js 环境不建议直接用sudo npm install -g因为 sudo 会绕过 npm 对全局目录的权限管理后续升级和卸载会变得很混乱。Windows 上如果codex命令无法识别通常是因为 npm 全局安装路径没有加入系统 PATH。可以通过npm config get prefix查看全局安装目录然后把它加入 PATH。4.2 登录 Codex安装完成后在终端执行codex login这个命令通常会打开浏览器引导你完成账号授权。登录成功后终端会提示登录完成并生成本地认证文件。如果你更倾向于使用 API Key可以通过环境变量方式配置export OPENAI_API_KEYsk-你的密钥注意这个环境变量只在当前终端窗口生效。如果你希望长期生效可以把它写入 shell 的配置文件例如~/.bashrc或~/.zshrc。但不要把 API Key 写进项目的版本控制文件里。4.3 初始化项目目录登录成功后找个空目录来做实验。mkdir codex-demo cd codex-demo git init然后执行codex init这个命令会生成一个AGENTS.md文件。你可以先打开它看一眼默认内容通常是一些基础说明。后面我们会手动补充内容。到这里一个最小可用的 Codex 环境就搭好了。接下来就可以让它干活了。5. 第一次使用让 Codex 完成一个最小任务很多人第一次用 Codex 时会直接扔一个大需求过去比如“帮我写个电商系统”。这种任务不仅大还模糊Codex 大概率会生成一堆并不符合你预期的代码。真正合理的用法是拆任务一次只做一件具体且可验证的事。我们先用一个 Python 示例跑通全流程。5.1 编写 AGENTS.md在codex-demo目录下把AGENTS.md改成如下内容# AGENTS.md ## 项目说明 这是一个用于演示 Codex 基础用法的 Python 项目。 ## 目录结构 - 根目录存放 Python 源文件 - tests/ 目录存放测试文件 ## 常用命令 - 运行测试python -m pytest tests/这段内容很简单但它告诉 Codex项目是什么、文件放哪、测试怎么跑。这样 Codex 在后续执行时就不用瞎猜了。5.2 下发任务在项目根目录启动交互式会话codex进入对话界面后输入以下任务请在当前项目里创建一个 quick_sort.py 文件实现快速排序。 然后在 tests/ 目录下创建 test_quick_sort.py写三个测试用例。 最后运行 python -m pytest tests/ 确认测试全部通过。这里的关键不是让 Codex 写快排而是让它演示完整的工作流创建文件、写测试、执行命令、根据结果调整。在 Codex 执行过程中你需要做两件事观察它给出的计划和每一步操作。在弹出的审批请求前确认它要做的事是否符合预期。如果它某个操作看着不对劲可以直接拒绝或纠正。5.3 查看 Codex 生成的代码任务执行完成后打开quick_sort.py看看。代码不一定要多惊艳但你应该能理解它是否完成了需求是否遵循了 AGENTS.md 里约定的目录结构是否真的生成了可运行的测试。再打开tests/test_quick_sort.py检查测试用例是否覆盖了空数组、单元素、乱序数组这些基本场景。5.4 手动验证结果不要完全信任 Codex 的“全部通过”汇报。自己也在终端跑一次python -m pytest tests/ -v如果输出显示 3 个测试全部通过那么这个最小任务就算完整跑通了。如果失败看是环境问题还是生成代码问题这就是你开始接触 Codex 排错的第一步。6. 进阶配置config.toml 与 AGENTS.md跑通最小流程后你会开始在意一些实际问题怎么切换模型怎么控制审批频率怎么让 Codex 在多个项目里表现稳定答案都在进阶配置里。6.1 Codex 的配置文件Codex 的配置文件通常位于用户目录下的~/.codex/config.toml。你可以用文本编辑器打开或创建它。一个典型的最小配置如下# 文件路径~/.codex/config.toml # 模型名称具体值以官方文档和你的账号权限为准 # model gpt-5-codex # 模型服务方默认是 openai model_provider openai # 沙箱模式read-only / workspace-write / danger-full-access sandbox_mode workspace-write # 审批策略never / on-failure / always approval_policy on-failure注意model字段的具体值我没有写死也不会建议你照抄网上某个模型的名称。原因很简单Codex 的可用模型会随着账号类型、订阅方案和官方版本变动。如果你在网上下载了一个教程里面写着model xxx而你账号里根本没有这个模型启动时就会报 “model is not supported” 之类的错误。排查这类问题最稳的方式是看官方文档和当前版本的codex --help输出而不是盲目修改配置。6.2 审批策略怎么选三个审批策略的适用场景never适合完全信任的、纯脚本化的流水线但风险最高。on-failure推荐日常使用。Codex 能自己玩得转时不用打扰你碰到命令失败、异常状况时再来请示。always适合刚上手或操作敏感项目时确保每一步都清楚。我的建议新手先用always跑几轮观察 Codex 的行为模式熟悉之后再切换到on-failure。不要一上来就用 never——那样等于让一个不认识的人直接改你的服务器。6.3 沙箱模式的边界如果你发现 Codex 说“无法写入文件”先检查是否处于只读read-only沙箱模式。如果只是在当前项目里改代码workspace-write就足够了。danger-full-access只有在需要安装全局依赖、修改系统级配置时才用而且用完应该立刻改回来。6.4 让 AGENTS.md 成为团队资产AGENTS.md 不是写过一次就完事的。随着项目发展建议持续维护。一个好的 AGENTS.md 通常包含项目简介和架构图。常用命令启动、测试、构建、格式化。代码风格约定。容易出现的问题和规避方式。目录结构和重要模块说明。当团队里所有人都用同一个 Codex 时AGENTS.md 就是团队知识库的一部分。它甚至比很多过时的 README 文档更有价值因为 AI 每次执行前都会重新读取。7. 高级玩法MCP 与自定义模型接入当你把 Codex 当作日常工具后可能不满足于它只能在项目里读写文件。你希望它查数据库、查工单系统、操作内部平台。这时候就要用到 MCP。7.1 MCP 是什么MCP全称 Model Context Protocol是一套让 AI Agent 连接外部工具和数据源的标准化协议。你可以把它理解成 AI 世界的“USB 接口”不同工具只要实现 MCP 协议就能被 AI 动态调用。没有 MCP 时Codex 只能操作文件系统和执行命令。有了 MCP它可以查数据库 schema、读监控指标、调内部 API 等能力边界一下子扩大了很多。7.2 如何配置一个 MCP ServerCodex 的配置文件中可以通过mcp_servers字段声明 MCP 服务。常见结构如下# 文件路径~/.codex/config.toml [mcp_servers.my-tool] command node args [/absolute/path/to/your/mcp-server.js] env { MY_SERVICE_TOKEN your-token }command启动 MCP Server 的可执行文件。args传给程序的参数通常是脚本路径。env需要的环境变量。具体 MCP Server 的安装和启动命令以该 Server 提供方文档为准。不要盲目抄配置每个工具的args和env都不同。7.3 自定义模型接口的限度与风险社区里经常有人讨论“Codex 接入其他模型服务”。这个需求可以理解因为不同模型在不同任务上的表现有差异。Codex 在理论上支持 OpenAI 兼容的服务接口配置你可以在配置里修改model_provider和模型名。但这里必须给出冷静提醒不是所有模型都兼容 Codex 的完整工具调用机制。就算接口格式一样底层能力不同实际执行效果可能天差地别。不要为了省事去使用非官方渠道的所谓“中转”或“共享”接口。这类渠道不稳定而且你的代码、业务上下文都可能暴露给不可控的第三方。如果确实需要在企业内部接入自研模型服务请先在测试环境验证兼容性并咨询你自己的服务商和服务条款。AI 编程工具正在成为开发者的“第二双手”它能干活的前提是安全、可控、可追溯。自定义服务可以尝试但必须在合法合规、自己可控的范围内。8. 常见问题与排查思路新手使用 Codex最常遇到的问题其实高度集中。下面这个表格基本覆盖了安装、启动、运行三个阶段的高频故障。问题现象可能原因排查方式解决方案npm install -g openai/codex报权限错误Linux/macOS 全局目录无写权限运行npm config get prefix查看全局目录优先使用 nvm 安装 Node.js避免直接 sudo npm installcodex不是内部或外部命令npm 全局 bin 目录不在 PATH使用npm config get prefix查看路径将prefix/bin加入系统 PATH 后重启终端codex login打不开浏览器终端环境或系统设置导致浏览器调用失败观察终端是否有输出授权链接复制终端中的授权链接到浏览器手动访问启动 Codex 后提示某个模型不受支持配置了不存在的模型名例如手误填写gpt-5.6-sol打开~/.codex/config.toml检查model字段改为官方文档支持的模型名或删除该字段使用默认模型错误信息形如cc switch local proxy failed while handling codex endpoint /responses本地某个流量转发组件接管了 Codex 的 HTTP 请求但没有正确转发到真实服务的/responses接口常见于第三方配置切换工具检查是否安装了第三方配置切换工具检查相关配置是否指向本机地址停止该本地转发进程或检查其配置是否正确确保 Codex 能直连官方服务Codex 无法写入文件或目录沙箱模式为 read-only查看当前会话提示的沙箱模式根据需求切换为workspace-write或danger-full-access执行python -m pytest报模块找不到Python 未安装或虚拟环境未激活运行python --version查看当前环境配置 AGENTS.md 写明 Python 环境建议使用 venvCodex 生成的代码风格和项目不一致AGENTS.md 中缺少代码风格约束查看 AGENTS.md 是否包含规范说明在 AGENTS.md 中补充缩进、命名、注释风格等约定任务执行到一半窗口卡住网络连接不稳定或模型服务端响应超时查看终端日志是否有超时记录检查网络稳定性稍后重试任务过长时拆分成多个小任务Windows 终端中文输出乱码终端编码和字符集不匹配在终端执行chcp 65001切换 UTF-8 编码将终端默认编码改为 UTF-8或在 AGENTS.md 中说明输出编码要求表格里的每个问题排查时都遵循一个顺序先看错误信息再看配置最后看网络。很多新手一遇到错误就想去重新安装其实重新安装往往解决不了配置问题。如果你遇到错误信息里包含endpoint /responses请记住这通常是“请求发出去了但收到的响应不是 Codex 期望的结构”造成的。原因要么是服务地址配错要么是某个本地流量转发组件没有正确工作。把注意力放在请求路径上而不是代码逻辑。9. 最佳实践与工程建议工具学完最重要的是形成一套稳定的使用习惯。以下建议不是空话每一项都是在真实工程里踩过坑之后总结出来的。9.1 一次只做一件事给 Codex 下发任务时尽量拆成小粒度。比如“修复 A 文件中的 bug并补一个回归测试”就比“优化一下整个项目的性能”可控得多。任务越小预期越明确Codex 越不容易自由发挥你审查代码的成本也越低。这就像带新人你不能让一个实习生第一天就负责“把系统做好”你要给他明确的小目标和验收标准。9.2 每次实验都在 Git 分支上进行无论 Codex 多么强大它都可能改坏你的代码。建议每次让它干活前先创建一个分支git checkout -b codex/task-fix-login即使 Codex 把工作区改得一团糟你也能随时切回干净状态。这比依靠你的记忆去撤销文件修改可靠一万倍。9.3 把敏感信息挡在 Prompt 外不要把数据库密码、API Token、私钥通过对话告诉 Codex。有些操作看似需要凭据比如让它连数据库你应该优先考虑使用环境变量或 MCP Server 自身的凭据管理机制而不是把密钥直接打字进 prompt。AI Agent 的日志、会话记录都可能被保留敏感信息暴露风险是真实存在的。9.4 维护 AGENTS.md 就像维护代码每次 Codex 因为缺少项目上下文而做错事就是一个提醒AGENTS.md 该更新了。我建议把 AGENTS.md 写进项目的评审流程。当项目结构发生重大变化时同步更新它。你会发现AGENTS.md 越完善Codex 的第一次成功率越高你需要做的返工越少。9.5 警惕“全自动模式”Codex 提供全自动能力也就是你只下命令它自动执行、自动批准、自动修改。听起来很爽但在生产环境里这是核武器级别的危险操作。如果你的项目涉及生产数据库、线上服务、用户数据千万不要用全自动模式直接操作。先在人肉可控的沙箱环境里跑通确认 Codex 的计划和你的预期一致再考虑扩大权限。这不能完全替代人工审查但可以减少低级错误。9.6 不要盲目跟风“最新版本”每次 Codex 发新版本官方都会写 Changelog。你可以关注但不要一看到新版本就升级生产环境。升级前先在自己常用的项目里跑一遍典型任务确认没有行为变化和兼容性问题。工具升级的黄金法则是新版本要先证明自己而不是让生产环境当小白鼠。9.7 关注 Skill 与结构化指令如果你在社区看到 Codex Skill、SKILL.md 这类词本质上是在 AGENTS.md 之外把“告诉 AI 怎么做某个任务”的经验封装成可复用的技能包。它就像一个函数输入任务目标输出一整套操作范式。等你对 Codex 的使用越来越熟练后可以尝试把重复性的复杂任务整理成 Skill。这样团队里的每个人都能通过同一套高质量指令获得稳定的结果。具体语法以官方文档为准但思想值得先理解把优秀的 Agent 用法沉淀成团队资产而不是只保存在个人脑子里。10. 总结与后续学习方向Codex 的价值不在“会写代码”而在“会执行任务”。安装它只需一条命令真正拉开差距的是你如何理解沙箱、审批、AGENTS.md 这些机制以及你能否把任务拆解得足够清晰。如果你今天只记住一件事那就记这一条每次让 Codex 干活之前先写清楚 AGENTS.md开好 Git 分支想清楚验收标准。这样就算 AI 犯错了你也能低成本地恢复和修正。下一步建议你按文章顺序做一遍最小实验安装 Codex登录账号初始化目录让它完成一个带测试的小任务再手动验证结果。这一步完整跑通后你可以继续研究 MCP、Skill、非交互执行模式逐渐把 Codex 融入自己的真实工作流。Codex 这类工具过去是被动回答问题现在是主动操作环境。它们正在重塑开发者的工作方式。对普通开发者来说现在正是学会使用它的好时机等它真正成为团队标配时你已经比身边的人多了一轮完整的实战经验。