第二章：Codex 安装与配置指南

环境准备与前置要求​

1.1 通用系统要求​

在开始安装 Codex 之前，请确保你的系统满足以下基本要求：​

​

​

1.2 API 站点注册与配置​

​

由于网络环境限制，国内开发者需要通过镜像 API 站点来使用 Codex。​

以下是详细的注册配置流程：​

​

1.2.1 注册账号​

•

访问 API独立站 进行账号注册​

•

完成邮箱验证和基本信息填写​

•

登录后进入控制台界面​

​

​

1.2.2 创建 API 令牌​

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

​

​

​

​

37%

​

​

​

​

63%

​

​

点击「添加令牌」按钮​

​

​

​

⭕

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

​

47%

​

​

​

​

53%

​

​

1.2.3 配置文件 说明​

Codex 需要两个核心配置文件：​

配置文件 作用 存放位置​

auth.json 存储 API 密钥 ~/.codex/auth.json​

config.toml 存储模型和站点配置 ~/.codex/config.toml​

​

Windows 系统安装 教程​

1.1 系统要求​

Windows 10 或 Windows 11（64位）​

Node.js 22 或更高版本​

npm 10 或更高版本​

稳定的网络连接​

1.2 前置步骤：安装 Git Bash​

Windows 系统建议先安装 Git Bash，以获得更好的命令行体验：​

•

访问 Git 官网 下载 Windows 版本​

•

运行安装程序，保持默认选项一路点击「Next」​

•

安装完成后，可在开始菜单找到「Git Bash」​

1.3 安装 Node.js​

访问 Node.js 官网 下载最新 LTS 版本​

运行安装程序，按提示完成安装​

安装完成后，打开 CMD 或 PowerShell 验证：​

node --version​

npm --version​

运行项目并下载源码​

3.4 安装 Codex​

打开命令提示符（CMD）或 PowerShell，执行以下命令：​

​

npm install -g @openai/codex​

运行项目并下载源码​

bash​

1​

​

​

安装过程可能需要几分钟，请耐心等待。​

​

3.5 验证安装​

安装完成后，验证 Codex 是否正确安装：​

​

codex --version​

运行项目并下载源码​

bash​

1​

​

​

如果显示版本号，说明安装成功。​

​

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"​

}​

运行项目并下载源码​

json​

1​

2​

3​

​

​

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"​

运行项目并下载源码​

toml​

​

1​

2​

3​

4​

5​

6​

7​

8​

9​

10​

​

​

配置参数说明：​

​

参数 可选值 说明​

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​

运行项目并下载源码​

bash​

1​

启动 Codex：​

​

codex​

运行项目并下载源码​

bash​

1​

macOS 系统安装教程​

4.1 系统要求​

macOS 12（Monterey）或更高版本​

Node.js 22 或更高版本​

npm 10 或更高版本​

管理员权限（安装时需要输入密码）​

4.2 安装 Node.js​

macOS 有两种安装方式：​

​

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

访问 Node.js 官网 下载 macOS 版本​

运行安装包，按提示完成安装​

方式二：使用 Homebrew 安装（推荐开发者）​

如果你已安装 Homebrew，可直接使用命令安装：​

​

brew install node​

运行项目并下载源码​

bash​

1​

如果尚未安装 Homebrew，先执行：​

​

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"​

运行项目并下载源码​

bash​

1​

4.3 安装 Codex​

打开终端（Terminal），执行以下命令：​

​

sudo npm install -g @openai/codex​

运行项目并下载源码​

bash​

1​

注意：命令执行时可能要求输入开机密码，输入时不会显示任何字符，输入完成后按 Enter 确认即可。​

​

4.4 验证安装​

codex --version​

运行项目并下载源码​

bash​

1​

4.5 配置 API​

重要提示：请将下方的 sk-xxx 替换为你在 API独立站 生成的实际 API 密钥！​

​

4.5.1 创建配置目录​

mkdir ~/.codex​

运行项目并下载源码​

bash​

1​

4.5.2 创建 auth.json​

vi ~/.codex/auth.json​

运行项目并下载源码​

bash​

1​

按 i 进入编辑模式，粘贴以下内容：​

​

{​

"OPENAI_API_KEY": "sk-xxx"​

}​

运行项目并下载源码​

json​

1​

2​

3​

粘贴后按 ESC 键，输入 :wq 后按 Enter 保存退出。​

​

4.5.3 创建 config.toml​

vi ~/.codex/config.toml​

运行项目并下载源码​

bash​

1​

按 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"​

运行项目并下载源码​

toml​

​

1​

2​

3​

4​

5​

6​

7​

8​

9​

10​

粘贴后按 ESC 键，输入 :wq 后按 Enter 保存退出。​

​

4.6 启动 Codex​

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

​

重启 Terminal​

进入项目目录：​

cd your-project-folder​

运行项目并下载源码​

bash​

1​

启动 Codex：​

codex​

运行项目并下载源码​

bash​

1​

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​

运行项目并下载源码​

bash​

1​

2​

3​

4​

5​

6​

CentOS / RHEL / Fedora​

使用 dnf (Fedora) 或 yum (CentOS/RHEL)​

sudo dnf install nodejs npm​

或​

sudo yum install nodejs npm​

运行项目并下载源码​

bash​

1​

2​

3​

4​

Arch Linux​

sudo pacman -S nodejs npm​

运行项目并下载源码​

bash​

1​

5.3 安装 Codex​

打开终端，执行：​

​

npm install -g @openai/codex​

运行项目并下载源码​

bash​

1​

如果提示权限不足，使用 sudo：​

​

sudo npm install -g @openai/codex​

运行项目并下载源码​

bash​

1​

5.4 验证安装​

codex --version​

运行项目并下载源码​

bash​

1​

5.5 配置 API​

重要提示：请将下方的 sk-xxx 替换为你在 API独立站 生成的实际 API 密钥！​

​

5.5.1 创建配置目录​

mkdir ~/.codex​

运行项目并下载源码​

bash​

1​

5.5.2 创建 auth.json​

vi ~/.codex/auth.json​

运行项目并下载源码​

bash​

1​

按 i 进入编辑模式，粘贴：​

​

{​

"OPENAI_API_KEY": "sk-xxx"​

}​

运行项目并下载源码​

json​

1​

2​

3​

按 ESC，输入 :wq，按 Enter 保存退出。​

​

5.5.3 创建 config.toml​

vi ~/.codex/config.toml​

运行项目并下载源码​

bash​

1​

按 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"​

运行项目并下载源码​

toml​

​

1​

2​

3​

4​

5​

6​

7​

8​

9​

10​

按 ESC，输入 :wq，按 Enter 保存退出。​

​

5.6 启动 Codex​

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

​

重启终端​

进入项目目录：​

cd your-project-folder​

运行项目并下载源码​

bash​

1​

启动 Codex：​

codex​

运行项目并下载源码​

bash​

1​

实战使用指南​

6.1 基本启动流程​

无论使用哪个操作系统，启动 Codex 的标准流程都是：​

​

1. 进入项目目录​

cd your-project-folder​

​

2. 启动 codex​

codex​

运行项目并下载源码​

bash​

1​

2​

3​

4​

5​

启动成功后，你会看到 Codex 的交互式命令行界面，可以开始输入自然语言指令。​

​

6.2 实战使用示例​

示例 1：代码生成​

​

帮我写一个 Python 函数，实现快速排序算法​

运行项目并下载源码​

1​

Codex 会立即生成完整的快速排序实现代码，包括注释说明。​

​

​

示例 2：代码分析​

​

分析这段代码的性能瓶颈​

运行项目并下载源码​

1​

将代码文件拖拽到对话框，Codex 会分析代码并指出潜在的性能问题。​

​

​

示例 3：Bug 修复​

​

这段代码为什么报错，如何修复？​

运行项目并下载源码​

1​

粘贴报错代码后，Codex 会分析错误原因并提供修复方案。​

​

​

6.3 VSCode 插件使用​

除了命令行工具，Codex 还提供了 VSCode 插件：​

​

在 VSCode 扩展商店搜索 “OpenAI Codex”​

点击安装​

安装完成后，Codex 会出现在侧边栏​

完成上述 API 配置后即可直接使用​

​

​

​

常见问题排查​

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.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.1 安装配置要点回顾​

恭喜！通过本文的详细指导，你已经完成了 OpenAI Codex 在 Windows、macOS 或 Linux 系统上的完整安装配置。让我们回顾一下关键步骤：​

​

环境准备：确保 Node.js 22+ 和 npm 10+ 已安装​

API 注册：在 API独立站 注册并创建专用令牌​

配置文件：正确创建 auth.json 和 config.toml​

重启终端：配置完成后务必重启终端使配置生效​

启动使用：进入项目目录，运行 codex 命令​

9.2 使用技巧与建议​

文件上传：建议将代码文件拖拽到对话框，让 Codex 更好地理解项目上下文​

清晰描述：提供详细、清晰的需求描述，能获得更高质量的代码​

迭代优化：不满意的结果可以通过补充说明让 Codex 继续优化​

版本控制：在重要项目上使用 Git，方便回溯 Codex 的修改​

​