연동 가이드

제공업체 연동 가이드

도구별 설정 단계 및 문제 해결 방법을 확인해 보세요.

제공업체 연동 가이드/CC-Switch-CLI 사용 가이드

CC-Switch-CLI 사용 가이드

CC-Switch-CLI는 커맨드라인 환경을 위한 Provider(중계 사이트) 전환 도구로, GUI가 없는 서버, SSH 환경 또는 Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw 간에 Provider를 빠르게 전환해야 하는 사용자에게 적합합니다.

공식 정보 다운로드 및 문서는 공식 사이트를 기준으로 합니다.
GitHub CC-Switch-CLI 공식 저장소, 명령어 목록 및 Releases Releases Windows / macOS / Linux 버전 다운로드 Homebrew macOS 환경에서는 Homebrew로 설치 가능

누구에게 적합한가요?

일반 데스크톱 사용자라면 CC Switch GUI(그래픽 인터페이스) 버전을 우선 사용하는 것이 좋습니다. 터미널 환경에 익숙하거나 일괄 설정 관리가 필요한 경우 이 가이드를 참고하세요. 아래 코드 블록에는 명령어만 포함되어 있으며, 명령어와 함께 설명이 복사되는 것을 방지하기 위해 설명은 코드 블록 외부에 배치했습니다.

설치 및 실행

macOS / Linux 사용자는 공식 문서를 참고하여 설치 스크립트나 Releases 패키지를 사용할 수 있으며, Windows 사용자는 Releases에서 해당 압축 파일을 다운로드하여 압축을 푼 후 해당 디렉터리에서 실행하는 것을 권장합니다.

공식 설치 스크립트
curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash cc-switch

cc-switch를 직접 입력하면 대화형 인터페이스(TUI)로 진입하여 초보자가 메뉴를 둘러보기에 적합합니다. 아래 명령어들은 수행할 작업을 이미 알고 있고 바로 실행하고자 할 때 유용합니다.

환경 점검

확인 항목확인 방법이유
CC Switch 또는 CLI 버전 설치 여부현재 터미널에서 해당 명령어를 인식하는지 확인설치되어 있지 않으면 모든 설정 명령어가 실패합니다.
대상 CLI 설치 여부Claude Code, Codex, Gemini CLI가 최소한 개별적으로 실행되는지 확인CC-Switch-CLI가 대상 도구를 대신 설치해주지 않습니다.
Provider(중계 사이트) 정보 완전성Base URL, API Key, 모델 이름을 준비CLI 설정에는 그래픽 안내가 없어 항목이 하나라도 누락되면 오류가 발생하기 쉽습니다.
테스트 디렉터리에서 먼저 검증실제 프로젝트에서 바로 일괄 전환하지 않음설정이 잘못되었을 때 롤백하기가 더 수월합니다.
로컬 환경 먼저 확인하기 다음 명령어를 사용하여 CC-Switch-CLI가 인식한 도구 목록, 현재 Provider, 프록시 상태가 정상인지 확인할 수 있습니다.
환경 확인 명령어
cc-switch env tools cc-switch env check cc-switch provider current cc-switch --app codex provider current

Provider 명령어

Provider는 중계 사이트의 연결 설정을 의미합니다. Provider를 추가하기 전에 중계 사이트 대시보드에서 Base URL, API Key, 모델 이름을 먼저 준비하세요. 수정하거나 전환할 때는 목록 명령어로 번호(ID)를 먼저 확인해야 합니다.

Provider 조회, 추가 및 편집
cc-switch provider list cc-switch provider add cc-switch provider edit <id> cc-switch provider fetch-models <id>
Provider 전환 및 연결 테스트
cc-switch provider switch <id> cc-switch provider stream-check <id> cc-switch provider fetch-models <id>
<id>는 cc-switch provider list에서 확인한 번호로 변경해야 합니다. <id> 그대로 입력하여 실행하지 마세요.

애플리케이션별 관리

특정 대상 도구의 설정만 보려면 --app 옵션을 추가할 수 있습니다. 이는 Claude Code, Codex, Gemini CLI를 개별적으로 문제 해결할 때 매우 유용합니다.

애플리케이션별 Provider 목록 확인
cc-switch --app claude provider list cc-switch --app codex provider list cc-switch --app gemini provider list cc-switch --app opencode provider list cc-switch --app openclaw provider list
애플리케이션별 현재 Provider 확인
cc-switch --app claude provider current cc-switch --app codex provider current cc-switch --app gemini provider current

대상 애플리케이션과 현재 Provider 상태를 확인한 후 전환을 진행하세요. 전환이 완료되면 터미널을 다시 시작한 다음 대상 도구로 가장 간단한 테스트 질문을 전송해 보세요.

전환 후 최소 테스트
claude "Please reply only: Claude Code is active" codex "Please reply only: Codex is active" gemini "Please reply only: Gemini is active"

MCP 동기화

MCP는 모든 초보자에게 필요한 것은 아닙니다. Claude Code, Codex, Gemini CLI에서 이미 MCP를 사용하고 있고 도구 간 동기화가 필요한 경우에만 설정하세요. 처음에는 TUI 메뉴에 진입하여 MCP 항목을 먼저 확인하는 것을 권장하며, 오래된 튜토리얼의 고급 명령어를 무작정 복사하지 마세요.

MCP 관리 메뉴 진입
cc-switch cc-switch --app codex

설치 및 설정 순서

  1. 전환하려는 대상 도구를 먼저 확인합니다: Claude Code, Codex, Gemini CLI 또는 기타 CLI.
  2. 중계 사이트 대시보드에서 Base URL, API Key, 모델 이름을 준비합니다.
  3. CC-Switch-CLI에서 Provider를 추가하거나 선택합니다.
  4. 해당 Provider를 대상 도구에 적용합니다.
  5. 터미널을 다시 연 후 대상 CLI에서 간단한 질문으로 테스트합니다.
  6. 성공적으로 확인되면 다른 대상 도구에도 동일한 Provider를 적용합니다.
사용 시나리오권장 사항
로컬 데스크톱 사용CC Switch GUI 인터페이스를 우선 사용 (입력 항목 및 상태가 더 직관적임)
원격 서버 / SSHCC-Switch-CLI 사용 권장 (작업 전 현재 버전의 명령어 확인)
일괄 설정 전환테스트 프로젝트에서 먼저 성공 여부를 검증한 후 실제 프로젝트에 적용
다중 사용자 공유 머신공용 설정에 개인 API Key를 기록하지 말고, 먼저 설정 파일의 적용 범위를 확인

초보자 문제 해결 (트러블슈팅)

증상우선 확인 사항해결 방법
Command not found (명령어를 찾을 수 없음)설치 여부 및 환경변수(PATH) 등록 여부 확인터미널을 다시 열거나 공식 설치 가이드로 돌아가 설치 경로 확인
전환 후 대상 도구의 설정이 변경되지 않음터미널을 재시작했는지, 올바른 대상 도구를 선택했는지 확인현재 터미널 창을 닫고 다시 연 후 다시 테스트
401 / Unauthorized (인증 실패)API Key가 완전하게 입력되었는지, 만료되지 않았는지 확인공백이 포함되지 않도록 주의하며 Key를 다시 복사하여 붙여넣기
model not found (모델을 찾을 수 없음)중계 사이트 대시보드에 명시된 모델 이름과 정확히 일치하는지 확인중계 사이트의 모델 목록에 맞춰 다시 입력
커맨드라인 도구는 오래된 튜토리얼의 명령어를 그대로 복사할 때 오류가 발생하기 가장 쉽습니다. 이 가이드에서는 설정 접근법과 문제 해결 로직을 중점적으로 다루며, 구체적인 세부 명령어는 항상 최신 공식 버전을 기준으로 확인하세요.