cc-switch (CC Switch) Installation Guide — Linux Desktop

Goal of this guide: install cc-switch (a GUI manager for switching API configurations across multiple tools) on a Linux desktop environment, then use it to configure Claude Code, Codex, and other tools to connect to MYAI168.

cc-switch is a GUI app (built with Tauri 2) and requires a desktop environment (Wayland or X11). It cannot run on a command-line-only server (headless, no desktop) — in that case use each tool's "manual config file" method instead, or the community cc-switch-cli project.

Before You Start

• A Linux machine with a desktop environment (e.g. Ubuntu desktop), with Wayland or X11.
• Choose the package format for your distro (see "1. Install").
• Download source: the official cc-switch GitHub Releases https://github.com/farion1231/cc-switch/releases (official site: ccswitch.io)
• Package file names look like CC-Switch-v{version}-Linux-x86_64.deb / .rpm / .AppImage.

Download the matching file from the Releases page, then follow your system:

[Ubuntu / Debian / Linux Mint / Pop!_OS] use .deb

Download CC-Switch-*-Linux*.deb and open a terminal in the folder holding the file:

sudo dpkg -i CC-Switch-*.deb
sudo apt-get install -f        # auto-installs missing dependencies, if any

(Or resolve dependencies in one line: sudo apt install ./CC-Switch-*.deb)

★ Common: missing libwebkit2gtk dependency ★

Ubuntu desktop often does NOT ship the graphics library cc-switch needs, so the first dpkg -i shows:

cc-switch depends on libwebkit2gtk-4.1-0; however:
  Package libwebkit2gtk-4.1-0 is not installed.
dpkg: error processing package cc-switch ...

This is normal, not broken. Run the following line — it auto-installs libwebkit2gtk and the other dependencies, and finishes configuring cc-switch:

sudo apt-get install -f       # answer Y at the Y/n prompt

If that still does not resolve everything (package names vary across Ubuntu versions), install manually and retry:

sudo apt-get update
sudo apt-get install -y libwebkit2gtk-4.1-0
sudo dpkg -i CC-Switch-*.deb

When done, check: which cc-switch should print /usr/bin/cc-switch

[Fedora / RHEL / CentOS / Rocky Linux] use .rpm

sudo rpm -i CC-Switch-*.rpm
# or: sudo dnf install ./CC-Switch-*.rpm

[openSUSE] use .rpm

sudo zypper install ./CC-Switch-*.rpm

[Arch Linux / Manjaro] use AUR (recommended) or AppImage

paru -S cc-switch-bin
# or: yay -S cc-switch-bin

[Other distros / not sure] use .AppImage (universal, no install)

Download CC-Switch-*-Linux*.AppImage and, in the folder holding the file:

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

(An AppImage is a portable file — double-click it or run the commands above; it is not written into the system package database.)

Open "CC Switch" from the application menu, or start it with the AppImage command above.

After launch:

• The window opens on the "Claude Code" panel by default.
• A CC Switch icon appears in the system tray.
• The switcher at the top left of the window lists the manageable tools: Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw, Hermes Agent.

Suggested settings (optional): go to Settings → General → Window Behavior and enable start-on-boot, minimize-to-tray, etc. as needed.

cc-switch is only a "configuration manager" — it does not include the AI tools themselves. Install Claude Code / Codex and the other CLIs first, then use cc-switch to configure them to connect to MYAI168.

For installing each tool and setting up MYAI168, see the corresponding Developer Center pages:

• Claude Code → see the "Claude Code CLI Linux" page
• Codex → see the "Codex CLI Linux" page
• Hermes → see the "Hermes Agent Linux" page (note: cc-switch writes for Hermes may silently fail; manual setup is recommended for Hermes)

Common Settings (when adding a provider on each tool tab in cc-switch)

• Claude Code → endpoint https://www.myai168.com/en/api/anthropic (without /v1), model claude-opus-4-8, key supplied via either apiKeyHelper or ANTHROPIC_API_KEY (see the Claude Code page).
• Codex → endpoint https://www.myai168.com/en/api/openai/v1, model gpt-5.6-sol.

• Double-clicking the .AppImage does nothing → chmod +x it first; some systems also need FUSE (Ubuntu: sudo apt-get install libfuse2).
• .deb install reports dependency errors → run sudo apt-get install -f to auto-install the missing dependencies.
• The window will not open / no display → make sure you are on a desktop environment (Wayland or X11). A command-line-only server cannot run GUI apps; use each tool's manual config file method instead.
• Update cc-switch → .deb / .rpm: download and install the new package (over the old version). AUR: paru -S cc-switch-bin (rerun to update). AppImage: download the new AppImage and replace the old file.
• Back up the settings → cc-switch settings live in ~/.cc-switch/; before a major upgrade you can manually back up ~/.cc-switch/cc-switch.db.

Official

• https://github.com/farion1231/cc-switch
• https://github.com/farion1231/cc-switch/releases