Claude Code

1. 개요

Claude Code는 Anthropic의 공식 터미널 AI 코딩 클라이언트입니다. GravitexAI(Anthropic 호환 API)를 통해 다음을 사용할 수 있습니다:

멀티 벤더 액세스

하나의 엔드포인트로 Claude 전체 제품군, Kimi K2, GPT 등 사용

듀얼 스레드 모델

무거운 작업은 메인 스레드, 가벼운 작업은 haiku 스레드

구독 불필요

토큰당 과금 — Claude Pro 불필요

글로벌 안정성

자동 장애 조치를 갖춘 분산 노드

2. Node.js 설치 (이미 설치된 경우 건너뛰기)

Node.js ≥ 18.0이 설치되어 있는지 확인하세요.

Windows
macOS
Ubuntu / Debian

다운로드: https://nodejs.org/dist/v22.18.0/node-v22.18.0-x64.msi

sudo xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node
node --version

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash -
sudo apt-get install -y nodejs
node --version

다른 프록시 클라이언트 제거 (선택)

이전에 포크된 @anthropic-ai/claude-code를 설치했다면 먼저 정리하세요:

# Check installation locations
npm ls @anthropic-ai/claude-code
npm ls -g @anthropic-ai/claude-code

# Uninstall
npm uninstall @anthropic-ai/claude-code
npm uninstall -g @anthropic-ai/claude-code

3. Claude Code 설치

전역 설치

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

설치 확인

claude --version

4. GravitexAI 키 발급

로그인

GravitexAI 콘솔로 이동합니다.

키 생성

API Keys → 새 토큰을 생성합니다.

정보 확인

base_url = "https://api.gravitex.ai"
api_key  = "sk-zbTYx*******************************fceTvn5"

Claude Code의 ANTHROPIC_BASE_URL에는 /v1 접미사가 필요 없습니다 — https://api.gravitex.ai를 직접 사용하세요.

5. 환경 변수 설정

5.1 기본 예시 (단일 모델)

Mac / Linux
Windows CMD
Windows PowerShell

export ANTHROPIC_BASE_URL="https://api.gravitex.ai"
export ANTHROPIC_AUTH_TOKEN="sk-zbTYx*******************************fceTvn5"
export ANTHROPIC_MODEL="kimi-k2-250905"
cd your-project-folder
claude

set ANTHROPIC_BASE_URL=https://api.gravitex.ai
set ANTHROPIC_AUTH_TOKEN=sk-zbTYx*******************************fceTvn5
set ANTHROPIC_MODEL=kimi-k2-250905
cd your-project-folder
claude

$env:ANTHROPIC_BASE_URL="https://api.gravitex.ai"
$env:ANTHROPIC_AUTH_TOKEN="sk-zbTYx*******************************fceTvn5"
$env:ANTHROPIC_MODEL="kimi-k2-250905"
cd your-project-folder
claude

5.2 듀얼 스레드 아키텍처

기본적으로 Claude Code는 비용 절감을 위해 듀얼 스레드 모델 아키텍처를 사용합니다:

스레드	환경 변수	용도
Main	`ANTHROPIC_MODEL`	주요 코드 생성, 대화, 복잡한 작업
Haiku	`ANTHROPIC_DEFAULT_HAIKU_MODEL`	파일 감시, linter 검사, 자동 완성, 백그라운드 작업

일반적인 조합: 메인 스레드는 claude-opus-4-7 또는 claude-sonnet-4-6으로 무거운 작업, haiku 스레드는 claude-haiku-4-5-20251001로 백그라운드 작업 — 높은 품질과 낮은 토큰 비용.

5.3 권장 설정 (듀얼 모델)

Mac / Linux
Windows CMD
Windows PowerShell

export ANTHROPIC_BASE_URL="https://api.gravitex.ai"
export ANTHROPIC_AUTH_TOKEN="sk-zbTYx*******************************fceTvn5"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
cd your-project-folder
claude

set ANTHROPIC_BASE_URL=https://api.gravitex.ai
set ANTHROPIC_AUTH_TOKEN=sk-zbTYx*******************************fceTvn5
set ANTHROPIC_MODEL=claude-sonnet-4-6
set ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
cd your-project-folder
claude

$env:ANTHROPIC_BASE_URL="https://api.gravitex.ai"
$env:ANTHROPIC_AUTH_TOKEN="sk-zbTYx*******************************fceTvn5"
$env:ANTHROPIC_MODEL="claude-sonnet-4-6"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
cd your-project-folder
claude

5.4 단일 모델 (선택)

하나의 모델만 사용하려면 두 가지 방법이 있습니다: 옵션 A — 두 환경 변수를 동일한 모델로 설정

export ANTHROPIC_BASE_URL="https://api.gravitex.ai"
export ANTHROPIC_AUTH_TOKEN="sk-zbTYx*******************************fceTvn5"
export ANTHROPIC_MODEL="kimi-k2-250905"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="kimi-k2-250905"
cd your-project-folder
claude

옵션 B — 세션 내 전환 듀얼 모델 설정을 유지하고 Claude Code를 시작한 뒤, 대화형 UI에서:

/model haiku

메인 스레드가 ANTHROPIC_DEFAULT_HAIKU_MODEL의 모델로 전환됩니다.

6. 추천 조합 (GravitexAI 경유)

시나리오	Main (`ANTHROPIC_MODEL`)	Haiku (`ANTHROPIC_DEFAULT_HAIKU_MODEL`)
프로덕션 (최고)	`claude-opus-4-7`	`claude-haiku-4-5-20251001`
일상 개발 (권장)	`claude-sonnet-4-6`	`claude-haiku-4-5-20251001`
비용 최적화	`kimi-k2-250905`	`claude-haiku-4-5-20251001`
긴 컨텍스트	`claude-sonnet-4-5-20250929` (200K)	`claude-haiku-4-5-20251001`
빠른 스모크 테스트	`claude-haiku-4-5-20251001`	`claude-haiku-4-5-20251001`

전체 ID는 GravitexAI 모델 카탈로그를 참조하세요.

7. FAQ

401 / invalid API key

ANTHROPIC_AUTH_TOKEN에 불필요한 공백이나 줄바꿈이 없는지 확인하세요.
GravitexAI 콘솔에서 키가 활성 상태인지 확인하세요.
잔액이 양수인지 확인하세요.

404 / wrong endpoint

Claude Code의 경우 ANTHROPIC_BASE_URL에 /v1을 붙이지 마세요. https://api.gravitex.ai를 사용하세요 (Anthropic 프로토콜은 OpenAI와 다릅니다).

Claude Code 내에서 모델을 전환하려면?

대화형 UI에서:

/model              # show current model
/model haiku        # switch to ANTHROPIC_DEFAULT_HAIKU_MODEL
/model sonnet       # alias supported in some versions

또는 종료 후 환경 변수를 변경하고 다시 실행하세요.

`model not found` 오류

GravitexAI 모델 목록의 전체 ID를 사용하세요, 예:

✅ claude-sonnet-4-5-20250929
❌ claude-sonnet-4-5

버전 접미사가 필요합니다.

토큰 비용을 줄이려면?

Haiku를 백그라운드 스레드로 사용하는 듀얼 모델 설정을 권장합니다.
--max-turns 등 플래그로 대화 길이를 제한하세요.
.claude/ 아래에 프로젝트 메모리를 유지하여 컨텍스트 반복을 피하세요.
/clear로 오래된 컨텍스트를 제거하세요.

팀 전체 설정?

환경 변수를 프로젝트 .env, 셸 프로필 또는 direnv에 넣으세요. 각 엔지니어는 자신의 ANTHROPIC_AUTH_TOKEN만 교체하면 됩니다.

8. 참고 자료

Claude Code 공식 문서: https://docs.anthropic.com/ko/docs/claude-code
GravitexAI 콘솔: https://maas.gravitex.ai
모델 카탈로그: https://maas.gravitex.ai/#/models
API 키: https://maas.gravitex.ai/#/keys

대화형 AI

프로그래밍 개발

AI 에이전트

기술 엔지니어링

번역

1. 개요

멀티 벤더 액세스

듀얼 스레드 모델

구독 불필요

글로벌 안정성

2. Node.js 설치 (이미 설치된 경우 건너뛰기)

다른 프록시 클라이언트 제거 (선택)

3. Claude Code 설치

4. GravitexAI 키 발급

5. 환경 변수 설정

5.1 기본 예시 (단일 모델)

5.2 듀얼 스레드 아키텍처

5.3 권장 설정 (듀얼 모델)

5.4 단일 모델 (선택)

6. 추천 조합 (GravitexAI 경유)

7. FAQ

8. 참고 자료

​1. 개요

멀티 벤더 액세스

듀얼 스레드 모델

구독 불필요

글로벌 안정성

​2. Node.js 설치 (이미 설치된 경우 건너뛰기)

​다른 프록시 클라이언트 제거 (선택)

​3. Claude Code 설치

​4. GravitexAI 키 발급

​5. 환경 변수 설정

​5.1 기본 예시 (단일 모델)

​5.2 듀얼 스레드 아키텍처

​5.3 권장 설정 (듀얼 모델)

​5.4 단일 모델 (선택)

​6. 추천 조합 (GravitexAI 경유)

​7. FAQ

​8. 참고 자료

1. 개요

2. Node.js 설치 (이미 설치된 경우 건너뛰기)

다른 프록시 클라이언트 제거 (선택)

3. Claude Code 설치

4. GravitexAI 키 발급

5. 환경 변수 설정

5.1 기본 예시 (단일 모델)

5.2 듀얼 스레드 아키텍처

5.3 권장 설정 (듀얼 모델)

5.4 단일 모델 (선택)

6. 추천 조합 (GravitexAI 경유)

7. FAQ

8. 참고 자료