Skip to main content

CC Switch

CC Switch is an open-source desktop application for centrally managing provider configurations for multiple AI coding tools (Claude Code, Codex, Gemini CLI, etc.). Add your CloudBase provider configuration once in CC Switch, and it becomes available across multiple tools — no separate configuration needed for each.

Prerequisites

  • You have activated a TCB environment and obtained the environment ID cloudBaseEnvID
  • Enable the required model in the AI console
  • Obtain the Base URL and API Key in the AI console
Base URLhttps://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase

Configuration Steps​

We use CC Switch v3.16.1 as an example.

1. Install CC Switch​

Recommended via Homebrew:

brew install --cask cc-switch

Or download CC-Switch-*-macOS.dmg from the Releases page.

2. Add CloudBase as a Provider​

  1. Open the CC Switch desktop app
  2. Click the + button in the top-right corner and select Add Provider
  3. Choose Custom Configuration from the presets
  4. Fill in the following information:
FieldDescription
Provider NameEnter "CloudBase" or a custom name
API KeyThe API key obtained from the AI console
Base URLRequest address: https://{{cloudBaseEnvID}}.api.tcloudbasegateway.com/v1/ai/cloudbase
  1. Select the API Format based on the AI tool you are using

Choosing the API Format​

CloudBase AI supports the following protocols:

  • Anthropic Messages: The native interface protocol for Claude models
  • Chat Completions: OpenAI-compatible general-purpose chat protocol
  • Responses API: OpenAI's next-generation API, currently only supported by some models

Select the API format based on the AI tool:

AI ToolRecommended API FormatNotes
Claude CodeAnthropic MessagesNative format, no additional setup needed
Claude DesktopAnthropic MessagesNative format, no additional setup needed
CodexChat CompletionsRequires local routing to be enabled
Gemini CLIChat CompletionsGeneral format
OpenCodeChat CompletionsGeneral format
OpenClawChat CompletionsGeneral format
HermesChat CompletionsGeneral format

Configuring for Claude Code / Claude Desktop (Anthropic Messages):

Select the Anthropic Messages format (default), paste your CloudBase API Key and Base URL. No advanced options changes needed.

Configuring for Codex (Chat Completions):

  1. In the advanced options, switch the API format to Chat Completions

  2. Check Needs Local Route Mapping

  3. In the model mapping table, enter the model ID (copy an enabled model identifier from the AI console model list)

  4. Save the configuration and enable the CloudBase provider

note

After switching providers, most AI tools require a restart of the terminal or CLI tool. Claude Code supports hot-switching and does not need a restart.

Usage with AI Tools​

Once configured, the following AI tools can directly use CloudBase AI models:

  • Claude Code — Uses Anthropic Messages protocol (native), run claude in the terminal
  • Claude Desktop — Uses Anthropic Messages protocol (native)
  • Codex — Uses Chat Completions protocol (requires local routing enabled), run codex in the terminal
  • Gemini CLI — Uses Chat Completions protocol, run gemini in the terminal
  • OpenCode — Uses Chat Completions protocol
  • OpenClaw — Uses Chat Completions protocol
  • Hermes — Uses Chat Completions protocol

Common Error Troubleshooting​

Error MessageSolution
401 Credentials are invalidThe API Key is incorrect or may have been deleted. Go to the AI console to obtain a new one.
404 Model not foundThe Base URL or model name is incorrect. Make sure the model is enabled in the AI console.
429 Token usage exceeded quota limitToken quota exhausted or the model is not enabled in the AI console.
Codex connection failedMake sure the local routing service (proxy mode) is enabled and the API format is set to Chat Completions.
Connection refusedCheck your network connectivity to the CloudBase API and verify the environment ID in the Base URL is correct.