Codex App 教程(一):先把工作台搭好

这是 Codex App 系列教程的第一篇。目标不是一次性讲完所有功能，而是帮你把 Codex App 的基础工作方式建立起来：安装准备、项目选择、线程管理、沙盒审批、上下文、模型选择，以及第一次让 Codex 安全地阅读项目。
本文基于 OpenAI 官方文档，并参考视频《 Codex (APP) 保姆级全攻略，海量实战教程，一期精通 Codex 》的演示顺序整理。

很多人第一次用 Codex App ，会把它当成一个更懂代码的聊天窗口。

这个理解只说对了一半。

Codex App 真正的价值，不是“你问一句，它答一句”，而是把 AI 放进一个真实项目里，让它能读文件、改代码、跑命令、看差异、查错误、做审查，并且在你的安全规则内持续工作。

所以第一篇先不急着做复杂功能。我们先解决一个更重要的问题：

怎样把 Codex App 配成一个可靠的工程工作台？

这篇读完，你应该能做到：

一、 Codex App 是什么？

OpenAI 官方对 Codex 的定位是软件开发 agent 。它面向的是完整的软件开发生命周期，而不是单点代码补全。

你可以把它理解成一个能进入项目现场工作的 AI 工程助手。

它可以做的事情包括：

这和普通聊天工具最大的区别是： Codex App 不只回答问题，它可以直接参与项目操作。

普通聊天工具更像“问答”：

我：这段代码是什么意思？
AI：它大概是在做用户鉴权。

Codex App 更像“协作”：

我：请阅读这个项目的鉴权流程，画出登录态流转，并指出 token 过期处理在哪里。
Codex：搜索相关文件，读取实现，解释流程，列出文件路径，并给出下一步排查建议。

这就是为什么学习 Codex App 不能只学提示词。你还要学习项目边界、权限、上下文、 Git 状态和验证流程。

二、安装前需要准备什么？

视频里提到，安装 Codex App 前建议准备三个基础工具：

这三个工具不一定每次都用到，但它们会直接影响 Codex 的工作质量。

1. Git ：所有安全工作的底座

Git 是 Codex App 里很多能力的基础。

它会影响：

如果你的项目还没有 Git ，建议先初始化：

gitinit
gitadd.
gitcommit-m"Initial commit"

如果项目已经是 Git 仓库，开始使用 Codex 前先看一眼状态：

gitstatus

为什么这一步重要？

因为 Codex 修改文件后，你需要分清哪些改动是你原本就有的，哪些是 Codex 新增的。如果一开始工作区很乱，后面 Review 和回滚都会变麻烦。

新手建议：

2. Node.js ：前端和工具生态的基础

很多现代项目依赖 Node.js 。

即使你不是前端开发者，也经常会遇到：

Codex 经常需要运行这些命令来验证修改。

如果你的机器没有 Node.js ，它可能能读代码，但无法启动项目、运行测试或生成构建结果。

建议至少确认：

node-v
npm-v

如果项目使用 pnpm 或 yarn，也要确认对应工具可用。

3. 编辑器： Codex 不是完整 IDE

Codex App 可以展示文件、 diff 、对话和浏览器，但它不是一个完整 IDE 。

复杂项目里，你仍然会需要编辑器做这些事：

视频里提到可以配合 VS Code 使用。你也可以用 Cursor 、 WebStorm 、 PyCharm 、 Zed 或其他编辑器。

更现实的使用方式是：

三、第一次打开 Codex App ：先选对项目

Codex App 当前主要面向 macOS 和 Windows 桌面端。安装后，你会先登录账号，然后选择要工作的项目目录。

这里最关键的是：不要随便选一个过大的目录。

错误做法：

选择 ~/Documents
选择整个用户目录
选择一个包含很多无关项目的大文件夹

更好的做法：

选择一个具体仓库
选择某个应用目录
选择一个你准备让 Codex 工作的项目根目录

原因有三个。

第一，项目越清晰， Codex 越容易理解边界。

第二，沙盒权限更好控制。

第三，上下文不会被无关文件污染。

如果你是 monorepo ，也就是一个仓库里有多个应用，可以先选择整个仓库，但第一次任务要限制范围：

请只阅读 apps/web 和 packages/ui，不要分析其他目录。

这比直接说“帮我看看这个项目”更稳。

四、理解 Codex App 的界面

Codex App 的界面可以分成三块：

1. 左侧：管理项目和线程

左侧最重要的是 Project 和 Thread 。

Project 是项目边界。

一个 Project 通常对应一个本地代码目录。 Codex 会在这个目录里读取文件、修改文件、运行命令。

Thread 是任务上下文。

一个 Thread 就是一条任务线。它会保存：

新手最常见的问题，是把所有任务塞进一个 Thread 。

例如：

先解释项目结构
再修登录 bug
再优化 UI
再写部署文档
再接入 MCP

这些事情如果都放在一个线程里，上下文会变得很复杂。 Codex 后面可能会混淆旧任务和新任务。

建议采用这个规则：

2. 中间：对话不是闲聊，而是任务控制台

中间的聊天区看起来像聊天软件，但你要把它当成任务控制台。

一个有效请求应该包含：

差的提示：

帮我优化一下项目。

好的提示：

请只读不改。阅读 apps/web/src/auth 目录，解释登录态从提交表单到写入 session 的完整流程。输出关键文件、函数名、数据流和你认为最容易出 bug 的位置。

差别很大。

第一个请求没有边界。第二个请求把任务变成了可执行流程。

3. 右侧：不要忽略辅助面板

右侧面板是 Codex App 和普通聊天工具最大的差异之一。

你会在这里看到：

新手容易只盯着聊天区看，这是不够的。

当 Codex 修改代码时，你要习惯打开 diff 。

当 Codex 说测试通过时，你要看命令输出。

当前端页面改完时，你要用浏览器看实际效果。

右侧面板是你验证 Codex 工作的地方。

五、 Local 、 Worktree 、 Cloud 先有个基本概念

Codex App 里常见三种工作模式：

第一篇先讲概念，第二篇和第三篇再展开实战。

1. Local ：直接在当前项目里工作

Local 模式最容易理解： Codex 直接在你选择的项目目录里工作。

适合：

风险：

新手第一天可以先用 Local ，但要尽量只读不改。

2. Worktree ：隔离副本里工作

Worktree 基于 Git worktree 。它会创建一个隔离工作目录，让 Codex 可以在里面修改文件，不直接污染你的主工作区。

适合：

注意：

Worktree 通常基于 Git 追踪文件。未追踪文件、被忽略文件、本地 .env 文件不一定会自动过去。

所以 Worktree 启动后，要检查配置和依赖。

3. Cloud ：云端执行任务

Cloud 模式适合把任务交给云端环境跑。

适合：

风险：

第一篇你只需要记住：

六、沙盒和审批： Codex 的安全边界

Codex App 会读文件、写文件、跑命令，所以安全机制非常重要。

这里有两个概念：

1. Sandbox 管“能不能”

沙盒决定 Codex 和它启动的命令可以做什么。

例如：

这不是形式主义。

如果你让 Codex 运行测试、构建、安装依赖，它启动的子进程也要受沙盒约束。

2. Approval 管“要不要问你”

审批决定 Codex 在遇到敏感操作时是否要停下来让你确认。

常见会触发审批的场景：

你看到审批弹窗时，不要机械点允许。

先看三点：

3. 新手推荐权限策略

刚开始建议使用相对保守的设置。

可以允许：

需要谨慎：

如果 Codex 申请权限，你可以让它先解释：

在我授权之前，请说明这个命令的目的、风险，以及有没有不需要提升权限的替代方案。

这是非常重要的习惯。

七、上下文： Codex 为什么有时会“忘事”

Codex 工作时会使用上下文。

上下文可以理解成它当前能看到、能记住、能利用的信息。

它包括：

上下文不是无限的。

当一个线程变得很长， Codex 会需要压缩历史。压缩可以继续任务，但也可能丢失一些细节。

1. 什么时候继续当前线程？

适合继续当前线程：

例如：

刚才你定位到问题在 session.ts，请继续只围绕这个文件修复。

2. 什么时候开新线程？

适合开新线程：

例如，前一个线程一直在排查登录 bug 。现在你要做部署文档，就应该开新线程。

3. 怎么减少上下文浪费？

有几个实用方法：

八、模型选择：不要只追求最强

Codex App 里可以选择不同模型和推理强度。具体模型名称会随着产品更新变化，所以这里讲原则。

1. 简单任务用快模型

适合：

这类任务不需要最高推理强度。

2. 复杂任务用强模型

适合：

这类任务建议选择更强模型和更高推理强度。

3. 让 Codex 自己推荐

如果你不确定，可以直接问：

这个任务涉及登录、数据库和前端状态管理。请先判断适合使用什么模型和推理强度，并说明原因。

这比盲目固定一个模型更灵活。

九、第一次练习：让 Codex 只读不改

第一天最推荐的练习，不是让 Codex 写代码，而是让它阅读项目。

你可以用这个提示词：

请先只读不改。阅读当前项目后，输出一份项目理解报告：

1. 项目主要技术栈
2. 启动和测试命令
3. 目录结构说明
4. 核心业务模块
5. 关键入口文件
6. 当前项目可能存在的风险点
7. 建议写入 AGENTS.md 的项目规则

不要修改任何文件，不要安装依赖。

这个练习有三个好处。

第一，你能观察 Codex 如何搜索和阅读项目。

第二，你能判断它对项目的理解是否靠谱。

第三，你能把它总结出的规则沉淀成后续工作基础。

1. 如何检查它的报告？

看四点：

如果它说得太泛，可以追问：

请把每个结论都附上对应文件路径或命令来源。没有证据的结论请标注为推测。

2. 让它补一份操作清单

理解项目后，可以让它继续输出：

请基于刚才的项目理解，给我一份新手上手清单。要求按顺序列出：安装依赖、启动、本地验证、运行测试、常见问题排查。

这会把 Codex 从“解释项目”带到“帮助你上手项目”。

十、第一篇的总结

这一篇只讲基础，但这些基础决定了后面能不能稳定使用 Codex 。

你需要记住：

下一篇会进入真正的开发流程：如何用 Plan 模式拆任务，如何让 Codex 实现功能，如何用 Steer 纠偏，如何用 Browser 验证页面，如何用 Review 检查 diff ，最后如何用 Git 安全提交和回滚。

参考资料

参考链接

[1] Codex App Overview: https://developers.openai.com/codex/app

[2] Codex App Features: https://developers.openai.com/codex/app/features

[3] Sandboxing: https://developers.openai.com/codex/concepts/sandboxing

[4] AGENTS.md: https://developers.openai.com/codex/guides/agents-md

[5] Codex (APP) 保姆级全攻略，海量实战教程，一期精通 Codex: https://www.bilibili.com/video/BV1Kk9kBAEJv/?spm_id_from=333.1387.homepage.video_card.click&vd_source=b5e784467105cb6f7ba5ef98491a2de4