1. Codex 概述与核心功能
1.1 什么是 Codex
Codex 是 OpenAI 官方推出的命令行 AI 编程助手工具，专为开发者打造。它基于 OpenAI 最新的大语言模型技术，能够理解自然语言描述并生成高质量的代码，是提升开发效率的利器。
Codex 不仅仅是一个代码生成工具，更是一个全方位的编程助手，可以：
- 根据自然语言描述生成完整的功能代码
- 分析现有代码的结构和潜在问题
- 协助调试和修复 Bug
- 自动生成代码文档和注释
- 与命令行环境无缝集成
1.2 实际开发效率对比
为了直观展示 Codex 的价值，我们来看一个典型开发场景的效率对比：
| 开发阶段 | 传统开发方式 | 使用 Codex |
|---|---|---|
| 需求理解与研究 | 30 分钟 | 30 秒 |
| 后端 API 编写 | 45 分钟 | 即时生成 |
| 前端组件开发 | 60 分钟 | 即时生成 |
| 调试与集成 | 30 分钟 | 2 分钟 |
| 总耗时 | 2.5 小时 | 3 分钟 |
| 效率提升 | 基准 | 50 倍 |
从上表可以看出，使用 Codex 可以将原本需要数小时的开发工作压缩到几分钟内完成，效率提升高达 50 倍以上。这种效率的飞跃，让开发者能够将更多精力投入到架构设计和创新思考中。
1.3 核心功能特性
Codex 提供以下五大核心功能：
| 功能模块 | 功能描述 | 适用场景 |
|---|---|---|
| 智能代码生成 | 根据自然语言描述快速生成高质量代码 | 新功能开发、原型构建 |
| 代码分析 | 深度理解代码结构，提供优化建议 | 代码重构、性能优化 |
| 调试助手 | 智能发现 Bug 并提供修复方案 | 问题排查、错误修复 |
| 文档生成 | 自动生成代码注释和说明文档 | 项目维护、团队协作 |
| 命令行集成 | 无缝嵌入终端工作流 | 日常开发、快速迭代 |
1.4 支持平台
Codex 支持多种主流操作系统，覆盖绝大多数开发环境：
| 操作系统 | 支持版本 | 安装方式 |
|---|---|---|
| Windows | Windows 10/11 | npm 全局安装 |
| macOS | macOS 12+ | npm 全局安装 / Homebrew |
| Linux | Ubuntu 20.04+、Debian 10+、CentOS、Fedora、Arch | 包管理器 + npm |
2. 环境准备与前置要求
2.1 通用系统要求
在开始安装 Codex 之前，请确保你的系统满足以下基本要求：
| 要求项 | 最低版本 | 说明 |
|---|---|---|
| Node.js | 22+ | 运行环境必需 |
| npm | 10+ | 包管理工具 |
| 网络连接 | - | 访问 API 服务商 |
| 终端工具 | - | CMD、PowerShell、Terminal 等 |
2.2 API 站点注册与配置
由于网络环境限制，国内开发者需要通过镜像 API 站点来使用 Codex。以下是详细的注册配置流程：
2.2.1 注册账号
- 访问 API 独立站进行账号注册
- 完成邮箱验证和基本信息填写
- 登录后进入控制台界面
2.2.2 创建 API 令牌
- 令牌名称可自定义，如 'codex-dev'
- 额度建议设置为「无限额度」，避免使用中额度耗尽
- 其他选项保持默认，点击「提交」
- 复制生成的令牌密钥（格式为
sk-xxx），妥善保存
重要：令牌分组请选择 'openai codex 专用'（务必选择此分组，否则无法使用）
点击「添加令牌」按钮
点击左侧菜单「控制台」→「API 令牌」页面
2.2.3 配置文件说明
Codex 需要两个核心配置文件：
| 配置文件 | 作用 | 存放位置 |
|---|---|---|
auth.json | 存储 API 密钥 | ~/.codex/auth.json |
config.toml | 存储模型和站点配置 | ~/.codex/config.toml |
3. Windows 系统安装教程
3.1 系统要求
- Windows 10 或 Windows 11（64 位）
- Node.js 22 或更高版本
- npm 10 或更高版本
- 稳定的网络连接
3.2 前置步骤：安装 Git Bash
Windows 系统建议先安装 Git Bash，以获得更好的命令行体验：
- 访问 Git 官网下载 Windows 版本
- 运行安装程序，保持默认选项一路点击「Next」
- 安装完成后，可在开始菜单找到「Git Bash」
3.3 安装 Node.js
- 访问 Node.js 官网下载最新 LTS 版本
- 运行安装程序，按提示完成安装
- 安装完成后，打开 CMD 或 PowerShell 验证：
node --version
npm --version
3.4 安装 Codex
打开命令提示符（CMD）或 PowerShell，执行以下命令：
npm install -g @openai/codex
安装过程可能需要几分钟，请耐心等待。
3.5 验证安装
安装完成后，验证 Codex 是否正确安装：
codex --version
如果显示版本号，说明安装成功。
3.6 配置 API
重要提示：请将下方的 sk-xxx 替换为你在 API 站点生成的实际 API 密钥！
3.6.1 创建配置目录
找到或创建 .codex 文件夹（路径示例：C:\Users\你的用户名\.codex）
打开文件资源管理器，进入当前用户的用户目录
如果看不到隐藏目录，请在文件资源管理器的「查看」选项卡中勾选「隐藏的项目」
3.6.2 创建配置文件
在 .codex 文件夹中创建两个文件：auth.json 和 config.toml
auth.json 内容 (需要将 sk-xxx 替换成刚才在 API 站点创建的真实的 sk)：
{"OPENAI_API_KEY":"sk-xxx"}
config.toml 内容：
model_provider = "aigcbar"
model = "gpt-5.2-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
[model_providers.aigcbar]
name = "aigcbar"
base_url = "https://api.aigc.bar/v1"
wire_api = "responses"
配置参数说明：
| 参数 | 可选值 | 说明 |
|---|---|---|
model_reasoning_effort | high / medium / low | 模型思考努力程度，high 为最高质量 |
model | gpt-5.2-codex / gpt-5-codex | 使用的模型版本 |
base_url | - | API 端点地址，代码块中保留原样 |
3.7 启动 Codex
关键步骤：配置完成后，必须重启终端才能使配置生效！
- 重启 CMD 或 PowerShell
- 进入你的项目目录：
cd your-project-folder
启动 Codex：
codex
4. macOS 系统安装教程
4.1 系统要求
- macOS 12（Monterey）或更高版本
- Node.js 22 或更高版本
- npm 10 或更高版本
- 管理员权限（安装时需要输入密码）
4.2 安装 Node.js
macOS 有两种安装方式：
方式一：官网下载安装（推荐新手）
- 访问 Node.js 官网下载 macOS 版本
- 运行安装包，按提示完成安装
方式二：使用 Homebrew 安装（推荐开发者）
如果你已安装 Homebrew，可直接使用命令安装：
brew install node
如果尚未安装 Homebrew，先执行：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
4.3 安装 Codex
打开终端（Terminal），执行以下命令：
sudo npm install -g @openai/codex
注意：命令执行时可能要求输入开机密码，输入时不会显示任何字符，输入完成后按 Enter 确认即可。
4.4 验证安装
codex --version
4.5 配置 API
重要提示：请将下方的 sk-xxx 替换为你在 API 站点生成的实际 API 密钥！
4.5.1 创建配置目录
mkdir ~/.codex
4.5.2 创建 auth.json
vi ~/.codex/auth.json
按 i 进入编辑模式，粘贴以下内容：
{"OPENAI_API_KEY":"sk-xxx"}
粘贴后按 ESC 键，输入 :wq 后按 Enter 保存退出。
4.5.3 创建 config.toml
vi ~/.codex/config.toml
按 i 进入编辑模式，粘贴以下内容：
model_provider = "aigcbar"
model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
[model_providers.aigcbar]
name = "aigcbar"
base_url = "https://api.aigc.bar/v1"
wire_api = "responses"
粘贴后按 ESC 键，输入 :wq 后按 Enter 保存退出。
4.6 启动 Codex
关键步骤：配置完成后，必须重启终端才能使配置生效！
- 重启 Terminal
- 进入项目目录：
cd your-project-folder
- 启动 Codex：
codex
5. Linux 系统安装教程
5.1 系统要求
- Linux 发行版：Ubuntu 20.04+、Debian 10+、CentOS 7+、Fedora、Arch Linux 等
- Node.js 22 或更高版本
- npm 10 或更高版本
- sudo 权限
5.2 安装 Node.js
不同发行版的安装命令有所不同：
Ubuntu / Debian
# 更新包列表
sudo apt update
# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
CentOS / RHEL / Fedora
# 使用 dnf (Fedora) 或 yum (CentOS/RHEL)
sudo dnf install nodejs npm
# 或
sudo yum install nodejs npm
Arch Linux
sudo pacman -S nodejs npm
5.3 安装 Codex
打开终端，执行：
npm install -g @openai/codex
如果提示权限不足，使用 sudo：
sudo npm install -g @openai/codex
5.4 验证安装
codex --version
5.5 配置 API
重要提示：请将下方的 sk-xxx 替换为你在 API 站点生成的实际 API 密钥！
5.5.1 创建配置目录
mkdir ~/.codex
5.5.2 创建 auth.json
vi ~/.codex/auth.json
按 i 进入编辑模式，粘贴：
{"OPENAI_API_KEY":"sk-xxx"}
按 ESC，输入 :wq，按 Enter 保存退出。
5.5.3 创建 config.toml
vi ~/.codex/config.toml
按 i 进入编辑模式，粘贴：
model_provider = "aigcbar"
model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"
[model_providers.aigcbar]
name = "aigcbar"
base_url = "https://api.aigc.bar/v1"
wire_api = "responses"
按 ESC，输入 :wq，按 Enter 保存退出。
5.6 启动 Codex
关键步骤：配置完成后，必须重启终端才能使配置生效！
- 重启终端
- 进入项目目录：
cd your-project-folder
- 启动 Codex：
codex
6. 实战使用指南
6.1 基本启动流程
无论使用哪个操作系统，启动 Codex 的标准流程都是：
# 1. 进入项目目录
cd your-project-folder
# 2. 启动 codex
codex
启动成功后，你会看到 Codex 的交互式命令行界面，可以开始输入自然语言指令。
6.2 实战使用示例
示例 1：代码生成
> 帮我写一个 Python 函数，实现快速排序算法
Codex 会立即生成完整的快速排序实现代码，包括注释说明。
示例 2：代码分析
> 分析这段代码的性能瓶颈
将代码文件拖拽到对话框，Codex 会分析代码并指出潜在的性能问题。
示例 3：Bug 修复
> 这段代码为什么报错，如何修复？
粘贴报错代码后，Codex 会分析错误原因并提供修复方案。
6.3 VSCode 插件使用
除了命令行工具，Codex 还提供了 VSCode 插件：
- 在 VSCode 扩展商店搜索 'OpenAI Codex'
- 点击安装
- 安装完成后，Codex 会出现在侧边栏
- 完成上述 API 配置后即可直接使用
7. 常见问题排查
7.1 安装问题
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| npm 命令不存在 | Node.js 未正确安装 | 重新安装 Node.js 并重启终端 |
| 安装权限不足 | 缺少管理员权限 | Windows 以管理员身份运行，macOS/Linux 使用 sudo |
| 安装卡住 | 网络问题 | 检查网络连接，或更换 npm 镜像源 |
7.2 配置问题
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 提示 API Key 无效 | 密钥错误或分组选择错误 | 检查密钥是否正确，确认分组选择 'openai codex 专用' |
| 提示额度不足 | 令牌额度设置过低 | 在 API 独立站将额度设为无限 |
| 配置不生效 | 未重启终端 | 配置完成后必须重启终端 |
7.3 使用问题
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 无法连接 API | 网络问题 | 检查网络连接，确认能访问 API 独立站 |
| 响应缓慢 | 模型推理级别设置过高 | 将 model_reasoning_effort 改为 medium 或 low |
| 代码质量不佳 | 提示词不够清晰 | 提供更详细的需求描述 |
8. 常用命令速查表
8.1 内置斜杠命令
Codex 提供了丰富的内置命令，通过输入 / 可以快速调用：
| 命令 | 功能描述 |
|---|---|
/mode | 切换审批模式（Suggest / Auto Edit / Full Auto） |
/model | 切换 AI 模型和推理级别 |
/approvals | 切换批准模式（Read Only / Auto / Full Access） |
/init | 创建 AGENTS.md 文件，为 Codex 提供项目指令 |
/status | 显示当前会话配置和令牌使用情况 |
/diff | 显示 Git 差异（包括未跟踪文件） |
/clear | 清除会话历史 |
/prompts | 显示示例提示 |
/help | 显示帮助信息 |
8.2 审批模式说明
| 模式 | 说明 | 适用场景 |
|---|---|---|
| Suggest | 仅提供建议，不直接修改代码 | 学习参考、谨慎操作 |
| Auto Edit | 自动编辑代码，但需要确认 | 日常开发、可控自动化 |
| Full Auto | 完全自动，无需确认 | 批量处理、信任场景 |
9. 总结与建议
9.1 安装配置要点回顾
恭喜！通过本文的详细指导，你已经完成了 OpenAI Codex 在 Windows、macOS 或 Linux 系统上的完整安装配置。让我们回顾一下关键步骤：
- 环境准备：确保 Node.js 22+ 和 npm 10+ 已安装
- API 注册：在 API 独立站注册并创建专用令牌
- 配置文件：正确创建
auth.json和config.toml - 重启终端：配置完成后务必重启终端使配置生效
- 启动使用：进入项目目录，运行
codex命令
9.2 使用技巧与建议
- 文件上传：建议将代码文件拖拽到对话框，让 Codex 更好地理解项目上下文
- 清晰描述：提供详细、清晰的需求描述，能获得更高质量的代码
- 迭代优化：不满意的结果可以通过补充说明让 Codex 继续优化
- 版本控制：在重要项目上使用 Git，方便回溯 Codex 的修改
9.3 进阶学习资源
如需了解更多 Codex 的高级配置和使用技巧，可参考：
