Codex CLI 是 OpenAI 推出的一个开源的本地命令行 AI 编码智能体（Coding Agent）。它能直接在你的终端中运行，通过自然语言指令来理解和操作代码库，从而执行生成代码、重构、运行测试、修复 Bug 等任务。
要上手使用 Codex CLI，主要流程可分为三个步骤：准备环境、安装验证和快速入门。
🚀 第一步：准备环境
开始前，请确保你的系统满足以下基本要求：
|---------------|--------------------------------------------------------|
| 环境要求 | 具体说明 |
| OpenAI 账户 | 需要一个有效的 ChatGPT 账户（Plus/Pro/Team/Edu/Enterprise 计划均可）。 |
| Node.js | 版本需要 v18 或更高，这是运行 Codex CLI 的基础。 |
| Git（推荐） | 虽然不是强制要求，但与 Git 配合能获得最佳体验，避免潜在的警告。 |
| 操作系统 | 官方主要支持 macOS、Linux 以及 Windows 11 (通过 WSL2)。 |
🛠️ 第二步：安装与验证
1. 检查与安装 Node.js
在终端中运行以下命令，检查你的 Node.js 版本：
node --version如果提示未找到命令或版本低于 v18，需要先安装或升级。可以从 nodejs.org 下载，或者使用包管理器安装（如 macOS 的 brew install node）。
2. 全局安装 Codex CLI
使用 npm (Node.js 的包管理器) 执行下面这行命令即可完成全局安装：
npm install -g @openai/codex提示 ：macOS 或 Linux 用户可能需要添加
sudo 来获取安装权限。国内用户如果遇到下载慢，可尝试换用镜像源：npm install -g @openai/codex --registry=https://registry.npmmirror.com。
3. 验证安装
安装成功后，可以运行以下命令来验证，如果正确显示版本号（例如 @openai/codex, 0.79.0），就说明安装成功了。
codex --version💻 第三步：快速入门
1. 首次登录
安装完成后，在终端直接运行 codex 命令启动。首次使用会引导你进行登录。有两种主要方式：
- 浏览器登录（推荐） ：在本地终端运行
codex，它会自动打开浏览器引导你登录你的 ChatGPT 账号。 - 设备码登录 ：如果你在远程或无图形界面的服务器上，可使用
codex login --device-auth获取一个设备码，然后在另一台设备的浏览器中访问 https://chatgpt.com/device 并输入该码完成认证。
2. 基本命令与使用模式
Codex CLI 的核心是它的各种命令，它们决定了你与这个 AI 助手的协作方式。下表整理了最常用的一些命令：
|-----------|--------------------------------------|--------------------------------------------|
| 命令类型 | 命令示例 | 功能说明 |
| 交互式对话 | codex | 启动一个持续的对话会话，适合多轮、复杂的任务。Codex 会记住上下文。 |
| 单次任务 | codex "解释这个代码库" | 带着一个具体的任务启动会话，任务完成后对话仍可继续。 |
| 自动化执行 | codex exec "为 utils.ts 添加错误处理" | 非交互式地执行一个任务，执行完毕后退出，非常适合集成到 CI/CD 等自动化脚本中。 |
| 代码审查 | codex review --uncommitted | 用于审查代码改动，例如审查当前尚未提交（uncommitted）的所有更改。 |
| 会话恢复 | codex resume | 继续一个之前暂停的交互式会话。 |
| 申请变更 | codex apply | 应用 Codex 最近一次生成的代码差异（diff）到你的工作区。 |
提示 ：
codex exec 命令还支持 --json 参数，可以输出机器可读的 JSON 格式结果，方便你在其他脚本中进行解析。
3. 理解"批准模式"
在执行任何操作（如修改文件、运行命令）时，Codex 的行为会受到 批准模式 的控制，这为你提供了不同层级的"安全开关"：
|------------------|---------------------------------------|-----------------------------------------------------------------|
| 模式 | 命令示例 | 行为描述 |
| Suggest (默认) | codex | Codex 只能读取文件并给出修改建议。所有文件写入和执行 Shell 命令的操作都需要你明确批准。 |
| Auto Edit | codex --approval-mode auto-edit | Codex 可以自动读写文件，但在执行 Shell 命令前仍需你的批准。 |
| Full Auto | codex --approval-mode full-auto | Codex 完全自主运行，可读写文件并执行命令。此模式风险最高，所有操作都在一个网络隔离、限制在当前目录的沙箱中运行。 |
4. 高级配置与模型切换
Codex CLI 提供了丰富的配置选项，你可以通过配置文件或命令行参数进行精细控制：
-
指定模型 ：通过
-m参数可以在运行时临时切换使用的 AI 模型。例如，使用功能更强的gpt-4.1处理复杂重构任务：codex -m gpt-4.1 "重构这个复杂的算法"
-
配置文件 (Profiles) ：你可以在
~/.codex/config.toml文件中定义多种配置预设（profile），例如一个用于日常快速任务的fast模式，和一个用于解决棘手问题的careful模式。通过--profile参数即可一键切换。使用名为 'fast' 的预设配置
codex --profile fast "修复这个简单的 lint 错误"
✨ 实战工作流建议
为了让新手更平滑地入门，可以参考这个三步走的实战路径：
- 从"只读"开始 ：不要一上来就让它改代码。先用
codex "请总结这个项目的目录结构和开发流程，先不要修改任何文件。"这样的指令，让它帮你熟悉代码库。 - 完成小范围改动 ：熟悉后，给它一个明确、可审查的任务。例如
codex "只修改 src/components/Header.tsx 组件里的标题文案，完成后总结一下改动。"。 - 加入验证环节 ：让它不只是修改，还要验证。比如
codex "修复 npm test 失败的那个测试用例，修复后只运行相关的测试，并用三句话说明你改了什么。"。
🔧 进阶玩法
一旦掌握了基础，你可以探索更多功能：
-
多模态交互 ：你可以直接把设计稿截图发给 Codex，让它根据图片生成代码。使用
-i或--image参数即可。codex -i ./design.png "根据这个设计稿实现一个 React 组件"
-
审查代码变更 ：Codex 可以作为一个强大的代码审查助手。使用
codex review系列命令，你可以让它审查未提交的变更、某个分支的差异，甚至是某个特定提交。审查当前所有未提交的更改
codex review --uncommitted
审查当前分支相对于 main 分支的所有更改
codex review --base main
-
集成与扩展 (MCP) ：Codex 支持 Model Context Protocol (MCP)，你可以通过
codex mcp命令添加或管理 MCP 服务器，扩展其能力，例如连接外部工具和数据库。
💎 最佳实践与技巧
- 保持目录整洁 ：Codex 需要将上下文信息写入本地文件，因此建议在一个干净的项目目录中运行它，并利用
.gitignore来管理这些临时文件。 - 善用 Git ：在使用
full-auto等高自主性模式前，务必确保你的代码变更已提交或有备份。Git 是你最好的"后悔药"。 - 任务分解：对于复杂的任务，可以尝试将其分解成多个小步骤，分别与 Codex 交互，这样可以获得更精确的结果。
- 保持更新 ：作为一个快速迭代的项目，建议时常运行
npm update -g @openai/codex来获取最新特性和修复。
❓ 常见问题与注意事项
- 版本与稳定性 ：Codex CLI 仍在积极开发中，可能包含 Bug 或发生破坏性变更，目前仍属于"实验性项目"。
- Windows 用户 ：官方对 Windows 的支持有限，强烈推荐通过 WSL (Windows Subsystem for Linux) 来安装和使用，以获得最稳定的体验。一个社区 Fork (
@ai-nd-co/codex) 对 Windows Git Bash 提供了更好的支持，可以作为备选方案。 - 认证问题：如果登录后工具仍无法正常工作，请确认你登录的 ChatGPT 账号是 Plus、Pro、Team 或 Enterprise 付费计划。
💎 总结与资源
|-----------|----------------------------------------------------------------------------------------------------------------------|
| 资源类型 | 链接与说明 |
| 官方文档 | Codex CLI 官方文档 - 最权威的信息来源。 |
| 社区与问题 | GitHub 仓库 (openai/codex) - 用于报告 Bug、参与讨论和查看最新进展。 |
| 深入学习 | Mintlify 上的 CLI 参考 - 详细的命令和配置说明。 |