Codex 橙皮书解读：AI编程助手从安装到实战的全链路指南
这不是一篇工具推荐文，而是一份以真实项目为背景的实操记录
写在前面
这篇文章源于一份非官方的Codex开源指南。我会用尽可能直白的语言，把这份指南里真正有用的信息整理出来。
我的目标读者是两类人：
第一类是完全没用过AI编程工具，但想认真开始用的人。你可能听说过ChatGPT能写代码，但不知道怎么把它真正接入自己的项目里。
第二类是已经用过Cursor、Claude Code或者ChatGPT，想弄明白Codex到底有什么不同、值不值得切换的人。
文章会分四个部分来讲：
-
Codex到底是什么，和ChatGPT、Cursor、Claude Code有什么区别 -
怎么安装、怎么上手、从哪个入口开始最合适 -
核心功能里哪些是真正实用的 -
一套完整的工作流，从接手一个新项目到最终提交代码
这篇文章尽可能少讲概念、多讲操作。内容完全基于2026年6月22日可访问的公开信息，实际使用时请以官方文档和你账号里显示的内容为准。
第一部分：先搞懂Codex是什么
Codex不是“能写代码的ChatGPT”
很多人第一次听到Codex，会下意识把它理解成“又一个帮你写代码的AI工具”。如果你也这么想，可能会低估它真正重要的变化。
要理解Codex，需要先看过去几年AI编程工具经历了什么。
2021年是Copilot代表的补全时代。 那时AI主要负责代码补全：你写开头，它补后面；你写函数名，它补函数体。它像一个更聪明的输入法，让你写得更快，但项目怎么拆、文件怎么找、测试怎么跑，仍然靠人完成。
2022年ChatGPT带来了对话时代。 AI编程从“补全”进入“对话”。你可以直接问它报错原因、代码优化、接口写法。但问题在于它不在真实项目里，你需要复制代码、粘贴报错、手动补上下文，再把答案搬回项目。
2023到2024年是Cursor代表的项目协作时代。 AI真正进入编辑器，能看见文件、修改函数、跨文件重构。但它大多数时候仍依附在IDE里，你需要盯着它改、判断下一步、跑测试、整理提交。
2025年开始，Codex代表的工程Agent时代到来。 它不只是当年负责代码补全的模型，而是一个面向真实软件工程任务的执行者。它能读项目、解释代码、修bug、加功能、补测试、重构模块、运行命令、检查diff、整理PR说明。
一句话总结这个变化：AI的角色从“代码输入法”变成“问答伙伴”，再到“结对编程助手”，最后走向“工程Agent”。从帮你写代码，到帮你交付任务。
Codex具体能做什么
Codex真正擅长的，不是凭空生成一段代码，而是在真实项目里完成一组工程任务。
它可以读项目、找文件、理解上下文、制定计划、修改代码、运行命令、检查结果、整理diff，最后把任务推进到可以review的状态。
具体来说，它擅长这几类事情：
读懂一个陌生项目。 使用Codex的第一步，不应该是让它直接写代码，而是让它先读项目。它可以帮你快速搞清楚项目用什么技术栈、入口文件在哪里、核心模块在哪里、测试和构建命令是什么、哪些文件不能随便动。很多Codex任务失败，不是因为它不会写代码，而是因为它还没理解项目就被要求直接动手。
解释代码和梳理逻辑。 Codex可以帮你解释看不懂的代码：这个函数是做什么的、这个组件为什么这样写、接口调用链路是什么、状态从哪里来、这个bug可能和哪些文件有关。它不只是解释单个函数，还可以结合上下文梳理模块关系、数据流和潜在风险，对接手旧项目尤其有用。
修bug和加功能。 Codex很适合处理边界清楚的开发任务：修复一个可复现bug、新增一个设置页、新增一个表单校验、新增一个接口、新增一个导出按钮、优化一个前端页面。但不要直接把一个大项目丢给它，更好的方式是把任务拆小：先读项目、再出方案、只改一个模块、跑测试、看diff、确认没问题后再继续。
写测试、做重构。 Codex可以补单元测试、补边界条件、补异常场景、提取重复逻辑、拆分过长函数、整理组件结构、封装API请求。但这类任务必须加边界：不改变业务逻辑、不改公共API、不引入无关依赖、不大范围重构、修改后必须跑测试。
写文档和整理PR。 Codex很适合写README、安装说明、启动说明、接口文档、环境变量说明、项目结构说明、PR描述、commit message、更新日志。在Codex工作流里，文档本身就是上下文基础设施，文档越清楚，后续人和AI接手项目都会更轻松。
跑命令、看diff、做review。 Codex和普通聊天工具最大的区别之一，是它可以在项目环境里运行命令：运行测试、运行lint、运行typecheck、运行build、查看git status、查看git diff、搜索代码、检查修改结果。这让Codex不只是“猜答案”，而是可以验证结果。
不适合直接用Codex的场景
有一些情况不建议直接让Codex处理：生产数据库、真实用户数据、支付核心逻辑、权限和安全核心模块、大规模架构迁移、没有备份的重要项目、没有测试的核心业务、你自己也无法验收的任务。如果你判断不了结果对不对，就不要让Codex独立完成。
和ChatGPT、Cursor、Claude Code的区别
很多人会问：既然ChatGPT也能写代码，为什么还要用Codex？
核心区别在于：ChatGPT更像一个顾问，有问题问它，从它那里得到答案，然后自己去执行。Codex更像一个实习生，你能真正让它干活、交代任务让它完成。
更合理的用法是：先用ChatGPT想清楚方案，再用Codex进项目执行。ChatGPT适合帮你想问题，Codex适合帮你推进任务。
Codex和Cursor的区别： Cursor更像一个AI编辑器，Codex更像一个工程Agent。Cursor负责陪你写，Codex负责帮你跑完整任务。一个偏IDE协作，一个偏Agent执行。两者不是替代关系，可以组合使用。
Codex和Claude Code的区别： 两者都是agentic coding工具，但侧重点不一样。Claude Code更偏终端里的长期协作，适合长时间读项目、持续追踪复杂任务、在终端里边讨论边修改。Codex更偏OpenAI生态里的多端任务执行，可以通过CLI、App、IDE Extension、Web等多个入口使用，在App、CLI、IDE、Web之间流转，用不同方式管理、执行和审查工程任务。
具体选择哪个，要看模型能力、上下文处理、工具链、价格、团队习惯和你自己的开发流程。
第二部分：安装、配置与环境准备
账号准备
如果你是普通个人用户，需要准备一个ChatGPT账号，选择当前包含Codex的套餐。套餐名称、额度和功能范围会变化，以官方页面和你账号实际显示为准。
Codex的四个入口
Codex有四种使用形态，选哪个取决于你的工作习惯：
Codex App桌面版：适合想要图形界面的人，适合并行处理多个任务，适合查看diff、管理线程、切换项目，适合不想一直在终端里操作的用户。支持macOS和Windows，这是新手最推荐的入口，也是目前功能最强的方式。
Codex CLI：适合开发者，适合真实项目目录，适合命令行工作流，适合自动化脚本，适合和Git、测试命令、构建命令结合。支持macOS、Windows和Linux。
Codex IDE Extension：适合VS Code、Cursor、Windsurf等编辑器用户，适合边看代码边让Codex修改，适合前端页面、组件、局部重构，适合需要频繁查看代码上下文的人。
Codex Web：适合云端任务，适合连接GitHub后让Codex在远程环境中处理任务，适合团队协作、代码审查、PR流程，适合不想在本机暴露复杂环境的人。
选择建议：如果你主要做本地项目、网页练习和日常开发，优先从Codex App开始通常就够用。等你熟悉Git、终端和团队协作后，再逐步补CLI、IDE Extension和Web。
软件工具准备
安装Codex之前，建议先准备这些基础工具：Git（让Codex能看代码变更、生成diff、回滚修改），VS Code或Cursor（方便查看和编辑代码），终端（Windows用PowerShell，Mac用Terminal），浏览器，Node.js（做网页、前端、Next.js、Vite项目常用），Python（做脚本、自动化、数据处理常用），GitHub账号（如果要用Codex Cloud或推送代码）。
项目目录准备
Codex不是单纯聊天工具，它需要进入一个具体项目目录工作。建议提前建一个专门练习目录，比如D:\AI-Codex-Projects或~/AI-Codex-Projects，里面放hello-web、ai-tools-page、landing-page-demo这类练习项目。不要一开始就让Codex操作最重要的真实项目，先用练习项目熟悉它怎么改文件、跑命令、生成结果。
权限与安全准备
Codex可以读取、修改文件，还能在项目目录里运行命令。安装前要注意几点：不要直接放重要文件，先用测试项目；不要把密码或API Key写在代码里，用.env文件并避免上传；操作前先Git提交方便回滚；看清Codex要执行的命令，不懂的命令先问它解释；不要给它整个C盘权限，只选择具体项目文件夹。
推荐每个项目先初始化Git，这样Codex改坏了也可以回退。
Codex App安装与上手
macOS安装：先确认芯片类型。点击左上角Apple图标选择“关于本机”，如果显示Apple M1/M2/M3/M4就选Apple Silicon版本，如果显示Intel Core就选Intel版本。下载完成后把Codex拖进“应用程序”文件夹。
Windows安装：进入Codex App官方页面，选择Windows版本，会跳转到Microsoft Store安装，点击“获取”或“安装”即可。
第一次打开Codex App：登录完成后，系统会让你选择一个项目目录。建议第一次选择一个干净的练习目录。选择项目目录后，Codex才知道应该读哪些文件、改哪些文件、在哪个地方运行命令。
理解项目列表：进入Codex App后，左侧会看到项目列表。每一个项目都对应你电脑上的一个本地文件夹或Git仓库。项目列表不是聊天记录列表，而是代码项目列表，点进不同项目，Codex看到的文件范围也不一样。
理解Thread（对话）：Thread可以理解成同一个项目里的一个任务对话。比如在hello-codex这个项目里可以开多个thread：thread 1做一个首页，thread 2修复按钮点击无反应的问题，thread 3优化移动端样式。每个thread都有自己的上下文。不要把所有事情都塞进同一个thread，更好的做法是一个清楚的任务开一个thread。
理解任务窗口：任务窗口是你和Codex对话、安排工作的地方。你可以输入任务，也可以继续追问。任务窗口里通常会出现你的任务描述、Codex的计划、Codex的执行过程、Codex的总结和后续输入框。第一次使用时不要写太复杂的任务，任务越清楚Codex越容易做好。
理解Review Pane：Review pane是检查Codex改了什么的地方。Codex改完文件后，不要只看文字总结，要打开review pane看实际改动。它会告诉你哪些文件被修改了、哪些地方新增了代码、哪些地方删除了代码、哪些改动可以接受、哪些可以退回。
理解Diff：Diff是代码改动对比，绿色代表新增内容，红色代表删除内容。不要只看最终页面，也不要只看Codex的总结，真正重要的是看diff。每次Codex完成任务后，先看diff，再决定要不要接受。
第一次打开后的推荐操作流程：登录ChatGPT → 选择一个练习项目目录 → 新建或选择一个thread → 在任务窗口输入一个简单任务 → 等Codex修改文件 → 打开review pane → 查看diff → 确认没有问题后再继续修改。
推荐第一个任务：请帮我做一个简单网页，黑色背景，页面中间显示大字Hello Codex，字体白色，页面整体水平和垂直居中，只使用HTML和CSS。
Codex CLI安装与上手
macOS安装：前提是已经安装Node.js。打开Terminal，输入npm install -g @openai/codex，安装完成后输入codex --version检查是否成功，或者直接运行codex。也可以用Homebrew安装：brew install --cask codex。
Windows安装：使用PowerShell或Windows Terminal。第一步安装Node.js，安装完成后输入node -v和npm -v能看到版本号说明安装成功。第二步安装Codex CLI：npm install -g @openai/codex。第三步检查是否安装成功：codex --version或直接运行codex。Windows用户第一次使用时，建议不要在系统目录里运行Codex，不要在这些位置直接操作：C盘系统目录、桌面、下载文件夹、重要资料文件夹。建议新建一个练习目录。
第一次运行：安装完成后在终端输入codex，第一次运行会提示登录。登录方式有两种：ChatGPT账号登录（最适合普通用户）和API Key登录（更适合开发者、自动化、CI/CD）。登录流程是终端输入codex或codex login，选择Sign in with ChatGPT，浏览器自动打开登录页面，输入ChatGPT账号，登录成功后浏览器把登录结果传回终端。
Codex CLI常用命令
启动相关：codex启动Codex CLI，codex --version查看版本，codex --help查看帮助。
登录相关：codex login默认打开浏览器用ChatGPT账号登录，codex login --device-auth用设备码登录远程服务器，codex login status查看当前登录状态，codex logout退出登录。
项目相关：先cd 项目目录进入项目文件夹，再codex让Codex在当前项目工作。也可以用codex --cd 项目路径指定目录启动。
新手最推荐记住的命令：codex启动、codex login登录、codex login status检查登录状态、codex doctor排查环境问题、codex --version查看版本、codex resume --last接着上次任务继续、codex archive归档不用的任务、codex update更新Codex、codex exec "任务"一次性执行任务、codex logout退出登录。
CLI斜杠命令
斜杠命令是在进入Codex后，在输入框里输入使用的命令。
最常用的包括：/diff查看代码改动，/plan进入计划模式先让Codex给方案不急着改代码，/permissions调整权限控制Codex能不能改文件、联网、运行命令，/model选择模型和推理强度，/status查看当前状态，/init生成AGENTS.md创建项目规则文件，/compact压缩长对话，/quit退出Codex CLI。
新手不用全部背，先记住这几个就够了。
Codex IDE Extension
把Codex直接装进代码编辑器里，不用单独打开Codex App，也不用一直切到终端，可以在VS Code、Cursor、Windsurf这类编辑器侧边栏里直接使用Codex。
安装步骤：打开VS Code或Cursor → 进入扩展市场Extensions → 搜索Codex → 安装OpenAI的Codex扩展 → 安装完成后重启编辑器 → 在侧边栏找到Codex图标 → 点击Codex登录账号 → 打开项目文件夹开始使用。
Codex IDE Extension能做什么：读当前文件、看选中代码、修改代码、运行命令、修复报错、生成文档、切换模型、调整推理强度、控制权限。
Codex Web
在网页里使用的云端Codex，不需要一直开着本地电脑，可以连接GitHub仓库，让Codex在云端环境里读取代码、执行任务、修改文件，并生成可review的结果。
Codex Web的入口是chatgpt.com/codex。打开后需要登录ChatGPT账号，进入Codex页面，连接GitHub账号，选择要处理的仓库，创建一个云端任务，等Codex在云端运行，查看结果和diff，满意后创建Pull Request。
本地Codex是在你电脑上干活，Codex Web是在云端帮GitHub仓库干活。
新手建议：先用Codex App做本地练习，会GitHub后，再用Codex Web处理仓库任务。
第三部分：核心功能详解
自动化
Codex自动化可以理解为让Codex不只是“听你指挥”，而是能按规则定期帮你巡查项目、发现问题、处理问题。就像给项目请了一个AI值班工程师，平时不打扰你，有问题它来提醒，简单问题它先尝试修，最后让你审核决定。
使用示例：让Codex定期检查最近一段时间的会话记录、任务结果和常见问题，沉淀成一份可复用的工作流程方案。
插件
插件是给Codex额外安装的“能力包”。Codex本身已经能读代码、改代码、运行命令，插件是在这个基础上让它连接更多工具、使用固定流程，或者获得某些专项能力。
常见插件类型包括：Chrome插件让Codex操作浏览器，GitHub插件管理仓库，Computer Use让Codex操作电脑上的应用，Build Web Apps生成网页应用，Figma设计稿转代码，Documents生成文档，Presentations生成PPT，Spreadsheets分析表格数据，HyperFrames和Remotion生成视频。
Skill
Skill是给Codex准备的一套“固定工作方法”。如果你经常让它做同一类任务，比如写README、做代码Review、生成网页、整理文档，就可以把这套流程做成Skill。
Skill和普通提示词的区别：普通提示词每次手动输入，容易漏要求，适合临时任务；Skill保存成固定能力，更稳定，适合重复任务，可以包含指令、模板、资料和脚本。
什么时候适合做Skill：同一类任务经常重复做、每次都要写一堆规则、想让Codex输出更稳定、团队里多人要用同一套流程。
Skill的基本结构包括：适用场景、工作目标、工作流程、输出格式、注意事项。
在Codex App里添加Skill有两种方式：使用已有Skill（在插件里面看系统推荐的Skill），或者创建自己的Skill（在thread里输入$skill-creator，它会帮你把一套重复流程整理成Skill）。
MCP
MCP是让Codex连接外部工具的接口。Codex本身可以读代码、改代码、运行命令，MCP的作用是让Codex连接更多外部工具、数据源或服务。
生活化理解：Codex是一个会干活的人，MCP是给他接上不同工具的插座，MCP Server是插在插座上的工具箱，Tool是工具箱里的具体工具。
MCP适合做什么：查开发文档、连接数据库、连接设计工具、连接项目管理工具、连接内部系统、连接知识库、连接自动化工具。普通写代码不一定需要MCP，需要Codex访问外部工具或外部数据时才考虑MCP。
代码管理（Git与GitHub工作流）
用Codex做真实项目时，一定要懂一点Git和GitHub。Git负责记录代码变化，GitHub负责远程保存和协作，Codex负责帮你完成具体编程任务。
为什么用Codex更需要Git：Codex改了很多代码可以查看具体改了哪里，改错了可以回退，删除了不该删的内容可以用Git找回，多次让Codex修改每次commit保存一个阶段，想让Codex大胆试方案用branch或worktree隔离风险。
记忆系统
让Codex记住一些长期有用的信息，方便以后继续工作。
AGENTS.md是写给Codex看的项目规则说明书。README.md是告诉人这个项目是什么、怎么安装、怎么使用，AGENTS.md是告诉AI在这个项目里应该怎么工作。
AGENTS.md放在项目根目录影响整个项目，放在子目录影响当前子目录，放在~/.codex/AGENTS.md影响所有项目。可以直接让AI总结项目核心内容制作成AGENTS.md。
第四部分：标准工作流
很多人刚开始用Codex会直接一句话丢给它：帮我做一个网站。这样不是不行，但很容易出现问题：AI改得很快，但你不知道它到底改了什么，也不知道能不能放心交付。
真正稳定的方式，是按照一套固定工作流来推进。需求不是直接变成交付物，中间必须经过理解、计划、修改、验证、检查、验收这几步。
标准六步法
第一步：需求拆解。 在让Codex修改项目之前，先拆需求。要说明背景是什么、要解决什么问题、哪些文件可能相关、哪些功能不能动、什么结果算完成、需要哪些测试、有哪些风险。这样可以给Codex画边界，避免它乱改。
第二步：制定计划。 需求拆解完成后，不要马上让Codex写代码，先让它制定计划。先计划后执行、先确认后修改。可以开启计划模式或输入/plan，让Codex先输出计划再决定是否执行。
第三步：小步实现。 一次只改一个功能点，改完一小步就检查一小步。不要让Codex一次性把所有东西都改完，也不要让它顺手重构无关代码。遇到不确定的情况先停下来问。
第四步：测试。 Codex完成修改后，不能马上进入下一步，必须先测试。包括单元测试、类型检查、lint检查、构建测试、手动测试、浏览器测试、回归测试。不是相信Codex说“完成”，而是用结果证明它真的完成。
第五步：代码审查。 测试通过后还需要做代码审查，不只是看代码能不能跑，还要看代码改得对不对、稳不稳、有没有风险。两轮审查：先让Codex自查，再人工审查。重点盯四类高风险问题：边界条件、安全问题、误删代码、业务逻辑。
第六步：提交与复盘。 代码测试通过、审查完成后，要做三件事：正式提交（生成好的commit message和PR描述）、记录问题（把这次过程中遇到的问题记录下来）、沉淀经验（把有效Prompt和规则更新到AGENTS.md）。
任务模板库
读项目模板：适合刚打开一个新项目时使用，让Codex先输出项目理解报告，包括技术栈、目录结构、启动方式、测试命令、核心模块、后续修改风险。
修Bug模板：描述现象、复现步骤、期望结果、实际结果、相关文件，让Codex先定位原因再修改。
加功能模板：描述功能、入口位置、交互流程、视觉要求、数据来源、验收标准，让Codex先给实现计划。
前端页面模板：描述页面用途、目标用户、视觉风格、功能需求、验收标准。
代码Review模板：让Codex按结构审查潜在bug、边界条件、安全风险、类型问题、性能问题、无关修改、测试是否充分。
第五部分：实战案例
案例一：制作宠物零食售卖前端页面
从零开始制作可发布在网上的前端网页。在本地创建文件夹命名为Pet treats，在Codex App里选择这个文件夹，开启计划模式生成初步项目计划，检查没问题后直接执行。打开index.html文件预览，创建Git仓库进行代码管理，用注释在页面进行细节修改，检查没问题后推送更新的代码到GitHub，通过GitHub Pages发布网页让其他人也能访问。
案例二：给宠物零食网站增加功能
新建用户登录注册页面，创建不同宠物分类并在分类下进行食品分类，先用计划模式看AI是否理解需求，用注释功能优化细节，选择食品加入购物车后点击购买时提示确认地址。
案例三：制作管理后台
依旧先使用计划模式，确认需求理解正确后再执行。
案例四：制作招商PPT
安装PPT Skill，把GitHub上对应的Skill地址发给Codex让它安装，使用斜杠选择对应的Skill，Codex最终生成完整的招商PPT。
案例五：制作宣传视频
安装HyperFrames Skill用于视频制作，让Codex计划生成视频，成品是宠物零食的宣传视频。
附录：第三方模型接入
本节介绍第三方模型接入的非官方思路，以CC Switch加DeepSeek为例。它不属于OpenAI官方功能，模型兼容性、稳定性、隐私和费用规则以对应第三方工具与模型服务商为准。
CC Switch是一个第三方开源桌面工具，用来统一管理不同Agent工具。以前要手动改Claude Code、Codex、Gemini CLI的配置文件，现在CC Switch做成可视化面板一键切换。
核心用途有三个：Provider切换（从官方Claude API切到中转API或另一个模型服务）、MCP统一管理（不用分别给不同工具配MCP）、Skills管理（从GitHub或ZIP安装Skill并同步到不同AI编程工具）。
使用流程：进入ccswitch.io下载，找到DeepSeek官网创建API Key，打开CC Switch点击添加模型，将API Key复制进去，开启本地路由映射，进入设置将路由全部打开，点击启用。如果配置兼容，再打开Codex就可能通过这套非官方路由使用DeepSeek等第三方模型。
这类方式不属于OpenAI官方功能，能否正常使用、模型能力、上下文长度、工具调用兼容性、费用和隐私规则，都要以CC Switch、模型服务商和你自己的配置为准。重要项目建议先用测试仓库验证，不要直接在生产项目里试。
最后说几句
这篇文章整理了Codex橙皮书的核心内容。AI编程工具发展很快，今天写的内容在几个月后可能部分已经过时。但有两个东西不太会变：一是工程化的思维方式——先理解项目再动手、小步迭代、重视测试和审查；二是工具背后想要解决的问题——让开发者把更多精力放在“做什么”而不是“怎么做”上。
如果你刚准备开始用Codex，我的建议是从Codex App加一个简单的HTML练习项目开始，花一两个小时走通完整流程，比看再多文档都管用。
