cc-switch — Agent Guide

No conflict-matrix pairs for this tool yet.

# CC Switch — Agent Guide

name: cc-switch ｜ version_range: 3.20.1~3.20.1｜ generated: 2026-08-28

title_en: CC Switch - Cross-Platform All-in-One Session/Provider Switcher ｜ desc_en: Switch sessions and providers across Claude Code, Codex, Gemini and OpenCode from one UI.

Preflight

note: Linux x86_64 desktop; requires libwebkit2gtk-4.1.

ldconfig -p | grep webkit2gtk-4.1 | head -1

预期输出: see command output

Install

note: Official release assets; GitHub direct download slow in mainland China, gh-proxy acceleration recommended. Desktop GUI not tested in this environment.

Method A: deb (Debian/Ubuntu)

curl -sL -o cc-switch.deb https://gh-proxy.com/https://github.com/farion1231/cc-switch/releases/download/v3.20.1/CC-Switch-v3.20.1-Linux-x86_64.deb
sudo dpkg -i cc-switch.deb
cc-switch --version

预期输出: version number (GUI launch requires desktop environment)

Method B: AppImage (no install)

curl -sL -o cc-switch.AppImage https://gh-proxy.com/https://github.com/farion1231/cc-switch/releases/download/v3.20.1/CC-Switch-v3.20.1-Linux-x86_64.AppImage
chmod +x cc-switch.AppImage && ./cc-switch.AppImage

预期输出: application window (desktop environment)

Operations

Switch Claude Code provider

note: GUI operation; rewrites provider config in ~/.claude.json.

# GUI：配置面板选择目标供应商/模型 → 应用

预期输出: ~/.claude.json provider config rewritten (switch takes effect)

Manage Codex config

note: GUI operation; manages ~/.codex/config.toml.

# GUI：Codex 面板添加供应商（OpenAI OAuth 或第三方）

预期输出: ~/.codex/config.toml managed (OAuth token expiry prompts re-login)

View session usage

note: GUI operation; stats persisted in SQLite.

# GUI：用量面板

预期输出: session stats per agent (Claude/Codex/Gemini/OpenCode etc.) (SQLite persistence)

Uninstall

note: dpkg uninstall; shared configs ~/.claude.json and ~/.codex/config.toml are NOT restored by uninstall, backup first.

sudo dpkg -r cc-switch 2>/dev/null || true
rm -rf ~/.cc-switch
command -v cc-switch >/dev/null 2>&1 && echo '残留: cc-switch 仍存在' || echo 'cc-switch removed: OK'

预期输出: cc-switch removed: OK

Facts

writes: ~/.claude.json, ~/.codex/config.toml, ~/.cc-switch (shared config, backup recommended) ｜ runtime: Linux x86_64 desktop, libwebkit2gtk-4.1 ｜ notes: GUI not tested in this environment; no background process

Source: cc-switch · validated 2026-08-31 · v3.20.1~3.20.1

← Agent index