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

# How to configure a custom Base URL and API Key in the VS Code Codex extension

> Open the shared config.toml from the VS Code Codex extension, configure BetterToken Base URL, API Key, and GPT Key group model, and fix config loading issues.

## Direct answer

The VS Code Codex extension has no separate Base URL or API Key fields. It shares configuration layers with Codex CLI. Click the gear icon, choose **Codex Settings → Open config.toml**, and add the BetterToken provider to your user config. Then run **Developer: Reload Window** so the extension reads the new endpoint, Key, and model.

<Info>
  It is normal if you do not see `Base URL` or API Key fields in VS Code settings. Do not put the custom endpoint in the general VS Code proxy settings.
</Info>

## Prerequisites

* VS Code is installed
* The **Codex - OpenAI's coding agent** extension is installed
* You have a BetterToken API Key (<a href={"https://www.bettertoken.ai/register"}>sign up and get one</a>)
* You have copied an available model ID from the **GPT Key group** in the <a href={"https://www.bettertoken.ai/pricing"}>model plaza</a>

<Warning>
  Do not put your API Key in project files, `AGENTS.md`, sample `.env` files, or public repositories. The configuration below should stay in your local Codex configuration directory.
</Warning>

## Setup methods

<Tabs>
  <Tab title="Recommended: use the Setup dialog">
    After you create an API Key, the console opens a **Setup** dialog. From that dialog, copy **API Key** and **Base URL**, then choose a Codex setup method.

    <Steps>
      <Step title="Select Codex">
        Select **Codex** under **Available tools**.
      </Step>

      <Step title="Choose a setup method">
        You can choose:

        * **One-click Bash Configuration**: copy the command and run it in your local terminal. Use this for quick setup.
        * **CC Switch Integration**: import the provider into CC Switch. Use this when you manage multiple tools.
        * **Manual Configuration**: copy API Key and Base URL, then write them into `config.toml`.
      </Step>

      <Step title="Restart VS Code">
        After the configuration is written, restart VS Code or run **Developer: Reload Window** so the Codex extension reads the local configuration again.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual configuration">
    <Steps>
      <Step title="Find config.toml">
        Click the gear icon in the Codex extension and choose **Codex Settings → Open config.toml**. You can also open:

        | System        | Configuration file                      |
        | ------------- | --------------------------------------- |
        | macOS / Linux | `~/.codex/config.toml`                  |
        | Windows       | `C:\Users\YOUR_USER\.codex\config.toml` |
        | Windows + WSL | `~/.codex/config.toml` inside WSL       |

        Codex CLI and the IDE extension read the same config layers. For a project opened through WSL, edit the file inside WSL rather than a separate file in the Windows user directory.
      </Step>

      <Step title="Add the BetterToken provider">
        Add the configuration below to `config.toml`. If the file already contains the same top-level fields, merge the configuration instead of writing duplicate `model_provider` entries.

        ```toml theme={null}
        model_provider = "custom"
        model = "gpt-5.5"
        review_model = "gpt-5.4"
        model_reasoning_effort = "high"
        model_context_window = 1000000
        model_auto_compact_token_limit = 900000
        windows_wsl_setup_acknowledged = true

        [model_providers]
        [model_providers.custom]
        name = "BetterToken"
        base_url = "https://www.bettertoken.ai/v1"
        wire_api = "responses"
        requires_openai_auth = true
        experimental_bearer_token = "YOUR_API_KEY"
        request_max_retries = 4
        stream_max_retries = 8
        stream_idle_timeout_ms = 300000
        supports_websockets = false
        ```

        Replace `YOUR_API_KEY` with your BetterToken API Key.
      </Step>

      <Step title="Confirm the key fields">
        Check these fields first:

        | Field                       | Value                                        |
        | --------------------------- | -------------------------------------------- |
        | `base_url`                  | `https://www.bettertoken.ai/v1`              |
        | `wire_api`                  | `responses`                                  |
        | `model`                     | A model ID copied from the **GPT Key group** |
        | `experimental_bearer_token` | Your BetterToken API Key                     |

        <Warning>
          For the VS Code Codex extension, do not convert `auth.json` into an API Key-only structure. `auth.json` keeps the official Codex login state; the third-party API Key belongs in `experimental_bearer_token`.
        </Warning>
      </Step>

      <Step title="Restart VS Code">
        After editing the file, close the current Codex session and restart VS Code.

        You can also run this from the command palette:

        ```text theme={null}
        Developer: Reload Window
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Why keep the official login state?

The VS Code Codex extension depends on Codex app-side capabilities such as the extension UI, session management, and VS Code integration. Keep the official login state while routing model requests through BetterToken.

In this configuration:

| Setting                                      | What it does                                                                     |
| -------------------------------------------- | -------------------------------------------------------------------------------- |
| `requires_openai_auth = true`                | Keeps the official Codex login state                                             |
| `experimental_bearer_token = "YOUR_API_KEY"` | Uses your BetterToken API Key for model requests                                 |
| `base_url = "https://www.bettertoken.ai/v1"` | Sends model requests to BetterToken's OpenAI-compatible / Responses API endpoint |

<Note>
  The official Codex config reference recommends `env_key` for ordinary custom-provider API Keys. This page uses `experimental_bearer_token` because this scenario also preserves the official Codex login. If you only use Codex CLI and do not need plugins, Remote Control, or the official login state, use the [ordinary custom-provider config.toml setup](/en/faq/codex/config-toml).
</Note>

## Verify which config the extension reads

After setup, open the Codex extension in VS Code and send a short test message.

If you get a normal response, the configuration is active. You can also open `config.toml` from the extension gear again and confirm it is the file you edited.

## Common errors

| Symptom                                         | Cause                                                        | Fix                                                                                                             |
| ----------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Codex CLI works but the VS Code extension fails | The extension runs in another environment or has stale state | Open the actual config from the gear icon; edit the WSL file for WSL projects; run **Developer: Reload Window** |
| The extension still asks for official login     | The Codex IDE extension needs its application-side login     | Complete official sign-in, then keep `requires_openai_auth = true` and the third-party bearer token             |
| `401` or `403`                                  | Wrong API Key or unchanged `experimental_bearer_token`       | Copy the Key again and do not replace the official login data in `auth.json`                                    |
| `404`                                           | Base URL is missing `/v1`                                    | Use `https://www.bettertoken.ai/v1`                                                                             |
| Model not found                                 | The Model ID is not in the GPT Key group                     | Copy a current ID from the <a href={"https://www.bettertoken.ai/pricing"}>model plaza</a>                       |
| TOML parse error                                | A field or table is declared twice                           | Merge the existing config and keep one `[model_providers.custom]` table                                         |

## Related docs

* [Codex setup guide](/en/ai-tools/codex)
* [How to keep the official Codex login state with a third-party API](/en/faq/codex/official-login-third-party-api)
* [How to configure Codex CLI config.toml](/en/faq/codex/config-toml)
* [What are model\_provider, base\_url, and wire\_api in Codex CLI?](/en/faq/codex/model-provider-base-url-wire-api)

## References

* [Codex IDE extension](https://developers.openai.com/codex/ide)
* [Codex basic configuration](https://developers.openai.com/codex/config-basic)
* [Codex configuration reference](https://developers.openai.com/codex/config-reference)