# OpenAI Codex Integration Guide

You can now use OpenAI series models through the UModelverse platform.

## **System Requirements**

| Platform | Requirements |
| --- | --- |
| Windows | Windows 10 or Windows 11 |
| macOS | macOS 10.15 (Catalina) or later |
| Linux | Ubuntu 18.04+, CentOS 7+, Debian 9+ |

All platforms require:

-   Node.js 18+

-   Network connection

## **1. Install Codex CLI**

### macOS

1.  Install or update [Node.js](https://nodejs.org/en/download/) (v18.0 or later).

2.  Run the following command in Terminal to install Codex CLI.

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

3.  Verify the installation. A version number in the output means success.

    ```
    codex --version
    ```

### Windows

1.  To use Codex on Windows, first install WSL or [Git for Windows](https://git-scm.com/install/windows).

2.  Run the following command in WSL or Git Bash to install Codex CLI.

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

3.  Verify the installation. A version number in the output means success.

    ```
    codex --version
    ```

### Linux

1.  Install or update [Node.js](https://nodejs.org/en/download/) (v18.0 or later).

2.  Run the following command in Terminal to install Codex CLI.

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

3.  Verify the installation. A version number in the output means success.

    ```
    codex --version
    ```

## **2. Configure the UModelverse API**

### 2.1 Get an API Key

Visit the [UModelverse Console](https://console.ucloud.cn/modelverse/api) to obtain your API key.

### 2.2 Configure Codex

Codex uses two files for configuration: `config.toml` specifies the model provider, and `auth.json` stores the API Key. Both files live in the same directory; the path differs by platform.

#### macOS

`~/.codex/config.toml`:

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

[model_providers.ucloud]
name = "ucloud"
base_url = "https://api-us-ca.umodelverse.ai/v1"
wire_api = "responses"
requires_openai_auth = true
```

`~/.codex/auth.json`:

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

#### Windows

`C:\Users\<username>\.codex\config.toml`:

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

[model_providers.ucloud]
name = "ucloud"
base_url = "https://api-us-ca.umodelverse.ai/v1"
wire_api = "responses"
requires_openai_auth = true
```

`C:\Users\<username>\.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-us-ca.umodelverse.ai/v1"
wire_api = "responses"
requires_openai_auth = true
```

`~/.codex/auth.json`:

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

> **Note:** Replace `your-umodelverse-api-key` with your actual API Key from the UModelverse platform.
>
> To specify a model, add `model = "gpt-5.1-codex"` at the top of `config.toml`. You can also switch models at launch with `codex -m <model ID>` or use the `/model` command in the interactive UI.

## **3. Start Codex**

After configuration, navigate to your project directory:

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

Then run:

```
codex
```

Follow the prompts on first launch to complete the initial setup and start coding! 🚀

## **4. VS Code Extension**

After completing the configuration above, you can also install the `codex` VS Code extension directly and switch the model and reasoning effort to use it.

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

## **FAQ**

### Getting "unexpected status 401 Unauthorized"?

**Cause:** The API Key is invalid, expired, or was copied incompletely with extra spaces.

**Solution:**

1.  Confirm that `OPENAI_API_KEY` in `~/.codex/auth.json` is a valid UModelverse API Key.

2.  Re-copy the API Key from the [UModelverse Console](https://console.ucloud.cn/modelverse/api), ensuring it is complete with no extra spaces.

3.  After editing `auth.json`, open a new terminal window and run `codex` again for the change to take effect.

### Getting "unexpected status 404 Not Found"?

**Cause:** `base_url` or `wire_api` in `config.toml` is incorrect.

**Solution:** Confirm that `base_url` is `https://api-us-ca.umodelverse.ai/v1`, `wire_api` is `responses`, and `model_provider` is `ucloud`, matching the configuration example in section 2.2 above.

### Getting "wire_api = chat is no longer supported"?

**Cause:** The newer version of Codex uses the Responses API and no longer supports `wire_api = "chat"`.

**Solution:** Change `wire_api` in `config.toml` to `responses` (already used in this guide's configuration), and make sure you have the latest version of Codex installed:

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