How to Point Claude Code and Codex at a Custom API Endpoint with CC Switch
Hand-editing Claude Code's settings.json or Codex's config.toml every time you change API providers is easy to get wrong. CC Switch is an open-source desktop app that switches those tools between providers for you. This
Hand-editing Claude Code's settings.json or Codex's config.toml every time you change API providers is easy to get wrong. CC Switch is an open-source desktop app that switches those tools between providers for you.
This walkthrough follows the Chinese user manual and the project GitHub repo. The custom-provider fields use NiceAI as a worked example. Any other OpenAI- or Anthropic-compatible endpoint works the same way: change the base URL, the key, and the model ID.
At the time of writing (19 Nov 2026, Pacific Time), the latest release was v4.0.35. Install whatever version the website or GitHub Releases shows.
What CC Switch does
CC Switch can manage Claude Code, Claude Desktop, Codex, Gemini CLI, and a few other tools. The usual mode is direct: switching a provider rewrites that tool's own config file.
It also has routing and aggregation modes. Routing sends requests through a local CC Switch process (default 127.0.0.1:15721) so it can translate protocols or fail over. Aggregation puts models from more than one provider in one list. Clicking a tab only changes the view. To actually change the mode, use Start routing, Switch to aggregation, or Back to direct.
This article covers Claude Code and Codex only. The example endpoint documents OpenAI-compatible POST /v1/chat/completions and Anthropic-compatible POST /v1/messages. It does not document a native Gemini API, so Gemini CLI is omitted.
Install
Download only from ccswitch.io, GitHub Releases, or the project's own repository.
-
macOS (Homebrew):
brew install --cask cc-switch. Update withbrew upgrade --cask cc-switch. A signed and notarized Universal DMG is also available. -
Windows: install the MSI, or unzip the portable build and run
CC-Switch.exe. If the installer does nothing, unblock the file in its properties. If the app will not start, install Microsoft Edge WebView2 and allow the app in your antivirus. -
Linux: use the
.deb,.rpm, or.AppImagefor your architecture. Arch users can installcc-switch-binfrom the AUR. AppImage needschmod +x. If you are on Wayland with an NVIDIA GPU and the window will not accept clicks, tryCC_SWITCH_GDK_BACKEND=wayland.
System requirements: Windows 10+ (x64 / ARM64), macOS 12+ (Intel or Apple Silicon), Linux with glibc 2.35+ and WebKitGTK 4.1 (for example Ubuntu 22.04+ or Debian 12+). RHEL / Rocky / Alma 8β9 are not supported.
CC Switch does not need Node.js. It only manages tools that are already installed. If Claude Code or Codex is missing, install it from the official docs, or from the Apps page at the bottom of the CC Switch sidebar.
You are set up when the window opens, a tray icon appears, and the sidebar lists the tools it found.
Get a key and the two different base URLs
- Create an API key in the provider console. Do not put the key in a screenshot, a git repo, or a comment.
- Copy the exact model ID from the console. Do not type it by hand.
- Fill in a different base URL depending on the tool. Getting
/v1wrong is the most common way to get a 404.
| Tool | Base URL | Why |
|---|---|---|
| Claude Code | https://api.niceai.dev |
Claude Code appends /v1/messages itself. The provider docs also tell you not to add /v1 here. |
| Codex | https://api.niceai.dev/v1 |
CC Switch's Codex base_url examples already include /v1. This is the usual OpenAI-compatible form. |
Swap the host if you are using a different compatible service. The /v1 rule stays the same: Anthropic clients usually want the origin only; OpenAI-compatible clients usually want the origin plus /v1.
Add a custom provider
The example service is not in CC Switch's built-in list. Select the tool in the sidebar, click Add provider (+) on the right, and choose Custom (or Add with custom config if a search returns nothing).
Claude Code
- Name:
NiceAI(or any label you will recognize). - Endpoint:
https://api.niceai.dev. - Paste the API key.
- In advanced options, set Upstream format to Anthropic Messages (native). If the provider already speaks
/v1/messages, you can stay in direct mode and skip local routing. - Optional: set the website to
https://niceai.devso you can open the console later. - Click Add.
The important fields written into Claude Code look like this:
{
"env": {
"ANTHROPIC_API_KEY": "your-key",
"ANTHROPIC_BASE_URL": "https://api.niceai.dev"
}
}
The manual also allows ANTHROPIC_AUTH_TOKEN instead of ANTHROPIC_API_KEY. Prefer the form in the UI over editing JSON by hand.
Codex
- Name:
NiceAI. - Endpoint:
https://api.niceai.dev/v1. - Paste the API key, and paste the exact model ID from the console.
- In advanced options, set Upstream format to Chat Completions (requires routing) if the provider documents Chat Completions and does not document the OpenAI Responses API. After you choose that, you must start local routing and leave CC Switch running.
- Click Add. Open the Routing tab on the Codex page and click Start routing. Clicking the tab label alone does not change the mode.
If you later confirm that the upstream actually supports Responses, you can switch the format to Responses (native) and go back to direct mode. Check the provider docs or a console test first. Do not guess.
You can click Fetch models when editing the provider and use whatever the API returns. After you change Codex model mappings, restart Codex so its /model list refreshes.
Switch and verify
On the provider card, click Switch. The button should change to In use. You can also right-click the tray icon and pick the provider under that tool's submenu.
- Claude Code usually hot-reloads and picks up the change immediately.
-
Codex needs a full quit and relaunch (close the CLI and run
codexagain; fully quit the desktop app, then reopen it). In routing mode, later requests go to the new provider right away, but a model change may still need a restart.
The first time CC Switch starts, it imports your existing config as a provider named default and adds the official providers. Your old files are not discarded. To return to official login, switch to Claude Official or OpenAI Official, restart the client, and follow that tool's own sign-in flow.
Then send a short prompt:
claude
> Hello, introduce yourself in one sentence.
codex
> Hello, introduce yourself in one sentence.
A normal reply means the config works. Optionally compare the provider console's request log for the same window, and check the model name and status. Never paste a live key into the chat or a screenshot.
Troubleshooting
-
A 404, or
/v1added twice. Claude Code should behttps://api.niceai.dev. Codex should behttps://api.niceai.dev/v1. - Codex fails immediately. If the upstream only has Chat Completions, Responses (native) will not work. After you choose Chat Completions, click Start routing and keep CC Switch open. Leaving routing returns you to direct mode.
-
Leave "full URL" off unless you know you need it. The default treats the field as a prefix and appends the path. Standard
/v1/chat/completionsand/v1/messageshosts should keep this off. A full URL also has to go through local routing. -
Shell or system environment variables win. If
ANTHROPIC_API_KEY,ANTHROPIC_BASE_URL, orOPENAI_API_KEYis set in~/.zshrc,~/.bashrc, or Windows environment variables, those values usually override the config file. CC Switch shows a yellow banner when it notices this. The manual recommends letting CC Switch manage the config and keeping keys out of the shell. - It looks like the switch did nothing. The file is usually already updated; the running process may not have reloaded it. Restart the terminal or IDE for Claude Code if hot reload did not happen. Always restart Codex.
-
Claude Code asks you to log in on first launch. In Settings β App config, enable Skip Claude Code's first-run confirmation, then restart Claude Code. That writes
hasCompletedOnboarding: trueto~/.claude.json. -
Do not let Magpie and CC Switch edit the same agent at the same time. Both write Claude Code's
settings.jsonand Codex'sconfig.toml, and they can overwrite each other.
For the complete official steps, see the manual pages for adding a provider, switching providers, and environment variable conflicts.
The example endpoint in this article is niceai.dev
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.