主流 Agent 入门教程 / Codex

1. Codex是什么

原文备份 · 第 2 / 27 篇 · 查看极客时间原知识库 ↗

本篇目录 · 20 节

来源：Codex

预计阅读时间：12 分钟
本篇目标：理解 Codex 的定位、工作方式和几种使用入口，知道什么任务适合交给它。

如果你以前用过 ChatGPT，一开始很容易把 Codex 理解成“更会写代码的聊天机器人”。这个理解不能说完全错，但会让你低估它。

普通对话工具通常停留在“告诉你怎么做”：你把报错贴进去，它解释原因，再给你一段代码。至于找到对应文件、修改代码、运行测试和检查结果，通常还得由你自己完成。

Codex 更像一个可以进入工作现场的协作者。只要你把它放进一个项目目录，并授予合适的权限，它就可以读取项目文件、搜索代码、运行命令、修改文件、执行测试，再根据测试结果继续调整。

这也是为什么 Codex 被称为 Coding Agent，而不只是代码生成工具。

一、先用一个例子理解 Codex

假设你接手了一个陌生项目，运行后发现“导出订单”功能报错。

如果使用普通对话工具，你可能要自己完成下面这些事情：

找到与订单导出有关的文件。
把部分代码复制到聊天窗口。
把错误日志也复制进去。
根据回答修改代码。
回到终端运行测试。
如果还有错误，再把新错误复制回去。

使用 Codex 时，你可以在项目目录中启动它，然后直接说：

订单导出功能运行时报错。请先阅读项目说明和相关代码，复现问题，解释根因，
然后给出最小修复方案。修改完成后运行相关测试，不要改动无关文件。

接下来，Codex 可以自己搜索相关文件、查看日志、运行程序、修改代码和执行测试。它会在需要额外权限时停下来询问你，也会把最终修改和验证结果报告给你。

这里真正重要的，不是它一次写出了多少代码，而是它可以围绕一个目标连续完成多步工作。

二、Codex 的基本工作过程

在实际使用中，Codex 通常会经历下面几个步骤：

理解任务：判断你想完成什么、有哪些限制、怎样才算完成。
收集上下文：读取目录结构、项目说明、配置文件、代码和测试。
制订方案：决定先检查哪里、修改哪些文件、如何验证。
执行操作：搜索内容、运行命令、创建或修改文件。
验证结果：运行测试、构建程序、检查输出或审查差异。
汇报结果：说明做了什么、验证了什么、还有哪些风险。

这个过程不会每次都完整出现。让 Codex 修改一句文案时，它可能很快完成；让它升级一个跨越多个模块的功能时，它可能需要反复检查和验证。

你给出的目标越清楚，项目提供的上下文越完整，它越容易沿着正确方向工作。

三、Codex 能做什么

Codex 最擅长处理与代码、项目文件和开发工具有关的任务。

1. 理解陌生项目

它可以读取目录和关键文件，帮你回答：

这个项目是做什么的？
应该怎样启动？
核心模块在哪里？
数据从哪里进入，又流向哪里？
修改某个功能可能影响哪些地方？

2. 开发功能

你可以让它从需求出发，完成方案设计、代码修改、测试补充和文档更新。小功能可以一次完成，复杂功能则适合拆成几个可以独立验收的阶段。

3. 修复问题

Codex 可以根据错误日志和复现步骤运行程序、定位原因、编写回归测试，再完成修复。

比起直接说“帮我修一下”，更可靠的做法是要求它先复现问题，再解释根因。

4. 补充测试和文档

它可以分析现有代码的测试缺口，补充单元测试、集成测试、README、接口说明和变更记录。

5. 审查代码

Codex 可以查看 Git Diff，检查逻辑错误、遗漏的边界情况、测试缺口和潜在风险。它也可以审查尚未提交的本地修改。

6. 处理重复工作

借助非交互模式，Codex 可以进入脚本或持续集成流程，例如分析测试日志、生成发布说明，或者把检查结果输出成结构化 JSON。

四、Codex 不会自动替你承担判断责任

Codex 可以执行很多操作，但最终结果仍然需要人来验收。

下面几类情况尤其需要谨慎：

需求本身含糊，团队也没有达成共识。
修改涉及支付、权限、隐私或生产数据。
项目缺少测试，无法快速判断修改是否正确。
Agent 需要访问工作目录之外的文件或外部系统。
一次修改范围很大，同时跨越多个模块。

使用 Codex 的关键能力，不只是“会写提示词”，还包括会限定范围、会检查差异、会运行验证、会在结果不可靠时及时停下来。

后面的教程会一直围绕这套工作方法展开。

五、Codex 的几种使用入口

Codex 并不只有一个界面。不同入口解决的问题不完全相同。

使用入口	更适合的任务	主要特点
Codex CLI	在终端中开发、调试、审查和自动化	离项目和开发工具最近，控制细致，是本教程的重点
桌面客户端中的 Codex	管理本地项目、查看修改、并行处理较长任务	界面直观，适合查看文件变化和管理多个任务
IDE 扩展	围绕当前打开的代码和编辑器上下文工作	适合边阅读代码边提问或修改
Codex Cloud	在云端环境中执行代码任务	不占用本机环境，适合已经配置好的远程项目

为什么先学 Codex CLI

CLI 是理解 Codex 工作方式最直接的入口。

在终端中，你能清楚看到它从哪个目录启动、读取了哪些上下文、运行了哪些命令、获得了什么权限。之后再使用桌面客户端或 IDE 扩展，很多概念就不会显得陌生。

CLI 还可以通过 codex exec 进入脚本和自动化流程，这是图形界面不容易替代的能力。

桌面客户端适合什么人

当前桌面客户端同时提供面向开发工作的 Codex，以及面向文档、表格、演示文稿等交付物的 ChatGPT Work。

程序员可以用 Codex 处理代码项目；产品经理、运营、编辑等非技术用户，则可以在同一个客户端中使用 Work 处理文件整理、数据分析和方案比较。

本教程会把桌面客户端放在最后讲。到那时，你已经理解工作目录、权限和任务上下文，再处理本地文件会更稳妥。

六、我们会开发什么项目

整套教程会围绕一个名为 TaskFlow 的小项目展开。

TaskFlow 是一个本地任务管理工具。第一版只支持添加、查看和完成任务，后面会逐渐增加：

按状态和日期筛选任务；
从 CSV 导入数据；
生成任务统计；
导出 Markdown 报告；
自动测试和发布前检查。

这个项目规模不大，不要求你先掌握复杂框架，但足以覆盖项目规划、功能开发、调试、测试、代码审查、项目规则、多 Agent 和自动化执行。

如果你不是程序员，也不用担心看不懂所有代码。教程的重点是理解怎样把一个真实任务交给 Codex，并判断它是否完成了任务。

七、学习时请保留三个习惯

习惯一：从正确的目录启动 Codex

Codex 会把当前目录视为重要的工作上下文。进入错误目录，轻则让它找不到文件，重则让它看到不该处理的内容。

习惯二：先说明完成标准

不要只说“帮我做个功能”。告诉它功能要解决什么问题、不能改动什么、需要运行哪些测试、最终应该交付什么。

习惯三：每次都检查结果

查看修改的文件，阅读 Git Diff，运行程序和测试。Codex 的总结可以帮助你理解结果，但不能代替验收。

八、开始前的小练习

先不用安装任何东西。请判断下面几项任务是否适合交给 Codex：

阅读一个陌生项目，说明它如何启动。
修复一个能够稳定复现的错误。
在没有任何需求说明的情况下，决定公司下一季度应该开发什么产品。
根据现有代码补充测试。
直接连接生产数据库并批量删除历史数据。

前两项和第四项很适合。第三项需要人先明确业务目标，第五项涉及高风险外部操作，不能只凭一句自然语言直接执行。

下一篇，我们会在 Windows、macOS 或 Linux 上安装 Codex CLI，完成登录，然后在一个专门的练习目录中启动它。