# OpenAI Codex 接入指南

现在你可以通过 UModelverse 平台使用 OpenAI 系列模型。

## **系统要求**

| 平台 | 要求 |
| --- | --- |
| Windows | Windows 10 或 Windows 11 |
| macOS | macOS 10.15 (Catalina) 或更高版本 |
| Linux | Ubuntu 18.04+、CentOS 7+、Debian 9+ |

所有平台均需要：

-   Node.js 18+
    
-   网络连接
    

## **1. 安装 Codex CLI**

### macOS

1.  安装或更新 [Node.js](https://nodejs.org/en/download/)（v18.0 或更高版本）。
    
2.  在终端中执行以下命令安装 Codex CLI。
    
    ```
    npm install -g @openai/codex@latest
    ```
    
3.  验证安装结果。输出版本号即表示安装成功。
    
    ```
    codex --version
    ```
    

### Windows

1.  在 Windows 上使用 Codex，需先安装 WSL 或 [Git for Windows](https://git-scm.com/install/windows)。
    
2.  在 WSL 或 Git Bash 中执行以下命令安装 Codex CLI。
    
    ```
    npm install -g @openai/codex@latest
    ```
    
3.  验证安装结果。输出版本号即表示安装成功。
    
    ```
    codex --version
    ```
    

### Linux

1.  安装或更新 [Node.js](https://nodejs.org/en/download/)（v18.0 或更高版本）。
    
2.  在终端中执行以下命令安装 Codex CLI。
    
    ```
    npm install -g @openai/codex@latest
    ```
    
3.  验证安装结果。输出版本号即表示安装成功。
    
    ```
    codex --version
    ```
    

## **2. 配置 UModelverse API**

### 2.1 获取 API Key

访问 [UModelverse 控制台](https://console.ucloud.cn/modelverse/api) 获取您的 API 密钥。

### 2.2 配置 Codex

Codex 通过两个文件完成配置：`config.toml` 指定模型提供商，`auth.json` 存放 API Key。两个文件位于同一目录，各平台路径不同。

#### macOS

`~/.codex/config.toml`：

```
model_provider = "ucloud"
model_reasoning_effort = "high"

[model_providers.ucloud]
name = "ucloud"
base_url = "https://api.modelverse.cn/v1"
wire_api = "responses"
requires_openai_auth = true
```

`~/.codex/auth.json`：

```
{
  "OPENAI_API_KEY": "your-umodelverse-api-key"
}
```

#### Windows

`C:\Users\<用户名>\.codex\config.toml`：

```
model_provider = "ucloud"
model_reasoning_effort = "high"

[model_providers.ucloud]
name = "ucloud"
base_url = "https://api.modelverse.cn/v1"
wire_api = "responses"
requires_openai_auth = true
```

`C:\Users\<用户名>\.codex\auth.json`：

```
{
  "OPENAI_API_KEY": "your-umodelverse-api-key"
}
```

#### Linux

`~/.codex/config.toml`：

```
model_provider = "ucloud"
model_reasoning_effort = "high"

[model_providers.ucloud]
name = "ucloud"
base_url = "https://api.modelverse.cn/v1"
wire_api = "responses"
requires_openai_auth = true
```

`~/.codex/auth.json`：

```
{
  "OPENAI_API_KEY": "your-umodelverse-api-key"
}
```

> **注意：** 请将 `your-umodelverse-api-key` 替换为您在 UModelverse 平台获取的实际 API Key。
>
> 如需指定模型，可在 `config.toml` 顶部加入 `model = "gpt-5.1-codex"`；不指定时也可在启动时通过 `codex -m <模型 ID>` 或交互界面的 `/model` 命令切换。

## **3. 启动 Codex**

配置完成后，先进入到工程目录：

```
cd your-project-folder
```

然后，运行以下命令启动：

```
codex
```

首次启动后按提示完成初始化即可开始编程！🚀

## **4. VS Code 插件**

配置完成后，也可以直接安装 `codex` VS Code 插件，并切换模型和推理强度进行使用。

![codex-vscode](https://static.ucloud.cn/docs/modelverse/images/codex/codex-vscode.png)

## **常见问题**

### 报错 unexpected status 401 Unauthorized 怎么办？

**原因：** API Key 无效、已过期，或复制时不完整、含空格。

**解决方案：**

1.  确认 `~/.codex/auth.json` 中 `OPENAI_API_KEY` 填入的是有效的 UModelverse API Key。
    
2.  重新从 [UModelverse 控制台](https://console.ucloud.cn/modelverse/api) 复制 API Key，确保完整且无多余空格。
    
3.  修改 `auth.json` 后，新开一个终端窗口再执行 `codex` 使其生效。
    

### 报错 unexpected status 404 Not Found 怎么办？

**原因：** `config.toml` 中的 `base_url` 或 `wire_api` 填写错误。

**解决方案：** 确认 `base_url` 为 `https://api.modelverse.cn/v1`、`wire_api` 为 `responses`、`model_provider` 为 `ucloud`，与上文 2.2 的配置示例一致。

### 报错 wire_api = chat is no longer supported 怎么办？

**原因：** 新版 Codex 使用 Responses API，不再支持 `wire_api = "chat"`。

**解决方案：** 将 `config.toml` 中的 `wire_api` 改为 `responses`（本文配置已采用），并确保安装的是最新版 Codex：

```
npm install -g @openai/codex@latest
```