夜雨聆风目标：让零基础的用户也能成功安装并使用 Codex
一、Codex 是什么？
Codex 是 OpenAI 推出的 AI 编程助手，它可以直接在你的电脑上：
简单说，它就像一个24小时待命的程序员搭档，你只需要用自然语言告诉它要做什么，它就能帮你完成。
Codex 的三种使用方式
| Codex App | ||
| Codex CLI | ||
| IDE 插件 |
推荐路线：新手先装 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 用户：
Win + R，输入 cmd，回车打开命令提示符node --versionmacOS/Linux 用户：打开终端（Terminal），输入：
node --versionv22.x.x 或更高版本 → ✅ 跳过这一步安装 Node.js（Windows）
方法一：官网下载（推荐）
node --version 确认方法二：使用 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.commacOS/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 的自主程度：
| 建议模式 | 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-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.mdmacOS/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 没有安装成功，或环境变量未配置。
解决：
source ~/.bashrcQ2: 安装后提示 "codex: command not found"
原因：npm 全局安装目录不在系统 PATH 中。
解决（Windows）：
npm config get prefix\bin 添加到系统环境变量 PATH解决（macOS/Linux）：
source ~/.bashrc# 或nvm use 22Q3: 登录时提示 401 Unauthorized
原因：授权过期或会员到期。
解决：
codex logoutcodex重新登录即可。
Q4: 提示 "502 stream error" 或连接失败
原因：网络问题。
解决：
export HTTPS_PROXY=http://127.0.0.1:7890codexQ5: 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分钟）
运行项目的测试，看看有没有失败的九、总结
新手推荐路线：
