# Claude Code

NezhaGate는 Anthropic과 같은 Messages API를 제공하므로 Claude Code의 도구 사용, 사고, 프롬프트 캐싱이 그대로 동작합니다. 환경 변수 두 개만 설정하면 시작할 수 있습니다.

> https://nezhagate.com/ko/docs/integrations/claude-code

## 시작하기 전에

- NezhaGate API 키(콘솔의 「API Keys」 페이지에서 만듭니다).

- Claude Code가 설치되어 있어야 합니다. 아직이라면 아래 명령을 실행하세요(Node.js 18 이상 필요):

```
npm install -g @anthropic-ai/claude-code
```

## 1단계: 환경 변수 설정

`claude`를 실행할 터미널에서 설정합니다. `ANTHROPIC_AUTH_TOKEN`에는 NezhaGate 키를, `ANTHROPIC_MODEL`에는 기본으로 쓸 모델을 넣습니다.

```
export ANTHROPIC_BASE_URL=https://nezhagate.com/anthropic
export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-sonnet-5
claude
```

```
$env:ANTHROPIC_BASE_URL = "https://nezhagate.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_API_KEY"
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-sonnet-5"
claude
```

이렇게 설정하면 현재 터미널에서만 유효해서 새 터미널에서는 다시 설정해야 합니다. 계속 유지하려면 다음 단계의 settings.json을 쓰세요.

## 2단계(권장): settings.json에 저장

같은 설정을 Claude Code의 사용자 설정 파일에 저장하면 어떤 터미널에서든 적용됩니다. 파일 위치는 macOS / Linux가 `~/.claude/settings.json`, Windows가 `%USERPROFILE%\.claude\settings.json`이며, 파일이 없으면 새로 만드세요.

```
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://nezhagate.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-5"
  }
}
```

## 3단계: 실행하고 확인하기

프로젝트 폴더에서 `claude`를 실행한 뒤 `/status`를 입력해 현재 설정을 확인하세요. 기본 URL이 `https://nezhagate.com/anthropic`이면 연결된 것입니다.

## 모델 고르기

Claude Code는 Claude 모델만 쓸 수 있습니다(/anthropic 엔드포인트는 Claude 모델만 받습니다). 지금 쓸 수 있는 모델:

| 모델 ID | 입력 | 출력 | 캐시 읽기 |
| --- | --- | --- | --- |
| `claude-sonnet-4-6` | $1.50 | $7.50 | $0.15 |
| `claude-opus-5` | $4.00 | $20.00 | $0.40 |
| `claude-fable-5` | $8.00 | $40.00 | $0.80 |
| `claude-sonnet-5` | $1.00 | $5.00 | $0.10 |

요금 단위: 100만 토큰당 미국 달러.

세션 중에 `/model` 뒤에 모델 ID를 입력하면 바꿀 수 있습니다(예: `/model claude-opus-5`). `/model` 메뉴에서 Opus나 Sonnet을 고를 때 쓰는 모델은 `ANTHROPIC_DEFAULT_OPUS_MODEL`과 `ANTHROPIC_DEFAULT_SONNET_MODEL`이 정합니다.

### 백그라운드 작업용 모델

Claude Code는 대화 제목 짓기 같은 작은 백그라운드 작업을 소형 모델에 맡기며, 기본으로 Claude Haiku를 요청합니다. NezhaGate는 Haiku를 제공하지 않으므로 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 위 표의 모델 중 하나로 지정하세요. 그렇지 않으면 이 백그라운드 요청은 404를 돌려받습니다.

## 과금과 캐시

토큰 단위로 과금하며 /v1 엔드포인트와 같은 요금입니다. 프롬프트 캐시에 적중한 부분은 표의 「캐시 읽기」 요금이 적용되어 입력 요금보다 훨씬 쌉니다. Claude Code는 매 턴 같은 시스템 프롬프트와 프로젝트 맥락을 보내므로 대개 매 턴 캐시에 적중합니다.

## 자주 나오는 오류

**401 또는 「Invalid API key」**

키를 잘못 입력했거나 공백이 섞였거나 키가 정지되었습니다. 콘솔에서 확인한 뒤 다시 설정하세요.

**404 「model: …」**

요청한 모델이 NezhaGate 목록에 없습니다. 가장 흔한 경우는 백그라운드 작업이 기본으로 요청하는 Haiku입니다. 위 설명대로 `ANTHROPIC_MODEL`과 `ANTHROPIC_DEFAULT_HAIKU_MODEL`을 설정하세요.

**402 잔액 부족**

계정 잔액이 부족하거나 키가 설정한 예산 한도에 도달했습니다. 콘솔에서 충전하거나 키 한도를 올리세요.

**설정이 적용되지 않는 것 같아요**

환경 변수는 `claude`를 실행하기 전에 같은 터미널에서 설정해야 합니다. settings.json을 고쳤다면 Claude Code를 다시 시작하세요. 사용 중인 기본 URL은 `/status`로 확인할 수 있습니다.

**429 또는 「overloaded」**

이 모델의 회선이 잠시 가득 찼습니다. 몇 초 뒤 다시 시도하세요. 과금되지 않습니다.