OpenAI Codex 详细入门教学（2026 版）

Codex 是 OpenAI 推出的AI 编程智能体（Agent），它不止是简单的代码补全工具，还能自主读取项目文件、修改代码、执行终端命令、运行测试并输出可验证的修改结果，相当于一个可以在本地代码仓库中工作的 AI 工程师。截至 2026 年，Codex 已形成桌面客户端、命令行工具、开放 API 三大使用形态，底层搭载 GPT-5.x 系列代码增强模型，支持上百种编程语言与主流技术栈。

一、核心认知：Codex 能做什么

在正式上手前，先明确它的核心能力边界，避免预期偏差：

• 代码全生命周期处理：从零生成功能、解释陌生代码、定位修复 Bug、重构优化、生成单元测试
• 项目级理解：自动扫描整个代码仓库，梳理目录结构、依赖关系与业务逻辑
• 自主执行能力：可直接运行终端命令、安装依赖、执行 Lint 检查与测试用例
• 版本化协作：支持对话分叉（Fork）、Git Diff 审查、历史回溯，适配工程化开发流程

二、环境准备：安装与登录

Codex 提供桌面客户端（适合新手可视化操作）和命令行 CLI（适合熟练开发者高效使用）两种主流入口，二者共享账号与项目数据。

2.1 前置条件

• 账号：拥有 ChatGPT Plus / ChatGPT Pro 订阅账号，或 OpenAI API 账号
• 系统：支持 macOS 12+、Windows 10+ 主流版本
• 环境：本地需安装对应开发环境（如 Python、Node.js 等，用于运行生成的代码）

2.2 桌面客户端安装（新手推荐）

1. 下载安装包 前往 OpenAI 官方 Codex 页面（openai.com/codex）下载对应系统版本。Mac 下载后将安装包拖入「应用程序」文件夹完成安装；Windows 版本通过 Microsoft Store 自动部署。

2. 登录账号 打开客户端后，选择「使用 ChatGPT 账号登录」，在浏览器中完成授权即可。企业用户可选择 API Key 或企业令牌登录。

3. 基础配置（可选） 若需默认使用中文回复，可在终端执行以下命令写入全局配置：

   mkdir -p ~/.codex && printf 'Always respond in Chinese-simplified\n' > ~/.codex/AGENTS.md

2.3 命令行 CLI 安装

适合习惯终端操作的开发者，执行以下命令一键安装：

curl -fsSL https://codex.openai.com/install.sh | bash

安装完成后执行登录命令，按提示完成授权：

codex login
# 无浏览器环境可使用设备码登录
codex login --device-auth

三、快速上手：完成第一个编码任务

新手最容易犯的错误是一上来就让 AI 重构整个项目，正确的入门流程是**「先理解项目→再小步修改→最后验证审查」**，我们以一个本地 Python 项目为例完整走一遍流程。

3.1 创建第一个项目

1. 打开 Codex 桌面端，点击「新建项目」
2. 填写项目名称，选择本地代码仓库的文件夹路径
3. 设置权限级别（新手建议先选「允许修改文件」，暂不开启「允许执行命令」）
4. 点击创建，Codex 会自动扫描项目目录结构

3.2 第一步：让 AI 先理解项目

不要直接提修改需求，先让 Codex 完成项目认知，避免后续理解偏差。在对话框输入：

请先梳理这个项目的目录结构，说明每个核心模块的作用，以及项目的主要功能。

等待 Codex 输出项目说明，确认它的理解与实际一致后，再下发具体任务。

3.3 下发第一个小任务

我们以「给现有函数补充参数校验」为例，输入精准的任务指令：

目标：给 utils 目录下的 calculate_total 函数补充参数校验
上下文：文件路径是 src/utils/calc.py
约束：
1. 校验输入的 price 和 count 必须为非负数字
2. 参数非法时抛出 ValueError 并附带明确提示
3. 不修改原有计算逻辑
完成标准：补充后代码可正常运行，保留原有注释

提交后 Codex 会自动读取对应文件、完成修改，并输出修改前后的差异对比。

3.4 审查与确认

任务完成后务必做两步验证：

1. 查看 Diff：核对修改范围，确认没有无关代码被改动
2. 本地验证：手动运行代码或让 Codex 执行测试命令，确认功能符合预期 确认无误后，即可接受修改；如果结果不符合预期，可以继续补充指令调整。

四、5 大高频场景实战

掌握以下场景，基本可以覆盖日常开发 80% 的使用需求。

4.1 从零生成代码

适合快速搭建工具脚本、基础功能模块。 示例指令：

你是一名资深Python后端工程师，请编写一个CSV文件批量处理脚本。
功能：读取指定目录下所有csv文件，按「日期」字段去重合并，输出到新文件
输入参数：目录路径、输出文件名
约束：
1. 仅使用Python标准库，不引入第三方依赖
2. 处理大文件时逐行读取，避免内存溢出
3. 包含异常处理：文件不存在、格式错误的情况
输出：完整可运行代码 + 使用说明

4.2 解释陌生代码

接手老项目、阅读开源库时非常实用。 示例指令：

请详细解释 src/services/order.py 文件中 create_order 函数的逻辑，包括：
1. 整体执行流程
2. 每个参数的含义
3. 可能的返回值与异常场景
4. 设计上的优缺点

4.3 Bug 定位与修复

可以直接粘贴报错信息或截图，让 Codex 自动定位修复。 示例指令：

运行项目时出现以下报错，请定位原因并修复：
[报错信息粘贴在此处]
相关文件：src/api/user.py
约束：做最小必要修改，不要改动原有接口定义
修复后请说明问题原因和修改点

CLI 模式下还支持直接传入报错截图：

codex -i error.png "修复图中的报错"

4.4 代码重构优化

针对可读性、性能、规范统一等场景。 示例指令：

请重构 src/utils/string_helper.py 中的所有函数，要求：
1. 遵循PEP8编码规范，统一命名风格
2. 补充类型注解和文档字符串
3. 提取重复逻辑为公共工具函数
4. 完全保留原有功能，不改变对外接口
重构后列出主要的优化点

4.5 自动生成单元测试

示例指令：

为 src/utils/calc.py 中的所有函数编写 pytest 单元测试
要求：
1. 覆盖正常场景、边界值、异常输入三类用例
2. 测试文件命名为 test_calc.py，放在 tests 目录下
3. 不引入额外测试依赖
编写完成后运行 pytest 验证通过率

五、Prompt 编写黄金法则

Codex 的输出质量，90% 取决于指令的精准度。一个合格的任务指令必须包含核心要素，避免模糊表述。

5.1 标准四要素结构

完整的指令包含四个核心部分，每一部分都有明确的表达标准，能大幅降低 AI 的理解偏差：

• 目标：一句话说清最终要达成的效果。模糊表述如 "优化一下代码" 很难得到可用结果，清晰的表述如 "修复登录页刷新后白屏的 Bug"。
• 上下文：说明相关文件路径、技术栈、现有逻辑背景。不要只说 "登录相关的代码"，要明确到 "登录逻辑在 src/pages/login，路由守卫在 src/router/auth"。
• 约束：明确不能改动的范围、技术限制、规范要求。不要说 "尽量写好一点"，要给出具体限制，比如 "不能修改数据库表结构，必须兼容原有接口"。
• 完成标准：定义任务完成的判定条件和验证方式。不要用 "能用就行" 作为标准，要明确到 "补充对应测试用例，运行通过，且不影响原有登录流程"。

5.2 万能通用模板

直接套用即可覆盖绝大多数场景：

# 角色
你是一名资深[编程语言]开发工程师，精通[技术栈]，代码风格严谨规范。

# 目标
[一句话明确任务最终效果]

# 上下文
- 相关文件：[文件路径列表]
- 现有逻辑：[简要说明背景]
- 技术限制：[框架/库/版本要求]

# 约束条件
1. [约束1，如：仅使用标准库]
2. [约束2，如：不修改对外接口]
3. [约束3，如：必须处理异常]

# 输出要求
1. 先说明实现思路
2. 输出完整代码，附带注释
3. 最后说明注意事项与验证方法

5.3 新手常见误区

• ❌ 指令太笼统：「帮我写个管理系统」→ 没有边界的需求一定会输出无用结果
• ❌ 一步到位：「帮我重构整个项目」→ 大任务务必拆分成多个小步骤迭代
• ❌ 只看结果不验证：代码能跑不代表逻辑正确，务必核对核心逻辑
• ❌ 不提供上下文：只发一句「修复这个 Bug」，不贴报错也不说相关文件

六、进阶：CLI 与 API 调用

6.1 CLI 常用命令

日常开发中高频使用的命令如下：

• 快速生成代码：执行 codex "写一个Python文件下载脚本"，可直接输出可运行代码
• 交互式修改：直接输入 codex 进入交互模式，支持多轮对话、Tab 补全、历史搜索
• 执行任务：执行 codex exec "跑通当前目录的pytest"，会自动安装依赖并执行对应命令
• 修复报错：执行 codex -i error.png "修复图中错误"，可解析截图自动定位问题

6.2 API 调用入门

适合将 Codex 能力集成到自有产品中，当前可调用 gpt-5.3-codex 等模型，基础请求示例（Python）：

from openai import OpenAI

client = OpenAI(api_key="你的API_KEY")

response = client.chat.completions.create(
    model="gpt-5.3-codex",
    messages=[
        {"role": "system", "content": "你是资深Go语言开发工程师，输出简洁高效的代码"},
        {"role": "user", "content": "写一个并发安全的缓存工具类"}
    ],
    temperature=0.2,
    max_tokens=2048
)

print(response.choices[0].message.content)

关键参数说明：

• temperature：代码生成建议设为 0.1~0.3，数值越低输出越稳定，减少随机发散
• max_tokens：控制输出长度，复杂功能可适当调大该参数
• reasoning_effort：复杂逻辑任务可设为 high，提升推理深度

七、最佳实践与安全注意事项

1. 务必做好版本备份：使用 Codex 前确保 Git 工作区干净，每完成一个任务提交一次，方便出现问题时快速回滚
2. 权限分级使用：简单代码生成用只读权限，需要修改文件时再开放写权限，谨慎开启命令执行权限
3. 敏感信息防护：不要将密钥、密码、业务敏感数据传入 Codex，本地配置文件提前加入忽略列表
4. 小步迭代原则：复杂任务拆分成多个小任务，每一步都验证，避免一次性修改过多文件难以排查问题
5. 人工终审不可少：Codex 可能生成逻辑存在疏漏的代码，核心业务逻辑必须经过人工审核验证，不可直接全量上线