bozhouDev/codex-orange-book · 上手攻略

• 仓库：bozhouDev/codex-orange-book
• 链接：https://github.com/bozhouDev/codex-orange-book
• 分类：AI 编程工具 · Agent 指南
• 作者：Tom
• 更新：2026-07-24

这是什么

《ChatGPT 橙皮书》是一份中文非官方开源指南，围绕 OpenAI Codex 的全流程使用编写，目标是帮助开发者把 AI Agent 能力落地到真实项目中。内容覆盖 Codex App、Codex CLI、Codex IDE Extension、Codex Web 四大入口，涵盖安装配置、核心功能（自动化、插件、Skill、MCP、Git 工作流、Sites 等）、标准工作流和五个完整实战案例。

⚠️ 重要提醒：本指南为非官方社区整理，不代表 OpenAI 官方文档。Codex 更新频繁，安装方式、模型名称、额度和命令参数都可能变化；涉及具体功能和价格时请以 OpenAI 官方文档 和账号实际界面为准。

解决什么问题

AI 编程工具经历了四个阶段：

Codex 解决的核心里程碑问题是：从"帮你写代码"到"帮你交付任务"。它不只是回答"这段代码怎么写"，而是能进入真实项目、理解上下文、制定计划、修改文件、运行命令、检查 diff，最终把改动推进到可 review 的状态。

快速安装

方式一：Codex App 桌面版（新手推荐，功能最全）

支持 macOS 和 Windows，图形界面，无需记忆命令。

macOS： 1. 确认芯片类型（Apple M1-M4 → Apple Silicon 版；Intel Core i5/i7/i9 → Intel 版） 2. 进入 Codex App 官方页面，下载对应版本 3. 打开安装包，将 Codex 拖入「应用程序」文件夹 4. 首次打开时选择「打开」确认

Windows： 1. 进入 Codex App 官方页面，点击 Windows 下载入口 2. 跳转 Microsoft Store 后点击「获取/安装」 3. 打开 Codex App，完成登录

建议：首次使用选一个干净的练习目录，不要直接操作重要项目：

# 提前建好练习目录
mkdir -p ~/AI-Codex-Projects/hello-codex
cd ~/AI-Codex-Projects/hello-codex
git init   # 初始化 Git，方便回滚

方式二：Codex CLI（开发者推荐）

支持 macOS、Windows（WSL）、Linux。需要 Node.js 18+ 和 Git。

安装方式：

# 方式 A：npm（最通用，Node.js 18+）
npm install -g @openai/codex

# 方式 B：Homebrew（macOS）
brew install openai/tap/codex

# 方式 C：winget（Windows）
winget install OpenAI.Codex

验证安装：

codex --version

首次认证：

codex login
# 浏览器自动打开 → 登录 ChatGPT/OpenAI 账号 → 返回访问令牌

📌 注意：Windows 原生原生支持有限，建议通过 WSL（Windows Subsystem for Linux）或 PowerShell 使用。

方式三：Codex IDE Extension

适合已用 VS Code / Cursor / Windsurf 的开发者。在对应编辑器的扩展市场搜索「Codex」安装即可。

核心用法

Codex App 基础操作流程

1. 选择项目目录：Codex App 打开后，选择一个本地文件夹作为工作范围（类似"公司地址"）
2. 新建 Thread：每个任务开一个 Thread（类似"公司里的员工"），不要把所有任务塞进同一个 Thread
3. 输入任务：在任务窗口描述你要做什么，任务越具体越好
4. 等待 Codex 执行：它会读文件、改文件、跑命令，并显示执行过程
5. Review Pane 检查：改完后，打开右侧 Review Pane 查看实际 diff（绿色=新增，红色=删除）
6. 确认/评论：检查无误后接受，有问题留下评论让 Codex 继续修改

推荐第一个练习任务：

请帮我做一个简单网页，要求：
1. 黑色背景
2. 页面中间显示大字 Hello, Codex
3. 字体白色
4. 页面整体水平和垂直居中
5. 只使用 HTML 和 CSS

Codex CLI 基础命令

# 进入项目目录，启动 Codex 对话
cd ~/your-project
codex

# 首次运行会自动打开浏览器认证
# 认证后，进入交互式对话，可以直接问问题：
# "What does this repo do?"
# "Fix the login bug in auth.js"
# "Add unit tests for the user service"

# 查看帮助
codex --help

权限控制与沙盒（Sandbox）

Codex 可以读取、修改文件并运行命令，通过沙盒模式控制权限边界：

# 查看当前沙盒权限设置（在 Codex App 设置中）

⚠️ 安全建议： - 不要把密码 / API Key 直接写在代码里，用 .env 文件 - 操作前先 git commit，方便出问题回滚 - 生产数据库、真实用户数据不要交给 Codex 自动执行

核心能力一览

典型适用场景

适合 Codex 的任务特点：目标明确、范围可控、上下文清楚、结果能验证、失败能回滚。

• 接手陌生项目，先让 Codex 读懂代码结构
• 修复可复现的 Bug
• 为现有项目增加一个小功能（如新增设置页、表单校验）
• 补单元测试或边界条件
• 写项目文档或 README
• 优化前端页面
• 整理 PR 描述和 commit message

不适合直接交给 Codex 处理： - 生产数据库操作 - 真实用户数据处理 - 支付核心逻辑 - 大规模架构迁移 - 无备份的重要项目

坑与注意

1. 不要一开始就用真实重要项目：先用练习项目熟悉流程，熟悉 diff 查看方式，再逐步迁移到真实项目。

2. 任务要拆小：不要丢一个"帮我做一个完整平台"的大需求，先读项目 → 出方案 → 只改一个模块 → 跑测试 → 看 diff → 确认后再继续。

3. 每次看 diff 再接受：Review Pane 里的 diff 是真实改动，不要只看 Codex 的文字总结就结束。

4. 操作前先 Git 提交： bash git add . git commit -m "before Codex changes" 万一改坏了可以直接回退。

5. 沙盒权限要看清：不了解的命令先问 Codex 解释，不要盲目批准执行。

6. 不同入口项目互通：Codex App、Codex CLI、Codex IDE Extension 里打开的项目可能出现在同一个列表里，理解这是同一个项目在不同入口的展示，不是重复。

7. 第三方模型接入（如 CC Switch、DeepSeek）：属于非官方扩展玩法，记录在指南附录中，不属于 OpenAI 官方功能。

与同类对比

一句话区别： - Copilot 帮你补代码 - ChatGPT 帮你想代码 - Cursor 陪你改项目 - Claude Code 是终端里的长期搭档 - Codex 是 OpenAI 生态里的多端工程执行者

怎么选：已在 OpenAI/ChatGPT 生态、需要在多端（桌面 App / 终端 / IDE / Web）之间切换管理任务和 PR → 用 Codex；偏好纯终端工作流、长期待在项目里和 AI 持续协作 → 用 Claude Code。

一句话推荐结论

如果你已经使用 ChatGPT 生态，想把 AI 编程能力从"问答"提升到"任务交付"，Codex 是目前 OpenAI 体系内最完整的工程 Agent 入口——从桌面 App 到 CLI、从 IDE 插件到云端 GitHub 集成，值得作为日常开发流程的核心工具上手。

参考来源

• GitHub：https://github.com/bozhouDev/codex-orange-book
• 在线阅读：https://bozhoudev.github.io/codex-orange-book/
• 指南原文（Markdown）：https://raw.githubusercontent.com/bozhouDev/codex-orange-book/main/ChatGPT%E6%A9%99%E7%9A%AE%E4%B9%A6.md
• 指南版本：v0.2.0（2026-07-13 校验）
• Codex CLI 2026 最新动态：CodeGateway / Serenities AI / Apidog 等技术博客（2026-07）