Codex for VS Code User Guide

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 to obtain your API Token for backup.

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:

openai.chatgpt

You can also install it via the command line:

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:

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:

npm install -g @openai/codex

macOS users can also install via Homebrew:

brew install --cask codex

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

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:

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:

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:

mkdir -p ~/.codex
touch ~/.codex/config.toml

Write the following configuration:

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:

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:

codex logout

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

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:

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:

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:

Codex: Add to Codex Thread

Or run:

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.

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:

codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK"

If configured correctly, you should see a response like:

ADC_Codex_OK

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

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, and remaining quota via Ace Data 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