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 桌面客户端安装新手推荐下载安装包 前往 OpenAI 官方 Codex 页面openai.com/codex下载对应系统版本。Mac 下载后将安装包拖入「应用程序」文件夹完成安装Windows 版本通过 Microsoft Store 自动部署。登录账号 打开客户端后选择「使用 ChatGPT 账号登录」在浏览器中完成授权即可。企业用户可选择 API Key 或企业令牌登录。基础配置可选 若需默认使用中文回复可在终端执行以下命令写入全局配置mkdir -p ~/.codex printf Always respond in Chinese-simplified\n ~/.codex/AGENTS.md2.3 命令行 CLI 安装适合习惯终端操作的开发者执行以下命令一键安装curl -fsSL https://codex.openai.com/install.sh | bash安装完成后执行登录命令按提示完成授权codex login # 无浏览器环境可使用设备码登录 codex login --device-auth三、快速上手完成第一个编码任务新手最容易犯的错误是一上来就让 AI 重构整个项目正确的入门流程是「先理解项目→再小步修改→最后验证审查」我们以一个本地 Python 项目为例完整走一遍流程。3.1 创建第一个项目打开 Codex 桌面端点击「新建项目」填写项目名称选择本地代码仓库的文件夹路径设置权限级别新手建议先选「允许修改文件」暂不开启「允许执行命令」点击创建Codex 会自动扫描项目目录结构3.2 第一步让 AI 先理解项目不要直接提修改需求先让 Codex 完成项目认知避免后续理解偏差。在对话框输入请先梳理这个项目的目录结构说明每个核心模块的作用以及项目的主要功能。等待 Codex 输出项目说明确认它的理解与实际一致后再下发具体任务。3.3 下发第一个小任务我们以「给现有函数补充参数校验」为例输入精准的任务指令目标给 utils 目录下的 calculate_total 函数补充参数校验 上下文文件路径是 src/utils/calc.py 约束 1. 校验输入的 price 和 count 必须为非负数字 2. 参数非法时抛出 ValueError 并附带明确提示 3. 不修改原有计算逻辑 完成标准补充后代码可正常运行保留原有注释提交后 Codex 会自动读取对应文件、完成修改并输出修改前后的差异对比。3.4 审查与确认任务完成后务必做两步验证查看 Diff核对修改范围确认没有无关代码被改动本地验证手动运行代码或让 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等模型基础请求示例Pythonfrom openai import OpenAI client OpenAI(api_key你的API_KEY) response client.chat.completions.create( modelgpt-5.3-codex, messages[ {role: system, content: 你是资深Go语言开发工程师输出简洁高效的代码}, {role: user, content: 写一个并发安全的缓存工具类} ], temperature0.2, max_tokens2048 ) print(response.choices[0].message.content)关键参数说明temperature代码生成建议设为 0.1~0.3数值越低输出越稳定减少随机发散max_tokens控制输出长度复杂功能可适当调大该参数reasoning_effort复杂逻辑任务可设为high提升推理深度七、最佳实践与安全注意事项务必做好版本备份使用 Codex 前确保 Git 工作区干净每完成一个任务提交一次方便出现问题时快速回滚权限分级使用简单代码生成用只读权限需要修改文件时再开放写权限谨慎开启命令执行权限敏感信息防护不要将密钥、密码、业务敏感数据传入 Codex本地配置文件提前加入忽略列表小步迭代原则复杂任务拆分成多个小任务每一步都验证避免一次性修改过多文件难以排查问题人工终审不可少Codex 可能生成逻辑存在疏漏的代码核心业务逻辑必须经过人工审核验证不可直接全量上线