3 步搞定 OpenAI Codex 国内环境：镜像站 + 配置文件 + 终端启动（含图文）

Codex 是 OpenAI 推出的命令行 AI 编程助手，专为开发者设计。它基于 OpenAI 最新的大语言模型技术，能够理解自然语言并生成高质量代码，是提升开发效率的利器。根据自然语言描述产出完整的功能代码分析现有代码结构并发现问题帮助调试和修复 Bug自动生成文档和注释无缝集成到命令行开发环境恭喜！通过本文的详细指导，你已经成功在 Windows、macOS 或 Linux 上完成了 Ope

小清河505

1794人浏览 · 2026-04-29 14:38:51

小清河505 · 2026-04-29 14:38:51 发布

摘要：本文为国内开发者提供了一份详尽的 OpenAI Codex 配置指南，覆盖 Windows、macOS 和 Linux 三大主流操作系统。通过 API独立站解决网络访问问题，手把手带你完成从环境搭建到实战使用的全部环节，让 AI 编程辅助轻松融入你的开发流程。如果你主要想学习编程语法，也可以试试他们的对话服务，GPT-5.5是最新，截止2026年4月29日当前最强模型（后期可能会有更新）。

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	10 / 11	npm 全局安装
macOS	12 及以上	npm 全局安装 / Homebrew
Linux	Ubuntu 20.04+、Debian 10+、CentOS 7+、Fedora、Arch	包管理器 + npm

2. 环境准备与前置条件

2.1 通用系统需求

开始安装前，请确保你的系统满足以下最低要求：

依赖项	最低版本	说明
Node.js	22+	运行环境
npm	10+	包管理工具
网络	-	可访问 API独立站
终端	-	CMD、PowerShell、Terminal 等

2.2 API 站点注册与配置

由于国内网络限制，需要借助镜像 API 站点来使用 Codex。以下是详细的注册配置流程。

2.2.1 注册账号

访问 API独立站并注册账号
完成邮箱验证和基本信息填写
登录后进入控制台

2.2.2 创建 API 令牌

点击左侧菜单「控制台」→「API令牌」页面
点击「添加令牌」按钮
重要：令牌分组请务必选择 “openai codex 专用”（否则无法使用）
令牌名称可自定义（例如 “codex-dev”）
额度建议设为「无限额度」，避免使用过程中额度耗尽
其他选项保持默认，点击「提交」
复制生成的令牌密钥（格式 sk-xxx）并妥善保管

2.2.3 配置文件说明

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

配置文件	作用	存放路径
`auth.json`	存储 API 密钥	`~/.codex/auth.json`
`config.toml`	存储模型和服务端配置	`~/.codex/config.toml`

3. Windows 系统安装步骤

3.1 系统要求

Windows 10 或 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 --version

在这里插入图片描述

若显示版本号，说明安装成功。

3.6 配置 API

重要：请将下面的 sk-xxx 替换为你从 API独立站获取的真实 API 密钥！

3.6.1 创建配置目录

打开文件资源管理器，进入用户目录（C:\Users\你的用户名）
找到或创建 .codex 文件夹
如果看不到隐藏目录，请在文件资源管理器的「查看」选项卡中勾选「隐藏的项目」

3.6.2 创建配置文件

在这里插入图片描述

在 .codex 文件夹中创建两个文件：auth.json 和 config.toml

auth.json 内容（将 sk-xxx 替换为真实密钥）：

{
  "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 系统要求

发行版：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

# Fedora 用 dnf，CentOS/RHEL 用 yum
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` 文件，用于项目级指令
`/status`	显示当前会话配置和令牌用量
`/diff`	显示 Git 差异（包括未跟踪文件）
`/clear`	清除会话历史
`/prompts`	显示示例提示
`/help`	显示帮助信息

8.2 审批模式说明

模式	说明	适用场景
Suggest	仅提供建议，不直接修改代码	学习、谨慎操作
Auto Edit	自动编辑代码，但需要确认	日常开发、可控自动化
Full Auto	完全自动，无需确认	批量处理、高度信任的场景