零基础到独立交付项目：OpenAI Codex 完全入门教程（含提示词模板+实战案例+避坑清单）

从安装到第一个项目上线，覆盖 CLI、桌面App、VS Code 三大形态，含提示词模板、配置详解、MCP插件、实战案例与避坑清单。零基础到独立交付项目，这一篇就够了。

OpenAI Codex 是2025年5月推出的 AI 编程智能体（Agent），它不是”代码补全工具”，而是一个能独立读取代码库、编写代码、运行测试、修复错误、提交 PR 的自主编程代理。底层搭载 GPT-5 / GPT-5-Codex 模型，支持终端 CLI、桌面 App、VS Code 扩展和网页版四种形态。12月又推出了 GPT-5.1-Codex-Max，专为编码任务优化，成为目前最强的 AI 编码工具之一。

与 GitHub Copilot 的”补全式”辅助不同，Codex 的核心突破在于完整的任务执行链：你描述需求 → 它自主分析代码库 → 编写代码 → 运行测试 → 修复错误 → 提交 PR。人类从”写代码的人”变成了”派活的人”。

一、Codex 是什么？先搞清楚定位

一句话定义

Codex 是 OpenAI 推出的本地运行的 AI 编码智能体，用 Rust 构建，开源（Apache 2.0），跨平台支持 macOS、Linux 和 Windows（WSL2）。它能在你的终端里通过自然语言读取、修改和执行代码，也可以通过桌面 App 或 IDE 插件使用。

它不是什么

• 不是代码补全工具：不是 Copilot 那样你写一行它补一行，而是你描述一个完整任务，它自主完成
• 不是聊天机器人：它有手有脚——能读文件、改文件、跑命令、操作浏览器
• 不是老 Codex（code-davinci）：2021 年的旧 Codex 已停用，这是全新的 Agent 产品

三种使用形态对比

二、安装指南：3条路径，选一条最适合的

路径 A：桌面 App（最推荐，零门槛）

1. 打开 chatgpt.com/codex 或 ChatGPT 左侧栏找 Codex（beta）图标
2. 点 Download for Windows / macOS，下载安装包
3. 双击安装（跟装微信差不多）
4. 打开 Codex → Sign in with ChatGPT account → 10秒授权完事
5. 选一个工作文件夹（第一次可以先建一个空文件夹，比如 Desktop/My-First-Codex/）
6. 选 Local 模式（本地运行）或 Cloud 模式（云端沙箱）

💡 要不要付费？Codex 走的是你的 ChatGPT 订阅额度（Plus / Pro / Team / Enterprise），不用另外掏钱。Plus 用户每月有 5 美元免费 API 额度，Pro 用户 50 美元。也可以选 API Key 登录按 token 计费，但零基础不建议碰。

路径 B：CLI 命令行（功能最全）

前提条件：Node.js v22 或更高版本。检查命令：

node --version # 输出应 >= v22.0.0

安装命令（三选一）：

• npm 全局安装（推荐）：npm install -g @openai/codex
• Homebrew 安装（macOS）：brew install --cask codex
• 下载二进制文件：访问 GitHub Releases 下载对应平台版本

Windows 用户注意：Codex CLI 在 Windows 原生环境可能有兼容问题，推荐通过 WSL2 使用。安装 WSL：wsl --install，重启后在 WSL 环境中安装 Codex。

验证安装：

codex --version

路径 C：VS Code 扩展

1. 打开 VS Code → 侧边栏扩展市场
2. 搜索 Codex → 安装
3. 登录 ChatGPT 账号
4. 选中代码块，右键选择 Ask Codex 获取解释或重构建议

💡 Cursor 用户：Codex 扩展默认隐藏在折叠项目中。可以固定它，或通过设置主侧边栏 Location 为垂直布局来显示。

三、认证配置：两种登录方式

方式一：Sign in with ChatGPT（新手推荐）

运行 codex 后选择 Sign in with ChatGPT，支持以下计划：

• ✅ ChatGPT Plus（$20/月）
• ✅ ChatGPT Pro（$200/月）
• ✅ ChatGPT Team（拼车约 10-15 元/月）
• ✅ ChatGPT Edu / Enterprise

方式二：API Key（脚本/CI/成本控制）

在 ~/.codex/auth.json 中配置：

{ “OPENAI_API_KEY”: “sk-your-api-key-here” }

或通过环境变量：export OPENAI_API_KEY="sk-your-api-key-here"

💡 远程服务器使用技巧：先在本地完成认证，然后复制认证文件到远程：scp ~/.codex/auth.json user@remote:~/.codex/auth.json，之后在远程服务器上就可以通过 ChatGPT 认证使用 Codex 了。

四、核心概念：理解这5个，Codex 就不”玄学”了

4.1 Ask vs Code：两个最关键的开关

• Ask（问）：只问问题、只读、不动手——比如”这个项目在干嘛？””哪行可能报错？”
• Code（写代码/干活）：让它动手改文件、建文件、跑命令——这才是最值钱的开关

新手第一次用，先 Ask 了解项目，再 Code 动手改。

4.2 三种审批模式（安全旋钮）

4.3 当前目录 = 工作台

Codex 在你运行命令的目录下工作，这个目录就是它的工作台。它能看到这个目录里的所有文件，但不能越界访问其他目录（除非你授权）。

4.4 Diff 工作流（为什么 Codex 相对安全）

Codex 改代码不是直接覆盖，而是先生成 Diff（差异），你确认后再应用。每次动手前最好有个 Git 存档能回滚——哪怕你不懂 Git，点一下”Create checkpoint / 初始化仓库”也行。

4.5 模型选择

• gpt-5-codex：专为编码优化，速度快，适合日常编码
• gpt-5：推理能力强，适合复杂逻辑和架构设计
• model_reasoning_effort：low / medium / high，级别越高处理复杂问题越准，但速度更慢

新手推荐：gpt-5 + high，理解能力强，虽然慢一点但值得。

五、第一个任务：从零写一个能”直接玩”的东西

别拿它练”写个登录系统”这种大词，从最小成就感开始。在输入框里直接打：

在这个文件夹里，写一个猜数字小游戏：电脑随机想 1–100 的数，我输入猜测，它回”大了/小了”，最多7次机会。把代码存成 guess.py，最后加一句运行指令提示我怎么玩。只写 Python 标准库，别装第三方包。写完了告诉我：我该在终端里打哪行命令来运行。

然后点 Code（不是 Ask）。Codex 会自动：创建文件 → 写代码 → 给你运行指令。整个过程不到 30 秒。

CLI 用户的非交互式单条命令：

codex “在这个文件夹里写一个猜数字小游戏，存成 guess.py，只用 Python 标准库”

六、配置文件详解：config.toml 与 AGENTS.md

6.1 config.toml（全局配置）

位置：~/.codex/config.toml，没有的话可以自己创建。这个配置文件是全局共享的，CLI 和 IDE 扩展共享配置。

model = “gpt-5”
model_reasoning_effort = “medium”
approval_mode = “auto-edit”
preferred_auth_method = “apikey”

[model_providers.my_provider]
name = “my_provider”
base_url = “https://your-api-provider.com/v1”
wire_api = “responses”

关键配置项说明：

6.2 AGENTS.md（项目记忆文件）

AGENTS.md 类似 Claude Code 的 CLAUDE.md，让 AI 记住项目特定的指导。有三个位置：

• ~/.codex/AGENTS.md：全局个人指令（如”Always respond in Chinese-simplified”）
• 项目根目录/AGENTS.md：针对整个项目的说明（构建步骤、测试命令、编码规范）
• 子目录/AGENTS.md：针对特定模块的详细说明

💡 核心原则：给 Codex 一张地图，而不是一本 1000 页的说明书。AGENTS.md 应该是”目录”而非”百科全书”——保持简短（约 100 行），指向 docs/ 目录中更详细的文档。过大的指令文件会挤占上下文，导致 AI 遗漏关键约束。

用 /init 命令可以让 Codex 自动生成初始 AGENTS.md 文件。

七、提示词工程：5条铁律 + 3套实战模板

7.1 五条提示词铁律

• 提供清晰的代码指引：指定文件名、包名、目录，甚至行数。Codex 能自己搜索，但缩小范围效率更高
• 包含验证步骤：告诉它任务完成时如何验证是否成功（如”运行 npm test 确保通过”）
• 拆分大任务：复杂任务分解成更小、更专注的步骤，每个步骤可独立提交
• 先计划再执行：让 Codex 先写执行计划，确认后再分阶段实现
• 遇到 bug 粘贴日志：把详细错误信息或堆栈跟踪粘贴给 Codex，它能并行分析问题

7.2 三套可直接复制的提示词模板

模板一：分阶段实现复杂功能

go ahead and do the following:
1. investigate how auth is currently implemented in this codebase
2. think about how to add OAuth2 (Google/GitHub) support
3. create a sectioned checklist to implement it, where each section:
– is a self-contained phase
– can be committed separately
– is prioritized by risk/importance
then go ahead and implement each phase. commit and push after a phase is done before you move to the next.

模板二：报错驱动的 Bug 修复

这个函数返回 null 但应该返回用户对象。请：
1. 阅读 src/auth/service.ts 中的 getUserInfo 函数
2. 检查数据库查询是否正确
3. 添加 console.log 打印中间结果
4. 运行 npm test 验证修复
5. 确保所有测试通过后再提交

模板三：代码审查 + 重构

审查 src/utils/ 目录下所有文件，找出：
1. 未使用的导入和变量
2. 重复的代码逻辑
3. 可以提取为公共函数的部分
4. 缺少类型注解的地方
然后生成一份重构计划，等我确认后再执行。

7.3 提示词好坏对比

八、CLI 日常用法速查

常用命令

TUI 内部命令

💡 VS Code 扩展拖拽技巧：直接拖文件到聊天框是不行的！需要按住 Shift 再拖拽，才能将文件完整路径加入聊天框。

九、MCP 插件系统：给 AI 装”外挂”

MCP（Model Context Protocol）是给 AI 装插件的协议。默认情况下 Codex 只能写代码、读文件；装了 MCP 插件后，它可以操作浏览器、查询数据库、调用外部 API。

安装 MCP 服务

方式一：CLI 命令（推荐）

codex mcp add context7 — npx -y @upstash/context7-mcp@latest

方式二：直接修改 ~/.codex/config.toml

[mcp_servers.context7]
command = “npx”
args = [“-y”, “@upstash/context7-mcp@latest”]

方式三：用提示词让 AI 帮你装（零代码）

帮我管理 MCP 服务。添加以下配置：
{ “mcpServers”: { “chrome-devtools”: { “command”: “npx”, “args”: [“chrome-devtools-mcp@latest”] } } }
提取配置中的服务名、command、args，转换成 codex mcp add-json 命令并执行。

Codex 作为 MCP Server 运行

Codex 还能反过来作为 MCP Server 给其他 AI 用，比如让 Claude Code 连上 Codex：

claude mcp add codex -s user — codex -m gpt-5-codex -c model_reasoning_effort=”high” mcp

这样日常工作用 Claude Code（快、理解能力强），遇到复杂 bug 自动调用 Codex（慢但查得准），完美搭档。

十、实战案例：3个真实项目拆解

案例一：实时聊天应用（全栈，2小时上线）

向 Codex 输入任务描述：

创建一个实时聊天 Web 应用，支持多房间、用户认证、消息历史记录和表情符号。使用 React、Node.js 和 MongoDB。

Codex 自动完成：项目结构生成 → 前后端代码 → 数据库模型 → 通信逻辑 → docker-compose 配置 → GitHub Actions 工作流。从零到上线不到 2 小时。

案例二：在线书店（多任务并行开发）

Codex 用时约 15 分钟，同时生成了所有需要的代码，包括前端组件、API 端点、数据模型和测试用例。

案例三：百万行级内部产品（3人团队，5个月）

OpenAI 内部团队用 Codex 从空仓库开始，5个月内由 3 名工程师驱动 Codex 产出约 100 万行代码、合并约 1500 个 PR。平均每位工程师每天 3.5 个 PR，且随团队扩大到 7 人后人均产出反而提升。整个过程中人类从未直接编写过任何代码。

核心经验：工程师的角色从”写代码”转向”设计环境、明确意图、构建反馈回路”。给 Codex 一张地图而非说明书，用 AGENTS.md 做目录索引，详细文档放 docs/ 目录。

十一、10大效率提升技巧

1. 先计划再执行：让 Codex 先生成执行计划清单，确认后分阶段实现，每个阶段独立 commit
2. 用 /init 初始化项目记忆：让 Codex 自动扫描项目并生成 AGENTS.md，后续使用时自动理解项目结构
3. 全局设置低详细度，代码设置高详细度：状态消息简洁，代码覆盖详细，可读性提升 3 倍
4. 指定工具调用预算：在提示词中加”最多 2 次搜索”，强制效率，减少 50% 不必要调用
5. 使用 Responses API：在工具调用之间保持推理，多步骤任务效率提升 25%
6. 推理强度按需切换：简单修复用 low（快 3 倍），复杂重构用 high（更准确）
7. 并行工具调用：明确请求”同时搜索多个文件”，获得 2 倍速度
8. 用 GPT-5 最了解的技术栈：Next.js + Tailwind + shadcn/ui 开箱即用，代码质量提升 40%
9. 启用工具前言：让模型在行动前解释计划，用户满意度提升 35%
10. 双 AI 联动：Claude Code 做日常执行，Codex 专门查 bug，取长补短

十二、成本分析与方案选择

API 定价参考（实际使用）

十三、避坑清单：10个高频问题解决方案

十四、Codex vs Claude Code：怎么选？

写在最后：AI 编程的工作方式变革

Codex 不是一个完美的工具——它慢、有时过于谨慎、偶尔会跑偏。但它代表了一种根本性的转变：从”人写代码、AI 辅助”到”AI 写代码、人指导”。

传统流程：写需求文档 → 设计架构 → 手动编码 → 调试 → 测试 → 部署（周期数周，团队数人）

Codex 流程：描述任务 → AI 自主实现 → 人类审查验证 → 迭代优化（周期数小时，一人即可）

OpenAI 内部团队的实践已经证明：3 名工程师用 Codex 在 5 个月内交付了百万行代码的内部产品。这不是效率提升，而是工作方式的质变。

当然，AI 还替代不了架构判断、产品洞察和系统设计能力。但它把这些能力的准入门槛，从”十年专业训练”降到了”认真学习一周”。

🚀 你的下一步

1. 选一条安装路径（推荐桌面 App），花 5 分钟装好
2. 用本文的第一个任务模板，让 Codex 写一个猜数字游戏
3. 用 /init 初始化你的项目 AGENTS.md
4. 选一个真实小需求（如修复一个 bug、添加一个功能），让 Codex 完成
5. 尝试 MCP 插件（如 context7），扩展 Codex 的能力边界
6. 建立你的提示词库，保存有效的模板反复使用

现在就打开终端，输入 codex，开始你的第一次 AI 编程。

关键词：Codex 入门教程 · OpenAI Codex CLI · AI 编程智能体 · GPT-5 编码 · AGENTS.md · MCP 插件 · Codex vs Claude Code · 提示词工程