Codex 完整使用教程

讲清 Codex 当前的产品形态与入口，并给出命令行安装、ChatGPT 账号登录、在真实仓库里交付开发任务的完整流程，包括沙箱与审批策略、AGENTS.md 与配置文件的用法。

Codex 现在指的是什么

先把名字理清楚，否则搜到的教程会互相矛盾。今天的 Codex 是 OpenAI 的编程智能体产品线，不是早年那个同名的代码补全模型。它读取整个仓库、编辑文件、执行命令、跑测试，交付的是一段完成的工作，而不是几行补全建议。

它的官方文档目前挂在 ChatGPT 的文档站点下，这也说明了它的定位：Codex 是 ChatGPT 账号体系里的一种工作模式，而不是一个独立售卖的开发工具。

当前有哪些入口

入口	位置	适合
Codex CLI	本地终端	在自己的工作区里直接改代码，功能最完整
IDE 插件	VS Code 及兼容编辑器（Cursor、Windsurf），以及 JetBrains、Xcode	对照代码看 diff、局部采纳修改
ChatGPT 桌面端	macOS、Windows、Linux 应用内切换到 Codex	不想用终端时的图形入口
网页端与云端环境	浏览器	长任务、并行任务，在隔离环境里跑
GitHub 集成	Pull Request	代码审查与从 PR 直接派活

几个入口共用同一个账号与任务记录，可以在终端起个头，再把耗时的部分丢到云端继续。

开始之前

账号。 用 ChatGPT 账号登录，官方建议以 Plus、Pro、Business、Edu 或 Enterprise 方案的身份使用。也可以改用 OpenAI API Key 按量计费，但要知道：部分随账号提供的能力在 API Key 模式下不可用。

项目。 一定要在版本控制下工作，最好是干净的工作区。智能体的价值建立在「改错了可以整段丢掉」之上。

网络。 除普通 HTTPS 外，Codex 的模型采样与流式输出走 WebSocket，需要放行到 chatgpt.com 的 WebSocket 升级请求（TCP 443）。企业网络里这一条经常被漏掉，表现是能登录但输出卡住。

安装 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"

包管理器：

npm install -g @openai/codex

brew install --cask codex

也可以直接从官方仓库的 Release 页面下载对应平台的二进制文件。安装完成后重开终端，确认命令可用：

codex --version

登录

在任意项目目录运行：

codex

首次启动会让你选择登录方式，选 Sign in with ChatGPT，在浏览器里完成授权。

也可以用显式命令：

codex login

codex login status

codex logout

远程开发机、容器或没有图形界面的服务器上，浏览器回调回不来，改用设备码登录：

codex login --device-auth

用 API Key 的场景则是 codex login --with-api-key。

凭据位置。 默认写在用户目录下的 ~/.codex/auth.json，是明文文件，里面有访问令牌，要按密钥对待：不要提交进仓库，不要随镜像分发。配置里可以把凭据存储切到系统钥匙串。

在项目里启动

cd /path/to/your/project
codex

和所有这类工具一样，启动目录决定它的工作范围。在仓库根目录启动。

先让它读，别急着让它改：

说明一下这个项目的结构，以及各目录分别负责什么

移动端导航是在哪几个文件里实现的？

如果它对项目的描述明显跑偏，先解决这个，再谈改代码。

交付一个开发任务

有效的任务描述包含目标、范围和验收标准：

当前 Astro 项目的移动端导航在 430px 以下会溢出容器。
请检查 src/components/layout/ 下的导航组件与相关样式并修复，
不要改动桌面端断点，改完运行 npm run build 确认构建通过。

对比一下无效的写法：「优化一下导航」。后者没有边界，也没有它可以自我判断的完成条件，返回什么都不奇怪。

TUI 里几个常用命令：

• /init — 生成 AGENTS.md 项目约定文件
• /status — 查看当前会话的账号、模型与配置
• /permissions — 调整它能访问什么
• /model — 切换模型与推理强度
• /review — 让它复查当前改动

想继续之前的会话用 codex resume；写进脚本或 CI 用 codex exec 以非交互方式执行。

沙箱与审批：它能做什么

这是使用 Codex 最需要搞清楚的一块。两个开关互相独立：

沙箱模式决定它能碰到什么。

模式	含义
read-only	只读。要改文件或执行命令都得先经过审批
workspace-write	默认。可以读、可以在工作区内改、可以跑常规本地命令
danger-full-access	去掉文件系统与网络边界

审批策略决定它什么时候停下来问你，官方提供 untrusted、on-request、on-failure、never 几档：从「不受信任的命令都要问」，到「只有越过沙箱边界时才问」，再到「完全不问」。

底层实现按平台不同：macOS 用系统自带的 Seatbelt，Linux 与 WSL2 用 bubblewrap（需要先装），Windows 上原生走 PowerShell 沙箱、在 WSL2 下则用 Linux 沙箱。默认情况下沙箱内的命令只能访问受管允许列表上的主机，不是随便联网。

命令行上有 --sandbox、--full-auto 等开关可以临时调整，完整列表以 codex --help 为准。

一条实践建议： 不要用「跳过全部审批与沙箱」的选项去换省事。真的需要完全放开时，把它放进容器或虚拟机里，而不是直接在自己的开发机上跑。

Git、测试与代码审查

改动本身可以直接用自然语言驱动：

我改了哪些文件？把改动提交，说明修复了移动端导航溢出

但更重要的是两件事：动手前建分支，以及让它跑项目自己的验证命令。让它执行 npm test 或 npm run build 并根据真实输出继续修，比看代码「像是对的」可靠得多。

改完之后可以用 /review 让它复查一遍自己的改动。云端与 GitHub 集成还支持从 Pull Request 直接派活，以及对 PR 做审查。

配置：config.toml 与 AGENTS.md

配置文件是 TOML 格式，按这个顺序生效（越靠前优先级越高）：命令行参数、项目里的 .codex/config.toml、用户目录下的 profile 文件、~/.codex/config.toml、系统级 /etc/codex/config.toml，最后才是内置默认值。

常用的键：

approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"

AGENTS.md 放在仓库里，写项目约定：构建命令、测试方式、目录职责、什么不能动。运行 /init 生成初稿，再补上代码里看不出来的部分。它和配置文件的分工很清楚——配置文件管工具行为，AGENTS.md 管项目知识。

顺带一提，这个文件名是跨工具通用的：Claude Code 读的是 CLAUDE.md，但可以用一行导入直接复用同一份 AGENTS.md，两个工具不必各写一遍。

云端环境与 IDE

云端要先把 GitHub 或 GitLab 仓库授权给 Codex，并选择它可以访问哪些仓库；然后在环境里配置依赖、工具、环境变量与密钥。任务跑起来后可以看日志，也可以让它在后台跑，完成后审阅摘要与 diff，确认无误再开 Pull Request。

IDE 插件装在 VS Code 及兼容编辑器（Cursor、Windsurf）里，JetBrains 与 Xcode 也有对应集成。它的优势是可以引用当前打开的文件与选中的代码，在编辑器里直接看 diff、按需采纳，也可以把大任务转派到云端。

安全注意事项

• 改动一律审阅。 当成同事提交的 PR 处理：读一遍、跑测试、有问题打回。
• auth.json 按密钥对待。 不进版本库，不进镜像，怀疑泄露就重新登录并吊销。
• 别在有敏感数据的目录里启动。 它读到的内容会随请求发出去。
• 完全放开权限只在隔离环境里做。 不要为了少按几次确认，在自己的开发机上关掉沙箱。
• 不要因为报证书错误就关闭 TLS 校验。 企业网络做 TLS 拦截时，正确做法是配置可信 CA，而不是跳过验证。

连不上怎么办

登录一直失败、请求超时、输出卡住，先按这个顺序看：

1. 官方服务状态。 打开 status.openai.com，页面上单独列了 Codex 的组件。
2. 账号与方案。 用 /status 确认当前登录身份与生效的配置。
3. 网络。 确认到 chatgpt.com 的 HTTPS 与 WebSocket 都放行；企业网络还要确认 TLS 拦截没有破坏 WebSocket 握手。
4. 代理与证书。 走公司代理时按官方文档配置可信 CA，不要关闭校验。

如果同一台机器上 ChatGPT 网页端也打不开，那说明问题在更靠前的一层，见 ChatGPT 无法使用与连接失败排查。

和 Claude Code 怎么选

两者定位高度重合，差别在账号体系、云端能力和默认的权限模型。横向对比见 Claude Code vs Codex vs Cursor；想按同样的深度把 Claude Code 走一遍，见 Claude Code 完整使用教程。

要把模型接进自己的应用而不是用现成的智能体，那是另一条路，见 OpenAI API 快速上手。

参考资料

• Codex 官方文档
• Codex CLI（官方文档）
• Codex 认证方式（官方文档）
• Codex 沙箱与审批（官方文档）
• openai/codex 官方仓库