OpenAI Codex 从入门到精通：完整实战指南

适用人群：零基础新手 → 进阶开发者

覆盖范围：产品认知、环境搭建、三平台安装、实战应用、效率优化 

---

目录

• 为什么写这篇教程

• 第一章：认知篇 —— 先搞懂再动手

  • 1.1 Codex 到底是什么

  • 1.2 App vs CLI：怎么选

  • 1.3 Codex vs Claude Code vs GitHub Copilot

• 第二章：准备篇 —— 环境与账号

  • 2.1 系统要求

  • 2.2 账号方案选择

  • 2.3 科学上网准备

• 第三章：安装篇 —— 三平台全覆盖

  • 3.1 Windows 安装

  • 3.2 macOS 安装

  • 3.3 Linux 安装

  • 3.4 安装验证清单

• 第四章：入门篇 —— 基本操作

  • 4.1 App 界面速览

  • 4.2 会话 vs 项目

  • 4.3 权限管理

  • 4.4 CLI 基本操作

• 第五章：实战篇 —— 让 Codex 干活

  • 5.1 开发场景

  • 5.2 非开发场景（App 特有）

  • 5.3 插件系统

  • 5.4 自动化任务

• 第六章：进阶篇 —— 提效技巧

  • 6.1 提示词工程

  • 6.2 高效工作流

  • 6.3 实用小技巧

  • 6.4 VSCode 插件

• 第七章：避坑篇 —— 常见问题与解决方案

  • 7.1 安装问题

  • 7.2 配置问题

  • 7.3 使用问题

  • 7.4 安全注意事项

• 第八章：总结与进阶路径

  • 8.1 学习路径建议

  • 8.2 核心要点回顾

  • 8.3 进阶资源

• 附录 A：配置文件模板

• 附录 B：CLI 内置命令速查

---

为什么写这篇教程

最近 AI 编程工具赛道竞争激烈，很多之前用 Claude Code 的开发者开始转向 Codex。原因很现实：

1. 账号稳定性：Claude Code 封号频率上升，Codex 对国内用户相对宽松

2. 能力快速迭代：电脑操控、浏览器操作、自动化任务、插件生态持续更新

3. 模型实力提升：GPT 系列在代码生成、推理、长文本处理上的进步明显

但问题是——Codex 的产品形态比 Claude Code 复杂得多，有 App、有 CLI、有云端 Agent，很多人下载后打开一脸懵。

---

第一章：认知篇 —— 先搞懂再动手

1.1 Codex 到底是什么

Codex 是 OpenAI 推出的 AI 编程助手，但它不是一个单一产品，而是一个产品矩阵：

产品形态	一句话描述	核心能力
Codex App	桌面端 AI 工作台	聊天 + 文件操作 + 电脑操控 + 插件
Codex CLI	终端里的编程搭档	轻量、快速、项目级代码操作
云端 Codex	服务器上的 AI Agent	7×24 小时运行，不受本地限制
VSCode 插件	编辑器内嵌助手	编码时即时辅助

1.2 App vs CLI：怎么选

这不是二选一，而是场景决定工具：

场景	推荐工具	原因
写调研报告、做文档	App	图形界面，所见即所得
让 AI 操作浏览器搜资料	App	Computer Use 需要 GUI
在项目里写代码、改 Bug	CLI	速度快，与终端工作流无缝衔接
批量处理文件、自动化任务	CLI	脚本化能力强
需要同时处理多个项目	两者配合	App 做规划，CLI 做执行

我的建议：先装 App 体验，再装 CLI 深入。两者共享会话，可以同时开。

1.3 Codex vs Claude Code vs GitHub Copilot

维度	Codex	Claude Code	GitHub Copilot
产品形态	App + CLI + 云端 + 插件	CLI 为主	IDE 插件为主
电脑操控	支持（Computer Use）	不支持	不支持
浏览器操作	内置 Browser Use	不支持	不支持
自动化任务	支持	有限	不支持
国内可用性	需要科学上网/API 镜像	需要科学上网	需要科学上网
账号稳定性	相对稳定	封号频繁	稳定
模型能力	GPT-5.x 系列	Claude 4.x 系列	GPT-4o/Claude
学习曲线	中等（功能多）	低（CLI 简洁）	低（插件无感）

---

第二章：准备篇 —— 环境与账号

2.1 系统要求

要求项	最低版本	说明
Node.js	22+	CLI 运行必需
npm	10+	包管理工具
网络连接	-	需要访问 OpenAI 或 API 镜像站
科学上网	-	App 和官方 CLI 必需

2.2 账号方案选择

方案 A：OpenAI 官方账号（推荐有科学上网的用户）

账号类型	价格	适合人群
免费	$0	体验几下，额度极少
Plus	$20/月	日常使用，性价比最高
Pro	$200/月	重度用户，额度拉满

注册注意事项：

• 需要海外手机号验证（国内号码不行）

• 可以用接码平台获取临时海外号码

• 全程需要科学上网

方案 B：API 镜像站（推荐国内开发者）

通过第三方 API 镜像站使用，无需 OpenAI 官方账号：

1. 注册镜像站账号

2. 创建 API 令牌（务必选择 "openai codex 专用" 分组）

3. 配置本地 Codex 指向镜像站

2.3 科学上网准备

这是使用 Codex 的硬性前提：

• 下载 App 需要科学上网

• 登录账号需要科学上网

• 使用过程需要科学上网

• 断开科学上网 = 连接中断

如果没有科学上网，走 API 镜像站方案是唯一选择。

---

第三章：安装篇 —— 三平台全覆盖

3.1 Windows 安装

3.1.1 安装 Node.js

1. 访问 Node.js 官网下载 LTS 版本

2. 双击安装包，一路 Next

3. 验证安装：

node --version
npm --version

3.1.2 安装 Git Bash（可选但推荐）

Windows 的 CMD 体验较差，建议安装 Git Bash：

1. 访问 git-scm.com 下载

2. 默认选项安装

3. 以后用 Git Bash 操作 Codex

3.1.3 安装 Codex App

1. 访问 openai.com/codex 下载 Windows 版本

2. 双击安装包完成安装

3. 打开后用 ChatGPT 账号登录（需要科学上网）

3.1.4 安装 Codex CLI

npm install -g @openai/codex

国内网络如果失败，使用阿里云镜像：

npm install -g @openai/codex --registry=https://registry.npmmirror.com

验证安装：

codex --version

3.1.5 配置 API（镜像站用户）

在 C:\Users\你的用户名\.codex\ 目录下创建两个文件：

auth.json：

{
  "OPENAI_API_KEY": "sk-你的密钥"
}

config.toml：

model_provider = "镜像站名称"
model = "gpt-5.2-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
​
[model_providers.镜像站名称]
name = "镜像站名称"
base_url = "https://镜像站地址/v1"
wire_api = "responses"

关键步骤：配置完成后必须重启终端，否则配置不生效！

3.2 macOS 安装

3.2.1 安装 Node.js

方式一：官网下载（新手推荐）

1. 访问 Node.js 官网下载 macOS 版本

2. 运行安装包

方式二：Homebrew（开发者推荐）

brew install node

如果没装 Homebrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3.2.2 安装 Codex App

1. 访问 openai.com/codex 下载 Mac 版本

2. 拖进"应用程序"文件夹

3. 打开登录

3.2.3 安装 Codex CLI

sudo npm install -g @openai/codex

输入密码时屏幕不会显示字符，这是正常的，输完按 Enter。

3.2.4 配置 API（镜像站用户）

mkdir ~/.codex
vi ~/.codex/auth.json

按 i 粘贴：

{
  "OPENAI_API_KEY": "sk-你的密钥"
}

按 ESC，输入 :wq，回车。

vi ~/.codex/config.toml

按 i 粘贴配置（同 Windows 的 config.toml 内容），保存退出。

3.3 Linux 安装

3.3.1 安装 Node.js

Ubuntu / Debian：

sudo apt update
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

CentOS / RHEL / Fedora：

sudo dnf install nodejs npm
# 或
sudo yum install nodejs npm

Arch Linux：

sudo pacman -S nodejs npm

3.3.2 安装 Codex CLI

npm install -g @openai/codex
# 或权限不足时
sudo npm install -g @openai/codex

3.3.3 配置 API（镜像站用户）

mkdir ~/.codex
vi ~/.codex/auth.json    # 内容同上
vi ~/.codex/config.toml  # 内容同上

3.4 安装验证清单

完成安装后，按这个清单检查：

• node --version 显示 22+
• npm --version 显示 10+
• codex --version 显示版本号
• ~/.codex/auth.json 文件存在且内容正确
• ~/.codex/config.toml 文件存在且内容正确
• 终端已重启（配置生效）
• 科学上网已连接

全部打勾就可以开始使用了。

---

第四章：入门篇 —— 基本操作

4.1 App 界面速览

Codex App 的界面分三个区域：

• 左侧导航栏：新对话、项目、插件、自动化、设置

• 中间对话区：你和 Codex 交流的地方

• 右侧结果区：生成的文件、网页预览、代码差异

记住口诀：左边找入口，中间说话，右边看结果。

4.2 会话 vs 项目

模式	绑定文件夹	适合场景	示例
新建会话	不绑定	纯聊天、问问题	"解释一下什么是 REST API"
新建项目	绑定	需要操作文件	"帮我重构这个项目的代码"

新手路径：先用会话模式熟悉 Codex → 需要操作文件时切换项目模式

4.3 权限管理

Codex 的权限是分层的，核心原则：最小权限原则

权限级别	能做什么	风险	建议
只读	只能查看，不能修改	无	安全场景
确认模式	改动前先问你	低	新手默认选这个
完全自动	自主执行所有操作	高	熟悉后再开

4.4 CLI 基本操作

启动：

cd 你的项目目录
codex

CLI 有三种审批模式：

模式	行为	适用场景
Suggest	只建议，不动文件	学习、谨慎操作
Auto Edit	改文件前确认	日常开发推荐
Full Auto	全自动	批量处理、信任场景

切换模式：

/mode          # 切换审批模式
/model         # 切换模型
/status        # 查看当前配置
/diff          # 查看 Git 差异
/clear         # 清除会话
/help          # 帮助

---

第五章：实战篇 —— 让 Codex 干活

5.1 开发场景

代码生成

帮我用 Python 写一个 FastAPI 项目，要求：
- 用户注册、登录、JWT 认证
- SQLAlchemy ORM
- Pydantic 数据验证
- 包含完整的错误处理

代码分析与重构

分析这个项目的代码结构，找出：
1. 重复代码
2. 潜在的性能瓶颈
3. 不符合最佳实践的地方
并给出重构建议

Bug 修复

这段代码运行报错：
[粘贴错误信息]

相关代码在 src/auth.py，帮我定位问题并修复

测试生成

为这个模块生成单元测试，覆盖：
- 正常流程
- 边界条件
- 异常情况
使用 pytest 框架

5.2 非开发场景（App 特有）

写调研报告

帮我写一份《2026年新能源汽车行业调研报告》，要求：
1. 自己搜索最新的行业数据
2. 包含市场规模、头部品牌、技术趋势、政策环境
3. 输出为 Word 文档

Codex 会自动打开浏览器搜索、整理数据、生成文档。人工可能需要大半天，Codex 几分钟搞定。

做 PPT

Codex 内置 Presentations 插件，可以直接生成演示文稿。基础 PPT 没问题，配合 Skill 和 MCP 效果更好。

知网搜论文

帮我去知网搜索"大模型"相关的论文，筛选最近一年的，
按照引用量排序，把前10篇的标题、作者、摘要整理成表格

Computer Use 功能会自动操作浏览器完成搜索和数据提取。

电商比价 / 招聘网站分析

同样的思路，让 Codex 自动浏览网站、提取信息、整理成表格。

5.3 插件系统

插件	功能	使用场景
Spreadsheets	处理表格	数据分析、报表
Presentations	做 PPT	汇报演示
Browser Use	操作内置浏览器	信息搜集
Computer Use	操作电脑软件	跨应用工作流
Gmail/GitHub/Google Drive	连接外部服务	邮件、代码、文件管理

概念区分：

• 插件：能力包（能做什么）

• Skill：工作流说明书（怎么做）

• MCP：外部工具连接通道（连接什么）

建议：先用内置插件，用到再装新的。

5.4 自动化任务

自动化 = 让 Codex 定时执行预设任务

典型场景：

• 每天早上整理邮件摘要

• 每周生成项目周报

• 定时监控网页变化

• 自动备份重要文件

建议：先把前面的功能玩熟了再折腾自动化。

---

第六章：进阶篇 —— 提效技巧

6.1 提示词工程

Codex 的输出质量直接取决于你的输入质量。几个原则：

具体 > 模糊

❌ 帮我写个网站
✅ 帮我用 React + TypeScript 写一个个人博客，包含文章列表、详情页、分类标签，
   使用 Tailwind CSS 做样式，部署到 Vercel

分步骤 > 一步到位

❌ 帮我做一个完整的电商系统
✅ 先帮我设计数据库 schema，包含用户、商品、订单三个核心表

给上下文 > 裸提问

❌ 这段代码有 bug
✅ 这段代码在处理大数据量时内存溢出，数据量约 100 万条，
   当前逻辑是把所有数据加载到内存，帮我优化

6.2 高效工作流

我的日常 Codex 工作流：

1. 早上打开 Codex App，让它整理邮件摘要
2. 切到 CLI，在项目目录里让它 review 昨天的代码
3. 遇到复杂需求，先用 App 对话理清思路
4. 具体编码用 CLI，Auto Edit 模式快速迭代
5. 需要写文档/报告时，切回 App 让它生成

App + CLI 协同技巧：

• App 做"规划"，CLI 做"执行"

• App 处理非代码任务，CLI 处理代码任务

• 两者共享会话，可以无缝切换

6.3 实用小技巧

• 用 @ 精准指定文件：输入 @ 可以选择项目下的具体文件

• 查看剩余额度：点击额度显示区域查看使用情况

• 模型选择：选最新的模型，推理级别用 high 质量最好

• CLI 和 App 会话共享：CLI 里的对话在 App 桌面端也能看到

• 不要重开对话：结果不满意在原对话基础上改，比重来效果好

6.4 VSCode 插件

除了 App 和 CLI，Codex 还有 VSCode 插件：

1. 扩展商店搜索 "OpenAI Codex"

2. 安装后出现在侧边栏

3. 配置 API 后即可使用

适合习惯在 VSCode 里工作的开发者。

---

第七章：避坑篇 —— 常见问题与解决方案

7.1 安装问题

问题	原因	解决方案
npm 命令不存在	Node.js 未装或路径不对	重装 Node.js，重启终端
安装权限不足	缺少管理员权限	Windows 管理员运行，macOS/Linux 用 sudo
安装卡住	网络问题	换 npm 镜像源：--registry=https://registry.npmmirror.com

7.2 配置问题

问题	原因	解决方案
API Key 无效	密钥错或分组选错	检查密钥，确认选了 "openai codex 专用"
额度不足	令牌额度太低	设为无限额度
配置不生效	没重启终端	配置改完必须重启终端

7.3 使用问题

问题	原因	解决方案
无法连接 API	网络/科学上网问题	检查科学上网是否正常
响应慢	推理级别太高	改为 medium 或 low
代码质量差	提示词不清晰	提供更多上下文和细节
CLI 报错	各种原因	把错误信息贴给 Codex，让它自己修

7.4 安全注意事项

使用 Computer Use 功能时，这些绝对不要让它碰：

• 微信、社交媒体账号

• 付费软件的付款页面

• 公司内部工具和私人资料

• 任何包含敏感信息的应用

看到权限弹窗不要无脑点确认，看不懂就问 Codex "这个权限会做什么"。

---

第八章：总结与进阶路径

8.1 学习路径建议

第一周：入门体验
├── 安装 App + CLI
├── 用会话模式聊天，熟悉界面
├── 尝试写一个简单文档
└── 用 CLI 做一个小项目

第二周：实战应用
├── 在真实项目中使用 CLI
├── 用 Computer Use 完成一个复杂任务
├── 配置插件，尝试自动化
└── 优化提示词，提升输出质量

第三周：效率提升
├── 建立自己的工作流
├── App + CLI 协同使用
├── 探索高级功能（MCP、Skill）
└── 分享经验，帮助他人

8.2 核心要点回顾

1. 产品认知：Codex 不是单一工具，是 App + CLI + 云端 + 插件的产品矩阵

2. 环境准备：Node.js 22+、科学上网（或 API 镜像站）、账号

3. 三平台安装：Windows/macOS/Linux 都有详细步骤

4. 权限管理：从最小权限开始，熟悉后再放开

5. 场景选择：文档任务用 App，编码任务用 CLI

6. 提示词质量：具体、分步骤、给上下文

7. 安全意识：敏感应用不要让 Computer Use 碰

8.3 进阶资源

• OpenAI 官方文档

• OpenAI 开发者论坛

• Codex GitHub 仓库

• 社区最佳实践分享

---

附录 A：配置文件模板

Windows 配置文件位置

C:\Users\你的用户名\.codex\auth.json
C:\Users\你的用户名\.codex\config.toml

macOS / Linux 配置文件位置

~/.codex/auth.json
~/.codex/config.toml

auth.json 模板

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxx"
}

config.toml 模板（镜像站）

model_provider = "your_provider"
model = "gpt-5.2-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.your_provider]
name = "your_provider"
base_url = "https://your-api-endpoint.com/v1"
wire_api = "responses"

config.toml 模板（OpenAI 官方）

model = "gpt-5.2-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

---

附录 B：CLI 内置命令速查

命令	功能
/mode	切换审批模式
/model	切换模型和推理级别
/approvals	切换批准模式
/init	创建 AGENTS.md 项目指令文件
/status	查看会话配置和 token 使用
/diff	查看 Git 差异
/clear	清除会话历史
/prompts	显示示例提示
/help	帮助信息