|OpenAI Codex

OpenAI Codex

官方

OpenAI 官方 AI 编程助手安装与使用教程,覆盖 CLI、IDE 扩展、云端任务、AGENTS.md、权限审批、安全规范和真实项目工作流。

BLUF 摘要(点开查看)

这篇教程说明如何配置 OpenAI Codex,重点是先准备 API Key、Base URL 和模型名称,再按章节完成安装、配置、验证与排错。

配置前检查

  • 确认工具读取的是哪个配置文件,避免改错项目目录或用户目录
  • 准备 API Key、Base URL、模型名称和计费平台登录方式
  • 先用测试模型跑通一次简单对话,再切换到更贵或更强的模型
  • 把 API Key 放在环境变量或工具密钥管理里,不要写进公开仓库

常见排错

  • 401/403:优先检查 API Key 是否复制完整、是否过期、是否有调用权限
  • 404/模型不存在:检查模型名、Base URL、供应商兼容接口路径是否匹配
  • 429:降低并发,开启重试退避,或升级额度与限速套餐
  • 超时:先切换更快模型或国内直连 API,再缩短输入上下文测试
1

Codex 是什么,适合谁

Codex 是 OpenAI 面向软件开发的 AI 编程助手。它不是单纯聊天工具,而是可以读取项目、解释代码、修改文件、运行命令、做 code review,并把失败日志继续交给模型修复的开发代理。新手最容易混淆的是:Codex 有 CLI、IDE 扩展和云端任务三种入口,适合的场景并不完全一样。

先分清三种入口

如果你只记一件事:本地 CLI 适合直接在项目目录里干活,IDE 扩展适合边看代码边改,云端 Codex 适合把明确任务委托出去后台跑。

先分清三种入口
  • Codex CLI:在终端中启动,适合修 bug、跑测试、生成脚本、批量读写项目文件。
  • Codex IDE:在 VS Code、Cursor、Windsurf、JetBrains 等编辑器内使用,适合结合当前文件和选区做修改。
  • Codex Cloud:从 chatgpt.com/codex 进入,适合把任务交给云端环境处理,例如修复 issue、分析仓库、准备 PR 草稿。
  • 三者不是替代关系:日常本地开发优先 CLI/IDE,明确的大任务再交给云端。

Codex 最适合的任务

Codex 的优势在于“理解项目上下文 + 修改代码 + 自己验证”。不要把它只当成问答模型,用任务目标和验收标准驱动它。

  • 读项目:让它先总结目录结构、技术栈、关键路由和数据来源。
  • 修 bug:给出复现路径、报错日志、期望行为,让它定位并改最小范围。
  • 写功能:明确页面路径、组件范围、数据结构、移动端要求和验证命令。
  • 做 review:让它检查当前 diff 的 bug、回归风险、遗漏测试和安全问题。
  • 写维护材料:让它生成 AGENTS.md、README、部署日志、排错清单。

哪些任务不建议直接交给它

Codex 很强,但不代表所有任务都应该一次性交给它自动完成。权限、安全、支付、生产数据库相关任务要拆小并人工确认。

  • 不要直接让它执行生产删除、批量覆盖、数据库迁移、密钥轮换这类高风险动作。
  • 不要把需求写成“优化一下全站”,应改成“只改这个页面,验证 360px 移动端不横向溢出”。
  • 不要把 API Key、服务器密码、Cookie 直接写进聊天记录或提交到仓库。
  • 不要让它在脏工作区里随便 commit,先要求列出会包含和会排除的文件。

核心要点

官方 CLI 文档:developers.openai.com/codex/cli

官方 IDE 文档:developers.openai.com/codex/ide

官方 AGENTS.md 文档:developers.openai.com/codex/guides/agents-md

2

安装前准备

安装 Codex 前先把基础环境准备好,可以避免一半以上的新手报错。Windows 用户尤其要确认 Node.js、npm、Git、终端路径和项目目录都可用。

准备账号与网络

Codex 首次启动需要登录 OpenAI / ChatGPT 账号,或按提示使用 API Key。账号、套餐、组织和项目权限会影响可用模型与额度。

准备账号与网络
  • 准备一个可正常登录的 ChatGPT / OpenAI 账号。
  • 如果使用 API Key,确认 key 属于正确的 OpenAI Project,并且账号有可用额度。
  • 网络需要能正常访问 OpenAI 相关服务,否则登录、模型调用和云端任务都会失败。
  • 不要把 API Key 写进前端代码、公开仓库、截图或教程评论区。

检查本机基础命令

打开终端,先确认 Node.js、npm 和 Git 都能输出版本号。没有版本号就先安装对应工具。

bash
node -v
npm -v
git --version
  • Node.js:建议安装 LTS 版本,安装后重新打开终端。
  • npm:随 Node.js 一起安装,用来安装 Codex CLI。
  • Git:建议安装 Git for Windows,便于 Codex 查看 diff、分支和提交历史。
  • 终端:Windows 可用 PowerShell、Windows Terminal 或 Git Bash。

准备一个干净项目目录

第一次不要直接拿生产项目练手,建议新建一个测试目录,或在真实项目里先让 Codex 只读分析。

bash
mkdir codex-demo
cd codex-demo
git init
  • 真实项目使用前先执行 git status --short,确认有哪些未提交改动。
  • 让 Codex 修改前先要求它列出计划修改的文件。
  • 重要项目先新建分支,避免把实验改动混进主分支。
  • 不要在没有版本控制的目录里让 Codex 大范围改文件。

注意事项

如果你的项目里已经有未提交改动,先保存或提交自己的工作,再让 Codex 动手。否则很难区分哪些是你改的,哪些是 AI 改的。

3

安装 Codex CLI

Codex CLI 是最直接的本地入口。官方推荐通过 npm 全局安装 @openai/codex,安装完成后用 codex --version 验证。

执行官方安装命令

在终端执行 npm 全局安装命令。安装过程需要联网下载依赖,第一次可能需要几十秒到几分钟。

bash
npm install -g @openai/codex
执行官方安装命令
  • 只从 npm 官方包名安装,不要安装来源不明的同名包。
  • Windows 如果提示权限不足,尝试以管理员身份打开终端后重试。
  • macOS / Linux 如果全局安装权限失败,优先修复 npm 全局目录权限,不要随便使用来路不明的一键脚本。

验证安装结果

安装完成后检查 Codex 命令是否可用。能输出版本号,说明 CLI 已经进入 PATH。

bash
codex --version
  • 能看到类似 codex-cli 0.x.x 的版本号:安装成功。
  • 提示 command not found:终端没有读取到 npm 全局 bin 路径。
  • 提示权限或执行策略错误:检查 Windows PowerShell 执行策略或 npm 全局目录权限。

command not found 的快速修复

先查 npm 全局安装目录,再确认对应 bin 目录已经加入 PATH。Windows 用户安装后一定要重新打开终端。

bash
npm config get prefix
npm bin -g
  • Windows 常见路径:C:\Users\你的用户名\AppData\Roaming\npm
  • macOS / Linux 常见路径:/usr/local/bin~/.npm-global/bin 或 Node 版本管理器目录。
  • 修改 PATH 后重新打开终端,再执行 codex --version
  • 如果公司电脑限制全局安装,先咨询管理员或使用受控开发环境。

核心要点

官方安装命令以 OpenAI 文档为准:developers.openai.com/codex/cli

如果只是临时试用,可以先在测试目录里启动,确认体验后再进入真实项目。

4

登录与首次启动

安装完成后不要急着让 Codex 改项目。第一次启动的目标是完成登录、确认当前目录、让它只读分析项目,并验证你能控制权限。

启动 Codex

进入一个测试目录或项目根目录,执行 codex。首次启动会进入登录或授权流程。

bash
cd your-project
codex
启动 Codex
  • 如果弹出浏览器登录,按页面提示完成 OpenAI / ChatGPT 授权。
  • 如果选择 API Key,确认 key 不会被写进项目文件。
  • 登录成功后,Codex 会以当前目录作为主要工作区。
  • 不要在桌面、下载目录或整个磁盘根目录直接启动 Codex。

第一条指令只做只读分析

首次使用建议先让 Codex 读项目,不要修改文件。这样可以确认它理解的是正确目录和技术栈。

bash
请阅读当前项目,先总结目录结构、技术栈、主要页面入口和数据来源。
不要修改任何文件,也不要运行会改变文件的命令。
第一条指令只做只读分析
  • 回答里应该能看到框架、路由目录、主要配置文件和启动脚本。
  • 如果它识别错项目,先退出,进入正确目录再启动。
  • 如果它准备修改文件,立刻打断并要求先给计划。

确认权限审批逻辑

Codex 在执行命令、写文件、联网或高风险操作时通常会按当前模式请求确认。新手建议保留审批,不要一开始就全自动。

  • 允许:读文件、搜索代码、运行无副作用的检查命令。
  • 谨慎允许:安装依赖、写文件、启动服务、联网下载。
  • 拒绝或拆小:删除目录、覆盖大量文件、重置 Git、修改生产配置。
  • 每次同意前看清命令和工作目录,尤其是 rmdelgit resetgit checkout
如果你看不懂某条命令,不要直接同意。让 Codex 先解释命令目的、影响范围和回退方式。

核心要点

安全的第一条提示词:先读项目,只总结,不修改。

Codex 能力越强,越要把任务边界、验收方式和禁止事项写清楚。

5

在真实项目里使用 Codex

真实项目里最稳的做法是:先让 Codex 只读定位,再确认计划,然后小范围修改,最后运行验证命令并查看 diff。不要一次性把“设计、重构、测试、部署”全部塞进一个模糊请求。

让它先定位问题,不要立刻改

当页面错位、接口报错或构建失败时,先让 Codex 收集上下文和复现原因。

bash
请只读排查这个问题:移动端 390px 下搜索框和推荐栏没有对齐。
先指出可能相关的文件、CSS 规则和复现路径,不要修改文件。
  • 适合 UI bug、构建失败、路由 404、搜索结果缺失等问题。
  • 让它先列文件和原因,可以避免误改无关页面。
  • 如果它的判断不准确,再补充截图、URL、报错日志。

确认计划后再让它修改

计划合理后,把任务改成可验收的修改请求。范围越明确,结果越稳定。

bash
按刚才定位结果修复,但只允许修改首页相关组件和样式。
要求:桌面端不变,移动端 360px 不横向溢出,修完后运行相关检查并给出截图。
  • 写清楚允许修改的目录或文件。
  • 写清楚不能影响的页面或端。
  • 写清楚验证方式,例如截图、lint、ts-check、单测、构建。

让它验证并解释 diff

修改完成后,要求 Codex 用命令和浏览器验证,并说明每个文件为什么被改。

bash
请运行必要检查,然后总结:
1. 修改了哪些文件
2. 每个文件为什么改
3. 如何验证
4. 是否有未处理风险
  • 前端页面:至少看桌面端和移动端首屏。
  • 后端或脚本:至少跑最接近的测试或类型检查。
  • 上线前:要求列出会提交的文件和排除的脏文件。

核心要点

推荐工作流:只读分析 → 修改计划 → 小范围改动 → 运行验证 → 查看 diff → 再决定提交。

如果项目有 AGENTS.md,Codex 会更稳定地遵守包管理器、测试命令、代码风格和安全边界。

6

写好 AGENTS.md

AGENTS.md 是给 Codex 看的项目说明文件,适合写包管理器、构建命令、目录约定、禁止事项、测试流程和提交规范。它相当于把你经常重复告诉 AI 的规则固化到仓库里。

在项目根目录创建 AGENTS.md

把项目级规则写在仓库根目录。以后 Codex 进入这个项目时,会优先读取这些说明。

bash
# AGENTS.md
 
## Project Rules
 
- Use pnpm only. Do not use npm or yarn.
- Make surgical changes. Do not refactor unrelated files.
- Before editing, state which files you plan to change.
- Never run destructive git commands unless explicitly requested.
- After code changes, run pnpm exec tsc -p tsconfig.json --noEmit.
- For frontend changes, verify desktop and 390px mobile layout.
在项目根目录创建 AGENTS.md
  • 规则要短、具体、可验证,不要写空泛价值观。
  • 把最容易出错的地方写进去,例如包管理器、启动命令、部署方式。
  • 如果项目有多套应用,可以在子目录再放一个 AGENTS.md 覆盖局部规则。

把常用验证命令写进去

不要只告诉 Codex “测试一下”,要把项目真实命令写清楚。

bash
## Verification
 
- Type check: pnpm exec tsc -p tsconfig.json --noEmit
- Lint changed files: pnpm exec eslint <changed-files>
- Local preview: pnpm run preview:local
- Production build: pnpm exec next build
  • 命令越准确,Codex 越不容易乱猜。
  • 如果某些命令很慢,写明什么时候才需要跑。
  • 如果部署由人工处理,写明 Codex 不要自动部署。

写清楚提交和部署边界

很多事故不是代码不会写,而是 AI 把无关文件一起提交或提前部署。把边界写进 AGENTS.md。

bash
## Git and Deployment
 
- Do not commit or push unless the user explicitly asks.
- Do not include unrelated dirty files in a commit.
- Before any commit, show git diff --stat and git status --short.
- Deployment requires a separate explicit instruction.
  • 适合多人协作仓库、线上网站、带密钥或部署脚本的项目。
  • Codex 可以帮你写日志,但不应该在你没确认时推送。
  • 如果有服务器部署流程,把入口和等待时间写清楚。

核心要点

官方 AGENTS.md 指南:developers.openai.com/codex/guides/agents-md

AGENTS.md 不是给用户看的文章,而是给 Codex 看的操作手册。

7

IDE 扩展怎么用

如果你主要在编辑器里写代码,Codex IDE 扩展比纯 CLI 更顺手。它能结合当前文件、选区、打开的上下文和编辑器状态,让你少复制路径和代码片段。

选择你的编辑器

OpenAI 官方 Codex IDE 扩展覆盖常见开发编辑器。安装前确认自己使用的是 VS Code、Cursor、Windsurf 或 JetBrains 系列。

选择你的编辑器
  • VS Code / Cursor / Windsurf:通常从扩展市场搜索 Codex 或 OpenAI Codex。
  • JetBrains:从插件市场安装对应插件。
  • 安装后按提示登录同一个 OpenAI / ChatGPT 账号。
  • 如果扩展无法连接,先确认本机网络和账号权限,再检查编辑器代理设置。

用选区驱动修改

IDE 场景下不要只说“优化这个文件”,更好的做法是选中一段代码,再要求它做具体修改。

bash
请只修改我选中的组件:
- 保持桌面端不变
- 移动端按钮换行
- 不改数据结构
- 修改后解释 CSS 变化
  • 适合局部 CSS、组件拆分、类型修复、函数重写。
  • 如果涉及多个文件,要求它先列出依赖关系。
  • 修改后在编辑器里逐个查看 diff,不要盲目全部接受。

CLI 和 IDE 怎么搭配

IDE 适合局部编辑,CLI 适合项目级搜索、批量修改和跑命令。两者搭配比只用一种入口更稳定。

  • 先用 CLI 让 Codex 读项目、找文件、跑测试。
  • 再用 IDE 扩展针对关键组件做精修。
  • 最后回到 CLI 跑检查、看 git diff、生成变更总结。

核心要点

官方 IDE 文档:developers.openai.com/codex/ide

编辑器扩展适合“看着代码改”,CLI 适合“围绕项目完成任务”。

8

云端 Codex 怎么用

云端 Codex 适合把边界清楚的任务交给后台处理。它不适合你一边改一边实时观察的小修小补,更适合“分析这个仓库并准备一个修复方案”这类明确任务。

进入云端入口

打开 chatgpt.com/codex,按页面提示选择仓库或任务入口。具体可用能力取决于你的账号、组织和产品开通状态。

进入云端入口
  • 入口地址:chatgpt.com/codex
  • 适合处理 issue、代码审查、修复明确 bug、准备 PR 草稿。
  • 第一次使用时通常需要授权代码仓库或选择可访问的项目。
  • 不要给云端任务粘贴生产密钥、服务器密码或私有客户数据。

给云端任务写清楚验收标准

云端任务比本地 CLI 更需要边界,因为你不会一直盯着它每一步。任务描述必须包含目标、范围、禁止事项和验证方式。

bash
目标:修复 /app/codex 移动端图片溢出。
范围:只允许修改 app 教程详情页样式。
禁止:不要重构路由,不要改其他内容数据。
验证:390px 宽度无横向滚动,桌面端布局不变。
  • 任务越像 issue,云端 Codex 越容易交付可 review 的结果。
  • 不要只写“优化一下”,要写页面、文件范围和成功标准。
  • 完成后先 review diff,再决定是否合并。

什么时候不用云端

如果你需要频繁查看本地浏览器、处理本机文件、使用本地登录态,优先用本地 CLI 或 IDE。

  • 需要本机浏览器截图:优先本地 Codex。
  • 需要访问本机服务 localhost:优先本地 Codex。
  • 需要非常快地来回调整 UI:优先 IDE 扩展。
  • 需要长时间后台分析仓库或准备 PR:适合云端 Codex。

核心要点

云端任务要写成“可验收的工单”,不要写成随口聊天。

本地 CLI、IDE 扩展和云端 Codex 可以按任务阶段组合使用。

9

权限、安全和密钥管理

Codex 可以读取和修改本地文件,也可能运行命令。安全使用的关键不是完全不用它,而是把权限边界、密钥处理和 Git 回退路径设置好。

先保护密钥文件

任何包含 API Key、数据库密码、Cookie、Token 的文件,都应该被 .gitignore 排除,并避免让 Codex 在回答中原样输出。

bash
# .gitignore
.env
.env.local
.env.*.local
*.key
*.pem
secrets.json
credentials.json
  • 让 Codex 检查配置时,可以要求它只说明变量名,不展示变量值。
  • 如果发现密钥已经提交到仓库,先轮换密钥,再清理 Git 历史。
  • 截图前检查页面上是否显示 API Key、Token 或服务器地址。

高风险命令必须人工确认

删除、覆盖、迁移、重置、推送、部署都属于高风险操作。让 Codex 先解释,再决定是否执行。

  • 谨慎命令:rm -rfRemove-Item -Recursegit reset --hardgit clean -fd
  • 谨慎操作:数据库迁移、生产部署、批量替换、依赖大版本升级。
  • 执行前要求它说明:影响目录、是否可回退、验证方式。
  • 如果只是改文章或页面,不应该出现删除整个目录的命令。
不要让 Codex 在你没确认的情况下执行 `git reset --hard` 或清理未跟踪文件。

用 Git 做回退保险

Codex 修改前后都看一眼 Git 状态。小步提交可以把风险控制在可回退范围内。

bash
git status --short
git diff --stat
git diff
  • 修改前:确认当前有哪些你自己的未提交改动。
  • 修改后:看 diff 是否只包含本次任务范围。
  • 提交前:排除无关文件、日志、临时截图、密钥和构建产物。
  • 不确定时:先让 Codex 列出“本次会提交”和“不会提交”的文件。

核心要点

Codex 能帮你提高速度,但最终合并、推送、部署仍然应由你确认。

安全边界写进 AGENTS.md,比每次口头提醒更稳定。

10

常见问题排查

Codex 的常见问题大多集中在 npm 安装、PATH、登录、网络、额度、权限和当前目录。按下面顺序排查,通常能快速定位。

npm 安装失败

先判断是网络问题、权限问题还是 npm 缓存问题。不要反复换来源不明的安装脚本。

bash
npm cache verify
npm install -g @openai/codex
  • 网络超时:换稳定网络后重试。
  • 权限不足:Windows 用管理员终端,macOS/Linux 修复 npm 全局目录权限。
  • 依赖解析失败:升级 Node.js LTS 后重新安装。
  • 公司网络限制:使用公司允许的代理或内部 npm 源。

codex 命令不存在

这通常不是 Codex 没装好,而是 npm 全局 bin 没进 PATH,或安装后没有重新打开终端。

bash
npm config get prefix
npm bin -g
where codex
  • Windows 用 where codex 查看命令是否能被找到。
  • macOS/Linux 用 which codex 查看命令路径。
  • 修改环境变量后关闭所有终端窗口,再重新打开。
  • 如果仍失败,重新安装 Node.js LTS 并勾选加入 PATH。

登录失败或无可用模型

先确认账号能正常登录 OpenAI / ChatGPT,再确认 API Key、项目权限、组织权限和额度。

  • 浏览器能登录,不代表 CLI 一定已授权;按 CLI 提示重新登录。
  • API Key 要属于正确项目,不要复制错组织或旧 key。
  • 额度不足、项目没开通、组织权限不足都会导致模型不可用。
  • 网络不稳定时,登录回调和模型请求都可能超时。

Codex 改错目录或改太多文件

这通常是启动目录不对,或任务边界写得太宽。先停止,再回到正确项目根目录重新启动。

bash
pwd
git status --short
  • 确认当前目录就是目标项目根目录。
  • 要求 Codex 先列修改计划,不要直接改。
  • 修改后如果范围不对,不要继续叠加修复,先查看 diff 再决定回退。
  • 把“只允许修改哪些文件”写进任务描述。

接口报 401、429、timeout

这些属于 API 调用问题,先按错误类型排查,不要盲目重装 Codex。

  • 401 / invalid API key:重新复制 API Key,确认没有空格、没有用错项目。
  • 429 / rate limit:降低并发,稍后重试,或检查套餐和限速。
  • insufficient quota:检查账单、余额、项目额度和组织限制。
  • timeout:先排查网络,再缩短上下文或换更快模型。

核心要点

本站相关排错:/error/invalid-api-key、/error/429-too-many-requests、/error/timeout、/error/insufficient-quota

如果只是 API Key 或额度问题,重装 Codex 通常没有用。

11

推荐工作流和内链

把 Codex 用好,不靠一次性长提示词,而靠稳定流程。下面这套流程适合大多数网站、脚本、后端和工具项目。

日常开发推荐流程

每次任务都按“读、计划、改、验、总结”推进,速度会比直接让它乱改更快。

bash
1. 只读分析:找相关文件和原因
2. 修改计划:列出要改的文件和验证方式
3. 小范围实现:只改本次任务需要的代码
4. 本地验证:运行测试、类型检查或页面截图
5. 查看 diff:确认没有混入无关文件
6. 人工决定:是否 commit、push、deploy
  • 复杂任务拆成多次小任务,比一次性全自动更可靠。
  • UI 任务必须给桌面端和移动端验收标准。
  • 内容任务必须给结构、语气、不可删除项和内链要求。
  • 部署任务必须明确是否只部署、是否需要检查、是否需要推送。

本站相关教程

如果你要把 Codex 和其他 AI API、模型切换工具一起用,可以继续看这些页面。

  • OpenAI API 接入:/api/openai
  • CC Switch 统一管理 Codex、Claude Code、Gemini CLI 配置:/app/ccswitch
  • Claude Code 安装与模型接入:/app/claude-code
  • API Key 错误排查:/error/invalid-api-key
  • 请求超时排查:/error/timeout

一个可以直接复制的高质量任务模板

以后给 Codex 派任务,可以从这个模板开始改。

bash
目标:修复/新增 [具体页面或功能]
范围:只允许修改 [文件或目录]
禁止:不要修改 [无关页面、数据源、部署脚本]
要求:保留现有风格,移动端 360px 不横向溢出
验证:运行 [具体命令],并截图检查 [具体 URL]
交付:列出修改文件、验证结果、未处理风险
  • 把“你要什么”和“不要什么”都写进去。
  • 把验收标准写成可检查的事实。
  • 把提交、推送、部署作为单独指令,不要默认授权。

核心要点

Codex 最适合处理边界清楚、可验证、有版本控制保护的开发任务。

写给 Codex 的提示词越像工程任务单,交付质量越稳定。