> ## 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 provider in Codex CLI config.toml

> Configure a Codex CLI custom provider with the correct file, Base URL, API Key environment variable, config precedence, verification, and troubleshooting.

## Direct answer

Put user-level settings in `~/.codex/config.toml` and make `model_provider = "custom"` point to `[model_providers.custom]`. For BetterToken, use `https://www.bettertoken.ai/v1` as `base_url`, `responses` as `wire_api`, and a Model ID from the **GPT Key group**. Use `env_key` to read the API Key from a local environment variable instead of storing it in TOML or a repository.

## Find the correct config file

| Environment   | User-level config                  |
| ------------- | ---------------------------------- |
| macOS / Linux | `~/.codex/config.toml`             |
| Windows       | `%USERPROFILE%\.codex\config.toml` |
| Windows + WSL | `~/.codex/config.toml` inside WSL  |

In the VS Code Codex extension, click the gear icon and choose **Codex Settings → Open config.toml**. The CLI and IDE extension share the same config layers.

<Warning>
  Provider and authentication settings belong in user-level `~/.codex/config.toml`. Project `.codex/config.toml` files can hold project overrides, but Codex ignores `model_provider` and `model_providers` there. Put project instructions in `AGENTS.md`.
</Warning>

## Minimum working configuration

<Steps>
  <Step title="Set the API Key environment variable">
    macOS, Linux, or WSL:

    ```bash theme={null}
    export MODEL_PROVIDER_API_KEY="YOUR_API_KEY"
    ```

    Windows PowerShell:

    ```powershell theme={null}
    [Environment]::SetEnvironmentVariable("MODEL_PROVIDER_API_KEY", "YOUR_API_KEY", "User")
    $env:MODEL_PROVIDER_API_KEY = "YOUR_API_KEY"
    ```

    Replace `YOUR_API_KEY` with your BetterToken API Key. For persistent use, store it in a protected operating-system environment, not the project repository.
  </Step>

  <Step title="Edit config.toml">
    ```toml theme={null}
    model_provider = "custom"
    model = "gpt-5.5"

    [model_providers.custom]
    name = "BetterToken"
    base_url = "https://www.bettertoken.ai/v1"
    env_key = "MODEL_PROVIDER_API_KEY"
    wire_api = "responses"
    requires_openai_auth = false
    ```

    `model` is an example. Copy a currently available Model ID from the **GPT Key group** in the <a href={"https://www.bettertoken.ai/pricing"}>model plaza</a>.
  </Step>

  <Step title="Restart and test">
    Exit Codex completely, open a new terminal, and run:

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

    Send a simple prompt. A normal response confirms the provider, authentication, and Model ID are active.
  </Step>
</Steps>

## Recommended full configuration

Use this version when you need a review model and longer stream timeout:

```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.custom]
name = "BetterToken"
base_url = "https://www.bettertoken.ai/v1"
env_key = "MODEL_PROVIDER_API_KEY"
wire_api = "responses"
requires_openai_auth = false
request_max_retries = 4
stream_max_retries = 8
stream_idle_timeout_ms = 300000
supports_websockets = false
```

Merge existing top-level fields and `[model_providers.custom]` content. Do not declare the same TOML table twice.

## How the fields fit together

| Field                      | Purpose                                               | BetterToken value                          |
| -------------------------- | ----------------------------------------------------- | ------------------------------------------ |
| `model_provider`           | Selects a provider ID                                 | `"custom"`                                 |
| `[model_providers.custom]` | Defines that provider                                 | Must match `model_provider`                |
| `base_url`                 | Model request endpoint                                | `https://www.bettertoken.ai/v1`            |
| `env_key`                  | Names the environment variable containing the API Key | `MODEL_PROVIDER_API_KEY`                   |
| `wire_api`                 | Provider protocol                                     | `"responses"`                              |
| `requires_openai_auth`     | Uses official OpenAI authentication                   | `false` for ordinary third-party API setup |
| `model`                    | Default Model ID                                      | A current GPT Key group ID                 |

<Note>
  To keep the official Codex App login, plugins, and Remote Control while using a third-party API, use the dedicated [official login and unified session setup](/en/faq/codex/official-login-third-party-api) instead of this ordinary authentication example.
</Note>

## Common errors

| Symptom                    | Cause                                                                   | Fix                                                                                    |
| -------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Provider not found         | `model_provider` does not match the table name                          | Use `custom` in both places                                                            |
| Missing API Key at startup | The environment variable is missing or the terminal has not reloaded it | Set `MODEL_PROVIDER_API_KEY` and open a new terminal                                   |
| `401` or `403`             | Wrong Key or mixed authentication methods                               | Copy the Key again; keep the `env_key` name aligned and `requires_openai_auth = false` |
| `404`                      | The Base URL lacks `/v1` or uses the wrong protocol                     | Use `https://www.bettertoken.ai/v1`                                                    |
| Model not found            | The Model ID is unavailable or not in the GPT Key group                 | Copy a current ID from the model plaza                                                 |
| Changes do not apply       | Wrong config layer, path, or WSL environment                            | Edit the user config in the environment that runs Codex, then restart Codex            |
| TOML parse error           | Duplicate table, quote, or nesting error                                | Remove duplicate `[model_providers.custom]` tables and check string quotes             |

## Related docs

* [Complete Codex setup guide](/en/ai-tools/codex)
* [Configure a custom Base URL in the VS Code Codex extension](/en/ai-tools/codex-vscode)
* [model\_provider, base\_url, and wire\_api explained](/en/faq/codex/model-provider-base-url-wire-api)
* [Codex CLI sandbox and approval mode](/en/faq/codex/sandbox-approval)
* [What is AGENTS.md?](/en/faq/codex/agents-md)

## References

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