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

# BetterToken provider를 위한 CC Switch 고급 설정

> CC Switch에서 Claude Code, Claude Desktop, Codex CLI, OpenCode 및 OpenClaw용 BetterToken provider, model mapping 및 proxy 설정을 관리하세요.

CC Switch는 Claude Code, Claude Desktop, Codex, OpenCode 및 OpenClaw 전반의 provider를 관리하는 cross-platform desktop app입니다. 이 페이지는 고급 설정을 한곳에 모았습니다. 각 도구의 직접 설정 페이지에서 시작하고, provider를 전환하거나 non-native model을 실행해야 할 때만 CC Switch를 사용하세요.

## CC Switch 설치

<Tabs>
  <Tab title="macOS">
    Homebrew가 가장 쉬운 방법입니다. [GitHub Releases](https://github.com/farion1231/cc-switch/releases)에서 최신 `.dmg` 또는 `.zip`을 다운로드할 수도 있습니다.

    ```bash theme={null}
    brew tap farion1231/ccswitch
    brew install --cask cc-switch
    ```
  </Tab>

  <Tab title="Windows">
    [GitHub Releases](https://github.com/farion1231/cc-switch/releases)에서 최신 `CC-Switch-v{version}-Windows.msi` installer 또는 portable `.zip` build를 다운로드하세요.
  </Tab>

  <Tab title="Linux">
    [GitHub Releases](https://github.com/farion1231/cc-switch/releases)에서 최신 `.deb`, `.rpm` 또는 `.AppImage` build를 다운로드하세요.
  </Tab>
</Tabs>

## 준비할 항목

* BetterToken API Key(<a href={"https://bettertoken.ai/register"}>여기에서 등록</a>)
* Claude Code는 Anthropic protocol을 사용하므로 `Base URL`은 `https://www.bettertoken.ai`입니다
* non-Claude provider를 사용하는 Claude Desktop에는 최신 Claude Desktop 및 CC Switch `v3.16.5` 이상이 필요합니다
* Codex, OpenCode 및 OpenClaw는 OpenAI-compatible protocol을 사용하므로 `Base URL`은 `https://www.bettertoken.ai/v1`입니다
* Codex, OpenCode 및 OpenClaw용 현재 **GPT provider** model ID 하나를 준비하세요. <a href={"https://bettertoken.ai/pricing"}>BetterToken 모델 광장</a>에서 복사하거나 CC Switch가 `/v1/models`에서 가져오게 할 수 있습니다

<Info>
  처음 실행하면 CC Switch가 기기에서 찾은 기존 configs를 자동으로 가져옵니다. official provider를 fallback으로 유지하고 BetterToken을 함께 추가할 수 있습니다.
</Info>

<Note>
  BetterToken은 Anthropic과 OpenAI-compatible의 두 access modes를 사용합니다. `https://www.bettertoken.ai`과 `https://www.bettertoken.ai/v1`이 섞이지 않도록 Claude Code와 OpenAI-compatible tools를 하나의 universal provider에 억지로 넣기보다 app별 provider를 만드는 편이 좋습니다.
</Note>

## BetterToken provider 추가

<Tabs>
  <Tab title="Claude Code" id="claude-code">
    <Steps>
      <Step title="CC Switch에서 Claude Code를 열고 provider 추가">
        CC Switch를 열고 **Claude Code**로 전환한 다음 **Add Provider**를 클릭하세요.

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/qbH0nwqS9mSIdsda/images/cc-switch/claude-code-add-provider.png?fit=max&auto=format&n=qbH0nwqS9mSIdsda&q=85&s=517f215f5f828187647dd214eacfe19b" alt="CC Switch의 Claude Code 페이지. 오른쪽 위 추가 버튼으로 새 provider를 만듭니다." style={{ borderRadius: '0.5rem' }} width="2000" height="1792" data-path="images/cc-switch/claude-code-add-provider.png" />
        </Frame>
      </Step>

      <Step title="기본 필드 입력">
        * **Provider Name**: `BetterToken-claude`(provider를 쉽게 식별할 수 있는 다른 이름도 가능)
        * **Base URL**: `https://www.bettertoken.ai`
        * **API Key**: BetterToken API Key
        * **API Format**: `OpenAI Responses API`

        스크린샷의 번호 표시는 다음 필드와 일치합니다.

        1. **Provider Name**
        2. **API Key**
        3. **Base URL**

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/PriHfVE9SgoOFlO4/images/cc-switch/claude-code-basic-fields.png?fit=max&auto=format&n=PriHfVE9SgoOFlO4&q=85&s=514944678fb16510d03f0f2610bd8b70" alt="CC Switch의 Claude Code provider edit 페이지. Provider Name, API Key 및 API Endpoint 입력 위치를 보여 줍니다." style={{ borderRadius: '0.5rem' }} width="2000" height="1300" data-path="images/cc-switch/claude-code-basic-fields.png" />
        </Frame>
      </Step>

      <Step title="provider에 따라 model mapping 처리">
        * **Claude provider**를 사용하면 보통 advanced options 또는 model mapping을 변경할 필요가 없습니다
        * **GPT provider**를 사용하면 아래 추가 설정을 완료하세요.

        1. **Advanced Options**를 엽니다
        2. **API Format**을 **OpenAI Responses API**로 설정합니다

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/PriHfVE9SgoOFlO4/images/cc-switch/claude-code-api-format.png?fit=max&auto=format&n=PriHfVE9SgoOFlO4&q=85&s=5605667b764f033854f78dc981592f84" alt="CC Switch의 advanced options 섹션. API Format이 OpenAI Responses API로 설정되어 있습니다." style={{ borderRadius: '0.5rem' }} width="2000" height="1300" data-path="images/cc-switch/claude-code-api-format.png" />
        </Frame>

        3. **Model Mapping**에서 **Fetch Model List**를 클릭합니다
        4. **Primary Model**, **Thinking Model**, **Haiku Default Model**, **Sonnet Default Model** 및 **Opus Default Model**의 dropdown에서 값을 명시적으로 선택합니다

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/PriHfVE9SgoOFlO4/images/cc-switch/claude-code-model-mapping.png?fit=max&auto=format&n=PriHfVE9SgoOFlO4&q=85&s=d1104cc24dae2825dfed3a6be53dc6b3" alt="CC Switch의 model mapping 섹션. Fetch Model List 및 Primary, Thinking, Haiku, Sonnet, Opus 모델 mapping을 보여 줍니다." style={{ borderRadius: '0.5rem' }} width="2000" height="1300" data-path="images/cc-switch/claude-code-model-mapping.png" />
        </Frame>

        이 모델들은 모두 <a href={"https://bettertoken.ai/pricing"}>BetterToken 모델 광장</a>의 현재 **GPT provider** model IDs를 사용해야 합니다.
      </Step>

      <Step title="저장, 전환 및 proxy 활성화 여부 결정">
        저장 후 provider list로 돌아가세요.

        1. BetterToken provider를 active로 표시합니다
        2. **Claude provider**를 사용하면 왼쪽 위의 **CC Switch proxy**를 활성화할 필요가 없습니다
        3. **GPT provider**를 사용하면 **CC Switch proxy**를 활성화합니다

        아래 스크린샷은 provider list에서 BetterToken-claude가 활성화된 모습입니다. **GPT provider**를 사용할 때만 왼쪽 위에서 **CC Switch proxy**를 활성화하세요.

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/PriHfVE9SgoOFlO4/images/cc-switch/claude-code-enable-proxy.png?fit=max&auto=format&n=PriHfVE9SgoOFlO4&q=85&s=13c9adc5d76d5a2d1fae0e52e90a87ca" alt="BetterToken-claude가 선택되어 In Use로 표시된 CC Switch provider list." style={{ borderRadius: '0.5rem' }} width="2000" height="1300" data-path="images/cc-switch/claude-code-enable-proxy.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Desktop" id="claude-desktop">
    <Info>
      이 탭은 GPT, Kimi, GLM 및 다른 non-Claude providers용입니다. Claude provider에는 [직접 Claude Desktop 설정](/ko/faq/claude-desktop-bettertoken-api)을 사용하세요.
    </Info>

    <Steps>
      <Step title="Claude Desktop으로 전환하고 provider 추가">
        CC Switch를 열고 상단 toolbar에서 **Claude Desktop** icon을 선택한 다음 오른쪽 위의 \*\*+\*\*를 클릭하세요.

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/zaxT_L3BQP7MnZS4/images/claude-desktop-third-party-models/cc-switch-claude-desktop-add-provider.png?fit=max&auto=format&n=zaxT_L3BQP7MnZS4&q=85&s=8906aaf8ead247cf406a55a51f402bdf" alt="CC Switch에서 Claude Desktop으로 전환하고 plus button을 클릭하여 provider를 추가합니다." style={{ borderRadius: '0.5rem' }} width="2000" height="1300" data-path="images/claude-desktop-third-party-models/cc-switch-claude-desktop-add-provider.png" />
        </Frame>
      </Step>

      <Step title="기본 필드 입력">
        * **Provider Name**: `BetterToken-GPT`처럼 알아보기 쉬운 이름 사용
        * **API Key**: BetterToken API Key
        * **API Endpoint**: `https://www.bettertoken.ai`

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/zaxT_L3BQP7MnZS4/images/claude-desktop-third-party-models/provider-basic-fields.png?fit=max&auto=format&n=zaxT_L3BQP7MnZS4&q=85&s=ba55f76085a213cde6527e86aca54798" alt="CC Switch에서 Claude Desktop용 Provider Name, API Key 및 API Endpoint를 입력합니다." style={{ borderRadius: '0.5rem' }} width="2000" height="1300" data-path="images/claude-desktop-third-party-models/provider-basic-fields.png" />
        </Frame>
      </Step>

      <Step title="API Format 및 model mapping 설정">
        **API Format**에서 \*\*OpenAI Responses API (Requires routing)\*\*를 선택한 다음 **Fetch Models**를 클릭하세요.

        Sonnet, Opus, Fable 및 Haiku를 사용할 model ID에 mapping하세요.

        | Model role | 요청 model        |
        | ---------- | --------------- |
        | Sonnet     | `YOUR_MODEL_ID` |
        | Opus       | `YOUR_MODEL_ID` |
        | Fable      | `YOUR_MODEL_ID` |
        | Haiku      | `YOUR_MODEL_ID` |

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/zaxT_L3BQP7MnZS4/images/claude-desktop-third-party-models/provider-model-mapping.png?fit=max&auto=format&n=zaxT_L3BQP7MnZS4&q=85&s=d93c1bd4098f1f839cd2ab6a426d1aba" alt="CC Switch에서 OpenAI Responses API를 선택하고 Claude Desktop model mapping을 구성합니다." style={{ borderRadius: '0.5rem' }} width="2000" height="1300" data-path="images/claude-desktop-third-party-models/provider-model-mapping.png" />
        </Frame>

        <a href={"https://bettertoken.ai/pricing"}>모델 광장</a> 또는 API Key **Setup** dialog에서 현재 model ID를 복사하세요. 모델 광장에서 해당 모델이 1M context window를 지원한다고 표시될 때만 **Declare 1M**을 활성화하세요.
      </Step>

      <Step title="저장, 전환 및 proxy 활성화">
        provider를 저장하고 **In use**로 설정한 다음 왼쪽 위의 proxy switch를 켜세요.

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/zaxT_L3BQP7MnZS4/images/claude-desktop-third-party-models/provider-enable-proxy.png?fit=max&auto=format&n=zaxT_L3BQP7MnZS4&q=85&s=99800d159627886f2e999f9eceb061bf" alt="Claude Desktop용 BetterToken provider가 active이고 CC Switch proxy가 활성화되어 있습니다." style={{ borderRadius: '0.5rem' }} width="2000" height="1300" data-path="images/claude-desktop-third-party-models/provider-enable-proxy.png" />
        </Frame>
      </Step>

      <Step title="Claude Desktop 다시 시작">
        Claude Desktop을 완전히 종료한 후 다시 여세요. 왼쪽 아래의 **Gateway**가 설정이 active임을 확인해 줍니다. message box의 model menu에서 mapping된 model을 선택하세요.

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/zaxT_L3BQP7MnZS4/images/claude-desktop-third-party-models/claude-desktop-gateway-ready.png?fit=max&auto=format&n=zaxT_L3BQP7MnZS4&q=85&s=bf573497e7a842b367f6c9ca95fdc99b" alt="다시 시작한 Claude Desktop에 Gateway가 표시되고 CC Switch로 mapping된 models를 제공합니다." style={{ borderRadius: '0.5rem' }} width="2400" height="1600" data-path="images/claude-desktop-third-party-models/claude-desktop-gateway-ready.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex" id="codex-cli">
    <Steps>
      <Step title="CC Switch에서 Codex를 열고 provider 추가">
        CC Switch를 열고 **Codex**로 전환한 다음 **Add Provider**를 클릭하세요. CC Switch가 먼저 preset 선택을 요구하면 **OpenAI Compatible** 또는 **Custom**을 우선 선택하세요.

        스크린샷의 번호 표시는 다음 작업과 일치합니다.

        1. **Codex**로 전환
        2. 오른쪽 위의 **Add Provider** 클릭

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/qbH0nwqS9mSIdsda/images/cc-switch/codex-cli-add-provider.png?fit=max&auto=format&n=qbH0nwqS9mSIdsda&q=85&s=5f892bf124c432babed54886c6051632" alt="CC Switch의 Codex 페이지. 상단에서 Codex가 선택되어 있고 오른쪽 위 추가 버튼으로 새 provider를 만듭니다." style={{ borderRadius: '0.5rem' }} width="1800" height="1532" data-path="images/cc-switch/codex-cli-add-provider.png" />
        </Frame>
      </Step>

      <Step title="기본 필드 입력">
        * **Provider Name**: `BetterToken`
        * **Base URL**: `https://www.bettertoken.ai/v1`
        * **API Key**: BetterToken API Key

        custom config view로 전환하면 underlying config가 `wire_api = "responses"`를 사용하는지 확인하세요.

        스크린샷의 번호 표시는 다음 필드와 일치합니다.

        1. **Provider Name**
        2. **API Key**
        3. **Base URL**

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/PriHfVE9SgoOFlO4/images/cc-switch/codex-cli-basic-fields.png?fit=max&auto=format&n=PriHfVE9SgoOFlO4&q=85&s=a6483a11bcf6eaf3663134f407843391" alt="CC Switch의 Codex provider edit 페이지. Provider Name, API Key 및 Base URL 입력 위치를 보여 줍니다." style={{ borderRadius: '0.5rem' }} width="2000" height="1300" data-path="images/cc-switch/codex-cli-basic-fields.png" />
        </Frame>
      </Step>

      <Step title="model 가져오기 및 mapping">
        **Fetch Models**를 클릭하고 <a href={"https://bettertoken.ai/pricing"}>모델 광장</a>에서 현재 Model ID를 선택하세요. Codex에는 CC Switch proxy가 필요하지 않습니다.
      </Step>

      <Step title="저장 및 전환">
        provider를 저장하고 Codex를 BetterToken으로 전환하세요. CC Switch가 해당 Codex auth 및 config files를 작성합니다.

        저장 후 list로 돌아가 BetterToken entry가 **In Use**로 표시되는지 확인하세요.

        <Frame>
          <img src="https://mintcdn.com/bettertoken-d796114e/ZMo3cJhJx4ISRrsG/images/cc-switch/codex-cli-activate-provider.png?fit=max&auto=format&n=ZMo3cJhJx4ISRrsG&q=85&s=52dc850977af1443b4b573a27726c4b5" alt="BetterToken이 선택되고 in use로 표시된 CC Switch의 Codex provider list." style={{ borderRadius: '0.5rem' }} width="1800" height="1686" data-path="images/cc-switch/codex-cli-activate-provider.png" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="OpenCode" id="opencode">
    <Steps>
      <Step title="CC Switch에서 OpenCode를 열고 provider 추가">
        CC Switch를 열고 **OpenCode**로 전환한 다음 **Add Provider**를 클릭하세요. CC Switch가 먼저 preset을 요구하면 **OpenAI Compatible** 또는 **Custom**을 우선 선택하세요.
      </Step>

      <Step title="기본 필드 입력">
        * **Provider Name**: `BetterToken`
        * **Base URL**: `https://www.bettertoken.ai/v1`
        * **API Key**: BetterToken API Key
        * **API Format**: `OpenAI Compatible`
      </Step>

      <Step title="default model 선택">
        가능하면 **Fetch Models**를 사용하세요. model을 직접 입력해야 하면 <a href={"https://bettertoken.ai/pricing"}>BetterToken 모델 광장</a>의 현재 **GPT provider** model ID를 사용하세요.

        OpenCode는 저장된 provider configuration을 직접 읽으며 CC Switch proxy가 필요하지 않습니다.
      </Step>

      <Step title="저장 및 전환">
        provider를 저장하고 OpenCode를 BetterToken으로 전환하세요.
      </Step>
    </Steps>
  </Tab>

  <Tab title="OpenClaw" id="openclaw">
    <Steps>
      <Step title="CC Switch에서 OpenClaw를 열고 provider 추가">
        CC Switch를 열고 **OpenClaw**로 전환한 다음 **Add Provider**를 클릭하세요. CC Switch가 먼저 preset을 요구하면 **OpenAI Compatible** 또는 **Custom**을 우선 선택하세요.
      </Step>

      <Step title="기본 필드 입력">
        * **Provider Name**: `BetterToken`
        * **Base URL**: `https://www.bettertoken.ai/v1`
        * **API Key**: BetterToken API Key
        * **API Format**: `OpenAI Responses API`

        custom OpenClaw provider config를 수정하는 경우 `api`가 `openai-responses`로 설정되었는지 확인하세요.
      </Step>

      <Step title="default model 선택">
        가능하면 **Fetch Models**를 사용하세요. model을 직접 입력해야 하면 현재 **GPT provider** model ID를 사용하세요.

        OpenClaw는 저장된 provider configuration을 직접 사용하며 CC Switch proxy가 필요하지 않습니다.
      </Step>

      <Step title="저장 및 전환">
        provider를 저장하고 OpenClaw를 BetterToken으로 전환하세요.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 저장한 변경 사항 적용

provider를 저장하고 전환한 후 설정을 확인하기 전에 영향을 받는 client 또는 gateway를 다시 시작하세요.

* Claude Code: 현재 Claude Code session을 완전히 종료한 다음 다시 시작합니다.
* Claude Desktop: app을 완전히 종료하고 다시 열어 왼쪽 아래에 **Gateway**가 표시되는지 확인합니다.
* Codex: 현재 Codex process를 다시 시작하거나 새 terminal session을 엽니다.
* OpenCode: 현재 OpenCode session을 종료하고 다시 시작합니다.
* OpenClaw: `openclaw gateway restart`를 실행한 후 Discord에서 `/new`, `/status` 및 `/model`을 사용합니다.

## CC Switch 전용 고급 기능

CC Switch는 third-party provider로 전환할 때 official Codex login을 유지하고 official 및 third-party sessions를 하나의 history로 결합할 수 있습니다. 이 옵션을 활성화한 후 Codex를 다시 시작하세요. [official Codex login 및 unified session history 유지](/ko/faq/codex/official-login-third-party-api)를 참조하세요.

## 일반적인 문제

* `/v1`을 Claude Code `Base URL`에 추가하지 마세요
* Claude Code에서 **GPT provider**를 사용하면 **Advanced Options**에서 **API Format**을 **OpenAI Responses API**로 설정하세요
* Claude Code에서 **Claude provider**를 사용하면 **CC Switch proxy**를 활성화할 필요가 없습니다
* Claude Desktop에서 non-Claude provider를 사용하면 **CC Switch proxy**를 활성화하고 app을 완전히 다시 시작하세요
* Codex, OpenCode 및 OpenClaw는 `https://www.bettertoken.ai/v1`을 사용해야 합니다
* Codex, OpenCode 또는 OpenClaw가 model을 요청하면 **GPT provider** model ID를 사용하세요
* **Fetch Models**가 실패하면 API Key와 `Base URL`을 확인한 뒤 model ID를 수동으로 붙여넣으세요
* 전환이 적용되지 않으면 CC Switch에서 BetterToken이 active provider인지 확인하고 위 설명대로 영향을 받는 client 또는 gateway를 다시 시작하세요

## 관련 페이지

* Claude Code 세부 정보: [Claude Code](/ko/ai-tools/claude-code)
* Claude Desktop용 직접 Claude provider 설정: [Claude Desktop](/ko/faq/claude-desktop-bettertoken-api)
* Codex 세부 정보: [Codex](/ko/ai-tools/codex)
* OpenCode 세부 정보: [OpenCode](/ko/ai-tools/opencode)
* OpenClaw 세부 정보: [OpenClaw](/ko/ai-tools/openclaw)

## 관련 FAQ

* [Claude Desktop에서 third-party models 및 Codex 사용](/ko/faq/claude-desktop/third-party-models)
* [OpenAI-compatible API와 Anthropic-compatible API 비교](/ko/faq/concepts/openai-compatible-vs-anthropic-compatible)
* [MCP와 API Key 및 Base URL 비교](/ko/faq/concepts/mcp-vs-api-key-base-url)
* [model\_provider, base\_url 및 wire\_api란 무엇인가요?](/ko/faq/codex/model-provider-base-url-wire-api)
* [Cline에서 OpenAI-compatible API 구성](/ko/faq/cline/openai-compatible-api)