Skip to main content

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.

Recent Claude Desktop versions changed how third-party API gateways are configured. In Gateway mode, Claude Desktop validates model IDs more strictly, so non-official model IDs such as GPT, DeepSeek, or GLM can be blocked. A common symptom is this warning at the top of the page: Your provider setup needs a fix Some required fields are missing or malformed. Open Setup to finish configuring it. At the same time, the third-party model selector in the lower-left area is empty, and Claude Desktop only shows a Legacy Model state.
Claude Desktop showing Your provider setup needs a fix while the third-party model selector is empty.
If you want to keep using Codex or other third-party models in Claude Desktop, route the requests through CC Switch: configure BetterToken under Claude Code in CC Switch, then enter the CC Switch local service address in Claude Desktop Gateway.
This path is for Codex group API keys. Do not enter https://www.bettertoken.ai/v1 directly in Claude Desktop Gateway.

​
Setup steps

1

Download Claude Desktop

Download the latest Claude Desktop app from the official link:Download Claude for MacAfter installation, do not sign in to a Claude account. Continue to the next step and enable developer mode.
2

Enable developer mode

Open Claude Desktop, then choose Help → Troubleshooting → Enable Developer Mode from the macOS menu bar.
Select Enable Developer Mode from the Claude Desktop Help menu.
In the confirmation window, click Enable, then restart Claude Desktop.
Confirm developer mode in Claude Desktop.
3

Open third-party inference settings

After restarting, the macOS menu bar shows a Developer menu.Choose Developer → Configure Third-Party Inference….
Choose Configure Third-Party Inference from the Developer menu.
4

Open Claude Code in CC Switch and add a provider

Open CC Switch, switch to Claude Code, and click Add Provider.
The Claude Code page in CC Switch, with the add button in the top-right corner used to create a new provider.
5

Fill in the basic fields

  • Provider Name: BetterToken
  • Base URL: https://www.bettertoken.ai
  • API Key: your BetterToken API Key
The screenshot labels map to:
  1. Provider Name
  2. API Key
  3. Base URL
The provider edit page in CC Switch, showing where to enter Provider Name, API Key, and Base URL.
6

Set the API format and model mappings

Open Advanced Options and set API Format to OpenAI Responses API.
The advanced options section in CC Switch, with API Format set to OpenAI Responses API.
In Model Mapping, click Fetch Model List. Explicitly select dropdown values for Primary Model, Thinking Model, Haiku Default Model, Sonnet Default Model, and Opus Default Model.
The model mapping section in CC Switch, showing Fetch Model List and the mappings for Primary, Thinking, Haiku, Sonnet, and Opus models.
Use model IDs from the current Codex group models in the BetterToken model plaza.
7

Save, switch, and enable the proxy

After saving, return to the provider list:
  1. Set the BetterToken provider you just saved as In use
  2. Enable the CC Switch proxy from the top-left corner
After saving, return to the provider list, set BetterToken as active, and enable the CC Switch proxy toggle in the top-left corner.
8

Open CC Switch settings

Return to the CC Switch home screen, then click Settings in the top-left corner.
The CC Switch home screen with the Settings button highlighted in the top-left corner.
9

Confirm routing is enabled and copy the service address

Open Routing settings. Confirm that the highlighted main routing switch and Claude route switch are both on. Then copy the Service address shown below.
The CC Switch routing settings page, with the main route switch, Claude route switch, and service address copy button highlighted.
10

Enter the Gateway base URL in Claude Desktop

Return to the Claude Desktop third-party inference settings window and select Gateway. Paste the CC Switch Service address into Gateway base URL, then enter your BetterToken API Key.Set Gateway auth scheme to bearer.
The Claude Desktop Gateway settings page with the CC Switch local service address entered.
11

Add the model list and apply locally

Add these models in Model list:
  • claude-opus
  • claude-sonnet
  • claude-haiku
After filling in the list, click Apply locally.
The Claude Desktop Model list with claude-opus, claude-haiku, and claude-sonnet added, and Apply locally available.
12

Confirm the app relaunch

After Claude writes the local configuration, it asks for a relaunch. Click Relaunch now so the new gateway configuration takes effect.
Claude Desktop asks to relaunch, with the Relaunch now button highlighted.
13

Sign in with Gateway

After restarting, wait about 3 seconds for the sign-in choice to appear.
Claude Desktop shows the Continue with Gateway sign-in option.
Choose Continue with Gateway. After Claude opens, Cowork 3P | Gateway appears in the lower-left corner and you can start using it.
Claude Desktop is ready after signing in with Gateway.

​
Troubleshooting

If you still see Your provider setup needs a fix, check these items first:
  1. The BetterToken provider in CC Switch is set as In use
  2. API Format is set to OpenAI Responses API
  3. Model Mapping explicitly selects Codex group models for Primary, Thinking, Haiku, Sonnet, and Opus
  4. CC Switch proxy, the main routing switch, and the Claude route switch are all enabled
  5. Claude Desktop Gateway base URL uses the local service address copied from CC Switch
  6. Model list includes claude-opus, claude-sonnet, and claude-haiku