CC Switch: Claude Code, Codex и 5 CLI в одном (2026)

Что вы получите за 30 секунд

Если CC Switch уже стоит и нужно решить конкретную проблему — не подхватывается конфиг, цикл OAuth-логина, несовпадение wire_api в Codex — переходите к разделу Типичные ошибки при установке ниже. Иначе следующие четыре раздела последовательно проведут через установку → первый провайдер → проверку → мульти-CLI.

Системные требования

CC Switch — десктопное приложение на Tauri 2, маленькое (~10 МБ установщик), но ему нужны графическая сессия и корректные рантаймы CLI под капотом. Проверьте каждую строку перед стартом — большинство жалоб «CC Switch не работает» сводится к отсутствию самого CLI, а не к приложению.

Ставить все CLI сразу не обязательно — CC Switch управляет только теми панелями, под которые на диске уже есть CLI. Начните с одного-двух, которыми пользуетесь чаще всего.

Шаг 1 — Установка CC Switch

Выбирайте нативный для платформы способ. На macOS не смешивайте Homebrew и ручную загрузку — автообновление работает только по одному каналу.

macOS (Homebrew)

brew install --cask cc-switch
# обновление позже:
brew upgrade --cask cc-switch

Cask подписан и нотаризован Apple — первый запуск проходит без диалога Gatekeeper.

macOS (вручную через .dmg)

# Скачайте свежий DMG со страницы Releases, затем:
open CC-Switch-v3.16.1-macOS.dmg
# Перетащите CC Switch.app в /Applications

Windows

Скачайте CC-Switch-v3.16.1-Windows.msi с github.com/farion1231/cc-switch/releases и запустите двойным кликом. Если машина блокирует установку MSI, доступен портативный CC-Switch-v3.16.1-Windows-Portable.zip.

Linux (Debian / Ubuntu)

# пример для x86_64
sudo dpkg -i CC-Switch-v3.16.1-Linux-x86_64.deb
# если apt ругается на зависимости:
sudo apt-get install -f

Linux (Arch)

paru -S cc-switch-bin   # или: yay -S cc-switch-bin

Linux (универсальный AppImage)

chmod +x CC-Switch-v3.16.1-Linux-x86_64.AppImage
./CC-Switch-v3.16.1-Linux-x86_64.AppImage

Headless-серверы / CI

Десктопу на Tauri 2 нужны Wayland или X11. Для безголовых машин — сборочных раннеров, удалённых песочниц — берите Rust-форк SaladDay/cc-switch-cli. Он читает тот же бандл конфигов, что синхронизируется по WebDAV, так что провайдеров можно завести на ноутбуке и подтянуть на агенте.

Проверка установки

После первого запуска:

1. Окно CC Switch открывается на панели Claude Code по умолчанию.
2. Иконка CC Switch появляется в системном трее (menu bar на macOS, system tray на Windows/Linux).
3. В переключателе приложений слева сверху перечислены семь управляемых целей — Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw, Hermes Agent. Серым отмечены CLI, которых CC Switch не нашёл на диске; это ожидаемо, если они ещё не установлены.

Если на Linux нет иконки в трее, ваше окружение, вероятно, не поддерживает StatusNotifierItem: установите gnome-shell-extension-appindicator (GNOME) или аналог и перезапустите сессию.

Шаг 2 — Установка CLI, которыми будете управлять

CC Switch не ставит сами CLI — он управляет их конфигами. Установите те, что нужны:

# Все семь, для справки. Берите только то, чем реально пользуетесь.
npm install -g @anthropic-ai/claude-code   # Claude Code (Node 18+)
npm install -g @openai/codex               # Codex (Node 16+)
npm install -g @google/gemini-cli          # Gemini CLI (Node 20+)
npm install -g opencode-ai                 # OpenCode (минимум по engines не задан)
npm install -g openclaw                    # OpenClaw (Node 22.19+)
npm install -g hermes-agent                # Hermes Agent (Node 20+)

Claude Desktop — отдельное приложение от Anthropic, его берут с claude.ai/download, а не из npm.

Если npm install -g падает с EACCES или новый shim не попадает в PATH, см. разбор исправления прав npm и PATH для Codex CLI — те же приёмы подходят для любого CLI из этого списка.

Шаг 3 — Добавление первого провайдера

Откройте CC Switch и нажмите + в правом верхнем углу. У панели добавления провайдера две вкладки:

• App-specific Provider — только для текущей панели
• Universal Provider — общий для Claude Code, Codex и Gemini CLI

Для первого раза берите App-specific:

1. В выпадающем списке Preset выберите провайдера, выдавшего ключ. CC Switch поставляет около 50 сторонних пресетов на всех панелях: DeepSeek, Zhipu GLM, MiniMax, Kimi, Bailian (Alibaba Qwen), AWS Bedrock, NVIDIA NIM, OpenRouter и длинный список релейных сервисов. Большинству нужен только API-ключ — endpoint и протокол заполнены заранее.
2. Вставьте свой API Key.
3. (Только Codex) Если у пресета есть пометка «Needs Local Routing» — это любой chat-completions backend, например DeepSeek или Zhipu — CC Switch сам включит переключатель Local Routing, который проксирует протокол Responses API в /v1/chat/completions провайдера. Не выключайте: Codex 0.137.0 убрал поддержку wire_api = "chat" при загрузке конфига и принимает только responses.
4. Нажмите Add.

Что именно пишет каждый пресет

Список пресетов — это слой удобства. Под ним CC Switch пишет в нативный конфиг CLI:

Принцип — «минимальное вмешательство»: даже если завтра удалить CC Switch, все CLI продолжат работать, потому что их нативные конфиги останутся целыми. Состояние CC Switch в ~/.cc-switch/cc-switch.db строго аддитивное.

Шаг 4 — Переключение и проверка

Когда хотя бы один провайдер заведён на каждой CLI-панели:

• Из приложения: кликните карточку провайдера и нажмите Enable.
• Из системного трея (по-настоящему полезная часть): правый клик по иконке CC Switch → выбор CLI-панели → клик по имени провайдера. Новый конфиг записывается до закрытия меню.

Затем активируйте на стороне CLI:

Быстрая проверка внутри сессии каждого CLI:

> Hello — which model am I talking to right now?

Разумное самоопределение модели подтверждает, что ключ валиден и роутинг корректный.

Типичные ошибки при установке и их исправление

Если CLI ругается на собственный конфиг — model_not_found, EACCES, 429, 503 — это проблема CLI, а не CC Switch. Для Codex отдельно сценарий command not found сразу после установки разобран в Codex command not found: 7 исправлений после npm install -g. У каждого CLI свой runbook по рантайм-ошибкам; CC Switch управляет только файлом конфига, не путём запроса.

Командные конфигурации и несколько разработчиков

Настоящая боль, которую решает CC Switch, — это команды, где сторонние ключи делятся между несколькими агентами, а не одиночка с одним CLI. Хорошо масштабируются три паттерна.

Паттерн 1 — Universal Provider для общего relay-ключа

Если команда использует один OpenAI-совместимый relay (один base URL, один общий ключ) для Claude Code, Codex и Gemini CLI, нужная вкладка — Universal Provider. Добавляете один раз endpoint и ключ relay, отмечаете три приложения для синхронизации — и CC Switch пишет один и тот же ключ в нативный конфиг каждого CLI. Когда relay ротирует ключ, достаточно обновить одну запись и нажать Save and Sync — все CLI на всех ноутбуках подхватят его при следующем переключении.

Паттерн 2 — Бандл конфигов по WebDAV для ноутбука + CI

Поднимите WebDAV-сервер (Nextcloud, self-hosted, что угодно из уже имеющегося у команды) и укажите Settings → Storage → custom config directory на него. Авторы заводят провайдеров на ноутбуках; CI-раннеры на SaladDay/cc-switch-cli подтягивают тот же SQLite-снимок. Не синхронизируйте ~/.cc-switch/cc-switch.db через обычный Dropbox или iCloud — они спокойно перезапишут базу прямо во время записи, если два устройства пушнут одновременно. Для файла базы безопаснее WebDAV с корректным локингом.

Паттерн 3 — Локальный override для дежурного инженера

Если одному инженеру нужно протестировать другого провайдера, не задевая остальную команду, помогает device-level ~/.cc-switch/settings.json с переопределениями claudeConfigDir, codexConfigDir и т. п., указывающими CC Switch на отдельный каталог конфигов. Командный WebDAV-бандл остаётся нетронутым; override испаряется, как только настройку откатить.

Во всех трёх случаях относитесь к ~/.cc-switch/cc-switch.db как к ~/.ssh/ — он не шифрован на диске, поэтому защита файла — это права файловой системы плюс транспорт, которым его синхронизируют.

Продвинутое — MCP, Skills, Prompts и OAuth-переиспользование

Когда переключение провайдеров решено, единые панели — это то, ради чего CC Switch начинает оправдываться.

Единый MCP по пяти CLI

Откройте кнопку MCP на любой панели. CC Switch читает список MCP-серверов из нативного места каждого CLI — ~/.claude.json для Claude Code, блоки [mcp_servers.*] в ~/.codex/config.toml, mcpServers в ~/.gemini/settings.json, аналоги в OpenCode и Hermes — и даёт включать каждый сервер отдельно по CLI. Добавили mcp-fetch один раз, синхронизировали на Claude Code + Codex + Gemini — и у каждого агента одинаковая поверхность инструментов.

Промпты (CLAUDE.md / AGENTS.md / GEMINI.md)

Панель Prompts — это Markdown-редактор с кросс-аппной синхронизацией. Правите один промпт в CC Switch, синхронизируете в ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md и ~/.gemini/GEMINI.md одним кликом. Защита от затирания подхватывает правки, сделанные напрямую в живых файлах, до того как следующая синхронизация их перепишет — полезно, если коллега правил CLAUDE.md руками.

Skills

Панель Skills ставит скиллы из GitHub-репозиториев или ZIP-архивов в каталог скиллов каждого CLI (~/.claude/skills/, ~/.config/opencode/skills/ и т. д.). По умолчанию используется режим симлинков — одна каноническая копия лежит в ~/.cc-switch/skills/, а CLI видят её через симлинк. Переключайтесь на режим копирования файлов, если CLI запущен в песочнице, которая не идёт по симлинкам.

Codex OAuth reverse-proxy (с v3.13)

CC Switch добавил способ переиспользовать Codex-привилегии аккаунта ChatGPT внутри Claude Code. Появляется как новый тип карточки Claude-провайдера — не как пресет Codex — и заворачивает запросы Claude Code через локальный прокси, прикидывающийся chatgpt.com и auth.openai.com. Полезно, если уже оплачен ChatGPT Plus или Pro. Перед использованием в продакшене прочитайте предупреждение внутри приложения: способ неофициальный и может сломаться в тот день, когда OpenAI закрутит авторизацию.

Альтернативы — когда десктоп не вариант

Два пути покрывают случаи, когда десктоп на Tauri не подходит.

• Единый OpenAI-совместимый gateway — если нужен один base URL, на который смотрят Claude Code, Codex, Cursor, Cline и OpenClaw, OfoxAI отдаёт https://api.ofox.ai/v1 как единый OpenAI-совместимый endpoint. К нему обращаются команды, которые хотят полностью уйти от редактирования конфигов каждого CLI; см. гайд по интеграции с Claude Code для настройки в одну строку. Можно оставить CC Switch ради переключений из трея и держать ofox как нижележащего провайдера — или отказаться от CC Switch вовсе, если хватает одного endpoint.
• Headless / скриптовые окружения — SaladDay/cc-switch-cli — Rust-форк CLI, который умеет переключение провайдеров, управление MCP, установку скиллов и локальный прокси из терминала. Формат хранения совместим с WebDAV, как у десктопа. Лучший вариант для сборочных агентов, удалённых dev-контейнеров и серверов «только tmux».
• Браузерный UI — Laliet/cc-switch-web — браузерная альтернатива от сообщества, покрывает Claude Code, Codex и Gemini CLI. По функциональности пока уступает десктопу, но удобна, если нужна общая ссылка, которую открывает вся команда.

Как следить за обновлениями и держать актуальную версию

• Автообновление — Settings → About → Check for updates. Десктоп автоматически проверяет при запуске.
• Лента релизов — подпишитесь на github.com/farion1231/cc-switch/releases. Свежие изменения, за которыми стоит следить: Claude Desktop как панель первого класса, Codex OAuth reverse-proxy (v3.13), унифицированная установка Skills из GitHub (добавлена до v3.16), дашборды использования по приложениям.
• Гигиена бэкапов — в ~/.cc-switch/backups/ автоматически хранятся 10 последних SQLite-снимков. Перед мажорным апгрейдом сделайте cp ~/.cc-switch/cc-switch.db ~/.cc-switch/cc-switch.db.bak.$(date +%F) — ручной снимок переживёт скользящее окно.

FAQ

Блок faq во frontmatter выше содержит канонические ответы; вопросы там зеркалят кластер People Also Ask по cc switch claude code install, ccswitch install npm и смежным запросам. Пробегитесь по ним — там покрыт состав поддерживаемых CLI, поведение при перезапуске терминала, ландшафт форков, сосуществование с официальными аккаунтами, режим OAuth reverse-proxy для Codex, хранение ключей, поддержка headless и сравнение с ручным редактированием.

Источники

• README farion1231/cc-switch
• User Manual CC Switch — installation guide
• FAQ CC Switch — 5.1 Configuration Files
• npm registry — npm view <pkg> version engines для @anthropic-ai/claude-code@2.1.163
• SaladDay/cc-switch-cli
• openai/codex, источник model-provider-info