Codex 不是一个“问代码问题”的聊天框，而是能进入项目目录、读取文件、修改代码、执行命令、展示 diff 的编码智能体。

如果你刚开始用 Codex，最重要的不是让它一次完成一个大项目，而是建立一套安全流程：

• 先让它读项目
• 再让它给方案
• 每次只改一小块
• 改完必须看 diff
• 能跑测试就跑测试
• 动手前先打 Git 检查点

这篇文章会从 Codex 是什么、怎么登录、选 App 还是 IDE、第一次任务怎么写、权限怎么收、常见报错怎么排查，一路讲到 AGENTS.md 和提示词模板。

本文中的 Codex，指 OpenAI 当前的 Codex 编码智能体。文中图片来自 OpenAI 官方页面或官方 GitHub 仓库，实际界面可能随版本变化。

1. Codex 适合解决什么问题

Codex 的核心价值，是把“读项目、改代码、跑命令、看结果”串成一个可审阅的工作流。

你可以把它用于这些场景：

• 看懂陌生代码仓库
• 解释目录结构和入口文件
• 根据报错定位 bug
• 做最小范围修复
• 补单元测试
• 审查未提交改动
• 整理 README 或项目文档
• 在 PR 里辅助代码评审

它和普通聊天工具最大的区别是：Codex 可以在项目上下文里工作。

比如你可以直接说：

请暂时不要修改文件，先解释这个项目的目录结构、技术栈、启动方式和入口文件。

也可以说：

我遇到了一个 bug。请先根据报错定位原因，再做最小必要修复，最后运行相关测试。

但要记住一个原则：Codex 的输出不是上线结论，diff 和测试结果才是你判断是否可信的依据。

Codex 的基本工作流程

这张流程图里，最关键的是最后一步：人来审阅。

新手刚上手时，不要急着让 Codex “帮我重构整个项目”。

更稳的方式是：

1. 让它读项目
2. 让它列不确定点
3. 让它只改一个文件
4. 查看 diff
5. 再决定是否继续

2. 入口怎么选：App、IDE、CLI、Web

Codex 有多个入口，新手最容易卡在“我到底该用哪个”。

结论很简单：

• 新手：优先用 Codex 应用
• 常驻编辑器：用 IDE 扩展
• 熟悉终端：再尝试 CLI
• GitHub PR 和后台任务：考虑 Web / 云端能力

Codex 欢迎与登录界面

第一次打开 Codex 应用，通常会看到欢迎界面。常见方式包括 ChatGPT 账号登录，以及工具支持的其他登录或模型服务配置方式。

Codex 欢迎登录界面

如果你不走 ChatGPT 账号登录，而是使用 API 方式，重点看三个字段：API Key、Base URL、模型名称。

这篇文章为了演示 Codex 的 API 登录配置，会使用 iThinkAPI 作为 OpenAI Compatible API 的示例环境。Codex 支持按 OpenAI Compatible API 方式填写模型服务信息；实际接入时，请重点核对 API Key、Base URL 和 Model，具体可用模型、接口格式与配置方式以服务文档为准。

Base URL：https://token.ithinkai.cn/v1 
API Key：YOUR_API_KEY 
Model：以服务文档为准，
最新模型 claude-fable-5, gpt-5.5, claude-opus-4-8,gpt-image-2 模型都有
几乎在 0.05¥/图，支持 2k,4k

这里容易踩坑：

• API Key 不要写进项目代码
• Base URL 末尾路径要按文档填写
• Model 不要凭记忆乱填
• 云端相关能力可能受账号、工作区和登录方式影响
• 配置失败时，先确认工具是否支持该登录模式

选择项目文件夹

Codex 不是孤立回答问题，它需要知道自己在哪个项目里工作。

你需要选择一个项目文件夹，最好是 Git 仓库。

Codex 项目选择界面

新手建议选一个练习项目，而不是直接打开生产项目。

如果项目里没有 Git，也建议先初始化仓库，至少方便你查看改动。

git init
git status

第一次任务输入

选好项目后，不要马上让 Codex 改代码。

第一条任务建议这样写：

请暂时不要修改任何文件。请用中文解释这个项目：
1. 这个项目大致是做什么的？
2. 主要目录分别负责什么？
3. 入口文件可能在哪里？
4. 如果我要在本地运行，通常要执行哪些命令？
5. 哪些地方你不确定？请直接说“不确定”，不要猜。

Codex 首次任务输入

这条提示词的重点，是限制它“只读不改”。

你先判断它是否真的理解项目，再决定下一步。

3. App、Worktree、云端模式怎么用

Codex 应用更像一个桌面工作台，适合新手建立完整工作流。

它可以同时管理多个会话，也能配合 Git、终端和本地预览来完成任务。

Codex 应用主界面

三种常见工作模式

Codex 应用里常见模式包括 Local、Worktree、Cloud。

• 本地模式：直接在当前项目目录下工作
• Worktree 模式：把改动隔离到新的 Git worktree
• 云端模式：在已配置的远端环境中运行任务

Codex 应用模式选择

新手第一次使用，建议用本地模式加练习项目。

如果要在重要项目里尝试比较大的改动，优先使用 Worktree。

为什么推荐 Worktree

Worktree 的好处是隔离。

你可以让 Codex 在一个独立工作区里尝试修改，不影响当前主目录。

适合这些任务：

• 大范围重构前的试验
• 新功能方案验证
• 多个 Codex 会话并行
• 不确定是否采纳的改动

常见命令如下：

git worktree add ../my-project-codex-task -b codex/task-demo

进入新目录后再打开 Codex：

cd ../my-project-codex-task
git status

如果尝试失败，删掉 worktree 即可，不会污染原工作区。

git worktree remove ../my-project-codex-task

4. 第一次改代码：只改 README

等 Codex 解释完项目，你可以让它做第一个小改动。

推荐目标是 README，而不是业务代码。

提示词可以直接用：

请只修改 README.md，新增一节“新手如何启动这个项目”。

要求：
- 不要修改任何其他文件。
- 不要安装新依赖。
- 不要改代码。
- 如果项目里没有明确启动命令，请写“不确定”，不要编造。
- 改完后告诉我修改了哪些内容。

这条提示词把范围限定得很窄。

Codex 如果改了 README 之外的文件，你就能立刻发现。

改完必须看 diff

Codex 完成后，不要只看它的总结。

先执行：

git status
git diff

如果用的是 Codex 应用，也可以直接在审阅面板里看改动。

Codex Git 提交面板

看 diff 时重点检查：

• 是否只改了你允许的文件
• 是否新增了陌生依赖
• 是否删除了重要配置
• 是否把“不确定”写成了确定结论
• 是否修改了无关格式
• 是否真的符合你的目标

新手不一定能看懂每一行代码。

但你至少要学会看：它动了哪些文件，动了多少，是否超范围。

集成终端怎么用

Codex 会话通常可以使用集成终端。

常用命令包括：

git status
git diff
npm test
pnpm test
pnpm run lint

Codex 集成终端

这里有个实用判断：

• 文档改动：通常看 diff 即可
• 代码改动：至少跑相关测试
• 前端 UI 改动：最好本地打开页面验证
• 配置改动：要看启动、构建、环境变量是否受影响

前端项目可以配合浏览器检查

如果是前端项目，Codex 可以配合内置浏览器预览页面。

这适合检查：

• 页面是否正常打开
• 样式是否错位
• 交互是否触发
• 修复是否真的生效
• 控制台是否有报错

Codex 内置浏览器

给 UI 任务时，提示词要带上查看方式：

完成后请告诉我：
1. 需要执行什么启动命令；
2. 本地访问哪个地址；
3. 我应该检查哪些页面和交互；
4. 如果你无法打开浏览器，请说明原因。

5. IDE 扩展、CLI 与 GitHub 评审

如果你已经每天使用 VS Code、Cursor 或 Windsurf，可以考虑 Codex IDE 扩展。

它更适合边写代码边让 Codex 解释、修改和评审。

Codex IDE 扩展入口

IDE 权限模式怎么选

Codex IDE 扩展通常会提供不同权限模式。

新手不要一开始就开高权限。

Codex IDE 审批模式

建议顺序：

1. Chat：只问问题，不让它改
2. Agent：允许有限改动，适合小任务
3. Agent Full Access：只在你理解风险时使用

新手最稳的组合是：

• 先用 Chat 解释代码
• 再用 Agent 修改小范围文件
• 每次改完看 diff
• 高风险命令必须审批

CLI 适合什么人

Codex CLI 让智能体直接在终端里工作。

它适合已经熟悉命令行、Git 和测试命令的人。

Codex CLI 终端界面

CLI 场景下，要特别注意当前目录。

执行任务前先确认：

pwd
git status

不要在错误目录里让 Codex 改文件。

如果你打开的是 monorepo，也要在提示词里明确范围：

本次只处理 packages/web 目录，不要修改 packages/api 和 packages/mobile。

GitHub PR 评审

配置好云端或 GitHub 集成后，可以在 PR 中请求 Codex 评审。

在 GitHub 上请求 Codex 评审

Codex 可以把评审意见写到具体代码位置。

Codex 在 GitHub 上的评审示例

评审提示词可以这样写：

请评审这个 PR，优先关注：
1. 明显 bug；
2. 边界情况；
3. 安全风险；
4. 性能问题；
5. 是否缺少测试。

请先列高风险问题，再列普通建议。
不要要求修改与本 PR 无关的代码。

6. 提示词模板：直接复制就能用

Codex 的提示词不需要华丽。

真正重要的是目标、范围、约束、验证方式。

通用任务模板

目标：我希望你完成什么？

上下文：相关文件、报错、复现步骤或截图是什么？

范围：你可以修改哪些文件？哪些文件不能动？

约束：不要新增依赖、不要改数据库结构、不要改 API 字段等。

验证：完成后需要运行哪些命令？如果跑不了，请说明原因。

输出：列出改动文件、验证结果、风险点和后续建议。

这个模板适合大多数编码任务。

尤其是“范围”和“约束”，能减少 Codex 自行发挥。

读项目模板

请暂时不要修改任何文件，先帮我理解这个项目：

1. 这个项目是做什么的？
2. 使用了什么技术栈？
3. 入口文件在哪里？
4. 主要目录分别负责什么？
5. 新手应该按什么顺序读代码？
6. 哪些地方你不确定？

适用场景：

• 接手旧项目
• 下载开源仓库
• 加入新团队
• 准备修 bug 前
• 不知道从哪个文件开始看

修 bug 模板

我遇到了一个 bug，请帮我定位并修复。

现象：
[粘贴报错或异常行为]

复现步骤：
1. [第一步]
2. [第二步]
3. [第三步]

要求：
- 先说明你判断的原因。
- 做最小必要改动。
- 不要在没问我之前新增依赖。
- 修复后运行相关测试，或说明为什么跑不了。
- 最后列出改动文件和风险。

修 bug 时，复现步骤比“帮我看看”更重要。

你给的信息越具体，Codex 越不容易猜错方向。

加功能模板

请帮我加一个小功能。

功能目标：
[描述功能]

范围：
- 可以改动：[文件或目录]
- 不要改动：[文件或目录]

要求：
- 先给一个简短方案。
- 每一步保持小步幅。
- 沿用现有代码风格。
- 如果需要新依赖，请先停下来问我。
- 完成后运行相关检查。

输出：
- 改了哪些文件
- 如何验证
- 仍需要我手工检查什么

这里要特别注意“小功能”。

如果一个功能会涉及前端、后端、数据库、权限、测试，最好拆成多轮任务。

代码评审模板

请评审当前未提交的改动。

关注点：
1. 明显 bug
2. 漏掉的边界情况
3. 可能造成的回归
4. 安全或性能风险
5. 是否需要补测试

要求：
- 先列高风险问题。
- 再列中低风险建议。
- 不要修改任何文件，除非我明确要求。

这个模板适合提交前自查。

哪怕你不采纳所有建议，也能发现不少遗漏。

UI 任务配截图模板

Codex 支持图片输入时，可以把截图、设计稿或报错截图一起给它。

请按附带截图实现这个页面。

要求：
- 使用项目现有技术栈。
- 布局、间距、字号层级尽量贴近截图。
- 不要在没问我之前引入新的 UI 库。
- 只新增必要组件。
- 完成后告诉我执行哪个命令、打开哪个地址查看效果。

UI 任务还要补充：

• 页面路由
• 目标浏览器
• 是否需要响应式
• 是否沿用现有组件库
• 是否需要深色模式适配

7. 权限、审批、隐私与 Git 检查点

Codex 能读文件、改文件、执行命令，所以权限边界必须提前想清楚。

新手建议：默认收紧权限，只在必要时放开。

审批弹窗怎么判断

当 Codex 请求审批时，不要机械点同意。

先看它到底要做什么。

这些命令要特别谨慎：

rm -rf
sudo
curl ... | sh
npm install some-package-you-do-not-understand

还有这些行为也要留意：

• 访问项目目录之外的文件
• 修改系统目录
• 下载并执行脚本
• 批量删除文件
• 改动锁文件但不解释原因
• 修改环境变量或密钥文件

不确定时，可以这样问：

请解释这条命令要做什么，为什么必要，有没有更安全或范围更小的做法。

不要把敏感信息交给 Codex

这些内容不要直接粘到提示词、日志、截图或项目文件里：

• API Key
• 数据库密码
• 生产环境令牌
• Cookie
• 客户隐私数据
• 生产数据库连接串
• 公司内部不允许外传的资料

报错日志也要检查。

很多日志里会带请求头、URL 参数、令牌片段或数据库地址。

粘贴前先脱敏，例如：

DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/DB

动手前先打 Git 检查点

在重要项目里使用 Codex 前，先确认工作区状态：

git status

如果当前改动已经有价值，先提交一个检查点：

git add .
git commit -m "checkpoint before codex task"

Codex 改完后再看：

git status
git diff

如果不满意，可以回滚未提交改动：

git restore .

如果想回到某个提交，再使用 Git 的回退能力。

新手先记住一句话：没有 Git 检查点，就不要让 Codex 在重要项目里做大范围修改。

8. AGENTS.md：让 Codex 记住项目规矩

经常使用 Codex 后，可以在项目根目录放一个 AGENTS.md。

它可以理解为写给编码智能体看的项目说明书。

适合写进去的内容包括：

• 项目启动命令
• 测试命令
• 构建命令
• lint 命令
• 代码风格
• 禁止修改的目录
• 发布流程
• PR 要求
• 数据库兼容规则
• API 字段兼容要求

示例：

# AGENTS.md

## 项目约定

- 修改 JavaScript 文件后，请运行 npm test。
- 在用户确认之前，不要新增生产依赖。
- 修改公共工具函数时，需要同步更新相关文档。
- 不要修改 generated 目录下的文件。
- 最终总结里，请列出改动文件、验证情况和风险。

什么时候该写 AGENTS.md？

判断标准很简单：

当你第二次提醒 Codex 同一件事，就该考虑写进 AGENTS.md。

比如你每次都要强调“不要新增依赖”，那就写进去。

比如你每次都要强调“修改 API 字段必须兼容旧版本”，也写进去。

这样能减少重复沟通，也能让团队成员使用 Codex 时保持一致。

9. 新手 7 天练习计划

想把 Codex 用稳，不需要一上来挑战复杂项目。

按 7 天练习，效果会更好。

第 1 天：只读项目

请不要修改任何文件。解释这个项目是做什么的、目录结构是什么、入口在哪里、怎么运行。

目标是弄清楚项目全貌。

这一天不要让 Codex 改文件。

第 2 天：生成项目概览

基于你对项目的理解，起草 docs/project-overview.md。

要求：
- 面向新手。
- 说明主要目录和启动步骤。
- 不要修改任何代码文件。

目标是练习文档任务。

文档任务风险低，适合建立信心。

第 3 天：只改 README

请只修改 README.md，加上安装和启动说明。
不要修改任何其他文件。

目标是练习看 diff。

重点不是 README 写得多好，而是你能看出 Codex 改了什么。

第 4 天：修一个小 bug

报错如下：
[粘贴报错]

复现步骤：
1. [第一步]
2. [第二步]
3. [第三步]

请找出原因，并做最小修复。
修完后运行相关检查。

目标是学会描述现象和复现步骤。

不要只写“项目跑不起来”。

第 5 天：补一个测试

请为刚才修复的问题补一个最小测试。

要求：
- 先讲清楚这个测试覆盖什么。
- 不要顺手做大改动。
- 完成后把测试跑一遍。

目标是让 Codex 不只写代码，也验证代码。

测试是降低回归风险的重要手段。

第 6 天：评审你的改动

请评审当前未提交的改动。

关注：
- bug
- 边界情况
- 回归风险
- 是否需要补测试

暂时不要修改文件，只输出评审意见。

目标是把 Codex 当作第二双眼睛。

这一步适合在提交前做。

第 7 天：尝试 Worktree

请在隔离的分支或 worktree 里，尝试实现下面这个小功能：

[功能描述]

要求：
- 先给方案。
- 改动保持小。
- 完成后说明如何验证。

目标是练习隔离环境。

从这一天开始，你可以尝试更复杂但仍可控的任务。

10. 常见问题与排错

Q1：不会写代码，可以用 Codex 吗？

可以，但要从低风险任务开始。

推荐顺序是：

1. 解释项目
2. 整理目录说明
3. 看懂报错
4. 修改 README
5. 修小 bug
6. 补测试
7. 做小功能

不要一上来就让它做完整系统、重构核心模块或操作生产环境。

Q2：Codex 改错了怎么办？

先看 diff。

如果只是小问题，可以继续让它调整：

你刚才修改了不该动的文件。请撤回这些文件的改动，只保留 README.md 的修改。

如果已经改乱，用 Git 回滚：

git restore .

如果你还不熟悉 Git，先在练习仓库里用 Codex。

Q3：Codex 让我批准命令，要不要同意？

只批准你能看懂的命令。

尤其注意：

• 删除文件
• 安装依赖
• 访问项目外目录
• 下载脚本
• 修改系统配置
• 操作生产环境

不懂就让它解释。

如果解释不清楚，拒绝。

Q4：必须使用 API Key 吗？

不一定。

Codex 的登录与使用方式会受产品版本、账号、工作区权限和配置方式影响。

如果使用 API Key 或自定义模型服务配置，要重点核对：

• API Key 是否有效
• Base URL 是否正确
• Model 是否存在
• 工具是否支持该配置方式
• 当前能力是否受账号或工作区限制

Q5：Codex 能直接帮我部署吗？

不要让 Codex 在无人复核的情况下操作生产环境。

更稳的流程是：

1. 本地小改
2. 查看 diff
3. 跑测试
4. 提交分支
5. 创建 PR
6. 人工复核
7. 再进入部署流程

部署涉及权限、密钥、数据和回滚，不适合完全交给自动流程决定。

Q6：Codex 总是改太多怎么办？

你的提示词通常范围太宽。

改成这样：

本次只允许修改 src/utils/date.ts。
不要修改其他文件。
不要新增依赖。
先给方案，等我确认后再改。

如果仍然超范围，停止当前任务，重新开一个更小的任务。

Q7：它编造启动命令怎么办？

让它明确标注不确定性。

可以在提示词里写：

如果项目里没有明确写启动命令，请直接说“不确定”，不要根据经验编造。

同时让它引用依据：

请说明你是根据哪些文件判断启动命令的。

常见依据包括：

• package.json
• README.md
• Makefile
• Dockerfile
• docker-compose.yml
• .github/workflows
• pyproject.toml
• pom.xml

11. 一套稳定的 Codex 工作流

把前面内容压缩成一套流程，就是：

1. 打开项目前先看 git status
2. 必要时提交检查点
3. 让 Codex 先读项目，不改文件
4. 明确目标、范围、约束、验证方式
5. 一次只做小任务
6. 改完看 diff
7. 能跑测试就跑测试
8. 让 Codex 汇总改动和风险
9. 人来决定是否提交

真正好用的 Codex 使用方式，不是“帮我把整个项目做好”。

而是让它在清晰边界里，帮你读代码、定位问题、做小步修改、补测试、做评审。

任务越具体，范围越清楚，验证越明确，Codex 的结果越容易被你掌控。

如果你是第一次用 Codex，就从这条提示词开始：

请暂时不要修改任何文件。请用中文解释这个项目的结构、技术栈、入口文件、运行方式和不确定点。

等你能稳定完成“读项目 -> 小改动 -> 看 diff -> 跑测试”这条链路，再去尝试 Worktree、CLI、云端任务和 PR 评审。

这才是新手使用 Codex 最稳的入门路线。