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,再缩短输入上下文测试
Codex 是什么,适合谁
先分清三种入口
如果你只记一件事:本地 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
安装前准备
准备账号与网络
Codex 首次启动需要登录 OpenAI / ChatGPT 账号,或按提示使用 API Key。账号、套餐、组织和项目权限会影响可用模型与额度。

- 准备一个可正常登录的 ChatGPT / OpenAI 账号。
- 如果使用 API Key,确认 key 属于正确的 OpenAI Project,并且账号有可用额度。
- 网络需要能正常访问 OpenAI 相关服务,否则登录、模型调用和云端任务都会失败。
- 不要把 API Key 写进前端代码、公开仓库、截图或教程评论区。
检查本机基础命令
打开终端,先确认 Node.js、npm 和 Git 都能输出版本号。没有版本号就先安装对应工具。
node -vnpm -vgit --version
- Node.js:建议安装 LTS 版本,安装后重新打开终端。
- npm:随 Node.js 一起安装,用来安装 Codex CLI。
- Git:建议安装 Git for Windows,便于 Codex 查看 diff、分支和提交历史。
- 终端:Windows 可用 PowerShell、Windows Terminal 或 Git Bash。
准备一个干净项目目录
第一次不要直接拿生产项目练手,建议新建一个测试目录,或在真实项目里先让 Codex 只读分析。
mkdir codex-democd codex-demogit init
- 真实项目使用前先执行
git status --short,确认有哪些未提交改动。 - 让 Codex 修改前先要求它列出计划修改的文件。
- 重要项目先新建分支,避免把实验改动混进主分支。
- 不要在没有版本控制的目录里让 Codex 大范围改文件。
注意事项
如果你的项目里已经有未提交改动,先保存或提交自己的工作,再让 Codex 动手。否则很难区分哪些是你改的,哪些是 AI 改的。
安装 Codex CLI
@openai/codex,安装完成后用 codex --version 验证。执行官方安装命令
在终端执行 npm 全局安装命令。安装过程需要联网下载依赖,第一次可能需要几十秒到几分钟。
npm install -g @openai/codex

- 只从 npm 官方包名安装,不要安装来源不明的同名包。
- Windows 如果提示权限不足,尝试以管理员身份打开终端后重试。
- macOS / Linux 如果全局安装权限失败,优先修复 npm 全局目录权限,不要随便使用来路不明的一键脚本。
验证安装结果
安装完成后检查 Codex 命令是否可用。能输出版本号,说明 CLI 已经进入 PATH。
codex --version
- 能看到类似
codex-cli 0.x.x的版本号:安装成功。 - 提示 command not found:终端没有读取到 npm 全局 bin 路径。
- 提示权限或执行策略错误:检查 Windows PowerShell 执行策略或 npm 全局目录权限。
command not found 的快速修复
先查 npm 全局安装目录,再确认对应 bin 目录已经加入 PATH。Windows 用户安装后一定要重新打开终端。
npm config get prefixnpm bin -g
- Windows 常见路径:
C:\Users\你的用户名\AppData\Roaming\npm。 - macOS / Linux 常见路径:
/usr/local/bin、~/.npm-global/bin或 Node 版本管理器目录。 - 修改 PATH 后重新打开终端,再执行
codex --version。 - 如果公司电脑限制全局安装,先咨询管理员或使用受控开发环境。
登录与首次启动
启动 Codex
进入一个测试目录或项目根目录,执行 codex。首次启动会进入登录或授权流程。
cd your-projectcodex

- 如果弹出浏览器登录,按页面提示完成 OpenAI / ChatGPT 授权。
- 如果选择 API Key,确认 key 不会被写进项目文件。
- 登录成功后,Codex 会以当前目录作为主要工作区。
- 不要在桌面、下载目录或整个磁盘根目录直接启动 Codex。
第一条指令只做只读分析
首次使用建议先让 Codex 读项目,不要修改文件。这样可以确认它理解的是正确目录和技术栈。
请阅读当前项目,先总结目录结构、技术栈、主要页面入口和数据来源。不要修改任何文件,也不要运行会改变文件的命令。

- 回答里应该能看到框架、路由目录、主要配置文件和启动脚本。
- 如果它识别错项目,先退出,进入正确目录再启动。
- 如果它准备修改文件,立刻打断并要求先给计划。
确认权限审批逻辑
Codex 在执行命令、写文件、联网或高风险操作时通常会按当前模式请求确认。新手建议保留审批,不要一开始就全自动。
- 允许:读文件、搜索代码、运行无副作用的检查命令。
- 谨慎允许:安装依赖、写文件、启动服务、联网下载。
- 拒绝或拆小:删除目录、覆盖大量文件、重置 Git、修改生产配置。
- 每次同意前看清命令和工作目录,尤其是
rm、del、git reset、git checkout。
核心要点
安全的第一条提示词:先读项目,只总结,不修改。
Codex 能力越强,越要把任务边界、验收方式和禁止事项写清楚。
在真实项目里使用 Codex
让它先定位问题,不要立刻改
当页面错位、接口报错或构建失败时,先让 Codex 收集上下文和复现原因。
请只读排查这个问题:移动端 390px 下搜索框和推荐栏没有对齐。先指出可能相关的文件、CSS 规则和复现路径,不要修改文件。
- 适合 UI bug、构建失败、路由 404、搜索结果缺失等问题。
- 让它先列文件和原因,可以避免误改无关页面。
- 如果它的判断不准确,再补充截图、URL、报错日志。
确认计划后再让它修改
计划合理后,把任务改成可验收的修改请求。范围越明确,结果越稳定。
按刚才定位结果修复,但只允许修改首页相关组件和样式。要求:桌面端不变,移动端 360px 不横向溢出,修完后运行相关检查并给出截图。
- 写清楚允许修改的目录或文件。
- 写清楚不能影响的页面或端。
- 写清楚验证方式,例如截图、lint、ts-check、单测、构建。
让它验证并解释 diff
修改完成后,要求 Codex 用命令和浏览器验证,并说明每个文件为什么被改。
请运行必要检查,然后总结:1. 修改了哪些文件2. 每个文件为什么改3. 如何验证4. 是否有未处理风险
- 前端页面:至少看桌面端和移动端首屏。
- 后端或脚本:至少跑最接近的测试或类型检查。
- 上线前:要求列出会提交的文件和排除的脏文件。
核心要点
推荐工作流:只读分析 → 修改计划 → 小范围改动 → 运行验证 → 查看 diff → 再决定提交。
如果项目有 AGENTS.md,Codex 会更稳定地遵守包管理器、测试命令、代码风格和安全边界。
写好 AGENTS.md
在项目根目录创建 AGENTS.md
把项目级规则写在仓库根目录。以后 Codex 进入这个项目时,会优先读取这些说明。
# 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 覆盖局部规则。
把常用验证命令写进去
不要只告诉 Codex “测试一下”,要把项目真实命令写清楚。
## 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。
## 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 看的操作手册。
IDE 扩展怎么用
选择你的编辑器
OpenAI 官方 Codex IDE 扩展覆盖常见开发编辑器。安装前确认自己使用的是 VS Code、Cursor、Windsurf 或 JetBrains 系列。

- VS Code / Cursor / Windsurf:通常从扩展市场搜索 Codex 或 OpenAI Codex。
- JetBrains:从插件市场安装对应插件。
- 安装后按提示登录同一个 OpenAI / ChatGPT 账号。
- 如果扩展无法连接,先确认本机网络和账号权限,再检查编辑器代理设置。
用选区驱动修改
IDE 场景下不要只说“优化这个文件”,更好的做法是选中一段代码,再要求它做具体修改。
请只修改我选中的组件:- 保持桌面端不变- 移动端按钮换行- 不改数据结构- 修改后解释 CSS 变化
- 适合局部 CSS、组件拆分、类型修复、函数重写。
- 如果涉及多个文件,要求它先列出依赖关系。
- 修改后在编辑器里逐个查看 diff,不要盲目全部接受。
CLI 和 IDE 怎么搭配
IDE 适合局部编辑,CLI 适合项目级搜索、批量修改和跑命令。两者搭配比只用一种入口更稳定。
- 先用 CLI 让 Codex 读项目、找文件、跑测试。
- 再用 IDE 扩展针对关键组件做精修。
- 最后回到 CLI 跑检查、看 git diff、生成变更总结。
云端 Codex 怎么用
进入云端入口
打开 chatgpt.com/codex,按页面提示选择仓库或任务入口。具体可用能力取决于你的账号、组织和产品开通状态。

- 入口地址:chatgpt.com/codex
- 适合处理 issue、代码审查、修复明确 bug、准备 PR 草稿。
- 第一次使用时通常需要授权代码仓库或选择可访问的项目。
- 不要给云端任务粘贴生产密钥、服务器密码或私有客户数据。
给云端任务写清楚验收标准
云端任务比本地 CLI 更需要边界,因为你不会一直盯着它每一步。任务描述必须包含目标、范围、禁止事项和验证方式。
目标:修复 /app/codex 移动端图片溢出。范围:只允许修改 app 教程详情页样式。禁止:不要重构路由,不要改其他内容数据。验证:390px 宽度无横向滚动,桌面端布局不变。
- 任务越像 issue,云端 Codex 越容易交付可 review 的结果。
- 不要只写“优化一下”,要写页面、文件范围和成功标准。
- 完成后先 review diff,再决定是否合并。
什么时候不用云端
如果你需要频繁查看本地浏览器、处理本机文件、使用本地登录态,优先用本地 CLI 或 IDE。
- 需要本机浏览器截图:优先本地 Codex。
- 需要访问本机服务 localhost:优先本地 Codex。
- 需要非常快地来回调整 UI:优先 IDE 扩展。
- 需要长时间后台分析仓库或准备 PR:适合云端 Codex。
核心要点
云端任务要写成“可验收的工单”,不要写成随口聊天。
本地 CLI、IDE 扩展和云端 Codex 可以按任务阶段组合使用。
权限、安全和密钥管理
先保护密钥文件
任何包含 API Key、数据库密码、Cookie、Token 的文件,都应该被 .gitignore 排除,并避免让 Codex 在回答中原样输出。
# .gitignore.env.env.local.env.*.local*.key*.pemsecrets.jsoncredentials.json
- 让 Codex 检查配置时,可以要求它只说明变量名,不展示变量值。
- 如果发现密钥已经提交到仓库,先轮换密钥,再清理 Git 历史。
- 截图前检查页面上是否显示 API Key、Token 或服务器地址。
高风险命令必须人工确认
删除、覆盖、迁移、重置、推送、部署都属于高风险操作。让 Codex 先解释,再决定是否执行。
- 谨慎命令:
rm -rf、Remove-Item -Recurse、git reset --hard、git clean -fd。 - 谨慎操作:数据库迁移、生产部署、批量替换、依赖大版本升级。
- 执行前要求它说明:影响目录、是否可回退、验证方式。
- 如果只是改文章或页面,不应该出现删除整个目录的命令。
用 Git 做回退保险
Codex 修改前后都看一眼 Git 状态。小步提交可以把风险控制在可回退范围内。
git status --shortgit diff --statgit diff
- 修改前:确认当前有哪些你自己的未提交改动。
- 修改后:看 diff 是否只包含本次任务范围。
- 提交前:排除无关文件、日志、临时截图、密钥和构建产物。
- 不确定时:先让 Codex 列出“本次会提交”和“不会提交”的文件。
核心要点
Codex 能帮你提高速度,但最终合并、推送、部署仍然应由你确认。
安全边界写进 AGENTS.md,比每次口头提醒更稳定。
常见问题排查
npm 安装失败
先判断是网络问题、权限问题还是 npm 缓存问题。不要反复换来源不明的安装脚本。
npm cache verifynpm install -g @openai/codex
- 网络超时:换稳定网络后重试。
- 权限不足:Windows 用管理员终端,macOS/Linux 修复 npm 全局目录权限。
- 依赖解析失败:升级 Node.js LTS 后重新安装。
- 公司网络限制:使用公司允许的代理或内部 npm 源。
codex 命令不存在
这通常不是 Codex 没装好,而是 npm 全局 bin 没进 PATH,或安装后没有重新打开终端。
npm config get prefixnpm bin -gwhere codex
- Windows 用
where codex查看命令是否能被找到。 - macOS/Linux 用
which codex查看命令路径。 - 修改环境变量后关闭所有终端窗口,再重新打开。
- 如果仍失败,重新安装 Node.js LTS 并勾选加入 PATH。
登录失败或无可用模型
先确认账号能正常登录 OpenAI / ChatGPT,再确认 API Key、项目权限、组织权限和额度。
- 浏览器能登录,不代表 CLI 一定已授权;按 CLI 提示重新登录。
- API Key 要属于正确项目,不要复制错组织或旧 key。
- 额度不足、项目没开通、组织权限不足都会导致模型不可用。
- 网络不稳定时,登录回调和模型请求都可能超时。
Codex 改错目录或改太多文件
这通常是启动目录不对,或任务边界写得太宽。先停止,再回到正确项目根目录重新启动。
pwdgit 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 通常没有用。
推荐工作流和内链
日常开发推荐流程
每次任务都按“读、计划、改、验、总结”推进,速度会比直接让它乱改更快。
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 派任务,可以从这个模板开始改。
目标:修复/新增 [具体页面或功能]范围:只允许修改 [文件或目录]禁止:不要修改 [无关页面、数据源、部署脚本]要求:保留现有风格,移动端 360px 不横向溢出验证:运行 [具体命令],并截图检查 [具体 URL]交付:列出修改文件、验证结果、未处理风险
- 把“你要什么”和“不要什么”都写进去。
- 把验收标准写成可检查的事实。
- 把提交、推送、部署作为单独指令,不要默认授权。
核心要点
Codex 最适合处理边界清楚、可验证、有版本控制保护的开发任务。
写给 Codex 的提示词越像工程任务单,交付质量越稳定。
其他应用教程
CC Switch
推荐跨平台 AI 终端配置管理工具,统一管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 的 API 供应商、模型、MCP 和 Skills。
Claude Code
热门Claude Code 安装、区域限制处理、CC Switch 配置与 DeepSeek 模型接入完整教程
OpenClaw
开源开源AI助手平台,支持飞书集成,一键部署私人AI助理
OpenClaw 接入飞书
飞书基于飞书开放平台创建机器人,并通过 OpenClaw Feishu 插件把本地 AI 助手接入飞书对话
Claudian Obsidian 插件
插件在Obsidian中直接使用Claude AI助手,结合笔记与AI提升效率
Hermes Agent
AgentNous Research 开源 AI Agent 安装与初始化教程,覆盖一键安装、模型配置、健康检查和常见问题排查
LLM Wiki 知识编译器
知识管理将零散信息编译成结构化知识网络的AI驱动知识管理系统,基于Obsidian和Claude构建