What Is CC Switch and How to Use It: Custom Providers for Claude Code and Codex (With Error Fixes)
CC Switch manages the provider settings on your own machine; it does not supply models or keys. Claude Code and Codex use different protocols, so their setups differ, and most provider errors come down to three mismatches: base URL, model name, or protocol.
1. What CC Switch is, and what it is not
AI coding tools such as Claude Code and Codex each read their own config files to decide where requests go, which key is used and which model answers. If you move between an official account, a few relay services and different projects, editing those files by hand is slow and error-prone. CC Switch centralises those settings and switches between them in one click. It is not a model service: it has no models, no keys and no balance. So the accurate description of 'using CC Switch to call cocodot' is that CC Switch stores and applies the configuration while cocodot provides the endpoint, key, model access and balance. The official repository is farion1231/cc-switch; install from that source and avoid third-party installers of unknown origin.
2. Before you start: key, balance, one small test
Create an API key in the cocodot dashboard and make sure the account has balance (the API is metered, topped up by Alipay or WeChat; Claude, GPT and Gemini lines are listed at or below official prices, and the live price per model is on the pricing page). After verifying your email there is a small trial credit, usable on the API only, with the eligible models listed on the pricing page; it is enough to prove the setup. Use one key per project so usage splits cleanly and a leaked key can be revoked alone. Before configuring, copy the exact checklist for your tool from the dashboard: it carries the current base URL and model roles and is fresher than anything written in an article.
3. Claude Code: native Anthropic endpoint, no routing needed
Claude Code speaks the Anthropic Messages protocol and cocodot offers a native Anthropic-compatible endpoint, so this path does not need CC Switch routing. Add a custom Claude Code provider, set the base URL to `https://cocodot.co/api/ai` (without /v1), fill the model roles from the checklist, paste the real key locally inside CC Switch, save, enable, then restart the Claude Code session. Whether the base URL carries /v1 is the most common mistake on this path; adding /v1 typically produces a 404.
4. Codex: why local routing is required
Codex speaks the OpenAI Responses protocol, while cocodot's OpenAI-compatible endpoint currently provides Chat Completions. The two are different protocols and cannot talk directly, so something has to translate: CC Switch's Codex routing does exactly that locally. Add a Codex provider, set the base URL to `https://cocodot.co/api/ai/v1` (with /v1), choose Chat Completions as the upstream format, turn on the global routing switch and Codex routing, and restart the Codex session. If any of the three is missing, you get 'cannot connect' or odd behaviour.
5. Model names and context window: two settings people skip
Model name: use the name the endpoint actually serves, not one from memory. Both official names and gateway codes work on cocodot; the full list is on the pricing page and machine-readable at `GET https://cocodot.co/api/ai/models`. Context window: some tools decide when to compact a conversation from the window size you declare. Declare far less than the model supports and the tool compacts too early; declare more than it supports and you may hit the limit. Use the window given in the checklist rather than guessing.
6. Reading 'provider error': align three things, then check key and balance
Check in this order. One, base URL: no /v1 for Claude Code, /v1 for Codex. Two, model name: identical to the endpoint's list. Three, protocol and routing: Codex needs routing on and Chat Completions chosen. Then four, the key: valid and without stray spaces. Finally five, the balance: requests fail when it is empty. Change one thing at a time and restart the session before each test, or you cannot tell which change mattered. To rule CC Switch out, send the same request with curl; if that works, the endpoint is fine and the problem is local configuration.
7. Key safety: three rules not to break
First, paste the real key only into CC Switch on your own device. Never put it in a deep link, a URL or a shared configuration link, because URLs can end up in browser history, logs, clipboard history and analytics. Second, keep keys out of screenshots, chat logs and public repositories; blur them before asking for help. Third, if you suspect a leak, revoke the key in the dashboard and create a new one. That is the benefit of one key per project: a leak affects one project.
8. How to confirm the request really went through cocodot
Do not stop at 'the tool answered'. Confirm the request used your endpoint: send one minimal request, then open the cocodot dashboard and check that the usage log shows it and the balance dropped as expected. If nothing appears, the tool is not using your provider, most often because the session was not restarted or the official login is still active. Once confirmed, use it for real work. A built-in cocodot preset has been submitted to the upstream CC Switch project; until it is accepted and released, add the provider manually as described here.
Provider errors: symptom, likely cause, first move
| Symptom | Likely cause | First move |
|---|---|---|
| 401 / authentication failed | Wrong or expired key, or pasted in the wrong field | Re-copy the key and check for stray spaces or line breaks |
| 404 / path not found | Base URL has an extra or missing /v1 | Claude Code: no /v1. Codex: with /v1 |
| model not found | Model name differs from what the endpoint serves | Copy it exactly from the checklist or the model list |
| Codex cannot connect or misbehaves | Local routing is off or the upstream format is not Chat Completions | Enable the routing switch and Codex routing, restart the Codex session |
| Switch did not take effect | The tool is reading old config; session not restarted | Restart the Claude Code or Codex session after switching |
| 'not logged in' message | The tool is still using the official login instead of the custom provider | Confirm the provider is enabled, then restart the session |