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

# OpenCode BetterToken setup guide

> Connect BetterToken to OpenCode with Codex group model IDs.

You can connect BetterToken to OpenCode by first adding credentials with `/connect`, then declaring BetterToken as an OpenAI-compatible provider in the config file and selecting a model ID from the Codex group.

## Prerequisites

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

## Install OpenCode

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -fsSL https://opencode.ai/install | bash
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g opencode-ai
    ```
  </Tab>
</Tabs>

## 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-opencode-provider.sh | bash
        ```
      </Step>

      <Step title="If you use Windows">
        ```powershell theme={null}
        iwr https://www.bettertoken.ai/install-opencode-provider.ps1 -OutFile "$env:TEMP\install-opencode-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-opencode-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#opencode).

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

    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="Clear conflicting environment variables">
        ```bash theme={null}
        unset OPENAI_API_KEY
        unset OPENAI_BASE_URL
        ```
      </Step>

      <Step title="Add the BetterToken credential with /connect first">
        Start OpenCode and run:

        ```bash theme={null}
        /connect
        ```

        In the wizard, choose **Other** and then:

        * set the **provider id** to `bettertoken`
        * paste your BetterToken API Key

        OpenCode stores the credential in `~/.local/share/opencode/auth.json`.
      </Step>

      <Step title="Edit the OpenCode config file">
        You can use the global config at `~/.config/opencode/opencode.json` or create `opencode.json` in your project root. The project config has higher precedence.

        ```json theme={null}
        {
          "$schema": "https://opencode.ai/config.json",
          "model": "bettertoken/YOUR_CODEX_MODEL_ID",
          "provider": {
            "bettertoken": {
              "npm": "@ai-sdk/openai-compatible",
              "name": "BetterToken",
              "options": {
                "baseURL": "https://www.bettertoken.ai/v1"
              },
              "models": {
                "YOUR_CODEX_MODEL_ID": {
                  "name": "YOUR_CODEX_MODEL_ID"
                }
              }
            }
          }
        }
        ```

        Replace `YOUR_CODEX_MODEL_ID` with a current **Codex group** model ID copied from the model plaza (`https://www.bettertoken.ai/pricing`).
      </Step>

      <Step title="If you want to inline the API key, use this fallback format">
        ```json theme={null}
        {
          "$schema": "https://opencode.ai/config.json",
          "model": "bettertoken/YOUR_CODEX_MODEL_ID",
          "provider": {
            "bettertoken": {
              "npm": "@ai-sdk/openai-compatible",
              "name": "BetterToken",
              "options": {
                "baseURL": "https://www.bettertoken.ai/v1",
                "apiKey": "YOUR_API_KEY"
              },
              "models": {
                "YOUR_CODEX_MODEL_ID": {
                  "name": "YOUR_CODEX_MODEL_ID"
                }
              }
            }
          }
        }
        ```

        This is a fallback. The `/connect` flow above is the preferred setup.
      </Step>

      <Step title="Only use `options.headers` for provider-specific needs">
        OpenCode's official docs support custom headers through `provider.<id>.options.headers`, but this is optional. You usually do not need an extra `User-Agent` when connecting BetterToken.

        If you are also using Helicone, tenant routing, observability, or caching services, add the required headers based on those upstream services' official docs.
      </Step>

      <Step title="Restart OpenCode">
        After updating the config file, quit the current OpenCode session and start it again.
      </Step>

      <Step title="Start OpenCode">
        ```bash theme={null}
        cd /path/to/your/project
        opencode
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Notes

* Use a **Codex group** model ID as the default model instead of fixed Claude model names
* BetterToken should currently use `@ai-sdk/openai-compatible` as the OpenAI-compatible provider adapter
* If you use `/connect`, you usually do not need to store the API key directly in the config file
* OpenCode's official docs treat `options.headers` as optional extended configuration; BetterToken usually does not need extra headers