> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# CC-Switch에서 BeatAPI 사용하기

> 데스크톱 앱 하나에서 Claude Code와 Codex CLI의 BeatAPI 제공자를 관리하고, 설정 파일을 편집하지 않고 제공자를 전환합니다.

# CC-Switch에서 BeatAPI 사용하기

CC-Switch는 Claude Code, Codex CLI, Gemini CLI 등 여러 AI 코딩 CLI의 제공자 설정을 한곳에서 관리하는 오픈 소스 데스크톱 앱입니다. BeatAPI를 한 번 추가해 두면 편집기를 열지 않고 클릭 한 번으로 전환하거나 되돌릴 수 있습니다.

## 사전 준비

1. **지원되는 CLI를 하나 이상 설치** — [Claude Code](/integrations/claude-code) 또는 [Codex CLI](/integrations/codex-cli).
2. **BeatAPI API 키** — [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 만드세요.

## 1단계: CC-Switch 설치

#### macOS

```bash
brew tap farion1231/ccswitch
brew install --cask cc-switch
```

서명된 `.dmg`는 GitHub Releases에서도 받을 수 있습니다. macOS 12 이상이 필요합니다.

#### Windows

GitHub Releases에서 `.msi` 설치 프로그램이나 포터블 `.zip`을 내려받으세요. Windows 10 이상이 필요합니다.

#### Linux

GitHub Releases에서 Debian·Ubuntu용 `.deb`, Fedora·RHEL용 `.rpm` 또는 범용 `.AppImage`를 받으세요. Arch에서는 `paru -S cc-switch-bin`을 사용합니다.

처음 실행하면 CC-Switch가 이미 설치된 CLI를 감지하고 현재 설정을 기본 제공자로 가져올 수 있습니다.

## 2단계: BeatAPI 추가

메인 창 위쪽에서 도구 그룹을 선택합니다. 사용하는 CLI를 설정하세요.

### Claude Code

1. **Claude Code** 그룹을 선택하세요.
2. 오른쪽 위의 \*\*+\*\*를 클릭하세요.
3. 양식을 작성하세요.

| 필드        | 값                        |
| --------- | ------------------------ |
| 이름        | `BeatAPI`                |
| 엔드포인트 URL | `https://api.beatapi.io` |
| API Key   | BeatAPI API 키            |
| API 형식    | `Anthropic Messages`     |

4. **Add**를 클릭하세요.

### Codex

1. **Codex** 그룹을 선택하세요.
2. 오른쪽 위의 \*\*+\*\*를 클릭하세요.
3. Codex 제공자는 블록 두 개로 구성됩니다. `auth.json` 블록에는 다음을 입력합니다.

```json
{
  "OPENAI_API_KEY": "<BEATAPI_API_KEY>"
}
```

`config.toml` 블록에는 다음을 입력합니다.

```toml
model = "gpt-5.6-sol"
model_provider = "beatapi"

[model_providers.beatapi]
name = "BeatAPI"
base_url = "https://api.beatapi.io/v1"
wire_api = "responses"
requires_openai_auth = true
```

4. 이름을 `BeatAPI`로 지정하고 **Add**를 클릭하세요. CC-Switch가 저장 전에 JSON과 TOML을 모두 검사합니다.

> **Note**
>
> 두 URL은 의도적으로 다르며, 둘을 혼동하는 것이 가장 흔한 설정 실패 원인입니다. Claude Code는 `https://api.beatapi.io`의 Anthropic 네이티브 형식을 사용하며 클라이언트가 `/v1/messages`를 직접 붙이므로 `/v1`이 **없습니다**. Codex는 `https://api.beatapi.io/v1`의 OpenAI 호환 형식을 사용하며 `/v1`이 **있습니다**.

## 3단계: 전환

메인 창에서: 제공자 목록에서 **BeatAPI**를 선택하고 **Enable**을 클릭하세요. 확인 알림이 표시됩니다.

시스템 트레이에서: CC-Switch 아이콘을 클릭하고 메뉴에서 제공자를 고르세요.

Claude Code는 즉시 전환되며 새 세션부터 변경 사항이 적용됩니다. Codex는 터미널이나 에이전트를 다시 시작해야 합니다.

## 모델

| 모델 ID              | 사용 가능한 도구   | 추천 용도                           |
| ------------------ | ----------- | ------------------------------- |
| `claude-fable-5-1` | Claude Code | 최신 세대. 에이전트 코딩의 기본값             |
| `claude-opus-5`    | Claude Code | 가장 강력한 추론 등급                    |
| `claude-sonnet-5`  | Claude Code | 성능과 속도의 균형                      |
| `gpt-5.6-sol`      | Codex       | 가장 강력한 코딩 등급                    |
| `gpt-6-astra`      | Codex       | 최신 세대. 입력 토큰이 272K를 넘으면 요금이 높아짐 |

두 CLI 모두 `/model`로 모델을 바꿀 수 있습니다. 전체 목록은 [텍스트 API](/text-api) 페이지에, 요금은 [가격 페이지](https://beatapi.io/pricing)에 있습니다.

## 자주 묻는 질문

### 전환해도 적용되지 않음

* **Claude Code** — 새 세션을 시작하세요. 계속되면 에이전트를 다시 시작하세요.
* **Codex** — 터미널이나 Codex를 다시 시작하세요.

### 키가 거부됨

1. 키를 앞뒤 공백 없이 전부 복사했는지 확인하세요.
2. [대시보드 → API Keys](https://beatapi.io/dashboard/apikeys)에서 활성 상태인지 확인하세요.
3. 위의 참고 사항에 맞게 엔드포인트 URL을 다시 확인하세요. Claude Code는 `/v1` 없이, Codex는 포함해서 씁니다.

### Codex 제공자 추가 시 형식 오류

CC-Switch는 `auth.json`을 JSON으로, `config.toml`을 TOML로 검사합니다. 빠진 중괄호나 쉼표, 철자가 틀린 필드, 문서에서 붙여 넣은 둥근 따옴표가 있는지 확인하세요.

### 어떤 파일을 수정하나요?

* Claude Code: `~/.claude/settings.json`
* Codex: `~/.codex/config.toml`, `~/.codex/auth.json`

CC-Switch는 전환할 때마다 이 파일을 백업하므로 직접 편집할 필요가 없습니다.

## 지원

[대시보드](https://beatapi.io/dashboard)에서 지원 티켓을 열고 실패한 응답의 `request_id`를 함께 보내 주세요.