Codex 新手安装教程(完全小白版)

目标：让零基础的用户也能成功安装并使用 Codex

一、Codex 是什么？

Codex 是 OpenAI 推出的 AI 编程助手，它可以直接在你的电脑上：

简单说，它就像一个24小时待命的程序员搭档，你只需要用自然语言告诉它要做什么，它就能帮你完成。

Codex 的三种使用方式

推荐路线：新手先装 App 体验 → 再装 CLI 深入使用

二、安装前的准备工作

1. 检查你的账号

Codex 需要付费使用，以下账号类型都可以：

建议：个人用户直接用 ChatGPT 账号登录，最省心。

2. Windows 用户特别注意

三、安装 Codex App（最简单，推荐新手）

第 1 步：下载安装包

第 2 步：登录账号

💡 小提示：如果你是用"邮箱+密码"注册的 ChatGPT，**必须先开启双重验证（MFA）**才能使用 Codex。

第 3 步：选择项目目录

登录后，Codex 会让你选择一个项目文件夹：

第 4 步：开始对话

在输入框里输入你的第一个指令：

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

Codex 会自动扫描目录，告诉你项目里有什么文件、是什么架构。

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

CLI（命令行版）功能更强大，适合日常开发使用。

第 1 步：安装 Node.js

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

Windows 用户：

node --version

macOS/Linux 用户：打开终端（Terminal），输入：

node --version

安装 Node.js（Windows）

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

方法二：使用 nvm（进阶用户）

# 安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash# 安装 Node.js 22nvm install 22nvm use 22

安装 Node.js（macOS）

方法一：官网下载（推荐）同 Windows，下载 pkg 安装包直接安装。

方法二：使用 Homebrew

brew install node

安装 Node.js（Linux/Ubuntu）

# 添加 NodeSource 仓库curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -# 安装 Node.jssudo apt-get install -y nodejs# 验证node --versionnpm --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

首次运行会提示登录：

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

五、Codex CLI 的基本使用

5.1 两种使用模式

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

直接输入 codex 进入交互式对话：

codex

然后你可以像聊天一样连续对话：

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

优点：有上下文记忆，可以连续执行复杂任务

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

直接在 codex 后面跟指令，执行完就退出：

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

优点：快速、适合一次性任务

5.2 三种安全模式

Codex 提供三种操作模式，控制 AI 的自主程度：

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

5.3 常用命令

# 查看帮助codex --help# 使用特定模型codex --model gpt-5-codex# 进入特定目录后启动cd my-projectcodex# 升级 Codex CLInpm update -g @openai/codex

六、配置优化（让 Codex 更好用）

6.1 设置中文回复

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

Windows：

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

macOS/Linux：

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

这样 Codex 就会用中文回复你了。

6.2 使用 API Key 登录（可选）

如果不想用 ChatGPT 账号登录，可以用 API Key：

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

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

永久设置（macOS/Linux）：

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

永久设置（Windows）：

setx OPENAI_API_KEY "sk-你的API密钥"

七、常见问题解决

Q1: 安装时提示 "npm: command not found"

原因：Node.js 没有安装成功，或环境变量未配置。

解决：

Q2: 安装后提示 "codex: command not found"

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

解决（Windows）：

npm config get prefix

解决（macOS/Linux）：

source ~/.bashrc# 或nvm use 22

Q3: 登录时提示 401 Unauthorized

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

解决：

codex logoutcodex

重新登录即可。

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

原因：网络问题。

解决：

export HTTPS_PROXY=http://127.0.0.1:7890codex

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

解决：

Q6: 提示 Node.js 版本过低

解决：

# 使用 nvm 升级到 Node.js 22nvm install 22nvm use 22nvm alias default 22# 重新安装 Codexnpm uninstall -g @openai/codexnpm install -g @openai/codex

八、快速开始建议

安装完成后，建议按这个顺序尝试：

第一步：分析项目（5分钟）

帮我分析当前项目的结构，告诉我主要有哪些模块

第二步：写个小功能（10分钟）

帮我写一个计算 BMI 的函数，包含输入验证

第三步：改代码（10分钟）

帮我把这个函数重构一下，加上错误处理

第四步：跑测试（10分钟）

运行项目的测试，看看有没有失败的

九、总结

新手推荐路线：