> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CC Switch

> Claude Code, Codex CLI, Gemini CLI, OpenCode, OpenClaw를 한 데스크톱 앱으로 관리 — 클릭 한 번으로 GravitexAI 설정 전환

## 1. 개요

**CC Switch**는 **Claude Code, Codex CLI, Gemini CLI, OpenCode, OpenClaw** 관리를 통합하는 **Tauri 2** 기반 데스크톱 앱입니다. GUI를 통해 API provider, 모델, 키를 전환하세요 — 다섯 도구의 `~/.config/*`, TOML, JSON 파일을 수동으로 편집할 필요가 없습니다.

<CardGroup cols={2}>
  <Card title="원클릭 전환" icon="toggle-on">
    하나의 GUI에서 5개 CLI 도구 관리 — 수동 설정 편집 불필요
  </Card>

  <Card title="멀티 모델 통합" icon="layer-group">
    **GravitexAI**와 함께 하나의 키로 Claude / GPT / Gemini / Kimi
  </Card>

  <Card title="사용량 추적" icon="chart-line">
    지출, 요청, 토큰 사용량을 위한 내장 Usage Dashboard
  </Card>

  <Card title="스마트 장애 조치" icon="shield">
    핫 스위칭, 자동 장애 조치, 서킷 브레이킹을 갖춘 로컬 프록시
  </Card>
</CardGroup>

<Info>
  **프로젝트 정보**

  * Repo: [github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)
  * License: MIT
  * Author: Jason Young (farion1231)
</Info>

## 2. 핵심 기능

### 2.1 Provider 관리

* 50개 이상의 내장 프리셋 (AWS Bedrock, NVIDIA NIM 등 포함)
* 커스텀 gateway 지원 (**GravitexAI** 연동 방식)
* 원클릭 전환, 드래그로 순서 변경, 설정 가져오기/내보내기
* 시스템 트레이 빠른 액세스

### 2.2 MCP 서버 관리

* 모든 CLI 도구의 MCP 서버 설정을 중앙 관리
* 양방향 동기화 — 한 번 변경하면 모든 곳에 적용

### 2.3 기타

| Feature              | Description                       |
| -------------------- | --------------------------------- |
| **Prompts manager**  | 크로스 앱 동기화를 갖춘 Markdown 편집기        |
| **Skills installer** | GitHub repo 또는 ZIP 파일에서 설치        |
| **Session browser**  | 대화 기록 보기 및 재개                     |
| **Cloud sync**       | Dropbox, OneDrive, iCloud, WebDAV |
| **Deep link**        | 원클릭 설정 가져오기를 위한 `ccswitch://`     |

## 3. 빠른 시작

### 1단계 — CC Switch 설치

<Tabs>
  <Tab title="macOS">
    Homebrew:

    ```bash theme={null}
    brew install --cask cc-switch
    ```

    또는 [GitHub Releases](https://github.com/farion1231/cc-switch/releases)에서 DMG를 다운로드합니다.
  </Tab>

  <Tab title="Windows">
    [GitHub Releases](https://github.com/farion1231/cc-switch/releases)에서 MSI 설치 프로그램 또는 Portable ZIP을 다운로드합니다.
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # Debian / Ubuntu
    sudo dpkg -i cc-switch_*.deb

    # Fedora / RHEL
    sudo rpm -i cc-switch_*.rpm

    # Arch Linux
    paru -S cc-switch-bin
    ```

    AppImage와 Flatpak도 사용 가능합니다.
  </Tab>
</Tabs>

<Info>
  **시스템 요구사항**: Windows 10+, macOS 10.15 (Catalina)+, Ubuntu 22.04+ / Debian 11+ / Fedora 34+.
</Info>

### 2단계 — GravitexAI 키 발급

<Steps>
  <Step title="로그인">
    [GravitexAI 콘솔](https://maas.gravitex.ai)을 열고 회원가입 또는 로그인합니다.
  </Step>

  <Step title="토큰 생성">
    [API Keys](https://maas.gravitex.ai/#/keys)를 방문하고 "Create new token"을 클릭합니다.
  </Step>

  <Step title="키 복사">
    생성된 키(형식 `sk-xxxxxxxxxx`)를 복사하여 안전하게 보관합니다.
  </Step>
</Steps>

### 3단계 — CC Switch에서 GravitexAI 설정

<Steps>
  <Step title="Provider 관리 열기">
    CC Switch를 실행하고 **Provider** 페이지를 열고 "Add"를 클릭한 뒤 **Custom Gateway**를 선택합니다.
  </Step>

  <Step title="양식 작성">
    | Field            | Value                                                                       |
    | ---------------- | --------------------------------------------------------------------------- |
    | **Name**         | `GravitexAI`                                                                |
    | **API URL**      | `https://api.gravitex.ai`                                                   |
    | **API Key**      | 2단계에서 발급한 키 붙여넣기                                                            |
    | **Enabled apps** | 최소 **Claude Code** 활성화 (필요에 따라 Codex / Gemini CLI / OpenCode / OpenClaw 켜기) |

    <Warning>
      각 CLI 도구는 Base URL 형식이 약간 다릅니다:

      * **Claude Code**: `https://api.gravitex.ai` (**`/v1` 없음**)
      * **Codex CLI / OpenCode**: `https://api.gravitex.ai/v1` (**반드시 `/v1`로 끝남**)
      * **Gemini CLI**: `https://api.gravitex.ai` (**`/v1` 없음**)

      CC Switch는 보통 앱별로 올바른 형식을 적용하지만, 수동 설정 시 위 표를 따르세요.
    </Warning>
  </Step>

  <Step title="저장">
    "Add"를 클릭합니다. CC Switch는 이 설정을 활성화한 모든 CLI 도구의 설정 파일에 동기화합니다.
  </Step>
</Steps>

### 4단계 — 모델 추가

사용할 GravitexAI 모델 ID를 추가합니다:

**Claude — 표준 모델**

| Display name      | Model ID                     | Notes                   |
| ----------------- | ---------------------------- | ----------------------- |
| Claude Opus 4.7   | `claude-opus-4-7`            | 최신 플래그십 — 복잡한 작업 최우선    |
| Claude Sonnet 4.6 | `claude-sonnet-4-6`          | 강력한 코딩 능력, 최고 가성비       |
| Claude Sonnet 4.5 | `claude-sonnet-4-5-20250929` | 200K 긴 컨텍스트             |
| Claude Haiku 4.5  | `claude-haiku-4-5-20251001`  | 빠르고 가벼움 — haiku 스레드에 적합 |

**GPT / Gemini / Kimi**(동일 provider에서 혼합 사용)

| Display name           | Model ID                 | Notes                                      |
| ---------------------- | ------------------------ | ------------------------------------------ |
| GPT 5.5                | `gpt-5.5`                | OpenAI 최신 플래그십                             |
| GPT 5.1 Codex          | `gpt-5.1-codex`          | Codex 전용 — OpenCode에서 Responses API와 함께 사용 |
| Gemini 3.5 Flash       | `gemini-3.5-flash`       | 고처리량 / 저지연                                 |
| Gemini 3.1 Pro Preview | `gemini-3.1-pro-preview` | 심층 추론                                      |
| Kimi K2                | `kimi-k2-250905`         | 장문 및 중국어 작업에 우수한 가성비                       |

<Tip>
  **모델 추천**:

  * 일상 코딩: `claude-sonnet-4-6`
  * 복잡한 아키텍처: `claude-opus-4-7`
  * 빠른 Q\&A / haiku 스레드: `claude-haiku-4-5-20251001`
  * 비용 최적화: `kimi-k2-250905` 또는 `gemini-3.5-flash`

  전체 ID 목록은 [GravitexAI 모델 카탈로그](https://maas.gravitex.ai/#/models)를 참조하세요.
</Tip>

### 5단계 — 전환 및 CLI 실행

**GravitexAI**가 현재 Provider로 설정되면 활성화된 모든 CLI 도구가 자동으로 설정을 적용합니다. 아무 CLI나 실행하세요:

```bash theme={null}
# Claude Code
claude

# Codex
codex

# Gemini CLI
gemini

# OpenCode
opencode
```

## 4. 사용 가이드

### 4.1 여러 CLI 도구 관리

CC Switch는 다음 도구를 동시에 구동할 수 있습니다:

| Tool            | Detailed config                                              |
| --------------- | ------------------------------------------------------------ |
| **Claude Code** | [/ko/integrations/claude-code](/ko/integrations/claude-code) |
| **Codex CLI**   | [/ko/integrations/codex](/ko/integrations/codex)             |
| **Gemini CLI**  | [/ko/integrations/gemini-cli](/ko/integrations/gemini-cli)   |
| **OpenCode**    | [/ko/integrations/open-code](/ko/integrations/open-code)     |
| **OpenClaw**    | [/ko/integrations/openclaw](/ko/integrations/openclaw)       |

모든 도구가 동일한 Provider 설정을 공유합니다 — 전환 시 모든 곳에 적용됩니다.

### 4.2 로컬 프록시

CC Switch는 로컬 프록시 서버를 제공합니다:

* **핫 스위칭** — CLI 재시작 없이 Provider 변경
* **자동 장애 조치** — 현재 Provider 장애 시 보조 Provider로 전환
* **서킷 브레이킹** — Provider가 계속 실패하면 요청 중단

<Tip>
  최대 가용성을 위해 **GravitexAI main** + **GravitexAI backup key**를 장애 조치 대상으로 설정하세요.
</Tip>

### 4.3 백업

* 자동 백업은 최근 **10개 버전** 유지
* 전체 설정 가져오기 / 내보내기
* Dropbox, OneDrive, iCloud, WebDAV를 통한 클라우드 동기화

## 5. FAQ

<AccordionGroup>
  <Accordion title="어떤 OS를 지원하나요?">
    Windows 10+, macOS 10.15 (Catalina)+, 주요 Linux 배포판 (Ubuntu 22.04+, Debian 11+, Fedora 34+, Arch Linux).
  </Accordion>

  <Accordion title="설정 후 Claude Code가 연결되지 않나요?">
    다음 순서로 확인하세요:

    1. **API key**가 `sk-`로 시작하고 불필요한 공백/줄바꿈이 없는지
    2. Claude Code의 **Base URL**이 `https://api.gravitex.ai`인지 (**`/v1` 없음**)
    3. 계정 잔액이 충분한지 — [GravitexAI 콘솔](https://maas.gravitex.ai) 확인
    4. CC Switch가 실제로 `~/.claude/`에 설정을 썼는지
    5. 터미널 재시작 — 환경 변수 변경은 새 세션이 필요
  </Accordion>

  <Accordion title="OpenCode에서 gpt-5.1-codex 오류?">
    Codex 시리즈 모델은 **Responses API만** 지원합니다. `opencode.jsonc`에서 해당 모델에 `"apiCompatibility": "responses"`를 추가하세요 — 자세한 내용은 [OpenCode 가이드](/ko/integrations/open-code)를 참조하세요.
  </Accordion>

  <Accordion title="수동 설정에서 마이그레이션하려면?">
    첫 실행 시 CC Switch가 `~/.claude/`, `~/.codex/`, `~/.config/opencode/` 등 경로를 스캔하고 기존 설정을 자동으로 가져옵니다. 백업 파일에는 **Import config**도 사용할 수 있습니다.
  </Accordion>

  <Accordion title="표준 모델과 Thinking 모델의 차이는?">
    Thinking 모델은 답변 전 chain-of-thought를 강제합니다 — 복잡한 추론 및 아키텍처 설계에 적합합니다. 표준 모델은 더 빠르게 응답하며 일상 코딩에 적합합니다. `-thinking`으로 끝나는 GravitexAI 변형이 추론 버전입니다.
  </Accordion>

  <Accordion title="CC Switch 자체에 비용이 있나요?">
    없습니다. CC Switch는 완전 오픈소스(MIT)입니다. API 호출만 비용이 발생하며 — GravitexAI의 토큰당 요금으로 청구됩니다.
  </Accordion>
</AccordionGroup>

## 6. 모범 사례

<Tip>
  **Pro tips**:

  1. **하나의 Provider로 통일** — 모든 CLI를 GravitexAI에 연결하여 여러 키/URL 관리를 피하세요.
  2. **핫 스위칭 활용** — 작업 복잡도에 따라 `claude-opus-4-7` / `claude-sonnet-4-6` / `claude-haiku-4-5-20251001` 간 전환
  3. **자동 장애 조치 활성화** — 주/보조 Provider(또는 두 키)를 페어링하여 연속성 확보
  4. **정기 백업** — 클라우드 동기화를 켜서 재설치 시 설정 유실 방지
  5. **MCP와 함께 사용** — MCP 서버를 중앙 관리하여 모든 CLI 도구가 동일한 외부 기능 공유
</Tip>

## 7. 참고 자료

<CardGroup cols={2}>
  <Card title="GitHub의 CC Switch" icon="github" href="https://github.com/farion1231/cc-switch">
    소스, 이슈 및 최신 릴리스
  </Card>

  <Card title="Claude Code 가이드" icon="terminal" href="/ko/integrations/claude-code">
    Claude Code 상세 설정
  </Card>

  <Card title="GravitexAI 콘솔" icon="gear" href="https://maas.gravitex.ai">
    키 및 사용량 관리
  </Card>

  <Card title="모델 카탈로그" icon="star" href="https://maas.gravitex.ai/#/models">
    100개 이상의 주류 AI 모델 탐색
  </Card>
</CardGroup>