OpenAI Codex CLI 新手入门指南
OpenAI Codex CLI 是 OpenAI 推出的终端 AI 编程智能体，命令名为 codex，是 Claude Code 最直接的对标产品。它能读懂你的代码库、编写和修改文件、运行命令并自我纠错，全程在终端内完成。最大的优势是：只要你已经订阅了 ChatGPT（Plus / Pro 等），就无需为命令行额外付费。本指南将带你从安装、登录，到第一次会话与项目上下文配置，逐步上手这款工具。
第一步：快速安装 Codex CLI
Codex CLI 支持 npm、Homebrew 和官方安装脚本三种方式，任选其一。
macOS / Linux
通过 npm 全局安装（需要 Node.js）：
npm install -g @openai/codex也可以使用 Homebrew：
brew install --cask codex或使用官方一键安装脚本：
curl -fsSL https://chatgpt.com/codex/install.sh | sh注意：npm 上的包名是
@openai/codex（带@openai/作用域）。不带作用域的codex是一个无关的旧项目，请勿安装错误。
Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"如果你已经安装了 Node.js，同样可以直接用 npm：
npm install -g @openai/codex验证安装
安装完成后，运行以下命令验证：
codex --version如果能看到版本号，说明安装成功。
第二步：登录与认证
Codex CLI 支持 ChatGPT 账号登录与 API Key 两种方式。
方式一：ChatGPT 账号登录（推荐个人用户）
在终端直接运行：
codex首次启动时，Codex 会提示你登录，并自动打开浏览器引导你完成 ChatGPT 授权；授权后自动回到终端。
支持命令行登录的订阅计划包括 Go、Plus、Pro、Business、Edu 和 Enterprise（ChatGPT Team 已于 2025 年更名为 Business）。这些计划已经包含 Codex 的使用额度，无需额外付费（以官方为准）。
提示：免费版 ChatGPT 账号目前只能在网页端试用 Codex，命令行需要升级到任一付费计划（最低为 Go，约 8 美元/月）。
方式二：API Key（适合脚本化 / CI 环境）
如果你需要在脚本、CI/CD 或无图形界面的服务器上使用，可以配置环境变量：
export OPENAI_API_KEY="你的API密钥"API Key 方式按 API 用量计费，且部分功能可能受限（以官方为准）。它更适合自动化场景，个人日常开发推荐用 ChatGPT 账号登录。
第三步：开始你的第一次会话
启动交互模式
codex进入交互式界面后，就可以用自然语言对话了：
请解释这个项目的整体结构帮我写一个 Go 函数，从 CSV 文件读取数据并去重引用文件使用 @ 符号，在输入时会触发文件名补全：
分析 @src/main.ts 的代码质量并指出潜在问题一次性命令模式（codex exec）
只想执行单个任务、或在脚本中调用时，使用 codex exec 子命令。它非交互地运行一次任务，把过程输出到 stderr，最终结果打印到 stdout，非常适合 CI/CD 与定时任务：
codex exec "为 src/utils.ts 编写单元测试"exec 也有简写 e：
codex e "运行测试并修复所有失败用例"小贴士：动手前先做一次 Git 提交作为检查点，万一改动不满意可以方便地回滚。
第四步：配置项目上下文（AGENTS.md）
Codex 使用 AGENTS.md 作为「项目记忆」，其中的内容会在每次会话开始时自动加载到上下文，用于告诉智能体你的技术栈、规范与约定。这与 Claude Code 的 CLAUDE.md 作用一致，而 AGENTS.md 正逐渐成为各家终端智能体通用的约定。
Codex 会按优先级合并多个位置的 AGENTS.md（大致为：~/.codex/AGENTS.md 全局文件，以及从 Git 仓库根目录到当前目录的项目文件，以官方为准）。
在交互界面里运行 /init 可以自动为当前项目生成一份 AGENTS.md 脚手架，再按需修改即可。一个典型示例：
# MyWebApp 项目指南
## 技术栈
- 前端：React + TypeScript + Vite
- 后端：Node.js + Express
- 数据库：PostgreSQL
## 编码规范
- 所有函数必须有 TypeScript 类型注解
- 组件名使用 PascalCase，文件名使用 kebab-case
- 每次改动后运行 `pnpm test` 确保测试通过
## 项目结构
- `/src/components/` - React 组件
- `/src/hooks/` - 自定义 Hooks
- `/src/api/` - API 调用全局配置文件则位于 ~/.codex/config.toml，可以在这里设置默认模型、审批策略、沙箱模式等。例如：
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"配置的优先级大致为：命令行参数 > 项目级 .codex/config.toml > ~/.codex/config.toml > 内置默认值。
第五步：掌握进阶功能
审批与沙箱模式
Codex 默认会在执行有风险的操作（写文件、跑命令）前征求你的确认，并把改动限制在工作区内。你可以通过两个维度调节自动化程度：
--ask-for-approval（简写-a）：控制何时暂停征求确认，可选untrusted、on-request、never。--sandbox（简写-s）：控制文件系统访问范围，可选read-only、workspace-write、danger-full-access。
在非交互的 codex exec 场景中，常用组合是允许在工作区内写入：
codex exec --sandbox workspace-write "把 CHANGELOG 更新到最新提交"关于
--full-auto：早期版本用--full-auto（等价于on-request审批 +workspace-write沙箱）实现自动模式，该写法现已标记为废弃，官方建议改用上面的--sandbox workspace-write（以官方为准）。
YOLO 模式（跳过所有确认与沙箱）
在受信任、可丢弃的环境（如一次性容器）中，可以彻底跳过审批与沙箱：
codex --dangerously-bypass-approvals-and-sandbox该标志也有简写别名 --yolo。
⚠️ 该模式会移除所有安全防护：没有沙箱、没有任何确认提示，存在误删文件、误执行命令的真实风险。请仅在隔离且受信任的环境中使用，并务必配合 Git 提交点做回滚保护。
常用斜杠命令
进入交互界面后，可用斜杠命令快速操作：
/init- 为当前项目生成AGENTS.md脚手架/model- 切换当前使用的模型/approvals（或/permissions）- 调整审批与权限策略/diff- 查看当前 Git 改动（含未跟踪文件）/review- 让 Codex 审查工作区的改动/plan- 切换到「先规划后实现」模式/compact- 压缩对话以节省上下文/status- 查看会话配置与 Token 用量/new- 在同一会话中开启全新对话
了解使用成本
免费额度（随 ChatGPT 订阅）
只要你订阅了 ChatGPT 的 Go、Plus、Pro、Business、Edu 或 Enterprise，就已经包含了 Codex 的使用额度，无需为命令行单独付费。不同档位的额度上限不同（Pro 通常显著高于 Plus）。免费版 ChatGPT 账号目前只能在网页端试用，命令行需要先升级到任一付费计划才能登录使用（以官方为准）。
付费 / API 计费
如果你不走 ChatGPT 订阅，而是用 OPENAI_API_KEY 登录，则按所选模型的 API 价格按用量计费。这种方式更适合自动化、CI 与服务器场景。具体额度与价格政策可能随官方调整，最终以 OpenAI Codex 官方文档 为准。
常见问题解答
Q: Codex CLI 要单独付费吗？ A: 不用。ChatGPT 的 Go、Plus、Pro、Business、Edu、Enterprise 订阅都已包含 Codex 额度。免费版账号在网页端可试用，但命令行需要先升级到任一付费计划，或改用按量计费的 OPENAI_API_KEY。
Q: 我的代码会被发送到 OpenAI 吗？ A: 会。运行期间相关代码与上下文会发送到 OpenAI 的模型进行处理。处理敏感代码前请先确认你的公司政策与 OpenAI 的数据使用条款。
Q: 怎么在脚本或 CI 里调用 Codex？ A: 使用非交互的 codex exec "你的任务"（简写 codex e），它会把结果打印到 stdout。配合 --sandbox workspace-write 可让它在工作区内自动改文件，认证则建议用 OPENAI_API_KEY。
Q: Codex CLI 和 Claude Code 怎么选？ A: 两者都是终端 AI 编程智能体，体验高度相似，都用 AGENTS.md / CLAUDE.md 作为项目记忆。Codex 绑定 ChatGPT 生态与 GPT-5.x 模型，Claude Code 绑定 Claude 模型。已有相应订阅、或更偏好对应模型，就选哪个；也完全可以两者并用。