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 的服务
检查环境
<span leaf="">node --version </span><span><span leaf=""># 检查 Node.js（npm 安装方式需要）</span></span><br><span leaf="">git --version </span><span><span leaf=""># 检查 Git</span></span>
两个都没有？Node.js 去 nodejs.org 下载 LTS 版本安装。Git 去 git-scm.com 下载。
Windows 用户特别说明
Codex CLI 对 Windows 的原生支持还在实验阶段。推荐用 WSL2（Windows Subsystem for Linux 2），在 WSL 里按 Linux 的方式装，体验和 Linux 一致。
如果你还没装 WSL2：
<span><span leaf=""># 在 PowerShell（管理员）里运行</span></span><br><span leaf="">wsl --install</span>
装完重启，打开 WSL 终端，后面按 Linux 的步骤来就行。
安装 Codex CLI
方法一：一键安装脚本（推荐）
macOS / Linux：
<span leaf="">curl -fsSL https://chatgpt.com/codex/install.sh | sh</span>
Windows（PowerShell）：
<span leaf="">powershell </span><span><span leaf="">-ExecutionPolicy</span></span><span leaf=""> ByPass </span><span><span leaf="">-c</span></span><span leaf=""> </span><span><span leaf="">"irm https://chatgpt.com/codex/install.ps1 | iex"</span></span>
这个脚本会自动下载对应平台的二进制文件，不需要 Node.js 环境，装完直接能用。
方法二：npm 全局安装
<span leaf="">npm install -g @openai/codex</span>
装完检查一下：
<span leaf="">codex --version</span>
能输出版本号就说明装好了。
方法三：Homebrew（macOS）
<span leaf="">brew install --cask codex</span>
Mac 用户如果习惯用 Homebrew 管理软件，这条最省事。
方法四：直接下载二进制
去 GitHub Releases 页面，下载对应平台的压缩包：
| 平台
|
文件名
macOS Apple Silicon
| codex-aarch64-apple-darwin.tar.gz |
|
macOS Intel
| codex-x86_64-apple-darwin.tar.gz |
|
Linux x86_64
| codex-x86_64-unknown-linux-musl.tar.gz |
|
Linux ARM64
| codex-aarch64-unknown-linux-musl.tar.gz |
解压后把可执行文件移到 PATH 里：
<span leaf="">tar -xzf codex-x86_64-unknown-linux-musl.tar.gz</span><br><span><span leaf="">mv</span></span><span leaf=""> codex-x86_64-unknown-linux-musl /usr/local/bin/codex</span>
如果 npm 装不上
网络问题或权限问题，试试：
<span><span leaf=""># macOS/Linux 权限问题</span></span><br><span><span leaf="">sudo</span></span><span leaf=""> npm install -g @openai/codex</span><br><br><span><span leaf=""># 换 npm 源</span></span><br><span leaf="">npm config </span><span><span leaf="">set</span></span><span leaf=""> registry https://registry.npmmirror.com</span><br><span leaf="">npm install -g @openai/codex</span>
登录和认证
装完第一次运行 codex，会提示你登录。有两种方式。
方式一：ChatGPT 账号登录（推荐）
选择 “Sign in with ChatGPT”，会打开浏览器授权页面。
如果你有 ChatGPT 订阅，额度包含在订阅里，不用额外花钱：
| 计划
|
月费
|
Codex 访问权限
Free
|
$0
|
有限访问
| |
Plus
|
$20/月
|
完整访问
| |
Pro
|
$200/月
|
完整访问 + 更高用量
| |
Business / Enterprise
|
按席位
|
完整访问
|
Free 账号也能用，但用量有限。Plus 及以上体验最好。
方式二：API Key（开发者推荐）
如果你不想走 ChatGPT 订阅，或者想精确控制成本，用 API Key：
<span><span leaf="">export</span></span><span leaf=""> OPENAI_API_KEY=</span><span><span leaf="">"sk-你的密钥"</span></span>
加到 ~/.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 回滚。
怎么选？
<span leaf="">新手 / 第一次用 → suggest</span><br><span leaf="">熟悉项目了 → auto-edit</span><br><span leaf="">隔离环境 / 全自动流水线 → full-auto（记得先 git commit）</span>
基本使用
启动交互模式
<span leaf="">codex</span>
进入交互式终端界面（TUI），可以一直对话，直到你退出。
退出方式：Ctrl+C 中断当前任务，Ctrl+D 退出 Codex。
单次任务模式
不想进交互模式，直接给一个任务：
<span leaf="">codex </span><span><span leaf="">"给 auth.py 的所有函数写单元测试"</span></span>
干完就退出。
指定审批模式
<span><span leaf=""># 全自动模式跑一个重构任务</span></span><br><span leaf="">codex --approval-mode full-auto </span><span><span leaf="">"重构 utils 目录，消除重复代码"</span></span><br><br><span><span leaf=""># 简写</span></span><br><span leaf="">codex -a full-auto </span><span><span leaf="">"add type hints to all functions"</span></span>
启动桌面应用
<span leaf="">codex app</span>
会打开一个图形界面版本，不习惯纯终端的话可以用这个。
交互模式快捷键
| 快捷键
|
功能
Enter
|
发送消息
| |
Ctrl+C
|
中断当前任务
| |
Ctrl+D
|
退出 Codex
| |
\ + Enter
|
换行继续输入（多行 prompt）
|
常用命令
在交互模式下，除了正常对话，还有一些命令可以用：
模型和配置
| 命令
|
作用
/model |
切换模型（codex-mini-latest / GPT 系列 / o 系列推理模型）
|
| /config |
查看和修改配置
|
会话管理
| 命令
|
作用
/clear |
清空当前会话上下文
|
| /compact |
压缩上下文，释放 token 空间
|
工具和诊断
| 命令
|
作用
/help |
查看所有可用命令
|
| codex doctor |
在终端运行，检查安装状态和排查问题
|
配置文件
Codex CLI 的配置文件在 ~/.codex/config.json（Windows WSL 里是 ~/.codex/config.json）。
常见配置项
<span><span leaf="">{</span></span><br><span leaf=""> </span><span><span leaf="">"model"</span></span><span><span leaf="">:</span></span><span leaf=""> </span><span><span leaf="">"codex-mini-latest"</span></span><span><span leaf="">,</span></span><br><span leaf=""> </span><span><span leaf="">"approvalMode"</span></span><span><span leaf="">:</span></span><span leaf=""> </span><span><span leaf="">"suggest"</span></span><span><span leaf="">,</span></span><br><span leaf=""> </span><span><span leaf="">"notify"</span></span><span><span leaf="">:</span></span><span leaf=""> </span><span><span><span leaf="">true</span></span></span><br><span><span leaf="">}</span></span>
| 选项
|
可选值
|
作用
model |
codex-mini-latest、GPT 系列、o 系列等
|
使用的模型
|
| approvalMode |
suggest / auto-edit / full-auto
|
审批模式
|
| notify |
true / false
|
任务完成后发桌面通知
|
环境变量
除了配置文件，也可以用环境变量：
<span><span leaf="">export</span></span><span leaf=""> OPENAI_API_KEY=</span><span><span leaf="">"sk-你的密钥"</span></span>
加到 ~/.bashrc 或 ~/.zshrc 里持久生效。
AGENTS.md 和 codex.md：让 Codex 记住你的规则
这是 Codex 版的"上岗说明书"，作用和 Claude Code 的 CLAUDE.md 类似——告诉 AI 你的项目是什么、有什么规矩。
codex.md：全局规则
放在 ~/.codex/codex.md 或项目根目录。内容作为持久化提示，每次会话自动注入。
<span><span leaf=""># 编码规范</span></span><br><br><span><span leaf="">-</span></span><span leaf=""> 所有 Python 函数必须有类型注解</span><br><span><span leaf="">-</span></span><span leaf=""> 测试文件统一放在 tests/ 目录下</span><br><span><span leaf="">-</span></span><span leaf=""> 提交前运行 ruff check . 检查格式</span><br><span><span leaf="">-</span></span><span leaf=""> 不要修改 legacy/ 目录下的任何文件</span>
AGENTS.md：目录级规则
放在仓库根目录或任意子目录。定义对应目录范围内的 Agent 行为和权限。
关键特性：子目录的 AGENTS.md 会覆盖父目录的规则。 也就是说你可以精细控制——API 目录一套规则，前端目录另一套规则。
<span><span leaf=""># API 目录 Agent 配置</span></span><br><br><span><span leaf="">-</span></span><span leaf=""> 只能读写本目录内的文件</span><br><span><span leaf="">-</span></span><span leaf=""> 禁止修改 routes/auth.py（由安全团队维护）</span><br><span><span leaf="">-</span></span><span leaf=""> 所有 API 响应必须包含 request</span><span><span leaf="">_id 字段</span></span>
两者怎么配合？
-
•
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 模式跑一遍，建立信任后再升级
实际使用场景
场景一：理解现有代码
<span leaf="">codex</span><br><span leaf="">> 这个项目的入口文件在哪里</span><br><span leaf="">> 数据库表结构是怎样的</span><br><span leaf="">> API 路由都在哪里定义的</span>
Codex 会扫描项目结构，帮你快速摸清全貌。
场景二：写新功能
<span leaf="">codex</span><br><span leaf="">> 帮我加一个用户注册的 API：</span><br><span leaf="">> - 接收邮箱和密码</span><br><span leaf="">> - 密码要加密存储</span><br><span leaf="">> - 返回格式跟项目里其他 API 保持一致</span>
它会看项目里现有的代码风格，尽量保持一致。
场景三：全仓库重构
<span leaf="">codex -a auto-edit </span><span><span leaf="">"把 /src 里所有的 fetch() 调用替换成 lib/http.js 里的 axios 封装"</span></span>
Codex 会在整个代码库里找到所有 fetch 调用，统一改写，然后跑测试。
场景四：批量写测试
<span leaf="">codex </span><span><span leaf="">"给 /src/utils 下所有导出函数写 Jest 测试，目标 80% 分支覆盖率"</span></span>
场景五：调试问题
<span leaf="">codex</span><br><span leaf="">> 运行 npm </span><span><span leaf="">test</span></span><span leaf=""> 报了这个错：</span><br><span leaf="">> Error: Cannot find module </span><span><span leaf="">'./config/database'</span></span><br><span leaf="">> 帮我看看是什么问题</span>
它会检查文件结构、导入路径，告诉你哪里出了问题。
场景六：跑命令并处理结果
<span leaf="">codex</span><br><span leaf="">> 跑一下 npm run build，如果有报错就帮我修</span>
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”
<span><span leaf="">sudo</span></span><span leaf=""> npm install -g @openai/codex</span>
或者修改 npm 全局安装路径权限：
<span><span leaf="">mkdir</span></span><span leaf=""> -p ~/.npm-global</span><br><span leaf="">npm config </span><span><span leaf="">set</span></span><span leaf=""> prefix </span><span><span leaf="">'~/.npm-global'</span></span><br><span><span leaf="">echo</span></span><span leaf=""> </span><span><span leaf="">'export PATH=~/.npm-global/bin:$PATH'</span></span><span leaf=""> >> ~/.bashrc</span><br><span><span leaf="">source</span></span><span leaf=""> ~/.bashrc</span><br><span leaf="">npm install -g @openai/codex</span>
Windows 原生终端能用吗？
实验性支持，不推荐。用 WSL2 体验最好。在 WSL 里按 Linux 方式安装就行。
ChatGPT Free 账号能用吗？
能用，但用量有限制。如果频繁用建议升 Plus。
Codex 会把我的代码传到 OpenAI 服务器吗？
会。Codex 需要把文件内容和上下文发给 OpenAI 模型处理。如果代码里有敏感信息（密钥、私人数据），建议：
-
• 在 AGENTS.md 里禁止 Codex 读取敏感文件
-
• 确认 OpenAI 的数据处理协议是否符合你的合规要求
-
• 企业用户可通过 Enterprise 计划申请数据不用于训练
full-auto 跑错了怎么办？
<span leaf="">git diff </span><span><span leaf=""># 查看改了什么</span></span><br><span leaf="">git checkout . </span><span><span leaf=""># 回滚所有未提交的修改</span></span><br><span leaf="">git revert <commit> </span><span><span leaf=""># 回滚特定提交</span></span>
这就是为什么建议用 full-auto 之前先 commit。
怎么更新？
<span leaf="">npm install -g @openai/codex@latest</span>
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
| 维度
|
Codex CLI
|
Claude Code
开发商
|
OpenAI
|
Anthropic
| |
开源
|
是（Apache 2.0）
|
否
| |
核心模型
|
codex-mini-latest / GPT 系列 / o 系列
|
Claude（sonnet / opus / haiku）
| |
审批模式
|
suggest / auto-edit / full-auto
|
类似的三档
| |
项目上下文文件
|
AGENTS.md + codex.md
|
CLAUDE.md
| |
沙箱安全
|
macOS Seatbelt 沙箱
|
有权限控制
| |
国内可用性
|
需要解决网络问题
|
需要解决网络问题
| |
费用
|
ChatGPT Plus $20/月 或 API 按量
|
Claude Pro $20/月 或 API 按量
| |
IDE 集成
|
VS Code / Cursor / Windsurf
|
VS Code / JetBrains
|
两个工具定位几乎一样，选哪个主要看你用哪个模型生态。详细的对比可以看我之前写的 Work Buddy vs Claude Code 那篇，里面有更全面的选型建议。
官方资源
-
• GitHub 仓库：https://github.com/openai/codex
-
• 官方文档：https://developers.openai.com/codex
-
• Codex Cloud（网页版）：https://chatgpt.com/codex
装好之后，找个小项目先用 suggest 模式跑一圈，感受一下它的工作方式。等建立信任了再逐步放开权限——这是用 Agent 类工具最稳的节奏。
- 原文作者：知识铺
- 原文链接：https://index.zshipu.com/ai002/post/20260814/Codex-CLI-%E5%AE%89%E8%A3%85%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97OpenAI-%E7%9A%84%E7%BB%88%E7%AB%AF%E7%BC%96%E7%A8%8B-Agent/
- 版权声明：本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可，非商业转载请注明出处（作者，原文链接），商业转载请联系作者获得授权。
- 免责声明：本页面内容均来源于站内编辑发布，部分信息来源互联网，并不意味着本站赞同其观点或者证实其内容的真实性，如涉及版权等问题，请立即联系客服进行更改或删除，保证您的合法权益。转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。也可以邮件至 sblig@126.com
