OpenAI Codex 国内使用完全指南：Windows/macOS/Linux 三平台详细安装配置教程（现在最新的有gpt-5.3-codex和gpt-5.4）

智算菩萨2026-05-05 8:51

摘要 ：本文是国内开发者使用 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 验证：
bash 复制代码 
node --version
npm --version

3.4 安装 Codex

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

bash 复制代码 
npm install -g @openai/codex

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

3.5 验证安装

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

bash 复制代码 
codex --version

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

3.6 配置 API

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

3.6.1 创建配置目录

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

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

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

3.6.2 创建配置文件

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

auth.json 内容(需要将sk-xxx替换成刚才在API站点创建的真实的sk)：

json 复制代码 
{
  "OPENAI_API_KEY": "sk-xxx"
}

config.toml 内容：

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. 进入你的项目目录：
bash 复制代码 
cd your-project-folder
  1. 启动 Codex：
bash 复制代码 
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，可直接使用命令安装：

bash 复制代码 
brew install node

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

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

4.3 安装 Codex

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

bash 复制代码 
sudo npm install -g @openai/codex

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

4.4 验证安装

bash 复制代码 
codex --version

4.5 配置 API

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

4.5.1 创建配置目录

bash 复制代码 
mkdir ~/.codex

4.5.2 创建 auth.json

bash 复制代码 
vi ~/.codex/auth.json

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

json 复制代码 
{
  "OPENAI_API_KEY": "sk-xxx"
}

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

4.5.3 创建 config.toml

bash 复制代码 
vi ~/.codex/config.toml

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

toml 复制代码 
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. 进入项目目录：
bash 复制代码 
cd your-project-folder
  1. 启动 Codex：
bash 复制代码 
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

bash 复制代码 
# 更新包列表
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

bash 复制代码 
# 使用 dnf (Fedora) 或 yum (CentOS/RHEL)
sudo dnf install nodejs npm
# 或
sudo yum install nodejs npm

Arch Linux

bash 复制代码 
sudo pacman -S nodejs npm

5.3 安装 Codex

打开终端，执行：

bash 复制代码 
npm install -g @openai/codex

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

bash 复制代码 
sudo npm install -g @openai/codex

5.4 验证安装

bash 复制代码 
codex --version

5.5 配置 API

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

5.5.1 创建配置目录

bash 复制代码 
mkdir ~/.codex

5.5.2 创建 auth.json

bash 复制代码 
vi ~/.codex/auth.json

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

json 复制代码 
{
  "OPENAI_API_KEY": "sk-xxx"
}

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

5.5.3 创建 config.toml

bash 复制代码 
vi ~/.codex/config.toml

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

toml 复制代码 
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. 进入项目目录：
bash 复制代码 
cd your-project-folder
  1. 启动 Codex：
bash 复制代码 
codex

6. 实战使用指南

6.1 基本启动流程

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

bash 复制代码 
# 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 的高级配置和使用技巧，可参考：

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

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

相关推荐
qcx232 小时前
【AI Agent通识九课】05 · AI 的红绿灯 — 长任务怎么管
人工智能·ai·agent·warp
AAI机器之心2 小时前
在 macOS 上本地部署 Ollama + LLaMA3（附教程）
人工智能·macos·langchain·llm·知识库·大模型部署
HSTK2 小时前
Mac上配置PlatformIO
macos
Yupureki2 小时前
《Linux网络编程》4.应用层HTTP协议
linux·服务器·c语言·网络·c++·http
孙同学_2 小时前
【Linux篇】网络层与数据链路层详解
linux·网络·智能路由器
薛定谔的猫3692 小时前
深入浅出 Model Context Protocol (MCP)：连接 AI 与外部数据的桥梁
ai·llm·agent·mcp·modelcontextprotocol
DogDaoDao2 小时前
【GitHub】Warp 终端深度解析：Rust + GPU 加速的 AI 原生终端开源架构
人工智能·程序员·rust·开源·github·ai编程·warp
拾光Ծ2 小时前
【Linux系统】进程信号（上）
linux·运维·服务器·面试·信号处理
咖喱o2 小时前
网络-堆叠
linux·运维·服务器·网络
热门推荐
01要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法02GitHub 镜像站点03【AI】2026 年具身智能模型和世界模型总结04Codex 接入 DeepSeek API 完整配置文档05零基础教你claude code 接入 deepseek V406裂开！ChatGPT 居然开始要手机号验证，附详细解决方法072026年AI前瞻：量子AI、具身智能与科学发现的新纪元08几个好用的ip纯净度检测网站09CC-Switch & Claude 基于 Linux 服务器安装使用指南10CVE-2026-31431 (Copy Fail) 漏洞复现与验证记录