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

第二步：安装Codex CLI

# npm 安装（推荐，全平台通用）
npm install -g @openai/codex

# macOS 还可以用 Homebrew
brew install --cask codex

国内用户如遇安装缓慢，可使用淘宝镜像

npm i -g @openai/codex --registry=https://registry.npmmirror.com

第三步：登录验证

codex login

浏览器会自动弹出授权页面，使用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/"]

这样在受信任项目目录中，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

第二步：编写需求提示词

在Codex的对话界面输入：

请帮我开发一个电影评分网站，具体要求如下：

1. 使用 React + Vite（项目已初始化）
2. 电影列表页面，每部电影展示封面、标题、简介、评分
3. 用户可以点击星星给电影打分（1-5星）
4. 搜索框支持按电影名过滤
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输入验证

批量处理与定时任务

使用exec模式配合crontab实现定时任务：

# 每天凌晨3点自动运行测试
0 3 * * * cd /path/to/project && codex exec "运行全部测试并生成报告"

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 <name>	切换模型
/permissions	切换权限模式
/mcp	查看MCP连接状态
/memories	管理记忆功能

B. Codex安装配置检查清单

• Node.js ≥ 18 已安装

• Git 已安装（推荐）

• npm install -g @openai/codex 安装成功

• codex login 登录成功

• codex --version 可输出版本号

• 项目目录已初始化Git仓库

• 权限模式已按需配置

C. 示例提示词模板

模板1（新项目脚手架）：
"创建一个基于 [框架] 的 [项目类型]，包含：
1. 项目结构说明
2. 核心功能模块代码
3. 基础样式和路由配置"

模板2（调试）：
"运行 [命令] 时报错：'[错误信息]'。请分析原因并修复，涉及的文件是 [文件路径]。"

模板3（代码审查）：
"请审查当前项目的代码质量，重点关注：
1. 安全性漏洞
2. 性能瓶颈
3. 代码规范问题
输出一份Markdown格式的审查报告。"