夜雨聆风Codex 是 OpenAI 推出的 AI 编程助手，和 GitHub Copilot 不同，它不只是做代码补全——它能理解整个项目结构，帮你重构、测试、写文档，甚至自动提交 PR。
这篇文章不讲虚的，直接从安装配置开始，带你系统地了解 Codex 的核心功能和高效用法。
01 安装 Codex
环境要求
Codex CLI 基于 Node.js 运行，确保你的系统满足以下条件：
• Node.js v18 或更高版本 • npm 或 yarn 包管理器 • macOS / Linux / Windows（WSL）
安装步骤
一行命令全局安装：
npm install -g @openai/codex验证是否安装成功：
codex --version # 输出类似：0.x.x如果遇到权限问题，macOS/Linux 前加 sudo，Windows 用管理员身份运行终端。
配置 API Key
Codex 默认使用 OpenAI 的模型，需要设置 API Key：
# 推荐写入配置，避免每次输入 export OPENAI_API_KEY=sk-your-api-key-here # 或首次启动时输入 codex --api-key sk-your-api-key-here如果你想使用其他模型（比如 DeepSeek、Claude），可以配置自定义端点：
# 使用 DeepSeek export OPENAI_BASE_URL=https://api.deepseek.com/v1 export OPENAI_API_KEY=sk-your-deepseek-key codex --model deepseek-chat02 三种工作模式
Codex 提供了三种模式，分别适用于不同阶段的任务。刚入手时建议先理解它们的区别。
Ask 模式用于纯问答，Agent 模式自动执行任务，Session 模式适合长期协作
Ask 模式（纯对话）
最简单的使用方式——你提问，Codex 回答。它不会修改任何文件，适合用来了解代码库、设计方案、做代码审查。
# 进入 Ask 模式 codex ask # 或者直接提问 codex ask "这个项目的认证逻辑是怎么实现的？"最佳用法：在开始大型修改之前，先用 Ask 模式让 Codex 出方案。确认方向正确后，再切换到 Agent 模式来执行。
Agent 模式（自动执行）
Agent 模式是 Codex 最强大的模式。它不只是回答问题——它会扫描项目目录、读取文件、修改代码、运行命令，甚至能帮你提交 git commit。
# 启动 Agent 模式 codex # 或指定模型和项目目录 codex --model gpt-4o --target-dir ./my-project # 指定任务 codex "为 UserService 添加单元测试，覆盖边界条件"Agent 模式下，Codex 会先分析项目结构，然后按步骤执行任务。每次操作前它会向你确认，批准后才执行——不用担心它乱改代码。
Session 模式（持续对话）
Session 模式让你和 Codex 保持连续的对话上下文。适合需要多轮交互的复杂任务——比如一个功能从设计到实现的完整流程。
# 启动 Session 模式 codex --session # 示例会话 > 帮我设计一个用户通知系统 [Codex] 分析了现有代码结构，给出三种方案... > 选方案二，先实现 NotificationService [Codex] 创建了文件，生成了基础代码... > 添加邮件发送功能 [Codex] 集成 nodemailer，处理了失败重试...Session 模式适合午餐前启动，回来后直接验收结果——Codex 会持续工作直到完成任务。
03 提示词技巧
提示词写得好不好，直接决定 Codex 的输出质量。以下几个技巧亲测有效：
1. 像写 Issue 一样写提示
提供明确的上下文——文件路径、函数名、预期行为。不要只写「加个验证」，而是：
# 好： 为 src/api/users.ts 中的 createUser 函数添加输入验证： - email 格式校验 - 密码长度 >= 8 - 用户名不能包含特殊字符 # 差： 加一下验证2. 分阶段提问
对复杂任务，先 Ask 再 Agent：
# 第一步：方案（Ask 模式） > 分析这个模块，给出重构方案 # 第二步：执行（Agent 模式） > 好的，按你刚才的方案开始实现3. 提供代码示例
用「按照 [已有模块 X] 的模式来写」这种方式引用项目中的既有代码。Codex 能理解你项目的代码风格和模式，生成的内容更一致。
4. 给出否定约束
明确告诉 Codex 不要做什么，效果往往比只告诉它要做什么更好：
# 好的提示词： 重构 PaymentService，保持接口不变，不要引入新的依赖，不要改动现有测试04 AGENTS.md：项目级上下文管理
这是 Codex 的一个隐藏神器。
在项目根目录创建一个 AGENTS.md 文件，写入项目的关键信息——架构说明、命名规范、业务规则、常见坑点。Codex 每次对话都会自动读取这个文件作为持久化上下文。
# 项目 AGENTS.md 示例 ## 技术栈 - 后端：Node.js + Express + TypeScript - 数据库：PostgreSQL + Prisma ORM - 测试：Vitest ## 代码规范 - 使用函数式组件，禁止 class 组件 - API 路由统一放在 src/api/ 下 - 所有错误都要用 AppError 类包装 ## 已知问题 - PaymentService 存在竞争条件，需加锁 - 旧的 getUserById 已被弃用，用 UserService.get 替代有了 AGENTS.md，Codex 生成的代码风格会和你的项目高度一致，不再需要反复纠正它。
05 常见命令速查
06 注意事项与避坑
1. 成本控制
Codex 不额外收费，但底层模型按 tokens 计费。一次大型重构可能消耗几十万 tokens。建议：
• 先用 Ask 模式确认方案再执行，减少无效输出 • 设置 --max-tokens 限制单次回复长度 • 考虑换用更便宜的模型（如 DeepSeek）做日常编码
2. 安全注意事项
Codex 会读取项目文件来理解上下文。如果你在涉及敏感信息的项目中使用，注意：
• .env 文件会被忽略，但硬编码的密码/密钥会被发送 • 代码内容会上传至 OpenAI 服务器处理 • 建议创建 .codexignore 文件排除敏感目录
3. 代码审核不能省
Codex 生成的代码质量很高，但不是 100% 正确。遇到以下情况时一定要人工把关：
• 涉及数据库事务和并发控制 • 配置文件和权限相关代码 • 安全相关的认证/授权逻辑 • 对外部 API 的调用参数
4. 大型项目的使用策略
代码量超过 10 万行的项目，建议：
• 按模块使用，用 --target-dir 限制范围 • 保持 AGENTS.md 精简，只包含关键信息 • Session 模式下上下文过长时，手动清理历史 • 考虑把大任务拆成多个小任务分步执行
07 推荐工作流
结合使用经验，这里给出一个经过验证的日常编码工作流：
第一步（早开工）：打开 Session 模式，列出今天要完成的任务。让 Codex 先扫描整个项目，建立上下文。
第二步（执行）：每个任务按「Ask 确认方案 → Agent 执行 → 审查结果」的节奏推进。先处理简单的代码修改，逐步到复杂的重构。
第三步（收尾）：让 Codex 生成变更总结和测试报告，确认没有遗漏。
很多开发者的经验是——用 Session 模式搭配 AGENTS.md，是 Codex 目前最舒服的使用方式。去开个会，回来看到 Codex 已经在后台帮你改好了代码，体验相当不错。
