cc-switch

CC Switch manages provider configurations for coding tools. It is not a model service and does not replace installing Codex or Claude Code. This guide configures the two tools separately; choose the one you need.

Before you start

Create an API Key with the correct group and model for your tool.
Download an installer for your operating system and CPU architecture from official CC Switch Releases, then follow its installation instructions.
Install Codex CLI or Claude Code.

On first launch, preserve or import existing configurations before making changes. Button names and positions can vary by CC Switch version.

Add an aibal.ai provider

Choose the target application

Open CC Switch and select Codex or Claude Code in the application selector. Use an application-specific provider so each tool keeps its own settings.

Open the add-provider form

Click + / Add provider at the top right, choose an application-specific provider, then Custom. Name it aibal.ai - Codex or aibal.ai - Claude Code.

Enter the client configuration

Use the Codex configuration or Claude Code configuration below. If the console’s Use Key provides a dedicated endpoint, use that address. The two clients use different base addresses; do not copy one directly into the other.

Save and enable

Click Add, return to the main screen, and click Enable on your new provider. Close the old client session and launch the target CLI again so it reads the new configuration.

Verify the first request

Ask the tool: “Reply only Connection successful. Do not read or edit files or run commands.” Check the matching key, model and time in aibal.ai Usage afterward. Saving a configuration does not verify a call, and test messages may incur charges.

Codex configuration

With Codex selected, enter these values in the form or configuration editor:

Field	Value
Name	`aibal.ai - Codex`
API Key	Your aibal.ai key for the current group
Base URL / endpoint	`https://aibal.ai/v1`
Model	Full available text model ID from the console
Protocol	`responses`

If your version offers auth.json and config.toml editors, use the paired examples below. Replace the key and model placeholders, and save them only in your local CC Switch installation. auth.json:

{
  "OPENAI_API_KEY": "YOUR_AIBAL_API_KEY"
}

config.toml:

model_provider = "aibal"
model = "YOUR_AVAILABLE_MODEL_ID"

[model_providers.aibal]
name = "aibal.ai"
base_url = "https://aibal.ai/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

This uses the auth.json key method from the official CC Switch guide, so requires_openai_auth = true. Do not also add env_key from our manual Codex guide, which uses a different authentication method. If your group requires a model catalog file, complete that setup under Use Key as well.

Claude Code configuration

Select Claude Code, name the provider aibal.ai - Claude Code, and enter this in the custom configuration editor:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://aibal.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_AIBAL_API_KEY",
    "ANTHROPIC_MODEL": "YOUR_AVAILABLE_CLAUDE_MODEL_ID"
  }
}

Replace both placeholders with your aibal.ai key and a Claude model supported by its group. This address does not include /v1. Start Claude Code and run /status to check the gateway address and credential source.

Switching and restoring providers

Find the provider under the relevant application, click Enable, and start a new session. Codex and Claude Code have separate configurations; switching one does not switch the other. To restore your previous service, enable its saved provider. To return to an official account, select the Official login preset and follow that client’s sign-in flow. Do not delete all settings as a recovery method.

Common questions

It still uses the old provider

Check the selected application, confirm the provider is enabled, and restart the client. Environment variables or CC Switch common settings may override provider values. Keep future edits in one place.

The model list is empty or discovery fails

Available models depend on the key’s group. Check the key and address, or enter the full model ID shown in Use Key manually. Do not substitute a model name from another provider.

Why do Codex and Claude Code use different addresses?

The clients build request paths differently. Codex uses a base address with /v1 in this guide, while Claude Code uses the site root. An extra or missing path component can cause 404. Provider configurations and backups may contain real API Keys. Do not publish them in repositories, chats or untrusted sync storage. Share only templates with keys replaced; disable an exposed key immediately. For connection errors, see Integration overview. For CC Switch features and current UI details, see its official user manual.

About aibal.ai

Getting started

AI creation

Developer integrations

Before you start

Add an aibal.ai provider

Codex configuration

Claude Code configuration

Switching and restoring providers

Common questions

It still uses the old provider

The model list is empty or discovery fails

Why do Codex and Claude Code use different addresses?

​Before you start

​Add an aibal.ai provider

​Codex configuration

​Claude Code configuration

​Switching and restoring providers

​Common questions

​It still uses the old provider

​The model list is empty or discovery fails

​Why do Codex and Claude Code use different addresses?

​Can I share exported settings?

Before you start

Add an aibal.ai provider

Codex configuration

Claude Code configuration

Switching and restoring providers

Common questions

It still uses the old provider

The model list is empty or discovery fails

Why do Codex and Claude Code use different addresses?

Can I share exported settings?