CC Switch

어떤 사용자에게 필요한가

CC Switch는 여러 AI 개발 도구나 API 공급자를 번갈아 쓰는 개발자를 위한 설정 관리 앱입니다. Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi, MiniMax Code를 관리합니다. 실제 코드 작성과 모델 응답은 연결한 도구와 공급자가 수행합니다.

JSON·TOML·YAML 설정을 반복해서 고치거나 도구마다 MCP와 Skills를 따로 등록하는 작업을 줄이는 데 적합합니다. 지원 기능은 도구마다 다르므로, 특정 도구가 목록에 있다는 이유만으로 모든 기능을 사용할 수 있다고 해석하면 안 됩니다.

지원 OS와 현재 버전

2026년 10월 9일 확인한 공식 배포 페이지의 최신 정식 버전은 4.0.5입니다. 제공된 macOS 분류 외에 Windows와 Linux도 공식 지원합니다. macOS는 12 Monterey 이상이며 Intel과 Apple Silicon에서 실행되는 Universal 빌드를 제공합니다.

Windows는 10 이상, Linux는 glibc 2.35 이상과 WebKitGTK 4.1이 필요합니다. 지원 종료 검토 결과, 최근 정식 배포와 문서 갱신이 확인되어 오래된 지원 종료 프로그램으로 분류할 근거는 없습니다.

macOS 설치와 첫 설정

공식 설치 안내는 Homebrew의 brew install --cask cc-switch 또는 GitHub Releases의 macOS DMG를 제시합니다. 수동 설치는 DMG를 열어 CC Switch.app을 Applications 폴더로 옮기는 순서입니다. 공식 문서는 macOS 배포본이 서명·공증되었다고 안내합니다. CC Switch 자체에는 Node.js가 필요하지 않지만, 관리할 개발 도구는 별도로 준비해야 합니다.

첫 작업은 사이드바에서 도구 선택 → 공급자 추가 → 프리셋 또는 Custom 선택 → API 키와 모델 확인 → 추가 → Switch 순서입니다. 직접 연결로 시작하고 해당 도구의 재시작 요구를 따릅니다. 마지막으로 짧은 질문을 보내 연결을 확인하는 방식이 공식 빠른 시작 안내에 제시되어 있습니다.

연결 방식과 실무 예시

직접 연결은 개발 도구가 공급자에 바로 접속합니다. 라우팅은 요청을 내 컴퓨터의 CC Switch로 보내 API 형식을 변환하고 예비 공급자로 전환할 수 있게 합니다. 집계는 Claude Code와 Codex에서 여러 공급자의 모델을 하나의 /model 목록으로 보여 줍니다. 집계 모드에는 장애 자동 전환이 없습니다.

예를 들어 같은 코드 검토 세션에서 공급자 A의 모델로 수정안을 만들고 공급자 B의 모델로 다시 검토하려면 집계에 두 공급자와 모델을 등록해 /model에서 선택할 수 있습니다. 집계와 라우팅은 CC Switch가 실행 중이어야 하며, 모델 변경 뒤 첫 요청은 프롬프트 캐시를 새로 만들면서 비용이 늘 수 있습니다.

무료 범위와 별도 비용

공식 배포 안내는 CC Switch를 완전히 무료인 오픈소스 앱으로 명시하며, 저장소 라이선스는 MIT입니다. 확인한 자료에는 별도 유료판이나 기능을 잠그는 무료판 구분이 제시되어 있지 않습니다.

앱이 무료여도 연결한 모델 API와 구독의 이용료·한도는 별개입니다. 사용량 화면의 비용은 추정값으로 이해하고 실제 청구 조건은 공급자에서 확인해야 합니다. 4.0.5는 Codex의 GitHub Copilot 계정 연결을 추가했지만, 이 연결에는 Codex 라우팅 활성화가 필요하며 계정 등급에 따라 모델 조건이 달라집니다.

문제가 생겼을 때 확인 순서

전환이 반영되지 않으면 먼저 현재 공급자와 연결 모드를 확인하고 도구를 재시작합니다. 특히 Codex 집계 모델 목록은 완전한 재시작이 필요합니다. macOS 데스크톱 앱은 창만 닫지 말고 ⌘Q로 종료해야 하며, CLI는 공유 데몬 재시작이 필요할 수 있습니다. 데몬 재시작은 진행 중인 작업을 중단하므로 작업 상태부터 확인합니다.

인증 오류는 키의 공백·만료 여부와 API 주소 순서로 점검합니다. Connectivity check는 주소 도달 여부를 확인하며 키 유효성을 검증하지 않습니다. 404·405 오류는 공급자의 API 형식과 라우팅 활성화 여부를 확인합니다. 로컬 라우팅 시작 실패는 기본 포트 15721의 점유 여부부터 살펴봅니다.

다른 방식과 선택 기준

도구 하나에서 공식 계정만 사용한다면 해당 도구의 기본 로그인과 설정으로 충분할 수 있습니다. 공급자 전환이 드물고 설정 파일에 익숙하다면 직접 편집도 선택지입니다. 여러 도구의 연결 설정과 확장 구성을 반복해서 관리할 때 CC Switch의 활용 가치가 커집니다.

선택 기준은 관리할 도구의 기능 지원 범위, API 형식 변환 필요성, 장애 자동 전환 필요성입니다. 모델을 한 목록에서 고르는 목적에는 집계, 장애 대응에는 라우팅을 검토합니다. 이 원고는 공식 자료를 확인해 작성했으며 설치·실사용 결과를 뜻하지 않습니다.

공식 안내

• CC Switch 官方网站 - AI 编程工具统一管理平台 · 확인 2026-10-09
• CC Switch — 공식 저장소 README · 확인 2026-10-09
• Release CC Switch v4.0.5 · 확인 2026-10-09
• 1.1 Introduction · 확인 2026-10-09
• 1.2 Installation Guide · 확인 2026-10-09
• 1.4 Quick Start · 확인 2026-10-09
• 4.6 Aggregation Mode · 확인 2026-10-09
• 5.2 Frequently Asked Questions · 확인 2026-10-09
• Release CC Switch v3.20.4 — 공식 채널 및 무료·오픈소스 안내 · 확인 2026-10-09