Codex新手入门推荐：零基础快速上手指南

近年来，AI编程工具的热度几乎没断过——Cursor、Windsurf、Copilot、Claude Code……每出一款新工具，社区里都会掀起一波讨论。直到2025年年中，OpenAI放出了Codex CLI，一款直接在终端里运行的AI编码“瑞士军刀”。它不光开源，还能直接操作你的文件系统、执行命令、生成完整项目，速度还快得离谱。 从底层看，Codex CLI基于Rust构建，响应速度达到240 tokens/s，比Claude快大约2.5倍；同时原生支持并行任务执行。更让人心动的是成本——完成同等任务时，它消耗的Token大约是Claude Code的三分之一。换句话说，同样的活儿，Codex干得更快、更便宜。 那么，它适合谁？ * **编程新手**：只要会用自然语言描述需求，Codex就能帮你生成代码、搭好项目框架。 * **效率提升需求者**：如果你厌倦了重复的编码工作，希望用AI自动化日常开发任务，它是好帮手。 * **AI工具爱好者**：喜欢在终端里工作、追求轻量高效可控的开发体验，那更对胃口了。 和Claude Code偏重生产级系统与复杂代码库的风格不同，Codex更像一把锋利的瑞士军刀——轻量、快速、灵活，特别适合快速原型开发。 读完之后，你将能独立完成Codex的安装与配置、掌握五种核心操作模式、理解线程系统与项目分层管理、学会用Skills和MCP扩展工具链，并且亲手完成一个完整的实战项目。 --- ## 二、安装与配置：迈出第一步 ### 2.1 获取Codex：三步搞定 安装过程真的简单——确保Node.js ≥ 18，然后在终端执行一行命令。 **第一步：环境检查** ```bash node --version # 确保 ≥ 18 git --version # 推荐安装Git ``` **第二步：安装Codex CLI** ```bash # npm 安装（推荐，全平台通用） npm install -g @openai/codex # macOS 还可以用 Homebrew brew install --cask codex ``` 国内用户如遇安装缓慢，可使用淘宝镜像： ```bash npm i -g @openai/codex --registry=https://registry.npmmirror.com ``` **第三步：登录验证** ```bash 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中运行，高级用户使用 | 模型选择也很灵活——在会话中随时切换： ```bash /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内置的归档功能，避免数据错乱。 每次启动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` 中预先配置受信任的目录： ```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而非Ja vaScript、记住项目的特定目录结构约定、记住API密钥位置等敏感信息。 ### 4.4 高效模式选择：快速 vs. 精准 Codex通过“批准模式”来平衡效率与安全： * **Suggest（建议）模式**：所有写操作都需确认，适合学习和审查代码 * **Auto（自动）模式（默认）**：工作区内自动执行，外部操作需确认 * **Full-Access（全自动）模式**：完全自主执行，禁用网络但可操作有限目录 日常开发用Auto模式最顺手——改动工作区文件无需每次确认，但涉及系统级操作时仍会征求你的意见。 --- ## 五、实战案例：从零开发一个电影评分网站 ### 5.1 任务描述与拆分 目标：用Codex从零构建一个单页电影评分网站，包含电影列表、评分功能、搜索过滤。 技术栈：React + Vite（前端）、JSON Server（模拟后端）、CSS Modules（样式）。 ### 5.2 Codex操作流程 **第一步：创建项目并启动Codex** ```bash mkdir movie-rating && cd movie-rating npm create vite@latest . -- --template react codex ``` **第二步：编写需求提示词** 在Codex的对话界面输入： ``` 请帮我开发一个电影评分网站，具体要求如下： - 使用 React + Vite（项目已初始化） - 电影列表页面，每部电影展示封面、标题、简介、评分 - 用户可以点击星星给电影打分（1-5星） - 搜索框支持按电影名过滤 - 使用 json-server 模拟后端 API，电影数据放在 db.json 中 请从安装依赖开始，逐步完成所有功能。每次写入文件前先向我展示代码差异。 ``` **第三步：监控执行过程与调试技巧** Codex会逐步执行：安装 json-server 和 concurrently 依赖 → 创建 db.json 模拟数据 → 编写组件代码（`MovieList`、`MovieCard`、`SearchBar`、`StarRating`）→ 配置并发启动前后端 → 添加样式。如果在执行过程中间出现问题（如依赖冲突），直接告诉Codex错误信息，“安装 XX 包时报错，错误信息是 XXX，请帮我解决”，它会读取错误日志并提出修复方案。 **第四步：检查与部署** 任务完成后检查项目根目录下的文件结构是否完整，然后验证效果： ```bash npm run dev ``` 浏览器中应该能看到完整的电影评分网站。 ### 5.3 进阶：Codex Exec模式——无交互自动化 除了交互式对话，Codex还支持 `exec` 模式，适合CI/CD场景： ```bash 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`（或 `codex.md`），编写项目约定，Codex会在每次会话开始时自动读取： ```markdown ## 项目约定 - 后端: Node.js + Express + TypeScript - 数据库: PostgreSQL + Prisma ORM - 测试: Vitest（单元） + Playwright（e2e） - 提交前必须运行 `npm test` - 所有API端点需要Zod输入验证 ``` 使用exec模式配合crontab实现定时任务： ```bash # 每天凌晨3点自动运行测试 0 3 * * * cd /path/to/project && codex exec "运行全部测试并生成报告" ``` 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格式的审查报告。”

来源：互联网