Codex 深度指南
Codex CLI 是 OpenAI 推出的本地终端编码代理，目标很直接：在你当前的代码仓库里理解上下文、执行命令、修改文件，并帮你持续推进开发任务。它不是传统意义上的聊天窗口，而是更接近“在本地仓库里工作的 AI 代码助手”。
对于中文读者来说，最容易理解的用法是：你把仓库交给它，它帮你读、帮你改、帮你跑，最后再一起检查结果。
官方地址
| 类型 | 地址 |
|---|---|
| 官方 Help Center | https://help.openai.com/en/articles/11096431-openai-codex-cli-getting-started |
| 官方 GitHub | https://github.com/openai/codex |
| Codex Web | https://chatgpt.com/codex |
适用场景
Codex 适合这些典型场景：
- 读取本地项目结构并总结代码逻辑
- 按照你的要求修改多个文件
- 辅助完成修复 bug、补测试、整理重构
- 从终端里直接处理 PR 相关任务
- 用脚本或命令行方式批量执行重复操作
如果你的工作习惯是“先在本地跑起来，再逐步验证”，Codex 会比较顺手。
安装准备
官方 README 和文档给出的安装思路比较直接：先把 CLI 装到本地，再通过账号登录或 API Key 使用。
常见准备项：
- macOS 或 Linux 用户可通过 Homebrew、npm 或官方发布包安装
- 需要联网以完成认证和模型请求
- 如果你打算用 API Key，需要提前准备好 OpenAI API Key
- 如果你打算用 ChatGPT 账号登录，需要确认账号可用于 Codex
初学者建议优先走官方推荐的 npm 或 Homebrew 路线，减少手工解压和路径配置的麻烦。
安装方式
官方 README 给出的主要方式有三种。
方式一：npm 安装
npm install -g @openai/codex
codex这是最通用的安装方式，适合大多数开发者。
方式二：Homebrew 安装
brew install --cask codex
codex如果你平时已经习惯用 Homebrew 管理命令行工具，这种方式比较省事。
方式三：直接下载 GitHub Release
官方 README 也说明了可以从最新 GitHub Release 下载平台对应的二进制包。适合离线管理、特定平台或想避开包管理器的场景。
首次登录 / 认证
Codex 的认证方式有两条主线：
1. 使用 ChatGPT 账号登录
运行 codex 后，选择 Sign in with ChatGPT。官方 README 明确建议 ChatGPT Plus、Pro、Business、Edu 或 Enterprise 订阅用户使用这种方式。
2. 使用 API Key
如果你更偏向 API 方式，可以使用 OpenAI API Key。官方文档和仓库讨论都说明，这通常通过 OPENAI_API_KEY 环境变量来提供，适合自动化环境或偏工程化的使用方式。
初次使用时，建议先把账号认证跑通，再考虑把 API Key 接入脚本和自动化流程。
常用命令大全
| 命令 | 作用 | 示例 | 注意事项 |
|---|---|---|---|
codex | 启动交互式 CLI | codex | 首次使用通常从这里开始 |
codex app | 打开桌面应用体验 | codex app | 适合想要图形界面的人 |
npm install -g @openai/codex | 通过 npm 安装 | npm install -g @openai/codex | 需要 Node 环境 |
brew install --cask codex | 通过 Homebrew 安装 | brew install --cask codex | macOS 上比较方便 |
codex resume | 继续最近会话 | codex resume | 适合延续上次任务 |
codex login | 登录认证 | codex login | 也可以先运行 codex 再按提示登录 |
codex logout | 退出登录 | codex logout | 共用机器上建议操作 |
codex exec | 执行一次性任务 | codex exec "explain this function" | 适合脚本化场景，具体参数以当前版本 --help 为准 |
codex update | 更新到最新版本 | codex update | 升级后建议重新确认认证状态 |
说明：Codex 官方公开文档的重点更偏向安装、登录和工作流。具体子命令和参数会随版本演进，实际使用时建议先看
codex --help和当前版本文档。
常用工作流
1. 先让它读仓库，再要求修改
最稳妥的方式是先让 Codex 理解项目，再逐步提出改动。比如先让它总结目录结构、关键入口和测试命令，然后再要求它修某个 bug。
2. 用非交互模式处理一次性任务
codex exec 适合做快速检查、摘要、解释错误和脚本化自动化。你可以把它看成“短任务执行模式”，也适合放进 CI 前后的半自动流程。
3. 让它先给方案，再动手
对于影响较大的改动，推荐先让它给出修改方案和风险点，再决定是否执行。这样能避免一上来就把仓库改乱。
4. 配合 PR 任务使用
Codex 很适合做“先修复、再验证、最后总结”的循环。你可以让它检查变更、补测试，再继续下一轮修改。
权限与安全建议
Codex 会接触本地文件和命令行，所以安全边界要提前想清楚。
- 不要在提示词里直接放入敏感密钥
- 在共享仓库里先确认当前工作目录是否正确
- 对会修改大量文件的命令保持人工复核
- 生产环境或敏感环境里，优先使用最小权限账号
- 如果使用 API Key，确认环境变量只在需要的终端会话里生效
如果你打算把 Codex 接进自动化流程，建议先在测试仓库或非关键分支验证。
排错
1. 安装后找不到 codex
通常是 PATH 没配好，或者安装步骤没有真正完成。先检查 npm / brew 安装是否成功，再确认终端是否重新加载了环境变量。
2. 登录后无法继续使用
先确认你选择的是 ChatGPT 登录还是 API Key 方式。Codex 的认证方式不同，环境变量和账号状态会影响可用性。
3. API Key 方式不工作
先确认环境变量设置正确，再检查当前版本是否优先读取了其他登录状态。官方社区里确实存在不同认证方式切换时的场景差异，所以遇到问题时最好先清理旧状态再重试。
4. 非交互模式结果不稳定
把提示词写具体一些，尽量明确输入、输出和限制条件。AI CLI 的输出稳定性很依赖输入质量。
总结
Codex 的优势在于：它是一个围绕代码库工作的终端代理，不只是聊天模型。对初学者来说，最值得先掌握的是安装、登录、codex 交互模式和 codex exec 非交互模式。这几个点足够支撑大部分基础开发场景。
当你熟悉了它的基本节奏之后，再把它接入更长的任务流，会更容易获得收益。