一、Codex 是什么

Codex 是 OpenAI 推出的 AI 编程助手，可直接在本地电脑上完成以下操作：

• 读代码 — 分析项目结构和代码逻辑
• 改代码 — 根据需求修改、重构代码
• 跑命令 — 执行终端命令、运行测试、安装依赖
• 修 Bug — 自动发现并修复代码中的问题

三种使用方式

方式	适合人群	特点
Codex App（桌面应用）	新手、不习惯命令行的用户	图形界面，最简单
Codex CLI（命令行）	开发者	功能最全，效率最高
IDE 插件	VS Code / Cursor 用户	在编辑器内直接使用

推荐路线：新手先装 App 体验，熟悉后再装 CLI 深入使用。

---

二、安装前的准备工作

账号要求

Codex 需要付费使用，以下账号均可：

• ChatGPT Plus / Pro
• ChatGPT Business / Edu / Enterprise
• OpenAI API Key（按量计费）

个人用户直接用 ChatGPT 账号登录最省心。

Windows 用户注意

• 推荐 Windows 11 或较新的 Windows 10
• 安装过程可能需要管理员权限
• 需要稳定的网络连接

---

三、安装 Codex App（推荐新手）

第 1 步：下载安装包

1. 访问 OpenAI 官方 Codex 页面：https://chatgpt.com/codex
2. 下载对应版本（Windows 或 macOS）
3. 双击安装包，按提示完成安装

第 2 步：登录账号

1. 打开 Codex App
2. 选择 Sign in with ChatGPT（推荐）
3. 浏览器弹出登录页面，用 ChatGPT 账号登录

如果使用"邮箱+密码"注册的 ChatGPT，必须先开启双重验证（MFA）才能使用 Codex。

第 3 步：选择项目目录

1. 点击 选择文件夹
2. 选择存放代码的目录（或新建一个）
3. 确认后进入主界面

第 4 步：开始对话

在输入框输入第一个指令：

帮我分析一下这个项目的结构

Codex 会自动扫描目录，返回项目文件结构和架构说明。

---

四、安装 Codex CLI（开发者推荐）

CLI 版功能更强大，适合日常开发使用。

第 1 步：安装 Node.js

Codex CLI 需要 Node.js 22+ 环境。先检查是否已安装：

node --version

• 显示 v22.x.x 或更高版本 -> 跳过此步
• 低于 v22 或未安装 -> 继续

Windows 安装 Node.js

方法一：官网下载（推荐）

1. 访问 https://nodejs.org/
2. 下载 LTS（长期支持版）
3. 双击安装包，一路"下一步"完成
4. 重启命令提示符，运行 node --version 验证

方法二：使用 nvm

# 安装 nvm（Windows 版 https://github.com/coreybutler/nvm-windows）
nvm install 22
nvm use 22

macOS 安装 Node.js

# 方法一：官网下载 pkg 安装包
# 方法二：使用 Homebrew
brew install node

Linux / Ubuntu 安装 Node.js

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

第 2 步：安装 Codex CLI

确认 Node.js 安装成功后：

npm install -g @openai/codex

国内用户加速：

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

macOS / Linux 如遇权限错误，加 sudo：

sudo npm install -g @openai/codex

第 3 步：验证安装

codex --version

显示版本号（如 0.42.0）即安装成功。

第 4 步：启动并登录

codex

首次运行会提示登录：

1. 选择 Sign in with ChatGPT
2. 浏览器弹出授权页面
3. 登录 ChatGPT 账号并完成授权
4. 授权完成后返回终端

登录失败时，尝试开启网络工具的全局模式（TUN 模式），然后重新运行 codex。

---

五、Codex CLI 的使用

5.1 两种使用模式

模式一：交互模式（推荐日常使用）

codex

进入后像聊天一样连续对话：

>> 帮我分析一下这个项目的结构
>> 给这个函数加上错误处理
>> 运行测试看看有没有问题

有上下文记忆，可连续执行复杂任务。

模式二：命令模式（快速任务）

codex "写一个计算斐波那契数列的 Python 函数"
codex "找出项目中所有的 TODO 注释"

执行完即退出，适合一次性任务。

5.2 三种安全模式

模式	命令	说明
建议模式	codex --approval-mode suggest	只给建议，不修改文件（最安全）
自动编辑	codex --approval-mode auto-edit	自动改文件，执行命令需确认（推荐）
全自动	codex --approval-mode full-auto	自动改文件、自动执行命令（最快）

默认是 suggest 模式，可在交互模式下输入 /approval 切换。

5.3 常用命令

# 查看帮助
codex --help

# 使用特定模型
codex --model gpt-5-codex

# 进入项目目录后启动
cd my-project
codex

# 升级 Codex CLI
npm update -g @openai/codex

---

六、配置优化

6.1 设置中文回复

在 ~/.codex/ 目录下创建 AGENTS.md 文件：

Windows：

mkdir %USERPROFILE%\.codex
echo Always respond in Chinese-simplified > %USERPROFILE%\.codex\AGENTS.md

macOS / Linux：

mkdir -p ~/.codex
echo "Always respond in Chinese-simplified" > ~/.codex/AGENTS.md

6.2 使用 API Key 登录（可选）

不想用 ChatGPT 账号登录时，可用 API Key：

临时设置（当前终端有效）：

export OPENAI_API_KEY="sk-你的API密钥"
codex

永久设置（macOS / Linux）：

echo 'export OPENAI_API_KEY="sk-你的API密钥"' >> ~/.bashrc
source ~/.bashrc

永久设置（Windows）：

setx OPENAI_API_KEY "sk-你的API密钥"

---

七、常见问题

Q1: 安装时提示 “npm: command not found”

原因：Node.js 未正确安装或环境变量未配置。

解决：

1. 重新安装 Node.js
2. Windows 用户重启命令提示符
3. macOS / Linux 用户重启终端或运行 source ~/.bashrc

Q2: 安装后提示 “codex: command not found”

原因：npm 全局安装目录不在系统 PATH 中。

解决（Windows）：

npm config get prefix

将输出路径下的 \bin 目录添加到系统环境变量 PATH，重启终端。

解决（macOS / Linux）：

source ~/.bashrc
# 或
nvm use 22

Q3: 登录时提示 401 Unauthorized

原因：授权过期或会员到期。

解决：

codex logout
codex

重新登录即可。

Q4: 提示 “502 stream error” 或连接失败

原因：网络问题。

解决：

1. 开启网络工具的全局模式（TUN 模式）
2. 或设置代理：

export HTTPS_PROXY=http://127.0.0.1:7890
codex

Q5: Windows 安装时提示权限错误

解决：以管理员身份运行 PowerShell 或命令提示符（右键 -> 以管理员身份运行）。

Q6: 提示 Node.js 版本过低

解决：

# 使用 nvm 升级到 Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

# 重新安装 Codex
npm uninstall -g @openai/codex
npm install -g @openai/codex

---

八、快速入门建议

安装完成后按此顺序尝试：

1. 分析项目：帮我分析当前项目的结构，告诉我主要有哪些模块
2. 写小功能：帮我写一个计算 BMI 的函数，包含输入验证
3. 改代码：帮我把这个函数重构一下，加上错误处理
4. 跑测试：运行项目的测试，看看有没有失败的

---

九、总结

步骤	操作	预计时间
1	确认有 ChatGPT 付费账号	1 分钟
2	安装 Node.js（CLI 用户需要）	5 分钟
3	安装 Codex（App 或 CLI）	3 分钟
4	登录授权	2 分钟
5	开始对话使用	立即

推荐路线：

1. 先装 Codex App 体验基本功能
2. 熟悉后再装 Codex CLI 提高效率
3. 日常开发中把重复性工作交给 Codex