摘要：本文是国内开发者使用 OpenAI Codex 的终极配置指南，涵盖 Windows、macOS、Linux 三大主流操作系统的完整安装流程。通过 API独立站 解决网络访问难题，手把手教你完成从环境准备到实战使用的全部步骤，让你无需复杂操作即可体验 AI 编程的强大能力。

---

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 注册账号

1. 访问 API独立站 进行账号注册
2. 完成邮箱验证和基本信息填写
3. 登录后进入控制台界面

2.2.2 创建 API 令牌

1. 点击左侧菜单「控制台」→「API令牌」页面
   

2. 点击「添加令牌」按钮

3. 重要：令牌分组请选择 “openai codex 专用”（务必选择此分组，否则无法使用）

4. 令牌名称可自定义，如 “codex-dev”

5. 额度建议设置为「无限额度」，避免使用中额度耗尽

6. 其他选项保持默认，点击「提交」

7. 复制生成的令牌密钥（格式为 sk-xxx），妥善保存

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，以获得更好的命令行体验：

1. 访问 Git 官网 下载 Windows 版本
2. 运行安装程序，保持默认选项一路点击「Next」
3. 安装完成后，可在开始菜单找到「Git Bash」

3.3 安装 Node.js

1. 访问 Node.js 官网 下载最新 LTS 版本
2. 运行安装程序，按提示完成安装
3. 安装完成后，打开 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 创建配置目录

1. 打开文件资源管理器，进入当前用户的用户目录

2. 找到或创建 .codex 文件夹（路径示例：C:\Users\你的用户名\.codex）

3. 如果看不到隐藏目录，请在文件资源管理器的「查看」选项卡中勾选「隐藏的项目」

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

关键步骤：配置完成后，必须重启终端才能使配置生效！

1. 重启 CMD 或 PowerShell
2. 进入你的项目目录：

cd your-project-folder

3. 启动 Codex：
   

codex

---

4. macOS 系统安装教程

4.1 系统要求

• macOS 12（Monterey）或更高版本
• Node.js 22 或更高版本
• npm 10 或更高版本
• 管理员权限（安装时需要输入密码）

4.2 安装 Node.js

macOS 有两种安装方式：

方式一：官网下载安装（推荐新手）

1. 访问 Node.js 官网 下载 macOS 版本
2. 运行安装包，按提示完成安装

方式二：使用 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

关键步骤：配置完成后，必须重启终端才能使配置生效！

1. 重启 Terminal
2. 进入项目目录：

cd your-project-folder

3. 启动 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

关键步骤：配置完成后，必须重启终端才能使配置生效！

1. 重启终端
2. 进入项目目录：

cd your-project-folder

3. 启动 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 插件：

1. 在 VSCode 扩展商店搜索 “OpenAI Codex”
2. 点击安装
3. 安装完成后，Codex 会出现在侧边栏
4. 完成上述 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 系统上的完整安装配置。让我们回顾一下关键步骤：

1. 环境准备：确保 Node.js 22+ 和 npm 10+ 已安装
2. API 注册：在 API独立站 注册并创建专用令牌
3. 配置文件：正确创建 auth.json 和 config.toml
4. 重启终端：配置完成后务必重启终端使配置生效
5. 启动使用：进入项目目录，运行 codex 命令

9.2 使用技巧与建议

• 文件上传：建议将代码文件拖拽到对话框，让 Codex 更好地理解项目上下文
• 清晰描述：提供详细、清晰的需求描述，能获得更高质量的代码
• 迭代优化：不满意的结果可以通过补充说明让 Codex 继续优化
• 版本控制：在重要项目上使用 Git，方便回溯 Codex 的修改

9.3 进阶学习资源

如需了解更多 Codex 的高级配置和使用技巧，可参考：

• Codex 官方文档
• OpenAI 开发者论坛

---

最后更新：2025年3月
适用版本：Codex CLI 最新版
作者声明：本文内容基于官方文档和社区实践整理，如有更新请以官方文档为准。

---

如果本文对你有帮助，欢迎点赞、收藏和分享！有任何问题欢迎在评论区留言讨论。