> ## 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.

# Claude Code

> Claude Code 클라이언트 연동 가이드: GravitexAI를 통해 Claude / Kimi / GPT 원스톱 액세스

## 1. 개요

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

<CardGroup cols={2}>
  <Card title="멀티 벤더 액세스" icon="plug">
    하나의 엔드포인트로 Claude 전체 제품군, Kimi K2, GPT 등 사용
  </Card>

  <Card title="듀얼 스레드 모델" icon="microchip">
    무거운 작업은 메인 스레드, 가벼운 작업은 haiku 스레드
  </Card>

  <Card title="구독 불필요" icon="wallet">
    토큰당 과금 — Claude Pro 불필요
  </Card>

  <Card title="글로벌 안정성" icon="globe">
    자동 장애 조치를 갖춘 분산 노드
  </Card>
</CardGroup>

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

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

<Tabs>
  <Tab title="Windows">
    다운로드: [https://nodejs.org/dist/v22.18.0/node-v22.18.0-x64.msi](https://nodejs.org/dist/v22.18.0/node-v22.18.0-x64.msi)
  </Tab>

  <Tab title="macOS">
    ```bash theme={null}
    sudo xcode-select --install
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    brew install node
    node --version
    ```
  </Tab>

  <Tab title="Ubuntu / Debian">
    ```bash theme={null}
    curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo bash -
    sudo apt-get install -y nodejs
    node --version
    ```
  </Tab>
</Tabs>

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

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

```bash theme={null}
# 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 설치

<Steps>
  <Step title="전역 설치">
    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code
    ```
  </Step>

  <Step title="설치 확인">
    ```bash theme={null}
    claude --version
    ```
  </Step>
</Steps>

## 4. GravitexAI 키 발급

<Steps>
  <Step title="로그인">
    [GravitexAI 콘솔](https://maas.gravitex.ai)로 이동합니다.
  </Step>

  <Step title="키 생성">
    [API Keys](https://maas.gravitex.ai/#/keys) → 새 토큰을 생성합니다.
  </Step>

  <Step title="정보 확인">
    ```
    base_url = "https://api.gravitex.ai"
    api_key  = "sk-zbTYx*******************************fceTvn5"
    ```

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

## 5. 환경 변수 설정

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

<Tabs>
  <Tab title="Mac / Linux">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Windows CMD">
    ```cmd theme={null}
    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
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    $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
    ```
  </Tab>
</Tabs>

### 5.2 듀얼 스레드 아키텍처

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

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

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

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

<Tabs>
  <Tab title="Mac / Linux">
    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="Windows CMD">
    ```cmd theme={null}
    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
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    $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
    ```
  </Tab>
</Tabs>

### 5.4 단일 모델 (선택)

하나의 모델만 사용하려면 두 가지 방법이 있습니다:

**옵션 A — 두 환경 변수를 동일한 모델로 설정**

```bash theme={null}
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 모델 카탈로그](https://maas.gravitex.ai/#/models)를 참조하세요.

## 7. FAQ

<AccordionGroup>
  <Accordion title="401 / invalid API key">
    1. `ANTHROPIC_AUTH_TOKEN`에 불필요한 공백이나 줄바꿈이 없는지 확인하세요.
    2. [GravitexAI 콘솔](https://maas.gravitex.ai/#/keys)에서 키가 활성 상태인지 확인하세요.
    3. 잔액이 양수인지 확인하세요.
  </Accordion>

  <Accordion title="404 / wrong endpoint">
    Claude Code의 경우 `ANTHROPIC_BASE_URL`에 **`/v1`을 붙이지 마세요**. `https://api.gravitex.ai`를 사용하세요 (Anthropic 프로토콜은 OpenAI와 다릅니다).
  </Accordion>

  <Accordion title="Claude Code 내에서 모델을 전환하려면?">
    대화형 UI에서:

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

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

  <Accordion title="`model not found` 오류">
    [GravitexAI 모델 목록](https://maas.gravitex.ai/#/models)의 **전체 ID**를 사용하세요, 예:

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

    버전 접미사가 필요합니다.
  </Accordion>

  <Accordion title="토큰 비용을 줄이려면?">
    1. Haiku를 백그라운드 스레드로 사용하는 **듀얼 모델** 설정을 권장합니다.
    2. `--max-turns` 등 플래그로 대화 길이를 제한하세요.
    3. `.claude/` 아래에 프로젝트 메모리를 유지하여 컨텍스트 반복을 피하세요.
    4. `/clear`로 오래된 컨텍스트를 제거하세요.
  </Accordion>

  <Accordion title="팀 전체 설정?">
    환경 변수를 프로젝트 `.env`, 셸 프로필 또는 `direnv`에 넣으세요. 각 엔지니어는 자신의 `ANTHROPIC_AUTH_TOKEN`만 교체하면 됩니다.
  </Accordion>
</AccordionGroup>

## 8. 참고 자료

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