> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex for VS Code User Guide

> Codex 集成指南 - Ace Data Cloud

Codex is a programming agent launched by OpenAI. Besides the terminal CLI, it also provides a VS Code extension that allows chatting, reading files, referencing context, generating modifications, and previewing changes in the editor sidebar.

This article explains how to configure and use the Codex extension in VS Code through Ace Data Cloud’s OpenAI Responses compatible proxy. The Codex VS Code extension and Codex CLI share the same local configuration system, so by pointing `~/.codex/config.toml` to Ace Data Cloud, Codex in VS Code will use `https://api.acedata.cloud/v1`.

## Application Process

To use Codex, first visit the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

If you are not logged in or registered, you will be automatically redirected to the login page to register and log in. After logging in or registering, you will be automatically returned to the current page.

A free quota is granted on the first application, allowing you to try Codex services for free.

## Install Codex Extension

Search for `Codex` in the VS Code extension marketplace and install the **Codex - OpenAI's coding agent** extension published by OpenAI. Its Marketplace ID is:

```text theme={null}
openai.chatgpt
```

You can also install it via the command line:

```bash theme={null}
code --install-extension openai.chatgpt
```

After installation, restart or reload VS Code. If you don’t see the Codex entry, open the command palette (macOS: `Cmd+Shift+P`, Windows/Linux: `Ctrl+Shift+P`), search for and run:

```text theme={null}
Codex: Open Codex Sidebar
```

By default, Codex appears in the right sidebar of VS Code. You can also drag it back to the left Activity Bar.

## Install Codex CLI (for Verification)

The official documentation states that the Codex VS Code extension and Codex CLI use the same configuration layer. To verify your API Token and model availability before configuring VS Code, it is recommended to install Codex CLI as well.

One official recommended method is installing via npm, requiring Node.js 18 or higher:

```bash theme={null}
npm install -g @openai/codex
```

macOS users can also install via Homebrew:

```bash theme={null}
brew install --cask codex
```

After installation, check if the command is available in the terminal:

```bash theme={null}
codex --version
```

If you only want to use the VS Code extension, you can skip the CLI verification step; the same `~/.codex/config.toml` configuration will be used later.

## Configure Ace Data Cloud API

Codex VS Code extension and Codex CLI share the configuration file. By default, Codex prompts to log in with an official OpenAI account or configure the official API Key. To use Ace Data Cloud instead, you need to configure the API Token and `~/.codex/config.toml`.

### Step 1: Set Environment Variable

It is recommended to write the API Token into your shell configuration file, such as `~/.zshrc`, `~/.bashrc`, or `~/.bash_profile`:

```bash theme={null}
export ACEDATACLOUD_API_KEY="{token}"
```

Replace `{token}` with the API Token you copied from the Ace Data Cloud console.

After configuration, reopen the terminal or run the corresponding `source` command to apply the changes immediately:

```bash theme={null}
source ~/.zshrc
```

If VS Code is already open, restart or reload it to let the extension read the new environment variable.

### Step 2: Edit Codex Configuration File

The user-level Codex configuration file is located at `~/.codex/config.toml`. If the file does not exist, create it:

```bash theme={null}
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

Write the following configuration:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.acedata.cloud/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"
```

Field descriptions:

| Field                    | Description                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------- |
| `model_provider`         | Default model provider, corresponding to `[model_providers.acedatacloud]` below                          |
| `model`                  | Default model ID                                                                                         |
| `model_reasoning_effort` | Reasoning intensity, common values are `low`, `medium`, `high`                                           |
| `approval_policy`        | Confirmation policy before command execution, `on-request` is recommended for daily use                  |
| `sandbox_mode`           | Sandbox permissions when Codex executes commands, `workspace-write` is recommended for daily development |
| `base_url`               | Ace Data Cloud’s OpenAI-compatible API endpoint                                                          |
| `env_key`                | Environment variable name from which Codex reads the API Token                                           |
| `wire_api`               | Protocol type, must be `responses` when using OpenAI Responses API                                       |

You can also click the gear icon at the top right of the Codex extension, select **Codex Settings > Open config.toml** to open this configuration file directly from VS Code.

### Project-level Configuration

If you want a different configuration for a specific project, create `.codex/config.toml` in the project root directory. Codex will prioritize loading project-level configuration, but the project must be marked as trusted for `.codex/` configurations to be loaded.

Example:

```toml theme={null}
model = "gpt-5-mini"
model_reasoning_effort = "medium"
```

It is recommended to keep personal Tokens in environment variables and not commit them to the project repository. Whether to commit project-level `.codex/config.toml` depends on your team’s policy.

## Clear Cached OpenAI Login

If you previously logged into the official OpenAI account in the Codex extension, the local official login state might still be retained. Before switching to the Ace Data Cloud proxy, you can run in the terminal:

```bash theme={null}
codex logout
```

If the command is unavailable, you can delete the local cache file:

```bash theme={null}
rm -f ~/.codex/auth.json
```

Then restart or reload VS Code.

## Basic Usage

After configuration, open the Codex panel on the left or right side of VS Code and enter your request directly. For example:

```text theme={null}
Explain the directory structure of the current project and point out the main entry file.
```

The Codex extension can use files and selected code in the editor as context. You can also reference files in the input box using `@`, for example:

```text theme={null}
Refer to @src/App.vue, help me split this page into clearer components.
```

If you select a piece of code, you can run from the command palette:

```text theme={null}
Codex: Add to Codex Thread
```

Or run:

```text theme={null}
Codex: Add File to Codex Thread
```

to add the entire current file to the context.

## Switch Model and Reasoning Effort

The Codex VS Code extension supports switching models and adjusting reasoning effort via the model switcher below the input box. When using a custom provider like Ace Data Cloud, the safest way is to set the default `model` in `~/.codex/config.toml` first, then switch as needed in the interface. Recommended defaults:

| Scenario                               | Recommended Model          | Reasoning Effort |
| -------------------------------------- | -------------------------- | ---------------- |
| Daily code reading and small edits     | `gpt-5-mini`               | `medium`         |
| Regular development tasks              | `gpt-5`                    | `high`           |
| Complex refactoring and deep reasoning | `gpt-5.5` or `gpt-5.5-pro` | `high`           |
| Reasoning-enhanced tasks               | `o3`                       | `high`           |

If the model you want is not shown in the interface, you can directly modify the `model` field in `~/.codex/config.toml` and then restart or reload VS Code. For the full model list, see the [Ace Data Cloud OpenAI Service Documentation](https://platform.acedata.cloud/documents/openai).

## Choose Working Mode

The Codex extension supports different working modes. Common modes:

| Mode                  | Suitable Scenario                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| `Chat`                | Only want to discuss, explain code, or plan first without Codex directly modifying files         |
| `Agent`               | Let Codex read files, modify code, and run necessary commands; recommended for daily development |
| `Agent (Full Access)` | Allows higher permissions and network access, suitable when you explicitly understand the risks  |

Daily use is recommended with `Agent` mode and keep `approval_policy = "on-request"`. This way, Codex will ask for confirmation before executing sensitive commands or accessing paths outside the workspace or the network.

## Verify Configuration

You can first verify Codex works through Ace Data Cloud with the same configuration in the terminal:

```bash theme={null}
codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK"
```

If configured correctly, you should see a response like:

```text theme={null}
ADC_Codex_OK
```

Then return to VS Code, open the Codex panel, and enter a simple question:

```text theme={null}
Describe the purpose of the current workspace in one sentence.
```

You can also check request logs and billing details via [Ace Data Cloud Console - Usage History](https://platform.acedata.cloud/console/usages), and remaining quota via [Ace Data Cloud Console - Applications](https://platform.acedata.cloud/console/applications).

## How It Works

The Codex VS Code extension does not have an independent model configuration. It uses the native Codex CLI and shares Codex’s configuration layer:

1. The VS Code extension starts Codex and reads the user-level `~/.codex/config.toml`.
2. If the current project is trusted and contains `.codex/config.toml`, Codex loads the project-level configuration.
3. When `model_provider` points to `acedatacloud`, Codex reads the API Token from `ACEDATACLOUD_API_KEY`.
4. Requests are sent via the OpenAI Responses protocol to `https://api.acedata.cloud/v1/responses`.
5. Ace Data Cloud verifies identity, checks quota, forwards requests, and records usage.

Therefore, the terminal CLI and VS Code extension usually only need to be configured once. After verifying in the terminal, the VS Code extension will use the same configuration.

## Learn More

* [Codex IDE extension official documentation](https://developers.openai.com/codex/ide)
* [Codex IDE extension settings reference](https://developers.openai.com/codex/ide/settings)
* [Codex CLI basic configuration](https://developers.openai.com/codex/config-basic)
* [Ace Data Cloud OpenAI Service Documentation](https://platform.acedata.cloud/documents/openai)