Codex 怎么用？从安装到跑通第一个任务的全流程教程
Codex 是 OpenAI 推出的命令行 AI 编程代理（coding agent）：你在项目目录里用自然语言描述需求，它会自己读代码、改文件、跑命令，把任务端到端做完。它和 Cursor 这类”编辑器里补全”的工具不同，更像一个住在终端里、会自己动手的助手。本文带你从零跑通第一个任务。
Codex 和 Cursor、Claude Code 有什么不一样
一句话区分这三类工具：
- Cursor：AI 原生的代码编辑器，你在 IDE 里边写边让 AI 补全、改写，手感最好。
- Codex / Claude Code：终端里的代理，你下指令、它自己读写文件跑命令，适合大改动和自动化任务。
Codex 的特点是和 OpenAI 的模型深度协同、开源、可跑在终端也可跑在云端。如果你已经在用 ChatGPT，套餐里通常就包含 Codex 的使用额度，上手成本低。想横向比较，可看 Claude Code vs Codex 怎么选。
这三类工具不是非此即彼：改一行样式、调一个函数签名，Cursor 的行内补全更快；但”把模块从 REST 改成 GraphQL，顺带把测试也补上”这种横跨多文件的活，代理式工具更省心。判断标准很简单：脑子里已清楚每一行怎么改，用 Cursor；只清楚”要达到什么效果”、具体怎么改懒得想，交给 Codex。
第一步：安装 Codex
Codex 的命令行版本通过 npm 全局安装，先确保本机装了 Node.js（建议 18 以上）：
npm install -g @openai/codex
macOS 用户也可以用 Homebrew：brew install codex。装完在终端输入 codex --version 能打印版本号，就说明装好了。Codex 同时提供 VS Code 扩展，习惯图形界面的可以在编辑器里用，核心能力一致。
装完之后花两分钟看一眼配置文件。Codex 的全局配置在 ~/.codex/config.toml，首次运行会自动生成一个空壳，你可以在里面提前定好几件事：
# ~/.codex/config.toml
model = "gpt-5-codex" # 默认用哪个模型，具体型号以官方最新列表为准
approval_policy = "on-request" # 默认审批策略
sandbox_mode = "workspace-write"
这样团队可以把约定好的 config.toml 分发给所有人，默认行为一致，不用每次手动加参数。如果 npm install -g 报权限错误（常见于 Linux 没配好 npm 全局目录），别用 sudo 硬来，先执行 npm config set prefix ~/.npm-global 挪目录，再把 ~/.npm-global/bin 加进 PATH。
第二步：登录——用 ChatGPT 账号还是 API Key
Codex 有两种认证方式，按你的情况选：
- 用 ChatGPT 账号登录（推荐多数人）：在终端运行
codex，按提示用浏览器登录 ChatGPT。Plus / Pro / Team 等付费套餐通常已包含 Codex 额度，不用额外按量付费，对个人开发者最划算。 - 用 OpenAI API Key：把密钥配进环境变量，按 token 计费。适合需要精细控制用量、或接入自动化流程的场景。
提示：两种方式的额度与计费规则会调整，以 OpenAI 官方说明为准。想搞清套餐里的额度怎么算，可看Codex 用量与计费（规划中）。
给你个更实操的判断：个人日常开发先用 ChatGPT 账号登录；团队做 CI 自动化（比如流水线里跑”自动修 lint 报错”）必须用 API Key，脚本没法弹浏览器登录。两种方式互不冲突，可以同时用。
第三步：跑通第一个任务
进入你的项目目录，直接运行：
cd your-project
codex
然后像对同事交代任务一样描述需求，例如：
给这个项目加一个 README，说明它是做什么的、怎么安装和运行。
Codex 会先读懂项目结构，再提出修改方案、生成文件内容，并请求你确认。确认后它落盘、必要时跑命令验证。整个过程你只需要审阅它的每一步，而不用自己敲代码——这就是”代理式”编程的核心体验。
新手建议第一个任务挑小而明确的：写 README、加一个工具函数、修一个小 bug。先建立信任，再交给它更大的活。
举个真实场景：修一个”分页组件数据为空时报错”的小 bug，描述现象——「列表页接口返回空数组时会白屏，定位并修好，加一个单测」；Codex 搜索代码后列出根因（比如没做 data.length === 0 兜底）；给方案后等你确认，别偷懒跳过；确认后落盘、跑测试，把结果贴回来。
整个过程你没敲一行代码，但每一步都在你的掌控之下。如果你想跳过交互式确认，直接用一条命令跑完整个任务（常用于脚本化、CI 里），可以用非交互模式：
codex exec "修复分页组件空数据报错，并补充单测"
exec 模式适合你已经充分信任某类任务、想批量处理时用，比如”给所有 API 路由加统一的错误处理”这种重复性强、风险可控的活；第一次接触陌生代码库时，还是老老实实用交互模式，边看边确认。
三种审批模式：在”放手”和”安全”之间平衡
代理会自己改文件、跑命令，所以 Codex 用审批模式控制它的权限边界，通常分三档：
- 只读 / 建议模式：它只读代码、给方案，每一步改动都要你点确认。最安全，适合不熟悉的项目或重要代码。
- 自动改文件：允许它在工作区内自动改文件，但跑命令仍需确认。日常开发的平衡点。
- 全自动：改文件、跑命令都不打断你，适合放进沙箱跑一个完整任务。务必在干净的 git 分支或隔离环境里用，方便随时回滚。
经验法则：越不熟悉的代码，权限给得越收。先用建议模式看它靠不靠谱，再逐步放权。
这三档在命令行里对应的是 --approval-policy 和 --sandbox 两个参数（或者你也可以把它们写死在前面提到的 config.toml 里），实际用起来大概是这样：
# 只读建议模式：每一步都要你点头
codex --approval-policy on-request
# 自动改文件、跑命令仍需确认（日常开发默认档）
codex --approval-policy on-failure --sandbox workspace-write
# 全自动：改文件、跑命令都不打断，务必配合隔离环境
codex --approval-policy never --sandbox danger-full-access
--sandbox 控制它能碰的范围：read-only 只能看，workspace-write 只能改当前工作区，danger-full-access 才真正解除限制。日常几乎不需要 danger-full-access，workspace-write 配合 git 分支已能覆盖大多数场景；真要全自动跑，最好丢进 Docker 容器，跑完就销毁。
审批模式可以中途切换：先用建议模式看它靠不靠谱，再按提示切到自动改文件模式，不用重启会话。
用 AGENTS.md 给 Codex 立规矩
想让 Codex 每次都按你的项目规范干活，在项目根目录建一个 AGENTS.md 文件，把”项目约定”写进去，例如：
# 项目约定
- 包管理用 pnpm，不要用 npm
- 组件放在 src/components，用 TypeScript
- 提交信息用中文，遵循 Conventional Commits
- 改完代码后跑 `pnpm test` 确认通过
Codex 会在工作时自动读取并遵守这些规则。这相当于把”新人入职文档”一次写好，省去每次重复交代——和 Claude Code 的 CLAUDE.md（规划中）是同一个思路。
AGENTS.md 不是只能放一个。Codex 支持在 monorepo 里的子目录分别放一份，比如根目录写全局规范，packages/api/AGENTS.md 再写包特有的约定（比如”接口返回统一走 Result<T> 封装”）。子目录规则可以覆盖或补充根目录规则，前后端团队各自维护自己那份，互不干扰。
写 AGENTS.md 时有个容易踩的坑：别写成一堆正确的废话，比如”代码要写得整洁”这种没有可执行标准的话，代理没法照着做。真正有效的写法是给出具体、可验证的规则，例如：
# 项目约定
- 包管理用 pnpm，不要用 npm 或 yarn
- 新增组件放在 src/components/{ComponentName}/index.tsx
- 所有对外暴露的函数必须写 JSDoc 注释
- 提交信息格式：`feat(scope): 描述`，遵循 Conventional Commits
- 改完代码后必须跑 `pnpm lint && pnpm test`，两个都通过才算完成
- 禁止直接操作数据库连接，统一走 src/db/client.ts 里的封装
每一条都能让 Codex 明确判断”做到了没有”。这份文件值得持续更新，一旦发现它踩了团队的隐性约定，就把约定显式写进去，下次不会再犯。
新手常见坑
- 目录开错了：一定要
cd进项目根目录再启动，否则 Codex 看不到完整代码，改得驴唇不对马嘴。 - 第一次就上全自动：还没建立信任就全自动放权，容易改乱。先用建议模式。
- 不开 git：代理会改文件，用 git 管理项目才能放心地”先让它改、不行就回滚”。这是用任何代理工具的前提。
- 需求太笼统：「优化一下这个项目」这种指令它很难做好。把任务拆小、说清楚目标和验收标准，效果立刻不同。
- 国内网络问题：连不上时优先排查网络代理，具体见 Codex 安装失败/连不上排查（规划中）。
- 上下文太大等半天：项目大、文件多时首次分析要花更长时间，别以为卡死了强行中断；先在需求里点明相关文件路径能明显提速。
- 忽略执行日志：Codex 跑完会贴出命令和结果，别只看最终代码，日志里常藏着”测试其实是跳过而不是通过”这类信息。
- 在生产分支上直接跑全自动：别在
main分支上开全自动权限，先切临时分支，跑完看 diff 再决定合不合并。
常见问题
Codex 收费吗？ 如果你已订阅 ChatGPT 付费套餐，套餐里通常含 Codex 额度，无需额外付费；也可以用 API Key 按量计费。具体额度以官方为准。
Codex 支持中文吗？ 支持。你完全可以用中文描述需求、写 AGENTS.md，它也能用中文回复和写注释。
Codex 能接国产模型吗？ Codex 主要与 OpenAI 模型协同。如果你想用 DeepSeek、Kimi 等国产模型做代理式编程，Claude Code 接入国产模型的方案更成熟。
和 Cursor 冲突吗？ 不冲突，很多人两个一起用：小步迭代用 Cursor，大改动和自动化任务交给 Codex。
任务跑到一半想改需求怎么办？ 直接在同一会话里说清楚新要求，不用中断重来；如果已经改了不该改的文件，先手动 git checkout 回退，再重新描述一次。
掌握 Codex 只是 AI 编程的起点。想系统学会”用 AI 从零做出能上线的产品”，从工具到工程化少走弯路？
👉 看看我们的 AI 编程实战体系课，或先逛逛 AI 编程教程大全 把基本功打扎实。