Codex CLI完全指南：终端AI Agent从安装到实战-育师

最近几周，Codex CLI 这个词在开发者圈子里出现频率极高。我一个做了多年全栈的老朋友说了一句让我印象很深的话："以前 Cursor 帮我少打字，现在 Codex 帮我少干活。" 用了几周之后，我基本认同这个判断。Codex CLI 是 OpenAl 开源的终端 Coding Agent，它会自己读项目文件、改代码、跑测试、看报错、继续修，直到把任务干完。这篇文章不打算把官方文档翻译一遍，而是把我真实用下来的安装方式、配置细节、核心命令、完整实战场景，以及那些文档里不会写清楚的坑，一次性讲透。适合用惯了 IDE 里的 AI 补全、但还没真正把"AI 打工"落到日常流程中的开发者。

先纠正一个常见的混游：现在说的 Codex，是 2025 年开源的 Codex CLI，一个跑在终端里的 agent，不是早年那个只做代码补全的 Codex 模型，也不是某些编辑器功能里挂名的"Codex 模式"。两者的形态和玩法完全不同。看完这篇，你应该能直接用 codex 命令在自己的项目里跑通一个真实任务。

1. 先说清楚 Codex 到底是什么

1.1 从"AI 补全"到"AI 打工"

如果你只用过 Cursor 或者 GitHub Copilot，你对 AI 编程的认知大概是"我写一半，AI 补另外一半"。这种模式本质上是把 AI 当成一个超强输入法，核心能力还是在你脑子里。而 Codex 这种终端 agent 的逻辑完全不一样：你只需要给出目标，比如"给用户接口加上分页，并补好测试"，它会自己规划步骤，读项目里的代码，确定改动范围，修改文件，运行测试命令，根据测试结果再次修改，最后告诉你完成了什么。

这个过程里，你作为开发者做的事情，从"怎么写"变成了"要什么、怎么验收、何时喊停"。换句话说，效率提升的重点从编码动作转移到了任务定义和质量把关。

1.2 和 IDE 插件、其他 agent 的本质区别

我把区别拆成三层。

第一层，工具形态。Cursor 和 Copilot 都是 IDE 插件，你必须在编辑器里用；Codex 是命令行工具，跟 git、shell、CI 脚本天然能组合，可以像一个真实同事一样出现在你的工作流任何环节。

第二层，执行闭环。IDE 插件通常只负责生成代码片段，而 Codex 会执行命令。它能自己跑npm test、python manage.py migrate、git diff，然后根据输出决定下一步。这个"执行闭环"是质变：AI 能亲眼看到自己的代码在真实环境里跑出什么结果，而不是盲写。

第三层，模型与玩法。Codex 底层可以用 OpenAI 的官方模型，也可以接本地模型；可以走交互式聊天，也可以单次 exec 脚本化执行；可以通过配置文件严格控制权限。这些东西组合起来，让它更像一个可编程的、有安全边界的"数字实习生"，而不是一个只会输出的聊天框。

提示：如果你还不确定自己是否需要它，可以先想一个问题——你每天花多少时间在"写代码"以外的琐碎操作上，比如跑测试、改格式、修 lint、更新文档。只要这个时间超过一小时，Codex 就值得你花一个晚上去上手。

2. 安装与配置：把环境一次弄明白

2.1 环境要求与安装步骤

Codex CLI 是 Node.js 写的，安装前确保本机满足下面几个条件：

Node.js 18 或更高版本（建议使用 20+，跑大任务更稳）
Git 已经安装并完成基础配置
macOS、Linux 或者 Windows 的 WSL 环境（原生 Windows 也可以用，但沙箱体验会差一些）

安装只有一条命令，官方走 npm：

npm install -g @openai/codex

装完先确认版本：

codex --version

如果提示command not found，先检查 npm 的全局 bin 目录是否在 PATH 里。macOS 用户常见的问题是用 Homebrew 装的 Node，但 npm 全局路径没有被 shell 识别；Linux 上则大多是 nvm 切换版本后的路径问题。用npm bin -g查看路径，加进~/.zshrc或~/.bashrc就行。

2.2 两种登录方式

Codex 有两条认证路径，很多人第一次就在这里卡住。

第一种，官方推荐的方式：

codex login

执行后浏览器会弹出登录页，用 OpenAI 账号授权即可。登录后，如果你的账号有 ChatGPT Plus/Pro 订阅，Codex 会走订阅额度，不需要额外为 API 充钱。这一点对个人用户非常友好，日常写点工具脚本、改改 bug，基本不用单独建 API key。

第二种，用 API key：

export OPENAI_API_KEY=sk-xxxxxx

这种方式适合企业里统一管理密钥，或者已经习惯用 API 计费的用户。需要注意，API key 的计费比订阅额度灵活，但费用会直接从账户扣除，跑大任务之前最好对 token 消耗有心理预期。

验证是否成功：

codex exec "你好，用一句话说明你在运行"

如果能正常返回文字，说明认证和环境都没问题。

2.3 config.toml：配置文件详解

Codex 的配置都集中在~/.codex/config.toml。第一次登录后会自动生成，你也可以手动创建。先给一份我目前生产环境在用的精简版：

model = "gpt-5-codex" [model_provider] name = "openai" base_url = "https://api.openai.com/v1" approval_policy = "suggested" sandbox_mode = "workspace-write"

解释一下几个核心字段：

model：指定跑任务用的模型。官方默认值通常是当前主推的代码模型，但如果你发现某些任务用特定模型表现更好，可以直接在这里改。不同版本支持的模型会有差异，用codex --help或官方发布日志能查到当前可用列表。

approval_policy：审批策略，这是整个工具的安全核心，可选值通常有suggested、untrusted、never、always。我的建议是平时用suggested，也就是 Codex 准备执行可能影响系统的命令前，会等你在终端里按 Y 确认；只有在完全可信、隔离的实验室项目里，才用always自动批准。

sandbox_mode：沙箱模式。read-only表示 Codex 只能读文件，不能写入；workspace-write允许它在当前工作目录内写文件；danger-full-access意味着不做限制，可以访问系统任意位置。新人最容易犯的错，就是把沙箱设成danger-full-access还配上always，一旦 agent 跑偏，后果是灾难性的。

提示：建议刚上手时坚持用read-only跑几天，看看它给你列出的"计划改动方案"，再逐步放开权限。让 AI 先展示、再执行，你会慢慢建立对它能力的信任边界。

3. 三大核心模式与常用参数

Codex CLI 日常用得最多的是三种模式：交互模式、单次任务模式、提问模式。

3.1 交互模式：codex

不带任何子命令，直接执行：

codex

会进入一个类似终端聊天界面的 REPL。你可以连续对话，Codex 会记住前面说过的内容，逐步调整改动。这种模式适合需求还不清晰、需要来回讨论的任务。比如你在构思一个功能，先让它提出方案，再让它动手实现。

交互模式里，Codex 每执行一条命令前都会按照审批策略等你的反馈。你可以输入y继续，也可以直接打字提出修改意见。

3.2 单次任务模式：codex exec

codex exec是非交互式执行，给一条指令，跑完就退出。这是我最常用的模式，因为它可以脚本化，也能直接嵌进 CI。

codex exec "修复 src/utils/date.ts 里处理时区的 bug，并补充对应测试"

一条命令下去，Codex 会自己读文件、改代码、跑测试、输出结果，最后返回给终端。没有交互，所以运行效率高，适合目标明确、验收标准清晰的改动。

codex exec支持带目录参数：

codex exec --cd /path/to/project "给项目加上 lint 配置"

3.3 只问不改：codex ask

有些时候你不想让 AI 碰文件，只想让它帮你理解现状，比如"这段代码在什么情况下会死循环"。这时候用：

codex ask "解释 src/auth.js 里 token 刷新的逻辑，重点说明异常分支"

codex ask只读取并回答问题，不做任何写入操作。在只读沙箱里可以放心使用，非常适合代码评审、问题定位、快速学习陌生项目。

3.4 天天要用的参数组合

我整理了一张高频参数速查表，这些参数在不同版本中可能略有差异，以你本机codex exec --help输出的为准：

参数	作用	我的使用场景
`--cd <路径>`	指定工作目录	在子目录或独立项目里跑任务
`--full-auto`	自动批准所有操作	可信任的本地小项目
`--sandbox <模式>`	覆盖沙箱模式	临时允许写文件
`-d`	快捷启用 danger-full-access	仅限个人实验环境
`-s`	跳过 git 仓库检查	在非 git 目录里跑任务
`--model <模型>`	临时切换模型	对比不同模型效果
`--json`	以 JSON 输出结果	脚本解析、CI 集成

我日常用得最顺手的组合是：

codex exec --cd ~/work/demo-project --sandbox workspace-write "重构 batch_process 函数，把重复逻辑提取成公共工具，并确保现有测试通过"

这样既给了 Codex 必要的写入权限，又没把整个系统放开，平衡了效率和安全。

4. 实战：让 Codex 从零给项目加一个功能

光讲参数没意思，接下来我带你完整跑一个真实任务。假设现在有一个本地 Node.js 项目，里面有一个用户列表接口，你要给这个接口加上分页功能，并补上测试。

4.1 任务定义

进入项目目录，输入：

codex exec --cd ~/work/demo-project --sandbox workspace-write "给 GET /api/users 接口增加分页支持，每页默认 20 条，支持 page 和 page_size 参数，并补充单元测试；测试覆盖边界情况。"

注意任务描述里的几个关键点：接口路径、参数名称、默认值、必须补测试、测试覆盖范围。给 agent 的任务越明确，输出越接近你要的东西。模糊的"加个分页"往往会得到偏离预期的结果。

4.2 观察 Codex 的工作过程

Codex 收到任务后，大致会经历下面这些步骤：

先读取项目结构，识别技术栈（看到package.json就明白是 Node.js 项目，看到测试框架配置就知道用什么跑测试）。
找到README.md和已有代码风格，理解命名习惯和模块组织方式。
定位用户接口的实现文件，分析当前逻辑。
设计分页参数校验、默认值、返回结构。
修改源码，修改测试文件。
运行测试命令，比如npm test。
如果测试挂了，它会读报错、修代码、再跑一次，直到通过。

在交互模式下，你能看到它是先展示修改计划，还是直接进入执行流程。在codex exec模式下，你只能看到最终结果，以及它执行过的关键命令。这个"读项目结构→理解既有代码→动手改→跑测试→自我修正"的能力，正是 Codex 区别于普通补全工具的核心价值。

4.3 验收：不要盲目相信输出

任务完成后，Codex 会输出一段总结，列明改了哪些文件、测试结果如何。但你要记住：agent 说的"完成"不等于需求真的完成。你需要自己检查。

我通常做三件事：

git diff看改动是否符合预期，有没有超出任务范围的修改。
自己跑一遍测试确认环境没问题。
手动发起一次请求验证边界值，比如page=0、page_size=1000。

如果发现 Codex 改得不对，直接跟进一条指令：

codex exec --cd ~/work/demo-project "刚才你给接口加的分页没有做大数值拦截，page_size 超过 100 时直接返回 400，并补充一个对应测试"

这就是终端 agent 的容错优势——它能基于当前仓库的最新状态继续改进，不用你把整个上下文复制粘贴到聊天框里。

5. 把 AGENTS.md 变成 Codex 的"项目大脑"

如果你只是让 Codex 零散地改代码，它会按照通用习惯工作。但想要它真正符合你的团队规范、代码风格和业务约束，需要给它一份"说明书"。这个文件叫AGENTS.md，是 Codex 读取项目理解规则的入口。

5.1 AGENTS.md 的优先级

Codex 在进入项目时会自动查找AGENTS.md文件，加载其中的指令作为行为约束。查找范围包括：用户级配置目录、项目根目录、以及当前工作目录的上一层目录。查找顺序和优先级在不同版本里有细微差别，但核心原则是：离当前任务越近的AGENTS.md，优先级越高。也就是说，项目根目录里的规则可以覆盖用户级配置。

我这里建议你至少维护两份：

~/.codex/AGENTS.md：你个人的通用偏好，比如"所有提交信息用中文写"、"不要修改 package-lock.json"。
项目根目录的AGENTS.md：团队规范和项目专属约束，比如"测试必须用 Vitest"、"仅允许修改 src 目录"。

5.2 一份可以直接抄的 AGENTS.md

# 项目规则 ## 语言风格 - 所有注释、提交信息、代码输出必须使用简体中文。 - 变量命名遵循仓库现有风格：TypeScript 项目用 camelCase，Python 项目用 snake_case。 ## 代码修改边界 - 只允许修改 src/ 和 tests/ 目录。 - 禁止修改 package-lock.json、pnpm-lock.yaml。 - 不要调整 ESLint 配置，除非任务明确要求。 ## 测试要求 - 修改任何逻辑后，必须运行 `npm run test`。 - 新增功能必须包含单元测试。 - 测试失败时，先读报错信息，再修代码，禁止通过删除测试来让测试通过。 ## 提交规范 - 每次修改后执行 `git status` 查看改动范围。 - 提交信息格式：`feat(模块): 描述` 或 `fix(模块): 描述`。

有了这份规则，Codex 的行为会明显"贴"你的项目，而不是用一套通用模板到处套。

5.3 一个真实收益场景

我接过一个遗留项目，代码风格非常混乱，既有 2 空格缩进也有 4 空格缩进，还混着制表符。以往让 AI 改代码，改出来的文件风格五花八门。后来我在AGENTS.md里写了一条："所有新增代码遵循 2 空格缩进，字符串用单引号，结尾不加分号；每次改动后运行npm run lint。" 从那以后，Codex 生成的代码基本一次通过 lint，review 工作量降了一个量级。

这给我们的启发是：AGENTS.md不是花架子，它决定了一个 agent 融不融得进你的工程体系。项目越老、规范越特殊，这份文件就越值钱。

6. 进阶玩法：本地模型、MCP 与自定义提示

当你把基础跑熟后，可以开始折腾一些进阶配置。

6.1 把 Codex 接到本地模型上

不是所有场景都必须用官方模型。隐私敏感的项目、离线开发环境、或者想省钱跑大量简单脚本时，可以把 Codex 指向本地模型。常见方案是结合 Ollama，在config.toml里改：

model = "qwen2.5-coder:7b" [model_provider] name = "ollama" base_url = "http://localhost:11434/v1"

需要注意，本地模型的代码能力差距非常大。像 qwen2.5-coder 这类 7B 模型，处理"重构一个函数"这种小任务还行，让它自主改大型多文件项目，很容易跑偏。我的实践经验是：本地模型适合简单、纯粹的代码生成和补全类任务，复杂业务逻辑建议还是用官方模型。

6.2 用 MCP 扩展 Codex 的能力

MCP(Model Context Protocol)是一种让模型连接外部工具的标准协议。Codex 支持通过 MCP 服务器连接数据库、GitHub、浏览器、内部 API 等外部能力，相当于给 agent 装上"手"。

配置方式同样在config.toml：

[mcp_servers.github] command = "npx" args = ["-y", "@modelcontextprotocol/server-github"]

配好后，Codex 就能在任务中直接查询仓库 Issue、创建 PR 等。这类扩展适合做自动化运维和团队协作场景，比如把"帮我给这个仓库建一个 PR，标题和描述按规范写"变成一条 codex 命令。

6.3 自定义系统提示，按自己的口味调教

config.toml还支持指定附加的系统提示，用来控制 agent 的整体语气和工作方式：

system_prompt = "你是一位严谨的全栈工程师。遇到不确定的情况先说明，不要编造 API。每次改完代码必须自己跑测试并汇报结果。"

我自己在写测试时，会让它"先写最小可复现测试，再写实现代码"，这种测试驱动的工作习惯，Codex 只要在系统提示里强调一次，就能稳定执行。

7. 常见问题与避坑实录

最后这部分，是我真实踩坑后的总结，含金量比前面所有命令加起来都高。

7.1 卡在"等待批准"一直不动

如果你跑了codex exec却发现任务一直没有进展，多半是因为某个命令在等确认，但非交互模式没人应答。解决方法是：临时用--full-auto自动批准，或者提前把approval_policy改成always。但强烈建议只在可信目录里这么做。

7.2 沙箱权限报错

Codex 报类似 "permission denied" 的错误，通常是因为sandbox_mode设成了read-only，但它想写文件。此时用--sandbox workspace-write覆盖即可。如果你明确知道自己在干什么，才用-d切换到完全访问。养成习惯：先用最小权限试，报错再提权，别一股脑放开。

7.3 token 烧得太快

Codex 在长任务上 token 消耗很快，因为它会反复读取文件、执行命令、看输出。对策有几个：

把任务描述写具体，减少来回试错。
临时用codex ask确认方案，再用codex exec执行。
在AGENTS.md里约束它"每次修代码前先 git diff，再继续"，避免无意义的大改动。
简单脚本类任务可以换本地模型。

7.4 改错文件、改过头了怎么办

这个最简单，也最容易被忽略：拉开 git 分支再让 Codex 干活。我每次会在新分支上跑 agent，干完git diff确认没问题再合并。一旦它改得离谱，直接丢弃分支重来，几秒钟回到干净状态。没有 git 保护就直接让 agent 自由发挥，本质上是裸奔。

git checkout -b feature/codex-pagination codex exec --cd . "实现分页功能，跑测试" git diff

7.5 我强烈不建议的做法

最后分享几条我亲眼见过别人踩的坑，建议你避雷：

不要用danger-full-access+--full-auto去操作生产数据库或生产服务器。
不要让它直接运行rm -rf、git push --force这类不可逆命令，除非你确认它理解自己在做什么。
不要把敏感密钥、生产环境变量直接写进项目让 Codex 读取。
不要因为它"说"测试通过了，就真的不去跑一遍验证。

AI 工具越强大，越需要你有清晰的验收意识和安全边界。把它当成一个能力很强但经验不足的新同事来管理，而不是一个全知全能的神。

我个人用下来的体会是，Codex CLI 真正改变的是开发节奏：以前我习惯先想清楚再动手，现在可以边让 agent 跑，边在另一个终端看 diff、想下一步需求，这种并行感是 IDE 插件给不了的。最后再分享一个小技巧：不要把 Codex 当成每次都从零开始的工具，你可以在同一个交互会话里逐步叠加需求，先让它分析代码结构，再让它改一个函数，最后让它补测试，上下文连贯时，它的准确率比一次性给个大任务要高得多。希望你读完这篇，能少走一些我走过的弯路，把它真正用进你的工作流里。

Codex CLI完全指南：终端AI Agent从安装到实战