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

# OpenClaw BetterToken setup guide

> Connect BetterToken to OpenClaw, a multi-platform AI agent gateway.

OpenClaw is a cross-platform AI agent gateway for Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more. This page shows you how to connect BetterToken to OpenClaw and do a basic verification.

## Install OpenClaw

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

  <Tab title="Windows">
    ```powershell theme={null}
    iwr -useb https://openclaw.ai/install.ps1 | iex
    ```
  </Tab>
</Tabs>

## Install and connect

<Tabs>
  <Tab title="Automatic setup">
    You can run the BetterToken automatic setup script directly. Have your BetterToken API Key ready before you start. 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. After the script finishes, continue to “Make it take effect” below.

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

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

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

    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 ANTHROPIC_AUTH_TOKEN
        unset ANTHROPIC_BASE_URL
        unset OPENAI_API_KEY
        unset OPENAI_BASE_URL
        ```
      </Step>

      <Step title="Run onboarding">
        ```bash theme={null}
        openclaw onboard --install-daemon
        ```
      </Step>

      <Step title="Add the BetterToken credential through the auth flow">
        ```bash theme={null}
        openclaw models auth add
        ```
      </Step>

      <Step title="Add or confirm the BetterToken provider">
        In the wizard or provider editor, fill in or confirm:

        * **Base URL**: `https://www.bettertoken.ai/v1`
        * **API**: `openai-responses`
        * **API Key**: your BetterToken API Key
        * **Model**: a currently available model ID copied from the model plaza (`https://www.bettertoken.ai/pricing`)

        A minimal provider config snippet looks like this:

        ```json theme={null}
        {
          "models": {
            "mode": "merge",
            "providers": {
              "bettertoken": {
                "baseUrl": "https://www.bettertoken.ai/v1",
                "apiKey": "YOUR_BETTERTOKEN_API_KEY",
                "api": "openai-responses",
                "models": [
                  {
                    "id": "YOUR_CODEX_MODEL_ID",
                    "name": "YOUR_CODEX_MODEL_ID"
                  }
                ]
              }
            }
          }
        }
        ```
      </Step>

      <Step title="You usually do not need extra `headers`">
        You usually do not need an extra `User-Agent` when connecting BetterToken.

        Only add headers when you are also using a custom gateway, tenant routing, or another upstream service that explicitly requires them.
      </Step>

      <Step title="Set the default model and verify">
        Run `openclaw models list` to confirm the provider id, then set the default model and check the status:

        ```bash theme={null}
        openclaw models list
        openclaw models set <provider>/<Codex model ID copied from https://www.bettertoken.ai/pricing>
        openclaw gateway restart
        openclaw models status
        ```

        After the config is written, continue to “Make it take effect” below to restart the gateway and verify the session.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Notes for multi-agent setups and existing sessions

The effective model priority in OpenClaw is usually:

`session override` > `agents.list[*].model` > `agents.defaults.model.primary`

This means:

* If an agent explicitly defines `model` in `agents.list`, it does not inherit the global default model.
* If you set BetterToken as the global default model but `main` still pins an older model, Discord DM flows that use `main` still keep using the older model.
* If a previous session still has `providerOverride`, `modelOverride`, or `authProfileOverride`, the current session may keep using the old route even after you update the default model.

Recommended workflow:

1. If you want `main` to follow the global default, do not set a separate `model` for `main`, or change it to BetterToken.
2. Run `openclaw gateway restart` after changing the config.
3. Run `/new` in Discord to start a fresh session.
4. Use `/status` and `/model` to verify the active model.

### Minimal config example

Use the provider id shown by `openclaw models list`. The example below uses `bettertoken/gpt-5.4`; replace it if your provider id is different.

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "bettertoken/gpt-5.4",
        "fallbacks": []
      },
      "models": {
        "bettertoken/gpt-5.4": {
          "alias": "bettertoken"
        }
      }
    },
    "list": [
      {
        "id": "main"
      },
      {
        "id": "fitness-coach"
      },
      {
        "id": "trade-recorder",
        "model": {
          "primary": "bettertoken/gpt-5.4",
          "fallbacks": []
        }
      }
    ]
  }
}
```

* `main` does not define `model`, so it inherits the global BetterToken default.
* `trade-recorder` defines `model`, so it does not follow later changes to the global default.

## Make it take effect

<Tip>
  If `/model` is unstable, hot reload is inconsistent, or the model picker behaves strangely on an older OpenClaw build, upgrade to the latest version before deeper troubleshooting.
</Tip>

<Steps>
  <Step title="Verify the config layer first">
    Run:

    ```bash theme={null}
    openclaw models list
    openclaw models status
    ```

    Confirm the BetterToken provider exists and the default model points to BetterToken.
  </Step>

  <Step title="Reload the gateway">
    ```bash theme={null}
    openclaw gateway restart
    ```
  </Step>

  <Step title="Start a new session">
    Run `/new` in Discord.
  </Step>

  <Step title="Verify the model used by the current session">
    Run `/status` in Discord and confirm the current agent and current session are using BetterToken.
  </Step>

  <Step title="Check the available model picker if needed">
    Run `/model` in Discord.

    If BetterToken does not appear there, check:

    * whether the current model is listed in `agents.defaults.models`
    * whether the provider model has a readable display name and, if needed, an `alias` in `agents.defaults.models`
    * whether you already ran `openclaw gateway restart`
    * whether you already ran `/new`
  </Step>
</Steps>

## Troubleshooting shortcuts

* If you changed the default model but runtime still uses the old one, check `agents.list.main.model` first
* If BetterToken does not appear in `/model`, check whether it is listed in `agents.defaults.models`
* If Discord still shows the old route after a config change, run `openclaw gateway restart` and then `/new`
* If the model picker or hot reload still looks stale, upgrade OpenClaw first and test again

## Fallback: let Codex configure it for you

If you do not want to edit the config manually, set the API Key as an environment variable and start Codex:

```bash theme={null}
export BETTERTOKEN_API_KEY="YOUR_API_KEY"
codex
```

Then send this prompt to Codex:

```text theme={null}
Please inspect and fix my local OpenClaw BetterToken setup. Requirements:
1. Read the current OpenClaw config first and identify the provider id, the default model, and which agents in agents.list explicitly define model.
2. If the BetterToken provider does not exist, add one that uses the Base URL `https://www.bettertoken.ai/v1` and sets `api: "openai-responses"`.
3. Reuse any credential already saved by OpenClaw. Only configure extra headers when the current version or your upstream gateway explicitly requires them; do not assume `User-Agent` is mandatory for BetterToken.
4. Switch the default model to BetterToken and check whether `main` is still pinned to an older model. If I want `main` to follow the global default, remove the explicit model from `main`.
5. Make sure the active BetterToken model is present in `agents.defaults.models` and add an easy-to-recognize `alias`.
6. Back up the original config, make the smallest possible diff, and tell me which fields you plan to change before editing.
7. After editing, run `openclaw gateway restart` and remind me to validate with `/new`, `/status`, and `/model` in Discord.

Constraints:
- If you need the API Key, read it from the `BETTERTOKEN_API_KEY` environment variable and do not print the secret in chat or logs.
- If the current config does not include a BetterToken model yet, ask me for a Codex-group model ID from the BetterToken model plaza.
```