CC-Switch 기본 사용 가이드
CC Switch는 오픈소스 AI 프로그래밍 CLI 통합 관리 도구입니다. 주로 한 가지 문제를 해결합니다. Claude Code, Codex, Gemini CLI, OpenCode 등의 도구를 동시에 사용할 때 도구마다 Key, Base URL, 모델명, MCP 설정을 일일이 변경해야 하는 번거로움을 덜어줍니다.
공식 정보 다운로드 및 문서는 공식 사이트를 기준으로 합니다.
이 도구의 역할 및 용도
이미 여러 개의 커맨드라인 AI 프로그래밍 도구를 설치해 사용하는 사용자에게 적합합니다. 단일 채팅 프로그램만 사용하는 일반 초보자는 CC Switch를 먼저 배울 필요가 없으며, Claude Code, Codex CLI, Gemini CLI 등을 동시에 사용하기 시작할 때 Provider를 통합 관리하는 용도로 고려해 보세요.
어떤 상황에 적합한가요?
여러 CLI에서 Provider 공유동일한 AI 제공업체 또는 공식 API를 Claude Code, Codex, Gemini CLI에서 동시에 사용해야 할 때.
빈번한 Provider 전환예: 낮에는 공식 계정을 사용하고 테스트 시에는 AI 제공업체로 전환하거나, 프로젝트별로 서로 다른 모델을 전환해 사용할 때.
MCP / Skills 통합 관리CC Switch 공식 문서에는 도구 간 MCP 및 Skills 관리 기능도 포함되어 있습니다. 초보자는 먼저 Provider 전환 방법부터 익히는 것을 권장합니다.
다운로드, 설치 및 최초 실행
먼저 메인 인터페이스 확인하기 설치 후 먼저 메인 프로그램을 열고 좌측에 Provider, MCP, Skills 등의 메뉴 항목이 보이는지 확인하세요. 초보자는 먼저 Provider 설정만 다루고, MCP나 프롬프트를 동시에 변경하지 않는 것이 좋습니다.
- CC Switch 공식 웹사이트 또는 GitHub Releases에서 현재 버전을 다운로드합니다.
- Windows 사용자는 시스템에 맞는 설치 패키지를 선택하고, macOS / Linux 사용자는 공식 설치 안내를 따릅니다.
- 설치 후 먼저 메인 프로그램을 열어 인터페이스가 정상적으로 로드되는지 확인합니다.
- 시스템에서 실행을 차단하는 경우, 먼저 출처가 공식 저장소 또는 공식 웹사이트인지 확인한 다음 시스템 안내에 따라 허용합니다.
Provider 추가하기
Provider 추가 참고 여기에서 새 Provider를 추가하기 위한 진입 메뉴와 필드 위치를 먼저 확인하세요. 타깃 CLI에 따라 버전별 필드에 세부적인 차이가 있을 수 있습니다.
- 먼저 Claude Code, Codex CLI, Gemini CLI가 개별적으로 정상 실행되는지 확인합니다. CC Switch는 관리 도구일 뿐, 모든 CLI를 대신 설치해 주지는 않습니다.
- CC Switch 공식 저장소나 공식 웹사이트에서 설치 패키지를 다운로드하세요. 출처가 불분명한 클라우드 드라이브에서 다운로드하지 마세요.
- CC Switch를 열고 Provider 관리 페이지로 이동합니다.
- 새 Provider를 추가하고 제공업체 이름을 본떠 '특정 AI 제공업체' 등으로 이름을 지정합니다.
- 제공업체 백엔드에서 제공한 Base URL, API Key, 모델명을 입력합니다. 타깃 도구에 따라 필드가 다를 수 있으므로 현재 CC Switch 화면의 안내에 맞게 입력하세요.
- 저장한 후 적용할 타깃 도구(예: Claude Code, Codex, Gemini CLI)를 선택합니다.
- Switch / Apply를 실행한 후 안내에 따라 해당 터미널 또는 CLI를 재시작합니다. 공식 문서에 따르면 대부분의 도구는 전환 후 재시작이 필요하지만, Claude Code는 현재 핫 스위칭을 지원합니다.
| 설정 항목 | 입력 방법 | 초보자 주의 사항 |
|---|---|---|
| Provider Name | 제공업체 이름 또는 용도 입력 | 예: '메인 AI 제공업체', '예비 공식 Key' 등으로 작성하고 1, 2, 3처럼 단순하게 적지 마세요 |
| Base URL | 제공업체 백엔드의 API 링크 복사 | 백엔드 예시에 따라 /v1 포함 여부를 결정하세요 |
| API Key | 전체 Key 복사 | 스크린샷으로 외부에 공개하지 말고, 메모 이름을 Key로 사용하지 마세요 |
| Model Name | 모델 목록 복사 | Claude Code, Codex, Gemini CLI마다 요구하는 모델명이 다를 수 있습니다 |
| Target Tool | 동기화할 CLI 선택 | 모든 제공업체가 모든 도구와 호환되는 것은 아닙니다. 실패할 경우 먼저 도구 하나만 선택해 테스트해 보세요. |
타깃 CLI별 개별 검증
| 타깃 도구 | 우선 확인 사항 | 상세 페이지 |
|---|---|---|
| Claude Code | Claude / Anthropic 인터페이스 주소, Key, Claude 모델명 | CC-Switch Claude Code |
| Codex CLI | OpenAI / Codex 호환 주소, Key, 사용 가능한 Codex 모델명 | CC-Switch Codex |
| Gemini CLI | Google / Gemini 또는 Vertex 관련 인증 방식 | CC-Switch Gemini |
| CC-Switch-CLI | GUI(그래픽 인터페이스)가 없을 때의 커맨드라인 설정 방법 | CC-Switch-CLI 사용법 |
CC Switch는 통합 관리 도구일 뿐이며, 하나의 Provider가 모든 CLI에 무조건 호환되는 것은 아닙니다. Claude, Codex, Gemini는 인터페이스 프로토콜이 서로 다르므로, 문제가 발생하면 먼저 타깃 도구를 하나만 선택해 테스트해 보세요.
전환 후 테스트 방법
전환 후 바로 실제 프로젝트 작업에 들어가지 마세요. 빈 디렉터리나 테스트 프로젝트에서 가장 짧은 질문을 전송하여 요청이 선택한 제공업체로 정상 전달되는지 먼저 확인하세요.
전환 후 최소 테스트 명령어
claude "Please reply only: Configuration successful" codex "Please reply only: Configuration successful" gemini "Please reply only: Configuration successful"특정 CLI에서 여전히 이전 설정을 사용하고 있다면, 현재 터미널 창을 닫고 다시 열어 재시도하세요. 설정 파일을 직접 수정하는 작업과 CC Switch를 통한 수정을 동시에 진행하지 마세요.