夜雨聆风万字 Codex 使用安装教程全攻略：看这一篇就够了
OpenAI Codex 是当前业界最强大的代码生成与理解模型之一，可完成代码补全、函数生成、bug 修复、命令行翻译、自然语言转代码、项目搭建等全流程开发任务，广泛用于前端、后端、移动端、数据分析、自动化脚本等场景。无论是个人开发者、学生、团队研发，还是 AI 编程工具二次开发，Codex 都能大幅提升编码效率。
本文为2026 最新完整版，覆盖Windows / macOS / Linux / WSL全平台，从环境准备、账号开通、CLI 安装、桌面端部署、API 对接、IDE 集成、权限配置、国内可用方案、实战案例、故障排查到高阶技巧，一步一图、命令可直接复制，零基础也能一次成功。
目录
• Codex 核心能力与适用场景
• 安装前必读：系统与账号要求
• 全平台 Node.js 安装（必选依赖）
• Codex CLI 官方安装（npm / Homebrew / 二进制）
• Codex Desktop 桌面端安装与登录
• API Key 获取与全局配置（永久生效）
• 国内可用配置（中转 / 代理 / 合规方案）
• VS Code / JetBrains 集成
• 基础命令与快速上手
• 实战案例：从 0 生成项目
• 权限与安全配置
• 常见报错与解决
• 高阶技巧与效率提升
• 官方更新与维护
1. Codex 核心能力与适用场景
Codex 基于 GPT 系列代码专用模型，支持Python / JavaScript / Java / C++ / Go / PHP / Ruby / Shell等数十种语言，核心能力：
• 自然语言描述 → 直接生成完整代码 / 函数 / 类
• 代码解释、重构、优化、注释生成
• Bug 自动检测与一键修复
• 命令行指令生成（自然语言转 Shell）
• 项目脚手架快速生成
• API 对接、SDK 封装、数据库操作
• 与 VS Code、Cursor、IDEA、CLI 无缝协同
适用人群：
• 前端 / 后端 / 测试 / 运维 / 算法工程师
• 学生、自学编程、低代码开发者
• 希望提升开发效率的团队
• AI 工具开发者（二次封装 Codex）
2. 安装前必读：系统与账号要求
2.1 系统支持
• macOS 12+（原生最佳）
• Windows 10/11（推荐 WSL2 提升稳定性）
• Linux（Ubuntu 20.04+/Debian 10+/CentOS 8+）
• 内存 ≥ 4GB（推荐 8GB+）
• 磁盘空间 ≥ 2GB
2.2 必备条件
• OpenAI 账号（支持 Plus / Pro / Team / Enterprise）
• 可用网络环境（官方 API 区域限制）
• Node.js ≥ 18 LTS（CLI 必须依赖）
• Git ≥ 2.0（可选，推荐安装）
重要：Codex 不提供完全本地离线模型，所有请求需调用 OpenAI 云端接口；国内用户请使用合规中转 / 企业代理。
3. 全平台 Node.js 安装（必选）
Codex CLI 基于 Node.js 开发，必须先安装。
3.1 Windows 安装
• 访问官网：https://nodejs.org/
• 下载 LTS 版本（v20+/v22+）
• 运行 .msi，务必勾选 Add to PATH
• 打开 PowerShell 验证：
node -v
npm -v出现版本号即成功。
3.2 macOS 安装
方式 1：官网下载 .pkg 安装方式 2：Homebrew（推荐）
brew install node@20验证：
node -v
npm -v3.3 Linux 安装
sudo apt update
sudo apt install -y nodejs npm或使用 nvm 管理多版本（推荐）。
4. Codex CLI 官方安装（推荐）
CLI 是最稳定、功能最全的使用方式，支持三种安装方式。
4.1 npm 全局安装（全平台通用）
npm install -g @openai/codex4.2 macOS / Linux Homebrew
brew install codex4.3 二进制文件安装（无 npm 环境）
前往 GitHub Releases 下载对应系统包：https://github.com/openai/codex/releases解压后加入 PATH 即可。
4.4 验证安装
codex --version
codex help显示帮助信息即安装完成。
5. Codex Desktop 桌面端安装
适合不喜欢命令行的用户，提供图形化界面。
5.1 macOS
• 下载：https://persistent.oaistatic.com/codex-app-prod/Codex.dmg
• 拖拽安装
• 启动后用 OpenAI 账号登录
5.2 Windows
• 微软商店搜索 Codex 安装
• 或下载官方安装包
• 登录后即可使用
6. API Key 获取与全局配置
6.1 获取 API Key
• 登录 https://platform.openai.com/
• 进入 API Keys → Create new secret key
• 复制保存（只显示一次）
6.2 配置认证（二选一）
方式 1：环境变量（临时）
Windows PowerShell：
$env:OPENAI_API_KEY="sk-xxxx"macOS/Linux：
export OPENAI_API_KEY="sk-xxxx"方式 2：配置文件（永久推荐）
创建配置目录与文件：
# macOS/Linux
mkdir -p ~/.codex
touch ~/.codex/config.toml
# Windows
mkdir $HOME/.codex
notepad $HOME/.codex/config.toml写入配置：
model = "gpt-4o-codex"
preferred_auth_method = "apikey"
api_key = "sk-你的密钥"6.3 验证认证
codex auth status显示 Authenticated 即成功。
7. 国内可用配置（合规方案）
国内直接访问官方 API 不稳定，可使用企业代理 / 合规中转，修改 config.toml：
model_provider = "openai"
base_url = "https://你的合规中转地址/v1"
api_key = "sk-xxxx"
model = "gpt-4o-codex"注意：请使用合法合规服务，禁止违规翻墙。
8. IDE 集成（VS Code / JetBrains）
8.1 VS Code
• 安装扩展：OpenAI Codex 或 Cursor
• 打开设置 → 输入 API Key
• 选中代码 → 右键 → 生成 / 解释 / 修复
8.2 JetBrains（IDEA/WebStorm）
• 安装插件：Codex / OpenAI Code Assistant
• 配置 API Key 与中转地址
• 快捷键直接触发代码生成
9. 基础命令与快速上手
9.1 查看帮助
codex --help
codex [命令] --help9.2 生成代码
codex generate "写一个Python快速排序函数"9.3 解释代码
codex explain test.py9.4 修复 Bug
codex fix buggy.js9.5 生成命令行
codex cmd "查看端口占用并杀死进程"9.6 项目初始化
codex init react-app my-project10. 实战案例：1 分钟搭建 Express 接口
• 创建项目：
mkdir api-demo && cd api-demo
npm init -y• 生成接口代码：
codex generate "用Express写一个GET /user接口，返回JSON用户数据"• 自动安装依赖并启动：
npm install express
node index.js• 访问：http://localhost:3000/user
11. 权限与安全配置
11.1 权限沙箱
# config.toml
permission = "workspace-write"
# 可选：read-only / workspace-write / full-access11.2 凭据权限（Linux/macOS）
chmod 600 ~/.codex/config.toml
chmod 700 ~/.codex11.3 安全建议
• 不要把 API Key 上传 Git
• 团队使用环境变量或密钥管理系统
• 限制文件写入权限
12. 常见报错与解决
12.1 command not found: codex
• 未全局安装：npm install -g @openai/codex
• 未加入 PATH：重启终端
12.2 认证失败
• 检查 API Key 是否正确
• 检查 base_url 是否可用
• 执行 codex auth status
12.3 网络超时
• 切换合规中转 / 代理
• 检查网络防火墙
12.4 配置文件解析错误
• 编码必须为 UTF-8
• 不要用 Windows 记事本编辑
13. 高阶技巧与效率提升
• 指令模板：保存常用 prompt 为别名
codex alias pyfunc "生成Python带类型注解的函数"• 批量处理：
codex generate --file prompts.txt --out src/• 模型切换：
model = "gpt-4o-codex"• 日志与调试：
codex --verbose generate "代码"14. 官方更新与维护
14.1 更新 CLI
npm update -g @openai/codex
# 或
brew upgrade codex14.2 查看版本
codex --version14.3 卸载
npm uninstall -g @openai/codex
rm -rf ~/.codex结语
本文覆盖 Codex 从安装到上线的全流程，是目前全网最完整、最新、可直接落地的教程。无论你是新手入门，还是团队部署，按步骤操作即可稳定使用。
Codex 的核心价值不是 “代替程序员”，而是把重复工作交给 AI，把创造力留给自己。合理使用可让开发效率提升 3–10 倍。