1.1 Codex简介：OpenAI的AI编程助手核心优势
近年来，AI编程工具如雨后春笋般涌现，从Cursor到Windsurf，从Copilot到Claude Code，每款工具都有自己的拥趸。而在2025年年中，OpenAI发布了Codex CLI——一款直接在终端运行的AI编码代理，它不仅开源，而且强大到能直接操作你的文件系统、执行命令、生成完整项目。
从技术层面看，Codex CLI基于Rust构建，拥有极快的响应速度（240+ tokens/s，比Claude快约2.5倍），并且原生支持并行任务执行。从成本角度看，Codex在完成同等任务时消耗的Token大约是Claude Code的三分之一。
1.2 适用人群
编程新手：只需用自然语言描述需求，Codex就能帮你生成代码、搭建项目
效率提升需求者：厌倦了重复性编码工作，希望借助AI自动化日常开发任务
AI工具爱好者：喜欢在终端环境工作，追求轻量、高效、可控的开发体验
和Claude Code偏重生产级系统与复杂代码库的风格不同，Codex更像一把锋利的瑞士军刀——轻量、快速、灵活，特别适合快速原型开发。
1.3 本文目标
读完本文你将能够：独立完成Codex的安装与配置、掌握五种核心操作模式、理解线程系统与项目分层管理、运用Skills和MCP扩展工具链，并亲手完成一个完整的实战项目。
二、安装与配置：迈出第一步
2.1 获取Codex：三步搞定
Codex CLI的安装异常简单，只需确保Node.js ≥ 18，然后在终端执行一行命令即可。
第一步：环境检查
node --version # 确保 ≥ 18
git --version # 推荐安装Git
AI写代码
第二步：安装Codex CLI
npm 安装（推荐，全平台通用）
npm install -g @openai/codex
macOS 还可以用 Homebrew
brew install --cask codex
AI写代码
国内用户如遇安装缓慢，可使用淘宝镜像
npm i -g @openai/codex --registry=https://registry.npmmirror.com
AI写代码
第三步：登录验证
codex login
AI写代码
浏览器会自动弹出授权页面，使用ChatGPT账号（Plus/Pro/Team/Enterprise均可）完成授权。
安装完成后用 codex --version 验证，若输出版本号则安装成功。
2.2 环境配置与系统要求
条件 要求
操作系统 macOS 12+ / Ubuntu 20.04+ / Debian 10+ / Windows WSL2
运行时 Node.js ≥ 18
内存 至少4GB（推荐8GB）
账号 ChatGPT Plus/Pro/Team/Enterprise 或 OpenAI API Key
Windows用户建议通过WSL2使用；macOS和Arm Linux用户安装无缝。
2.3 初始化设置：让Codex更懂你
权限模式：安全与效率的平衡
Codex提供三种沙箱安全级别：
模式 权限 适用场景
read-only 仅读取文件，只提供建议 审查代码、学习理解
workspace-write（默认） 可在工作目录内写文件 日常开发，推荐使用
danger-full-access 无沙箱限制，完整系统访问 在容器/VM中运行，高级用户使用
模型选择
Codex支持多种OpenAI模型，在会话中随时切换：
/model gpt-5-codex # 生产级代码模型，适合复杂任务
/model gpt-5-mini # 快速轻量模型，适合简单任务
主题与快捷键定制
Codex的交互界面（TUI）可在 ~/.codex/config.toml 中自定义主题颜色、快捷操作等，具体参数参见官方文档。
三、基础操作：5分钟掌握核心功能
3.1 文件管理技巧
文件夹结构解析
Codex的数据默认存储在 ~/.codex/ 目录下：
sessions/ — 当前活跃的线程记录
sessions_archived/ — 已归档的对话
config.toml — 全局配置文件
skills/ — 自定义Skills存放处
提示：尽量不要手动移动这些文件。如需归档，使用Codex内置的归档功能，避免数据错乱。
项目文件夹 vs. 线程系统
每次启动Codex时，当前工作目录会成为该线程的“项目文件夹”。一个线程绑定一个项目目录，切换项目只需在对应目录下启动新线程即可。
3.2 命令与交互
常用命令速查
命令 功能
/new 开启新对话线程
/list 列出所有线程
/model [模型名] 切换模型
/mcp 管理MCP连接
/permissions 切换权限模式
/memories 管理记忆功能
提示词编写基础
新手编写提示词时记住一个原则：任务描述越具体，Codex输出越精准。推荐“需求目标 + 技术栈指定 + 约束条件”三段式写法：
错误示范：“写个登录接口”
正确示范：“创建一个用户登录系统，包含：1. MySQL用户表设计 2. Node.js Express登录接口 3. JWT Token认证。框架用Express+TypeScript，密码需bcrypt加密。”
3.3 权限管理实战
每次需要访问工作目录以外的文件时，Codex会弹出确认提示。你可以在 ~/.codex/config.toml 中预先配置受信任的目录：
[sandbox]
trusted = ["/home/user/Projects/"]
AI写代码
这样在受信任项目目录中，Codex将自动获得更宽松的权限，减少频繁确认的烦恼。
四、核心特性深度解析：Codex的“智能内核”
4.1 线程系统与项目分层管理
Codex围绕三个核心要素构建工作流：
Thread（线程）：你与Codex之间的一条完整对话。每个线程维护独立的历史记录和上下文，持久化存储为JSONL格式的rollout文件。
Turn（轮次）：一次完整的交互往返（提出问题 → AI处理 → 执行操作）。
Item（条目）：构成一次Turn的最小单元，包括用户消息、技能调用、文件修改、MCP工具调用等。
线程可以被恢复（codex resume）、归档、分支创建（thread/fork），让你在不同任务之间自由切换而不丢失上下文。
4.2 可视化Skills管理
Skills是Codex的可扩展能力单元。你可以理解为“给AI安装自定义工具”。
创建一个Skill只需两步：在 ~/.codex/skills/ 目录下创建Markdown文件，描述Skill的功能和使用说明；然后在Codex中通过 $skill-name 调用。例如你可以创建“浏览器调用”Skill让Codex自动打开网页，或“API集成”Skill自动调用第三方API。
如果需要跨工具管理Skills，开源社区已有 @omrikais/skill-manager 这样的工具，可在Claude Code和Codex之间统一管理Skills。
4.3 记忆功能：让Codex“越用越懂你”
Codex支持记忆功能，让AI在多次会话之间保持对你偏好和项目规则的认知：
text
/memories enable # 开启记忆
记忆会在下一次会话中生效。使用场景包括：让Codex记住你偏好TypeScript而非JavaScript、记住项目的特定目录结构约定、记住API密钥位置等敏感信息。
4.4 高效模式选择：快速 vs. 精准
Codex通过“批准模式”来平衡效率与安全：
Suggest（建议）模式：所有写操作都需确认，适合学习和审查代码
Auto（自动）模式（默认）：工作区内自动执行，外部操作需确认
Full-Access（全自动）模式：完全自主执行，禁用网络但可操作有限目录
日常开发用Auto模式最顺手——改动工作区文件无需每次确认，但涉及系统级操作时仍会征求你的意见。
五、实战案例：从零开发一个电影评分网站
5.1 任务描述与拆分
目标：用Codex从零构建一个单页电影评分网站，包含电影列表、评分功能、搜索过滤。
技术栈：React + Vite（前端）、JSON Server（模拟后端）、CSS Modules（样式）
5.2 Codex操作流程
第一步：创建项目并启动Codex
mkdir movie-rating && cd movie-rating
npm create vite@latest . -- --template react
codex
AI写代码
第二步：编写需求提示词
在Codex的对话界面输入：
请帮我开发一个电影评分网站，具体要求如下：
- 使用 React + Vite（项目已初始化）
- 电影列表页面，每部电影展示封面、标题、简介、评分
- 用户可以点击星星给电影打分（1-5星）
- 搜索框支持按电影名过滤
- 使用 json-server 模拟后端 API，电影数据放在 db.json 中
请从安装依赖开始，逐步完成所有功能。每次写入文件前先向我展示代码差异。
第三步：监控执行过程与调试技巧
Codex会逐步执行：安装 json-server 和 concurrently 依赖 → 创建 db.json 模拟数据 → 编写组件代码（MovieList、MovieCard、SearchBar、StarRating）→ 配置并发启动前后端 → 添加样式。
如果在执行过程中出现问题（如依赖冲突），直接告诉Codex错误信息，“安装 XX 包时报错，错误信息是 XXX，请帮我解决”，它会读取错误日志并提出修复方案。
第四步：检查与部署
任务完成后检查项目根目录下的文件结构是否完整，然后验证效果：
npm run dev
浏览器中应该能看到完整的电影评分网站。
5.3 进阶：Codex Exec模式——无交互自动化
除了交互式对话，Codex还支持 exec 模式，适合CI/CD场景：
codex exec "运行 npm test 并修复所有失败的测试用例"
Exec模式通过JSONL事件流输出结果，不依赖终端UI，是构建自动化的利器。
六、避坑指南与优化建议
6.1 常见错误汇总
版本回归问题：更新Codex后若出现命令失效等情况，用 npm install -g @openai/codex@版本号 回退到稳定版本
WSL路径问题：Windows WSL2用户应将项目放在WSL的Linux文件系统中（/home/目录下），而非 /mnt/c/ 的Windows分区
长时间任务中断：设置系统不进入休眠模式，或使用 tmux/screen 保持会话存活
权限错误：如果Codex反复要求权限确认，检查是否在受信任目录中运行，或调整 config.toml 设置
6.2 效率优化技巧
使用 AGENTS.md 定制项目专属规则
在项目根目录创建 AGENTS.md（或 codex.md），编写项目约定，Codex会在每次会话开始时自动读取：
项目约定
- 后端: Node.js + Express + TypeScript
- 数据库: PostgreSQL + Prisma ORM
- 测试: Vitest（单元）+ Playwright（e2e）
- 提交前必须运行
npm test - 所有API端点需要Zod输入验证
AI写代码
批量处理与定时任务
使用exec模式配合crontab实现定时任务：
每天凌晨3点自动运行测试
0 3 * cd /path/to/project && codex exec "运行全部测试并生成报告"
AI写代码
MCP扩展工具链
Codex通过MCP（Model Context Protocol）集成外部工具。以连接SonarQube代码质量检测为例，在 ~/.codex/config.toml 中添加MCP配置后，Codex就能直接调用SonarQube的代码扫描能力。
6.3 资源管理：监控Token消耗
Codex的Token效率在同级工具中表现优异，但仍建议：将大体量任务拆分为小步骤分别执行、定期归档不用的线程释放存储空间、复杂任务用 gpt-5-codex，简单任务用轻量模型节省Token。
七、总结与进阶路线
7.1 Codex学习资源推荐
官方文档：developers.openai.com/codex/cli
GitHub仓库：github.com/openai/codex（开源，可查看源码）
社区扩展：oh-my-codex（OMX）——为Codex添加标准化的四步工作流和并行执行管理
7.2 下一步探索方向
高级MCP开发：自己编写MCP服务器，让Codex对接内部API、数据库等
OpenAI生态整合：Codex与ChatGPT、Atlas深度集成，实现全链路AI开发
构建私有化AI工作站：通过Azure Foundry在合规边界内部署Codex，适用于企业场景
Codex不只是一款AI编程工具，它正在重新定义“开发”这件事。从写下第一条提示词开始，你就已经站在了AI驱动开发的新起点上。
附录
A. 快捷键与命令速查表
快捷键/命令 功能
Ctrl+C 中断当前执行
/new 开启新线程
/list 查看所有线程
/model 切换模型
/permissions 切换权限模式
/mcp 查看MCP连接状态
/memories 管理记忆功能
B. Codex安装配置检查清单
Node.js ≥ 18 已安装
Git 已安装（推荐）
npm install -g @openai/codex 安装成功
codex login 登录成功
codex --version 可输出版本号
项目目录已初始化Git仓库
权限模式已按需配置
C. 示例提示词模板
模板1（新项目脚手架）：
"创建一个基于 [框架] 的 [项目类型]，包含：
- 项目结构说明
- 核心功能模块代码
- 基础样式和路由配置"
模板2（调试）：
"运行 [命令] 时报错：'[错误信息]'。请分析原因并修复，涉及的文件是 [文件路径]。"
模板3（代码审查）：
"请审查当前项目的代码质量，重点关注：
- 安全性漏洞
- 性能瓶颈
- 代码规范问题
输出一份Markdown格式的审查报告。"
