> ## 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.

# Codex BetterToken setup guide

> Connect BetterToken to Codex with /v1 and OpenAI Responses.

Connecting Codex to BetterToken requires a custom model provider and API Key. The `base_url` must be `https://www.bettertoken.ai/v1`, and the protocol is `OpenAI Responses`.

## Prerequisites

* Node.js installed
* BetterToken API Key (register here (`https://www.bettertoken.ai/register`))

<Warning>
  Clear OpenAI-related environment variables before setup so they do not override the settings in `config.toml` or `auth.json`.

  Clear these variables:

  * `OPENAI_API_KEY`
  * `OPENAI_BASE_URL`

  Run on macOS / Linux:

  ```bash theme={null}
  unset OPENAI_API_KEY
  unset OPENAI_BASE_URL
  ```

  Run in Windows PowerShell:

  ```powershell theme={null}
  Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
  Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
  [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", $null, "User")
  [Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", $null, "User")
  ```
</Warning>

## Install Codex

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

## Setup

<Tabs>
  <Tab title="Automatic setup">
    You can run the BetterToken automatic setup script directly. It only writes the BetterToken provider configuration and does not replace the installation prerequisites above. The script requires `Node.js`. If you do not pass an API Key or model explicitly, the script prompts for them when the tool supports interactive input.

    Follow the step for your operating system. You only need one of them.

    <Steps>
      <Step title="If you use macOS / Linux">
        ```bash theme={null}
        curl -fsSL https://www.bettertoken.ai/install-codex-provider.sh | bash
        ```
      </Step>

      <Step title="If you use Windows">
        ```powershell theme={null}
        iwr https://www.bettertoken.ai/install-codex-provider.ps1 -OutFile "$env:TEMP\install-codex-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-codex-provider.ps1"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Configure via CC Switch">
    This setup path is maintained in the [CC Switch guide](/en/ai-tools/cc-switch#codex-cli).

    Go straight to [the Codex tab in the CC Switch guide](/en/ai-tools/cc-switch#codex-cli).

    After you finish in CC Switch, come back to this page for the remaining startup, verification, or activation notes.
  </Tab>

  <Tab title="Manual setup">
    <Steps>
      <Step title="Copy a model ID from the model plaza">
        Open the BetterToken model plaza (`https://www.bettertoken.ai/pricing`) and copy a currently available model ID from the **Codex group**. Replace every `YOUR_CODEX_MODEL_ID` below with that value.
      </Step>

      <Step title="Confirm the config file locations">
        Manual setup requires both the Codex `config.toml` and `auth.json` files.

        | System        | `config.toml`                           | `auth.json`                           |
        | ------------- | --------------------------------------- | ------------------------------------- |
        | macOS / Linux | `~/.codex/config.toml`                  | `~/.codex/auth.json`                  |
        | Windows       | `C:\Users\YOUR_USER\.codex\config.toml` | `C:\Users\YOUR_USER\.codex\auth.json` |
      </Step>

      <Step title="Edit the Codex config file">
        Open `config.toml`. Create it if it does not exist.

        <Warning>
          This config only applies when you manually edit `~/.codex/config.toml`. If you configure Codex through CC Switch, follow the [CC Switch guide](/en/ai-tools/cc-switch#codex-cli) exactly. Do not copy this block to replace configuration managed by CC Switch.
        </Warning>

        Add the following config:

        ```toml theme={null}
        model_provider = "bettertoken"
        model = "YOUR_CODEX_MODEL_ID"
        model_reasoning_effort = "high"
        disable_response_storage = true

        [model_providers.bettertoken]
        name = "BetterToken"
        base_url = "https://www.bettertoken.ai/v1"
        wire_api = "responses"
        requires_openai_auth = true
        model_context_window = 1000000
        model_auto_compact_token_limit = 900000
        ```
      </Step>

      <Step title="Write the Codex auth file">
        Open `auth.json`. Create it if it does not exist.

        Write the following content, replacing `YOUR_API_KEY` with your BetterToken API Key:

        ```json theme={null}
        {
          "OPENAI_API_KEY": "YOUR_API_KEY"
        }
        ```
      </Step>

      <Step title="Restart Codex in the terminal">
        After changing `config.toml` or `auth.json`, stop the current Codex process and start it again in a new terminal session.
      </Step>

      <Step title="Start Codex">
        ```bash theme={null}
        codex
        ```
      </Step>
    </Steps>

    ### Config parameter reference

    | Parameter                  | Description                                                                                                   |
    | -------------------------- | ------------------------------------------------------------------------------------------------------------- |
    | `model_provider`           | The default model provider ID. It must match `bettertoken` in `[model_providers.bettertoken]`                 |
    | `model`                    | The default model ID Codex uses after startup. Use a model copied from the **Codex group** in the model plaza |
    | `model_reasoning_effort`   | Model reasoning effort. Set it to `low`, `medium`, or `high` as needed                                        |
    | `disable_response_storage` | Disables response storage. Keep this set to `true`                                                            |
    | `name`                     | Provider display name. You can keep it as `BetterToken`                                                       |
    | `base_url`                 | BetterToken Codex / OpenAI-compatible protocol endpoint. It must include `/v1`                                |
    | `wire_api`                 | The API protocol used by Codex. Keep this set to `responses`                                                  |
    | `requires_openai_auth`     | Tells Codex to read the API Key from its OpenAI auth file. Keep this set to `true`                            |

    ### 1M context config

    If you use a long-context model from the **Codex group**, keep these two settings:

    ```toml theme={null}
    model_context_window = 1000000
    model_auto_compact_token_limit = 900000
    ```

    | Parameter                        | Purpose                                                                                                                    |
    | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
    | `model_context_window`           | Sets the available context window to `1,000,000` tokens                                                                    |
    | `model_auto_compact_token_limit` | Triggers compaction before the context reaches the hard limit, reducing the chance that a conversation runs out of context |

    If you write the config through CC Switch, prefer the config generated by CC Switch. Only edit these values yourself for manual setup or troubleshooting.
  </Tab>
</Tabs>

## Verify the setup

After startup, send a test message. A normal reply means the connection is working.

If something fails, check:

1. `base_url` is `https://www.bettertoken.ai/v1`
2. `wire_api` is still `responses`
3. `model` is a model ID copied from the **Codex group**
4. `OPENAI_API_KEY` in `~/.codex/auth.json` is your BetterToken API Key
5. No old `OPENAI_API_KEY` or `OPENAI_BASE_URL` variables are interfering