How to Use CC-Switch with Omniside: Manage All AI Coding Tools with One API Key

CC-Switch is a cross-platform desktop app that manages provider configurations for Claude Code, Codex, OpenCode, and Gemini CLI — all from a single GUI. No more manually editing JSON and TOML files; just add a provider, click switch, and all your coding tools are reconfigured instantly.

The problem? Each AI coding tool needs its own provider config, and if you use multiple LLM providers, managing keys across four different tools gets messy fast.

With Omniside as your unified API gateway, you add one provider in CC-Switch and every tool — Claude Code, Codex, OpenCode, Gemini CLI — routes through the same endpoint with the same API key.

This guide covers installation and configuration on macOS, Windows, and Linux (Ubuntu, Debian, CentOS).

What CC-Switch Does

CC-Switch sits in your system tray and manages the config files for your AI coding tools:

• Claude Code → writes to ~/.claude.json (API key + base URL)
• Codex → writes to ~/.codex/config.toml (model provider + API key)
• OpenCode → writes to ~/.config/opencode/opencode.json (provider config)
• Gemini CLI → writes to ~/.gemini/.env (API key + base URL)

When you switch providers in CC-Switch, it rewrites these config files automatically. No manual editing required.

Prerequisites

1. At least one AI coding tool installed — Claude Code, Codex, OpenCode, or Gemini CLI
2. An Omniside API Key — sign up here

Step 1: Install CC-Switch

macOS

1. Download the latest .dmg or .zip from the GitHub Releases
2. Drag CC-Switch.app into your Applications folder
3. On first launch, macOS may show a Gatekeeper warning — go to System Settings → Privacy & Security → Open Anyway

Or install via Homebrew (if available):

brew install --cask cc-switch

Windows

Option A: MSI Installer (recommended)

1. Download the .msi file from GitHub Releases
2. Double-click to install
3. Launch from the Start menu

Option B: Portable

1. Download the .zip portable version
2. Extract and run CC-Switch.exe directly — no installation needed

Ubuntu / Debian

Download the .deb package from GitHub Releases:

# Download the latest .deb (check releases for exact URL)
wget https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch_amd64.deb

# Install
sudo dpkg -i cc-switch_amd64.deb

# Fix dependencies if needed
sudo apt-get install -f

CentOS / RHEL / Fedora

Download the .rpm package:

# Download the latest .rpm
wget https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch_x86_64.rpm

# Install
sudo rpm -i cc-switch_x86_64.rpm
# or on Fedora:
sudo dnf install cc-switch_x86_64.rpm

Arch Linux

An AppImage is also available on the releases page — download and run directly:

chmod +x CC-Switch-*.AppImage
./CC-Switch-*.AppImage

Linux ARM64

ARM64 builds are available since v3.10.3. Download the arm64.deb or arm64.AppImage from the releases page.

Step 2: Get Your Omniside API Key

1. Go to platform.omniside.ai
2. Sign up or log in
3. Navigate to API Keys
4. Click Create API Key
5. Copy the key (starts with sk-)

Step 3: Add Omniside as a Provider

After launching CC-Switch, you’ll see a top navigation bar with tabs for each coding tool (Claude Code, Codex, OpenCode, Gemini).

For Claude Code

1. Select the Claude Code tab
2. Click Add Provider
3. Fill in the following:

4. Click Save

Important: Since Omniside is an OpenAI-compatible API, select “OpenAI Chat Completions” as the API Format. CC-Switch v3.10.3+ supports this format selector for Claude providers. When switching to an OpenAI Chat format provider, CC-Switch will remind you to enable its built-in proxy.

For Codex

1. Select the Codex tab
2. Click Add Provider
3. Fill in:

4. Click Save

CC-Switch writes this to ~/.codex/config.toml as a custom model_providers entry.

For OpenCode

1. Select the OpenCode tab
2. Click Add Provider
3. Fill in:

4. Click Save

CC-Switch generates the opencode.json config with the @ai-sdk/openai-compatible npm adapter automatically.

For Gemini CLI

1. Select the Gemini tab
2. Click Add Provider
3. Fill in:

4. Click Save

CC-Switch writes the key and base URL to ~/.gemini/.env.

Universal Provider (Recommended)

CC-Switch supports Universal Provider mode — configure Omniside once, and it syncs across all four tools automatically:

1. When adding the provider, enable “Cross-app sharing (Universal Provider)”
2. The same Omniside configuration will be applied to Claude Code, Codex, OpenCode, and Gemini CLI simultaneously

This is the fastest way to set up everything.

Step 4: Switch to Omniside

In the provider list, click the toggle button next to “Omniside” to activate it. CC-Switch rewrites the config files for the selected tool immediately.

You can verify by running a health check — CC-Switch has a built-in speed test that measures API latency. Click the speed test icon next to your provider to confirm connectivity.

Step 5: Configure Model Mapping (Claude Code)

For Claude Code specifically, CC-Switch lets you map Claude Code’s three speed tiers to Omniside models:

This way, when Claude Code picks a tier based on task complexity, it routes to the most cost-effective Omniside model.

Using CC-Switch’s Built-in Proxy

CC-Switch includes a local proxy server that provides advanced features:

• Automatic failover — if Omniside is temporarily unreachable, CC-Switch can fall back to a backup provider
• Request logging — see all API calls, token usage, and costs in real time
• Thinking signature fixer (Claude Rectifier) — fixes compatibility issues with third-party APIs when using Claude models

To enable the proxy: go to Settings → Proxy and toggle it on. When using OpenAI Chat format providers like Omniside, CC-Switch will remind you to enable this.

Platform-Specific Notes

macOS

CC-Switch runs as a menu bar app. If you don’t see the icon, check System Settings → Login Items to ensure it’s allowed to run.

Windows

CC-Switch supports three terminal options for launching coding tools: cmd, PowerShell, and Windows Terminal. Set your preference in Settings → Preferred Terminal.

Config paths on Windows:

• CC-Switch data: %USERPROFILE%\.cc-switch\
• Claude Code config: %USERPROFILE%\.claude.json
• Codex config: %USERPROFILE%\.codex\config.toml
• OpenCode config: %USERPROFILE%\.config\opencode\opencode.json

Linux

On Wayland (GNOME/Sway), CC-Switch disables modal backdrop blur to avoid freezes. If you experience UI issues, try running with --disable-gpu flag.

CC-Switch stores its data at ~/.cc-switch/:

• cc-switch.db — SQLite database (providers, MCP servers, prompts, skills)
• settings.json — device-level settings
• backups/ — auto-rotating backups (keeps 10 most recent)

CentOS / RHEL

If the .rpm package has dependency issues, try the AppImage instead — it bundles all dependencies.

Import / Export & Cloud Sync

CC-Switch supports backup and restore of all configurations:

• Export: Settings → Export → saves a .sql backup file
• Import: Settings → Import → restores from a CC-Switch backup

For cloud sync across machines:

1. Go to Settings → Custom Configuration Directory
2. Point it to a cloud sync folder (Dropbox, OneDrive, iCloud Drive)
3. Restart the app

All your Omniside provider configs will sync across devices automatically.

Troubleshooting

Provider switch doesn’t take effect

Make sure you’ve clicked the toggle to activate the provider (not just saved it). After switching, try restarting your coding tool’s session.

404 errors with Codex

The base URL for Codex should be https://api.omniside.ai/v1. CC-Switch v3.10.3 fixed a bug where /v1 was being duplicated. Make sure you’re on the latest version.

Health check fails

Run the speed test in CC-Switch. If it fails:

1. Check your API key is correct
2. Verify network connectivity: curl https://api.omniside.ai/v1/models -H "Authorization: Bearer sk-your-key"
3. If behind a proxy, configure it in Settings → Global Proxy

Claude Code shows authentication errors

If using OpenAI Chat Completions format, make sure CC-Switch’s built-in proxy is enabled. Claude Code natively speaks the Anthropic protocol — the proxy translates between formats.

Why CC-Switch + Omniside?

Without CC-Switch, switching providers means editing JSON and TOML files across four different tools — and getting the syntax right each time. Without Omniside, you need separate API keys for each LLM provider.

Together, they give you a single GUI where you configure one provider (Omniside), switch it on with one click, and all four coding tools — Claude Code, Codex, OpenCode, and Gemini CLI — are instantly configured with access to every major AI model.

Get your API key at platform.omniside.ai and start coding.