Codex CLI 安装使用指南：OpenAI 的终端编程 Agent

OpenAI 出的终端编程 Agent，开源，能读你的整个代码库，能跑命令，能自己改文件

这东西是什么

Codex CLI 是 OpenAI 在 2025 年 4 月开源的终端编程 Agent。注意是 Agent，不是补全工具——它不光帮你写代码，还能自己读项目、规划方案、改文件、跑测试，一整套流程自己走完。

跟 GitHub Copilot 那种"你写一行它补一行"的逻辑完全不同。Copilot 是副驾驶，Codex 是你给它派活儿的下属。

2025 年 4 月刚出来的时候是 TypeScript 写的，后来用 Rust 重写了，性能提升不少。开源协议是 Apache 2.0，GitHub 上到现在攒了八万多个 Star。

跟 Claude Code 的定位很像——都是终端里的编程 Agent，都能操作本地文件和执行命令。区别是 Codex 背后是 OpenAI 的模型生态，Claude Code 背后是 Anthropic 的 Claude。

适合谁？已经在用命令行干活的人，想试试 OpenAI 生态的编程 Agent。如果你连终端都没打开过，这篇可能不太适合你。

___

安装前准备

系统要求

• • 操作系统：macOS、Linux 原生支持。Windows 目前是实验性支持，推荐用 WSL2

• • Node.js：如果你用 npm 安装方式，需要 Node.js 环境（建议 20 LTS 或以上）

• • Git 2.23+：推荐安装，Codex 的安全回滚机制依赖 Git

• • 网络：需要能访问 OpenAI 的服务

检查环境

node --version    # 检查 Node.js（npm 安装方式需要）
git --version     # 检查 Git

两个都没有？Node.js 去 nodejs.org 下载 LTS 版本安装。Git 去 git-scm.com 下载。

Windows 用户特别说明

Codex CLI 对 Windows 的原生支持还在实验阶段。推荐用 WSL2（Windows Subsystem for Linux 2），在 WSL 里按 Linux 的方式装，体验和 Linux 一致。

如果你还没装 WSL2：

# 在 PowerShell（管理员）里运行
wsl --install

装完重启，打开 WSL 终端，后面按 Linux 的步骤来就行。

___

安装 Codex CLI

方法一：一键安装脚本（推荐）

macOS / Linux：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

这个脚本会自动下载对应平台的二进制文件，不需要 Node.js 环境，装完直接能用。

方法二：npm 全局安装

npm install -g @openai/codex

装完检查一下：

codex --version

能输出版本号就说明装好了。

方法三：Homebrew（macOS）

brew install --cask codex

Mac 用户如果习惯用 Homebrew 管理软件，这条最省事。

方法四：直接下载二进制

去 GitHub Releases 页面，下载对应平台的压缩包：

解压后把可执行文件移到 PATH 里：

tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex

如果 npm 装不上

网络问题或权限问题，试试：

# macOS/Linux 权限问题
sudo npm install -g @openai/codex

# 换 npm 源
npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex

___

登录和认证

装完第一次运行 codex，会提示你登录。有两种方式。

方式一：ChatGPT 账号登录（推荐）

选择 "Sign in with ChatGPT"，会打开浏览器授权页面。

如果你有 ChatGPT 订阅，额度包含在订阅里，不用额外花钱：

Free 账号也能用，但用量有限。Plus 及以上体验最好。

方式二：API Key（开发者推荐）

如果你不想走 ChatGPT 订阅，或者想精确控制成本，用 API Key：

export OPENAI_API_KEY="sk-你的密钥"

加到 ~/.bashrc 或 ~/.zshrc 里，每次开终端自动生效。

API Key 方式按用量计费，默认使用 codex-mini-latest 模型（专门为编程优化的轻量模型，成本比完整模型低）。

注意： API Key 不要提交到 Git 里。在 .gitignore 里排除掉相关文件，或者用环境变量管理。

___

三种审批模式：Codex 最核心的设计

这是 Codex 和其他编程工具最大的区别——你可以控制 AI 的自主程度。

通过 --approval-mode（简写 -a）参数设置：

suggest 模式（默认）

Codex 提出修改建议，每一个文件改动、每一条命令都需要你手动确认。

适合：第一次接触代码库、生产环境、不太放心的时候。

最安全，但最慢。

auto-edit 模式

Codex 自动修改文件，但执行 shell 命令前会问你。

适合：你信任它改代码的能力，但不想让它随便跑命令。

速度和安全的平衡点。

full-auto 模式

Codex 全自动——改文件、跑命令、跑测试，全程不用你确认。

适合：隔离的功能分支、测试环境、你清楚自己在干什么的时候。

最快，但风险最高。建议在 Git 仓库里用，出问题直接 git checkout 回滚。

怎么选？

新手 / 第一次用 → suggest
熟悉项目了 → auto-edit
隔离环境 / 全自动流水线 → full-auto（记得先 git commit）

___

基本使用

启动交互模式

codex

进入交互式终端界面（TUI），可以一直对话，直到你退出。

退出方式：Ctrl+C 中断当前任务，Ctrl+D 退出 Codex。

单次任务模式

不想进交互模式，直接给一个任务：

codex "给 auth.py 的所有函数写单元测试"

干完就退出。

指定审批模式

# 全自动模式跑一个重构任务
codex --approval-mode full-auto "重构 utils 目录，消除重复代码"

# 简写
codex -a full-auto "add type hints to all functions"

启动桌面应用

codex app

会打开一个图形界面版本，不习惯纯终端的话可以用这个。

交互模式快捷键

___

常用命令

在交互模式下，除了正常对话，还有一些命令可以用：

模型和配置

会话管理

工具和诊断

___

配置文件

Codex CLI 的配置文件在 ~/.codex/config.json（Windows WSL 里是 ~/.codex/config.json）。

常见配置项

{
  "model": "codex-mini-latest",
  "approvalMode": "suggest",
  "notify": true
}

环境变量

除了配置文件，也可以用环境变量：

export OPENAI_API_KEY="sk-你的密钥"

加到 ~/.bashrc 或 ~/.zshrc 里持久生效。

___

AGENTS.md 和 codex.md：让 Codex 记住你的规则

这是 Codex 版的"上岗说明书"，作用和 Claude Code 的 CLAUDE.md 类似——告诉 AI 你的项目是什么、有什么规矩。

codex.md：全局规则

放在 ~/.codex/codex.md 或项目根目录。内容作为持久化提示，每次会话自动注入。

# 编码规范

- 所有 Python 函数必须有类型注解
- 测试文件统一放在 tests/ 目录下
- 提交前运行 ruff check . 检查格式
- 不要修改 legacy/ 目录下的任何文件

AGENTS.md：目录级规则

放在仓库根目录或任意子目录。定义对应目录范围内的 Agent 行为和权限。

关键特性：子目录的 AGENTS.md 会覆盖父目录的规则。 也就是说你可以精细控制——API 目录一套规则，前端目录另一套规则。

# API 目录 Agent 配置

- 只能读写本目录内的文件
- 禁止修改 routes/auth.py（由安全团队维护）
- 所有 API 响应必须包含 request_id 字段

两者怎么配合？

• • codex.md 写项目通用规则（全局默认值）

• • AGENTS.md 写目录级权限控制（局部覆盖）

• • 子目录的 AGENTS.md 优先级 > 父目录的 AGENTS.md > codex.md

___

沙箱安全机制

Codex 在安全设计上做了不少工作，不是随便就能乱改你文件的：

macOS：使用系统内置的 sandbox-exec（Apple Seatbelt 沙箱技术），限制进程能访问的文件路径和网络资源。

Git 回滚保障：Codex 在 Git 仓库中工作，任何修改都能通过 git diff 查看、git checkout 回滚。full-auto 模式的最终安全网就是 Git。

建议的安全习惯：

• • 用 full-auto 之前先 git commit，保留干净的回滚点

• • 在 AGENTS.md 里明确禁止修改敏感文件

• • 新项目先用 suggest 模式跑一遍，建立信任后再升级

___

实际使用场景

场景一：理解现有代码

codex
> 这个项目的入口文件在哪里
> 数据库表结构是怎样的
> API 路由都在哪里定义的

Codex 会扫描项目结构，帮你快速摸清全貌。

场景二：写新功能

codex
> 帮我加一个用户注册的 API：
> - 接收邮箱和密码
> - 密码要加密存储
> - 返回格式跟项目里其他 API 保持一致

它会看项目里现有的代码风格，尽量保持一致。

场景三：全仓库重构

codex -a auto-edit "把 /src 里所有的 fetch() 调用替换成 lib/http.js 里的 axios 封装"

Codex 会在整个代码库里找到所有 fetch 调用，统一改写，然后跑测试。

场景四：批量写测试

codex "给 /src/utils 下所有导出函数写 Jest 测试，目标 80% 分支覆盖率"

场景五：调试问题

codex
> 运行 npm test 报了这个错：
> Error: Cannot find module './config/database'
> 帮我看看是什么问题

它会检查文件结构、导入路径，告诉你哪里出了问题。

场景六：跑命令并处理结果

codex
> 跑一下 npm run build，如果有报错就帮我修

Codex 能执行命令、看输出、根据输出决定下一步。如果 build 失败了，它会诊断错误而不是继续往下跑。

___

使用技巧

1. 描述清楚目标，不要描述步骤

别说"打开 app.js，找到第 30 行，改一下"——说"给 Express API 加一个限流中间件，每分钟 100 次请求，超了返回 429"。

Codex 会自己规划步骤，你只需要告诉它要什么。

2. 善用审批模式

不需要一直用 suggest。摸熟了之后切 auto-edit，效率高很多。full-auto 留给隔离环境。

3. 用 AGENTS.md 固定规则

每次新开会话都要重复说"别改 legacy 目录""测试放 tests 下"——写进 AGENTS.md，一劳永逸。

4. 及时清理上下文

聊了很久之后上下文会变大，响应变慢。用 /compact 压缩，或者 /clear 重新开始。

5. full-auto 之前先 commit

养成习惯：用 full-auto 之前先 git commit，出问题 git checkout . 一键回滚。

___

常见问题

安装时报错 "permission denied"

sudo npm install -g @openai/codex

或者修改 npm 全局安装路径权限：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex

Windows 原生终端能用吗？

实验性支持，不推荐。用 WSL2 体验最好。在 WSL 里按 Linux 方式安装就行。

ChatGPT Free 账号能用吗？

能用，但用量有限制。如果频繁用建议升 Plus。

Codex 会把我的代码传到 OpenAI 服务器吗？

会。Codex 需要把文件内容和上下文发给 OpenAI 模型处理。如果代码里有敏感信息（密钥、私人数据），建议：

• • 在 AGENTS.md 里禁止 Codex 读取敏感文件

• • 确认 OpenAI 的数据处理协议是否符合你的合规要求

• • 企业用户可通过 Enterprise 计划申请数据不用于训练

full-auto 跑错了怎么办？

git diff          # 查看改了什么
git checkout .    # 回滚所有未提交的修改
git revert   # 回滚特定提交

这就是为什么建议用 full-auto 之前先 commit。

怎么更新？

npm install -g @openai/codex@latest

Codex 更新频率挺高的，建议定期更新。

___

费用相关

工具本身免费

Codex CLI 是开源的（Apache 2.0），安装和使用工具本身不花钱。

花钱的地方是模型调用

ChatGPT 订阅方式：

• • Plus（$20/月）：完整访问，额度包含在订阅里

• • Pro（$200/月）：完整访问 + 更高用量

• • Free：能用，但用量有限

API Key 方式：

按 token 用量计费。默认用 codex-mini-latest，成本比较低。切到更强的模型（比如 o 系列推理模型）会贵一些。

省钱建议

• • 日常用 codex-mini-latest，复杂任务再切强模型

• • 问题描述清楚，减少来回

• • 及时 /compact 或 /clear 清理上下文

• • 简单任务用单次模式（codex "任务"），不进交互模式

___

Codex CLI vs Claude Code

两个工具定位几乎一样，选哪个主要看你用哪个模型生态。详细的对比可以看我之前写的 Work Buddy vs Claude Code 那篇，里面有更全面的选型建议。

___

官方资源

• • GitHub 仓库：https://github.com/openai/codex

• • 官方文档：https://developers.openai.com/codex

• • Codex Cloud（网页版）：https://chatgpt.com/codex

___

装好之后，找个小项目先用 suggest 模式跑一圈，感受一下它的工作方式。等建立信任了再逐步放开权限——这是用 Agent 类工具最稳的节奏。