全网最详细的 Codex 入门教程：Codex 安装、使用与获取APIKey 配置全攻略

一、Codex 是什么？

Codex 是 OpenAI 推出的 AI 编程 Agent，也可以理解为一个能在本地或云端帮助你处理代码任务的 AI 开发助手。

和普通聊天式 AI 不同，Codex 不只是回答“这段代码是什么意思”，它更像一个真正的 AI 编程助手，可以读取项目文件、理解代码结构、修改代码、运行命令、排查错误，并根据你的需求完成实际开发任务。OpenAI 官方对 Codex CLI 的介绍是：它可以在你选择的目录中读取、修改并运行代码。

简单来说，Codex 适合这些场景：

• 新手快速看懂一个陌生项目；
• 自动排查项目启动报错；
• 帮你修复 Bug；
• 帮你写前端页面、后端接口、脚本工具；
• 帮你检查代码质量和安全问题；
• 帮你生成 README、部署文档和测试用例；
• 帮你做项目重构和功能优化。

如果说 ChatGPT 更像“代码顾问”，那么 Codex 更像“能进入项目干活的 AI 程序员”。

二、Codex、CodeX、Codex CLI 是一回事吗？

很多人会把它写成 CodeX，但官方名称是 Codex。

目前常见的使用方式主要有几种：

1. Codex CLI

这是最适合开发者和站长使用的方式。你可以直接在终端里进入项目目录，然后运行：

codex

Codex 会读取当前项目，并在终端里帮你分析、修改和运行代码。

2. Codex App 客户端

Codex App 是桌面客户端，更适合不喜欢纯命令行的新手使用。OpenAI 官方介绍中提到，Codex App 是一个专门用于并行处理 Codex 任务的桌面体验，支持 worktree、自动化和 Git 功能。

3. Codex IDE 插件

适合 VS Code、Cursor、Windsurf 等编辑器用户，可以把 Codex 融入日常写代码流程。

新手建议：

想最快上手：用 Codex App 客户端
想真实改项目：用 Codex CLI
想处理 GitHub 仓库：用 Codex Web
想日常写代码：用 Codex IDE 插件

三、安装 Codex 前需要准备什么？

在安装 Codex 之前，建议先准备好两个基础环境：Git 和 Node.js。

如果你的电脑上已经安装过 Git 和 Node.js，可以直接跳过这一部分。

如果没有安装，建议新手无脑选择默认路径，一路 Next 安装即可，避免后续环境变量出问题。

四、步骤 1：安装 Git

Git 是代码管理工具，很多项目都需要用到。Codex 在处理项目、查看修改、配合 GitHub 或生成 diff 时，也经常会用到 Git。

Windows 用户

访问 Git 官方下载页面，下载 Windows 版本安装包。

安装时建议：

一路 Next
保持默认路径
不要随便修改高级选项

安装完成后，打开 CMD 或 PowerShell，输入：

git --version

如果能看到版本号，说明 Git 安装成功。

macOS 用户

macOS 通常自带 Git，也可以通过 Homebrew 安装：

brew install git

检查命令：

git --version

五、步骤 2：安装 Node.js

Codex CLI 可以通过 npm 安装，因此需要先安装 Node.js。

建议安装 Node.js LTS 长期支持版本。

安装完成后，打开 CMD 或 PowerShell，输入：

node -v
npm -v

如果两个命令都能正常显示版本号，说明 Node.js 和 npm 已经安装成功。

新手注意：

Windows 安装 Node.js 时，不建议修改安装路径。
默认路径最省心。

六、步骤 3：安装 Codex CLI

环境准备好以后，就可以安装 Codex CLI 了。

打开 CMD、PowerShell 或终端，执行：

npm install -g @openai/codex@latest

Windows 用户建议以管理员身份运行终端。

macOS / Linux 用户如果遇到权限问题，可以尝试：

sudo npm install -g @openai/codex@latest

安装完成后，输入：

codex --version

如果能看到版本号，说明 Codex CLI 安装成功。

OpenAI 官方 GitHub 仓库也说明，Codex CLI 可以通过 npm 全局安装，并在安装后直接运行 codex 启动。

七、Windows 提示找不到 codex 命令怎么办？

这是新手最常见的问题。

如果安装完成后输入：

codex

提示：

codex 不是内部或外部命令
command not found

可以尝试下面几个方法。

方法一：重新打开终端

安装完成后，关闭当前 CMD 或 PowerShell，重新打开一个新的终端窗口，再输入：

codex --version

方法二：使用 npx 临时启动

如果环境变量还没有配置好，可以先用：

npx @openai/codex

这种方式不依赖全局命令，适合临时启动。

方法三：检查 npm 全局路径

输入：

npm config get prefix

检查 npm 全局安装路径是否已经加入 Windows 环境变量。

如果你是新手，最简单的方法是重新安装 Node.js，并保持默认路径安装。

八、Codex 客户端下载方式

除了命令行安装，也可以直接使用 Codex 客户端。

打开 OpenAI Codex 官方页面，选择对应系统下载安装即可。OpenAI 官方 Codex 页面介绍，Codex 面向真实工程任务，可以帮助用户完成代码修改、重构、迁移和开发任务。

客户端适合这类用户：

不想一直敲命令
想用图形界面管理任务
想同时处理多个项目
想更直观看到 Codex 的修改内容

如果你是新手，建议：

Codex App 客户端 + Codex CLI 都安装
客户端负责可视化操作
CLI 负责项目目录里的真实开发任务

九、步骤 4：配置 uiuiAPI 聚合节点,获取APIKey调用GPT-5.5大模型

接下来是本文重点：把 Codex 配置为使用 uiuiAPI 聚合平台。

这样做的目的，是让 Codex 的模型请求走你自己的 uiuiAPI 聚合节点，从而统一管理模型、Key、分组、额度和接口地址。

Codex 的核心配置主要涉及两个文件：

config.toml
auth.json

我们需要通过这两个文件，把请求地址和鉴权信息指向 uiuiAPI。

十、获取 uiuiAPI API 密钥

首先进入 uiuiAPI 控制台。

操作步骤：

1. 登录 uiuiAPI 控制台
2. 进入令牌 / Token 管理
3. 创建一个新的 API Token
4. 复制生成的 sk- 开头密钥
5. 保存备用

密钥格式通常类似：

sk-xxxxxxxxxxxxxxxxxxxxxxxx

注意：

不要把 API Key 发给别人
不要把 API Key 上传到 GitHub
不要把 API Key 写进公开项目代码

十一、创建 Codex 配置目录

Codex 的配置文件需要放在用户主目录下的 .codex 文件夹中。

Windows 路径

%USERPROFILE%\.codex

通常实际路径类似：

C:\Users\你的用户名\.codex

macOS / Linux 路径

~/.codex

如果没有 .codex 文件夹，就手动新建一个。

Windows 用户可以这样操作：

打开文件资源管理器
进入 C:\Users\你的用户名
新建文件夹 .codex

如果 Windows 提示“必须键入文件名”，可以用命令创建：

mkdir $env:USERPROFILE\.codex

十二、配置文件一：config.toml

在 .codex 文件夹里新建第一个文件：

config.toml

写入以下内容：

disable_response_storage = true
model = "gpt-5.4"
model_provider = "uiuiapi"
model_reasoning_effort = "xhigh"
model_verbosity = "high"

[features]
web_search_request = true

[model_providers.uiuiapi]
name = "uiuiAPI"
base_url = "https://你的uiuiAPI接口地址/v1"
wire_api = "responses"
requires_openai_auth = true

这里需要重点注意：

base_url 必须替换成你自己的 uiuiAPI 接口地址
结尾必须带 /v1
model 必须填写你平台支持的模型名称
model_provider 要和下方 [model_providers.uiuiapi] 对应

十三、config.toml 参数解释

disable_response_storage

disable_response_storage = true

表示尽量关闭响应存储。这个配置适合更注重隐私和业务安全的用户。

model

model = "gpt-5.4"

表示 Codex 默认调用的模型。

这里的模型名称必须以 uiuiAPI 控制台实际支持的模型为准。如果你的平台支持的是其他模型，就替换成对应模型名。

model_provider

model_provider = "uiuiapi"

表示默认模型服务商使用 uiuiAPI。

model_reasoning_effort

model_reasoning_effort = "xhigh"

表示推理强度。xhigh 更适合复杂代码分析、重构、Bug 排查和大型项目理解。

model_verbosity

model_verbosity = "high"

表示输出详细程度。新手建议用 high，因为它会解释得更清楚。

web_search_request

[features]
web_search_request = true

表示开启联网搜索请求能力。适合处理依赖文档、报错查询、版本兼容等问题。

wire_api

wire_api = "responses"

表示使用 Responses API 方式请求。这个配置适合新版 OpenAI 接口兼容模式。

requires_openai_auth

requires_openai_auth = true

表示需要通过 auth.json 中的 API Key 进行鉴权。

十四、配置文件二：auth.json

在 .codex 文件夹里新建第二个文件：

auth.json

写入以下内容：

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-请在此处粘贴您从 uiuiAPI 获取的真实密钥"
}

例如：

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
}

注意事项：

必须是英文双引号
不要多写逗号
不要把 sk- 密钥写错
不要把 auth.json 保存成 auth.json.txt

Windows 用户尤其要注意文件后缀。

建议打开文件资源管理器：

查看 → 显示 → 文件扩展名

确认文件名真的是：

auth.json

而不是：

auth.json.txt

十五、完整目录结构示例

配置完成后，你的 .codex 文件夹应该是这样：

.codex
├── config.toml
└── auth.json

Windows 示例：

C:\Users\你的用户名\.codex\config.toml
C:\Users\你的用户名\.codex\auth.json

macOS / Linux 示例：

~/.codex/config.toml
~/.codex/auth.json

十六、启动 Codex CLI

配置完成后，打开终端，进入你的项目目录。

例如：

cd D:\my-project

或者：

cd /Users/yourname/my-project

然后运行：

codex

如果配置正确，Codex 会读取当前目录，并开始进入交互模式。

OpenAI 官方文档说明，Codex CLI 运行在本地终端中，可以读取当前仓库、进行编辑并执行命令。

十七、Codex 客户端如何使用 uiuiAPI Key？

如果你使用的是 Codex 客户端，配置好 .codex 文件夹后，也可以直接使用同一套配置。

一般操作流程是：

1. 打开 Codex 客户端
2. 选择其他登录方式
3. 使用 API Key 方式登录
4. 输入你在 auth.json 中配置的 Key
5. 进入 Codex 操作界面

如果你已经提前配置好了 config.toml 和 auth.json，客户端通常可以读取相关配置。

如果客户端没有自动识别，优先检查：

配置文件路径是否正确
auth.json 文件名是否正确
base_url 是否带 /v1
API Key 是否有效
模型名称是否存在

十八、Codex 第一次使用建议

第一次不要直接让 Codex 改代码，建议先让它分析项目。

进入项目目录后运行：

codex

然后输入：

请先完整阅读当前项目，告诉我：
1. 项目技术栈
2. 目录结构
3. 启动方式
4. 核心功能
5. 可能存在的问题
先不要修改任何代码。

确认它理解项目后，再让它处理具体任务。

例如：

请检查当前项目为什么启动失败，先分析原因，不要直接修改代码。

如果分析正确，再继续：

按照刚才的方案修复代码，修改完成后告诉我改了哪些文件，并给出验证方法。

十九、Codex 常用提示词模板

1. 项目分析

请完整阅读当前项目，输出项目技术栈、目录结构、启动方式、核心模块和潜在风险。先不要修改代码。

2. Bug 排查

当前项目出现以下报错：【粘贴报错内容】。请先定位原因，说明涉及哪些文件，给出修复方案。未经确认不要修改代码。

3. 功能开发

请在当前项目中新增【功能名称】。要求保持现有代码风格，不破坏原有功能，修改完成后列出文件清单和验证方式。

4. 前端优化

请优化当前页面 UI，让界面更现代、更大气、更有 AI 科技感。不要修改接口逻辑，不要影响原有功能。

5. 接口排查

请检查接口【接口路径】的调用链路，包括前端请求、后端处理、参数、返回值和可能失败的原因。

6. 上线检查

请帮我做一次上线前检查，重点检查环境变量、接口地址、构建命令、敏感信息、调试日志和明显安全风险。

二十、Codex 使用安全建议

虽然 Codex 很方便，但使用时也要注意安全。

建议做到：

不要把真实数据库密码发给 Codex
不要把支付密钥、邮箱密钥、云服务器密钥直接暴露
不要让 Codex 随便修改生产环境代码
不要在没有 Git 备份的情况下大改项目
不要把 auth.json 上传到 GitHub

推荐每次让 Codex 改代码前，先提交一个备份：

git add .
git commit -m "backup before codex changes"

如果改坏了，可以快速回滚：

git restore .

二十一、Codex 入门最佳流程

新手建议按照这个流程使用：

第一步：安装 Git
第二步：安装 Node.js
第三步：安装 Codex CLI
第四步：创建 .codex 配置目录
第五步：配置 config.toml
第六步：配置 auth.json
第七步：进入项目目录
第八步：运行 codex
第九步：先让 Codex 分析项目
第十步：确认方案后再让 Codex 修改代码

一句话总结：

先配置，再启动；
先分析，再修改；
先验证，再上线。

二十二、总结

Codex 是 OpenAI 面向真实软件开发场景推出的 AI 编程助手，可以帮助开发者完成代码阅读、Bug 排查、功能开发、项目重构、文档生成和上线检查等任务。

通过本文教程，你可以完成三件事：

1. 在电脑上安装 Codex CLI
2. 学会 Codex 的基础使用方式
3. 将 Codex 配置为使用 uiuiAPI 聚合平台

对于新手来说，最关键的是不要一开始就让 Codex 大范围改项目，而是先让它分析，再让它制定方案，最后确认后再修改。

对于经常做项目开发、AI 工具运营、网站部署和接口调试的人来说，Codex + uiuiAPI 是一套非常高效的 AI 编程工作流。

最终记住这句话：

Codex 负责帮你干活，uiuiAPI 负责帮你管模型、管接口、管额度。
两者结合，才能真正把 AI 编程助手用到实战里。