Codex使用教程：安装、项目分析、代码修改与安全检查

Codex是OpenAI提供的编程智能体，可以读取项目文件、解释代码、修改程序、运行命令和检查结果。它与普通代码问答工具的区别在于：Codex不仅能给出代码片段，还能在获得相应权限后直接处理当前工作区。

这篇Codex使用教程以Codex CLI为主，介绍安装登录、打开项目、编写任务提示、分析代码库、修复Bug、添加功能、运行测试、检查差异和控制权限。Codex的桌面端、IDE扩展与CLI界面并不完全相同，本文中的斜杠命令默认指CLI交互界面。

一、Codex适合处理哪些开发任务

Codex常见用途包括：

• 阅读陌生项目并说明目录结构；
• 跟踪一次请求经过哪些模块；
• 根据复现步骤定位Bug；
• 在既有代码中增加小型功能；
• 编写或补充单元测试；
• 修改配置、脚本和文档；
• 检查未提交的代码差异；
• 运行格式检查、静态检查和测试；
• 根据明确要求完成重复性开发任务。

Codex不能代替代码审查、自动化测试和发布审批。它生成或修改的代码仍可能存在边界遗漏、兼容性问题和安全风险。涉及数据库删除、生产环境、账号权限、密钥、支付或外部消息发送时，需要人工确认目标和影响范围。

二、选择CLI、IDE还是桌面端

Codex提供多种使用入口，适合的场景不同。

使用方式	特点	适合场景
Codex CLI	在终端中读取文件、编辑代码并运行本机命令	后端项目、脚本、测试、命令行工作流
IDE扩展	能结合当前打开的文件和选中代码	阅读局部代码、快速修改、边写边问
ChatGPT桌面端中的Codex	适合项目、文件和持续时间较长的任务	计划、实现、审查和跨文件工作
云端任务	在托管环境中执行任务	需要把任务交给远程环境处理的场景

第一次学习时，可以先选择CLI。它能清楚展示当前目录、权限、运行命令和代码差异，便于理解Codex实际做了什么。

三、使用Codex前的准备工作

1. 确认项目可以独立恢复

在让Codex修改代码前，建议项目已经纳入Git版本控制，并且当前改动状态明确。

git status --short

如果工作区中存在未提交内容，要先确认这些修改来自谁、是否需要保留。不要把用户自己的改动误认为Codex生成的内容。

对于重要任务，可以在开始前建立一个Git检查点：

git add -A
git commit -m "chore: checkpoint before codex task"

是否提交应根据团队流程决定。如果当前修改还不能提交，至少先查看并记录状态。

2. 准备项目的验证命令

提前确定项目常用的检查方式，例如：

npm test
npm run lint
pytest
mvn test
go test ./...

不要把所有示例命令原样复制到自己的项目。应选择仓库中实际存在的脚本，并优先运行与改动范围最接近的测试。

3. 清理敏感信息

在提示词、日志和示例代码中不要粘贴：

• API密钥和访问令牌；
• 数据库密码与连接字符串；
• 私钥、证书和会话Cookie；
• 客户个人信息；
• 未公开的生产数据；
• 内部服务器地址和安全配置。

必须展示结构时，可替换为占位符：

API_KEY=<REDACTED>
DATABASE_URL=<REDACTED>

四、安装Codex CLI

使用npm安装时，需要先准备可用的Node.js和npm环境，然后运行：

npm install -g @openai/codex

安装完成后检查版本：

codex --version

如果系统提示找不到codex命令，先关闭并重新打开终端，再检查npm全局可执行目录是否已加入PATH。

OpenAI也提供独立安装程序和平台对应的发布包。不同操作系统的安装方式可能调整，使用时应以OpenAI官方Codex CLI安装页面为准，不要从来源不明的网站下载安装文件。

更新Codex CLI

如果使用npm安装，可以执行：

npm install -g @openai/codex

更新后再次确认版本：

codex --version

遇到命令行为与教程不一致时，先检查版本和官方更新说明，因为斜杠命令、默认模型和界面可能随版本变化。

五、第一次启动和登录

进入项目根目录，再启动Codex：

cd your-project
codex

第一次运行时，按照界面选择可用的登录方式。常见方式包括使用ChatGPT账号登录，或者在支持的本地场景中使用API密钥。具体可用方式受到账号、工作区和管理员策略影响。

不要把API密钥直接写进项目代码、Git仓库、聊天记录或公开截图。需要使用密钥时，应按官方认证说明通过安全方式配置。

登录后，可以先输入：

/status

/status用于查看当前会话配置，例如模型、权限、可写目录和上下文使用情况。开始任务前确认当前目录非常重要：在错误目录启动Codex，可能导致它读取或修改错误的项目。

六、第一次任务先让Codex阅读，不要急着改

进入陌生项目后，适合先执行只读分析。

请先阅读这个项目，不要修改文件。

需要输出：
1. 项目的主要用途；
2. 目录结构和各模块职责；
3. 程序启动入口；
4. 测试、格式检查和构建命令；
5. 你还无法确认的信息。

每条结论列出对应文件路径。

这条提示包含三个有效限制：先不修改、结论要有文件依据、无法确认时明确说明。读完结果后，再针对关键模块追问：

继续分析登录请求从路由到数据库的调用过程。
按执行顺序列出文件、函数、输入输出和错误处理，不要修改代码。

如果Codex对项目结构理解错误，应先纠正上下文，再让它实施功能。错误的项目理解会传递到后续修改中。

七、Codex提示词怎么写

Codex不要求固定语法。小任务可以直接说明目标；复杂任务建议包含四类信息：目标、上下文、边界和验证。

通用提示词模板

目标：完成【具体开发任务】。

上下文：
- 相关文件或目录：【路径】
- 当前行为：【实际情况】
- 预期行为：【目标情况】

边界：
- 不要修改【无关模块】；
- 保持【接口/数据格式/兼容性】不变；
- 如需新增依赖或执行破坏性操作，先说明原因并等待确认。

验证：
- 运行【测试或检查命令】；
- 汇报修改文件、关键差异和测试结果；
- 无法验证的部分单独列出。

不必每次填写所有项目。只保留会影响结果的内容。一个很小的文案修改，不需要写成长篇需求；涉及接口、数据库或跨模块修改时，边界和验证应写得更具体。

不够明确的写法

优化一下这个项目。

“优化”可能指性能、可读性、依赖、界面、构建速度或目录结构，范围没有边界。

更可执行的写法

分析src/api/orders.ts中订单列表接口的响应时间问题。
先诊断，不要修改代码。

请检查数据库查询次数、循环中的重复计算和不必要的序列化。
给出证据、影响范围和最小修改方案。
不要改变接口字段和排序规则。

八、使用Codex修复Bug

修复Bug时，复现步骤通常比“这里有问题”更有价值。

Bug：用户在设置页面保存通知开关后，刷新页面会恢复旧值。

复现步骤：
1. 启动项目：npm run dev；
2. 打开/settings；
3. 修改通知开关；
4. 点击保存；
5. 刷新页面，开关恢复原状态。

限制：
- 不改变现有API字段；
- 不重构无关组件；
- 优先做最小修复；
- 如果能稳定复现，请补充回归测试。

先复现并定位根因，再提出修改方案。完成后重新执行复现步骤和相关测试。

一个较稳妥的Bug修复过程是：

1. 复现问题；
2. 找到失败路径；
3. 说明根因及证据；
4. 确定最小修改范围；
5. 实施补丁；
6. 运行回归测试；
7. 查看代码差异；
8. 说明仍未覆盖的风险。

如果Bug无法复现，Codex不应假装已经确认根因。可以要求它输出已检查内容、当前证据和下一步需要的日志。

九、使用Codex添加功能

功能开发需要说明用户行为和完成标准，不能只给一个功能名称。

为文章列表增加按状态筛选功能。

要求：
- 状态包括全部、草稿、已发布；
- 默认选择全部；
- 筛选条件写入URL查询参数；
- 刷新页面后保留当前筛选；
- 不改变现有分页和排序行为；
- 使用项目已有组件，不新增UI依赖。

先阅读相关页面、路由和测试，给出修改计划。
我确认计划后再编辑文件。

完成后运行相关测试，并说明手动验证步骤。

这类提示把界面行为、状态范围、URL规则、兼容要求和依赖边界写清楚。Codex可以自行寻找相关文件，但不必猜测什么叫“功能完成”。

什么时候先使用计划模式

跨多个模块、存在多种实现方式或影响范围较大的任务，可以先输入：

/plan

然后描述需求，让Codex先调查并提出方案。计划阶段应重点检查：

• 修改了哪些模块；
• 是否影响公开接口；
• 是否需要数据迁移；
• 是否引入依赖；
• 测试范围是否足够；
• 有没有超出原需求的重构。

计划确认后再进入实施，能够减少做到一半才发现方向错误的情况。

十、给Codex提供准确的文件上下文

在Codex CLI中，可以输入@搜索工作区文件，也可以使用：

/mention src/api/orders.ts

提示词中直接写路径同样有用：

阅读src/auth/login.ts和src/auth/session.ts，解释登录成功后会话如何写入和校验。

IDE扩展通常会利用当前打开的文件和选中内容，但仍应说明关注范围。不要只依赖“我当前打开了某个文件”这种隐含上下文，关键路径最好写进提示词。

文件很多时怎么处理

不要一次要求Codex阅读整个大型仓库的每个文件。可以分层进行：

1. 先确认项目入口和模块边界；
2. 再跟踪目标请求或功能路径；
3. 最后阅读即将修改的文件和相邻测试；
4. 修改前让它总结影响范围。

这样能减少无关上下文，也方便人工核对它的理解是否正确。

十一、常用斜杠命令

下面是Codex CLI中较常用的命令。具体命令以当前版本的/菜单为准。

命令	用途	常见使用时机
/status	查看当前会话配置和上下文	开始任务或排查环境问题
/permissions	调整读取、编辑和执行权限	只读分析或需要写入时
/model	选择当前模型和推理强度	根据任务难度调整
/plan	先调查并形成计划	跨模块或高影响任务
/init	为当前项目生成AGENTS.md初始文件	建立仓库级协作说明
/mention	把指定文件加入上下文	需要Codex重点阅读某个文件
/diff	查看工作区代码差异	修改后审查具体变更
/review	检查工作区修改并发现问题	测试完成后、提交前
/compact	压缩过长的对话上下文	长任务继续进行时
/new	在同一CLI会话中开始新聊天	切换到无关任务
/resume	恢复以前保存的聊天	继续未完成任务
/fork	复制当前聊天并尝试另一条方案	对比不同实现思路
/ps	查看后台终端	检查长时间运行的命令
/stop	停止当前会话的后台终端	后台服务或测试不再需要时

新版本可能增加、调整或隐藏部分命令。输入/查看当前界面实际提供的命令，比照搬旧教程更可靠。

十二、使用AGENTS.md保存项目规则

如果每次都要重复说明测试命令、代码风格和禁止事项，可以在项目中使用AGENTS.md。

在CLI中可以输入：

/init

生成初始文件后，再根据项目实际情况修改。例如：

# AGENTS.md

## Project structure

- `src/api` contains HTTP handlers.
- `src/services` contains business logic.
- `tests` mirrors the source directory structure.

## Working rules

- Keep public API response fields backward compatible.
- Do not add production dependencies without confirmation.
- Prefer focused changes; do not refactor unrelated modules.

## Verification

- Run `npm run lint` after changing TypeScript files.
- Run the nearest relevant test before the full test suite.
- Report commands and results at the end of the task.

AGENTS.md适合记录稳定的仓库约定，不适合放一次性需求。某个Bug的复现步骤、当前任务截止范围和临时判断，应写在当前提示词中。

AGENTS.md的读取范围

Codex会从全局和项目目录中读取指令文件，并从项目根目录向当前工作目录合并。更靠近当前目录的项目指令可以覆盖上层规则。

因此，大型仓库可以在根目录放通用要求，在具体子目录放与该模块有关的补充要求。指令发生冲突时，应检查当前目录路径以及各层AGENTS.md或AGENTS.override.md。

修改指令文件后，通常需要开启新的运行，让Codex重新读取完整指令链。

十三、权限、沙箱和网络访问

Codex CLI在本地运行命令时会受到沙箱和审批策略控制。

• 沙箱模式决定它在技术上能访问和写入哪些位置，以及命令能否访问网络；
• 审批策略决定哪些操作需要暂停并请求用户确认。

默认情况下，本地Codex通常把写入限制在当前工作区，并关闭命令的网络访问。需要超出工作区、访问网络或执行高风险操作时，可能要求批准。

只想阅读代码时

输入：

/permissions

选择只读权限。这样适合项目梳理、代码解释、风险审查和方案讨论。

需要修改代码时

选择允许在当前工作区编辑的权限，并保持工作目录准确。看到审批请求时，至少检查：

• 具体要运行什么命令；
• 命令在哪个目录执行；
• 会修改或删除哪些文件；
• 是否访问网络；
• 是否安装依赖；
• 是否影响工作区之外的内容。

不要为了减少弹窗就长期使用绕过审批和沙箱的高权限模式。官方文档也建议仅在隔离环境中考虑完全绕过保护的方式。

十四、修改后怎样检查结果

1. 查看具体差异

在Codex CLI中输入：

/diff

也可以使用Git查看：

git status --short
git diff

审查时不要只看“改了几个文件”，还要检查：

• 是否改动了需求之外的模块；
• 是否删除了原有错误处理；
• 是否改变公开接口或数据结构；
• 是否加入新的依赖和配置；
• 测试是否真正覆盖失败场景；
• 日志中是否出现敏感信息；
• 注释和文档是否与实现一致。

2. 运行最接近改动的测试

先运行范围小、定位明确的测试，再考虑完整测试套件。例如：

先运行本次修改对应的单元测试。通过后再运行lint。
报告每条命令、退出状态和失败摘要，不要只说“测试通过”。

3. 使用代码审查命令

/review

可以要求审查重点：

审查当前未提交修改，重点检查：
1. 数据丢失风险；
2. 权限校验遗漏；
3. 空值和并发边界；
4. 向后兼容性；
5. 测试覆盖不足。

只报告能从代码差异中得到证据的问题，并标出文件位置。

审查结果仍需要人工判断。自动审查可能漏报，也可能把设计选择误判为缺陷。

十五、一个完整的Codex工作流程

下面是一套适合日常开发的顺序：

第1步：确认工作区

git status --short

第2步：启动Codex并检查状态

codex

/status

第3步：只读分析

先分析相关代码和测试，不要修改。列出当前行为、目标行为、可能影响范围和缺失信息。

第4步：确认计划

高影响任务先使用/plan，小任务也应让Codex简要说明准备修改哪些文件。

第5步：实施最小变更

按确认的计划实施。不要重构无关代码，不新增依赖。遇到范围变化先暂停并说明。

第6步：运行验证

运行最接近改动的测试和项目规定的检查，记录完整命令与结果。

第7步：查看差异和审查

/diff
/review

第8步：人工验收

核对功能、代码差异、测试结果和未覆盖风险，再决定是否提交。

这套流程的重点是每个阶段都有可检查的产物：分析结果、计划、补丁、测试记录和差异审查。

十六、对话过长或需要继续旧任务怎么办

长时间开发可能占用较多上下文，可以输入：

/compact

它会把前面的对话压缩成摘要，保留关键任务信息。压缩后建议让Codex列出当前目标、已完成事项、剩余问题和下一步，确认摘要没有漏掉重要边界。

需要开始无关任务时：

/new

恢复旧会话：

/resume

退出CLI后，也可以从终端继续最近的会话：

codex resume --last

需要保留当前讨论并尝试另一种方案时：

/fork

这些操作改变的是聊天状态，不会自动撤销已经写入工作区的文件。切换会话前应先查看git status和git diff。

十七、常见问题及处理方法

1. Codex找不到命令

先运行：

codex --version

如果系统仍提示命令不存在，重新打开终端，检查安装是否成功，以及npm全局可执行目录是否在PATH中。

2. Codex读取了错误的项目

使用/status检查工作目录。退出后进入正确的项目根目录，再重新运行codex。

3. Codex一直要求确认

审批次数与当前权限、命令风险、网络访问和工作区边界有关。使用/permissions检查模式，不要通过永久关闭安全限制来解决普通配置问题。

4. Codex不能访问网络

本地命令默认可能处于无网络环境。先判断任务是否真的需要联网；如果只缺少依赖或资料，应按当前审批和组织策略处理。不要自行开启不受限制的网络访问。

5. Codex修改范围过大

暂停任务，查看/diff，然后明确：

只保留解决当前Bug所需的最小修改。不要整理格式、重命名变量或重构无关文件。先列出准备撤回的无关改动，等待确认。

不要在未确认用户改动来源时执行大范围回滚命令。

6. 测试显示通过，但功能仍然失败

检查测试是否覆盖真实复现路径。让Codex重新执行原始复现步骤，并列出测试没有覆盖的环境差异、数据条件和外部依赖。

7. Codex反复沿用错误前提

先明确指出哪条前提错误，并要求重新总结任务。如果对话已经混乱，可以整理正确背景后使用/new开始新聊天。

十八、六个可以直接修改使用的提示词

1. 阅读项目

先只读分析当前项目，不修改文件。
说明项目用途、启动入口、主要模块、数据流、测试命令和你无法确认的内容。
每条结论列出文件路径。

2. 定位Bug

根据下面的环境、复现步骤、预期结果、实际结果和完整报错定位Bug。
先复现并说明根因证据，再给最小修改方案。
不要改变无关功能；修复后运行回归测试。

3. 添加功能

实现【功能】。用户行为和完成标准如下：【要求】。
保持【接口/数据结构/兼容性】不变，不新增依赖。
先列修改计划和影响文件，确认后再编辑。

4. 补充测试

阅读【目标代码】和现有测试，列出尚未覆盖的关键分支。
只补充与【目标行为】有关的测试，沿用项目现有测试风格。
运行新增测试并汇报命令和结果。

5. 代码审查

审查当前未提交修改。
重点检查正确性、安全性、兼容性、错误处理和测试覆盖。
只报告有代码证据的问题，按严重程度排序并标出文件位置。

6. 修改完成后的交付说明

不要继续修改。请汇总：
1. 已解决的问题；
2. 修改过的文件及原因；
3. 运行过的命令和结果；
4. 未验证内容；
5. 建议人工检查的风险。

十九、提交代码前检查清单

• 当前工作目录是否正确；
• 原有未提交修改是否得到保留；
• Codex是否只修改了任务范围内的文件；
• 公开接口和数据格式是否意外变化；
• 是否添加了未经确认的依赖；
• 是否运行了相关测试和静态检查；
• 测试是否覆盖真实失败场景；
• 日志、代码和配置中是否出现密钥；
• 是否检查了git diff；
• 是否记录无法验证的内容；
• 数据库、文件删除和外部操作是否经过人工确认。

结语

这篇Codex使用教程的关键可以归纳为五个动作：先读代码，写清边界，小步修改，运行验证，人工审查。Codex能帮助开发者完成跨文件分析和本地开发任务，但最终代码质量仍取决于需求是否明确、权限是否合适、测试是否有效，以及提交前有没有认真检查差异。

第一次使用时，不必马上交给Codex一个大型改造任务。先从解释模块、修复可复现Bug或补充一条测试开始，熟悉它如何读取项目、请求权限、修改文件和报告结果，再逐步扩大任务范围。本篇文章由环球巴士整理，环球巴士是一站式账号服务平台（https://bit.ly/4yZyxTH ）

资料核对范围：OpenAI官方Codex CLI、Prompting、Developer commands、AGENTS.md及Agent approvals & security文档。命令和界面可能随版本更新，请以当前产品页面及CLI中的/命令菜单为准。