> ## Documentation Index
> Fetch the complete documentation index at: https://veniceai-mintlify-de47a659.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Claude Code Router를 사용해 Venice를 통해 Claude 모델로 Claude Code를 실행하세요.

[Claude Code](https://code.claude.com/docs)는 Anthropic의 에이전트 코딩용 CLI 도구입니다. 이 가이드는 익명화된 토큰 단위 결제로 Claude 모델을 사용할 수 있도록 Venice를 통해 Claude Code를 실행하는 방법을 보여줍니다.

<CardGroup cols={3}>
  <Card title="토큰 단위 결제" icon="coins">
    구독 없이 사용한 만큼만 지불
  </Card>

  <Card title="Claude 모델" icon="cpu">
    Venice를 통해 최신 Opus, Sonnet 및 Fable 모델에 접근
  </Card>

  <Card title="Prompt 캐싱" icon="bolt">
    Venice 캐싱이 Claude Code와 함께 작동
  </Card>
</CardGroup>

## 라우터가 필요한 이유

Claude Code는 기본적으로 Anthropic API에 직접 연결됩니다. Venice와 함께 사용하려면 다음 작업을 수행하는 오픈소스 로컬 프록시인 [claude-code-router](https://github.com/musistudio/claude-code-router)가 필요합니다:

<Steps>
  <Step title="가로채기" icon="hand-stop">
    Claude Code의 outgoing 요청이 Anthropic에 도달하기 전에 잡아냅니다
  </Step>

  <Step title="변환" icon="refresh">
    Anthropic Messages 요청을 Venice의 OpenAI 호환 chat 포맷으로 변환합니다
  </Step>

  <Step title="리다이렉트" icon="route">
    요청을 `api.venice.ai/api/v1/chat/completions`로 전달합니다
  </Step>
</Steps>

***

## 사전 요구사항

<CardGroup cols={3}>
  <Card title="Venice 계정" icon="user" href="https://venice.ai/settings/api?utm_source=venice-api-documentation">
    Venice 크레딧이 있는 계정
  </Card>

  <Card title="Node.js" icon="brand-nodejs" href="https://nodejs.org/">
    v22 이상
  </Card>

  <Card title="Claude Code" icon="terminal" href="https://code.claude.com/docs">
    npm으로 설치된 상태
  </Card>
</CardGroup>

***

## 설정

<Steps>
  <Step title="Claude Code 설치 또는 업데이트">
    최신 Claude Code CLI를 설치하세요:

    ```bash theme={null}
    npm install -g @anthropic-ai/claude-code@latest
    claude --version
    ```
  </Step>

  <Step title="Claude Code Router 설치">
    ```bash theme={null}
    npm install -g @musistudio/claude-code-router@latest
    npm list -g @musistudio/claude-code-router --depth=0
    ```
  </Step>

  <Step title="API 키 발급">
    [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation)에서 키를 생성하세요. 다음 단계에서 CCR에 추가하게 됩니다.
  </Step>

  <Step title="Venice를 프로바이더로 추가">
    CCR의 관리 UI를 시작하세요:

    ```bash theme={null}
    ccr ui
    ```

    **Providers** 페이지에서 **Add provider**를 선택한 다음 **Other / custom API endpoint**를 선택하세요. 다음을 입력합니다:

    * **Name:** `Venice`
    * **API endpoint:** `https://api.venice.ai/api/v1`
    * **API key:** 여러분의 Venice API 키

    CCR이 **OpenAI Chat**을 자동으로 감지할 것입니다. 감지하지 못하면 **Advanced settings**를 열고 자동 프로토콜 감지를 끈 뒤 **OpenAI Chat**을 선택하세요.

    **Search models** 또는 **Custom models**를 사용해 원하는 Claude 모델을 추가한 다음, **Check Connection**을 실행하고 프로바이더를 저장하세요. 연결 확인은 출력 토큰을 1개로 제한한 실제 요청을 전송합니다.
  </Step>

  <Step title="Claude Code 프로필 생성">
    **Agent Config**에서 **Add profile**을 선택한 다음 **Claude Code**를 선택하세요:

    * 프로필 이름을 `Claude Code - Venice`로 지정하세요.
    * 테스트하는 동안에는 **Effect scope**를 **Only opened from CCR**로 유지하세요.
    * **CLI only** 또는 **CLI & APP**을 선택하세요.
    * **Model**을 `Venice/claude-opus-4-8` 같은 Venice 모델로 설정하세요.
    * Claude Code의 모든 티어를 Venice에서 유지하려면 선택 사항인 Fable, Opus, Sonnet, Haiku 모델 필드도 Venice 모델로 설정하세요.

    프로필을 저장하세요.
  </Step>

  <Step title="실행 및 확인">
    프로필 이름으로 실행하세요:

    ```bash theme={null}
    ccr "Claude Code - Venice"
    ```

    Claude Code에서:

    1. `/context`를 실행해 컨텍스트 윈도우가 선택한 모델과 일치하는지 확인하세요. `claude-opus-4-8`의 경우 `1M`이 표시되어야 합니다.
    2. 다른 Venice 모델로 전환하고 싶다면 `/model`을 실행하세요. 1M 버전에는 **1M context** 표시가 있습니다.
    3. 테스트 메시지를 보낸 다음 CCR의 **Request logs**에서 Venice가 사용되었는지 확인하세요.
  </Step>
</Steps>

***

## 지원 모델

| 모델                   | Venice ID              | 컨텍스트 |
| -------------------- | ---------------------- | ---- |
| Claude Fable 5.1     | `claude-fable-5-1`     | 1M   |
| Claude Fable 5       | `claude-fable-5`       | 1M   |
| Claude Opus 5        | `claude-opus-5`        | 1M   |
| Claude Opus 5 Fast   | `claude-opus-5-fast`   | 1M   |
| Claude Opus 4.8      | `claude-opus-4-8`      | 1M   |
| Claude Opus 4.8 Fast | `claude-opus-4-8-fast` | 1M   |
| Claude Opus 4.7      | `claude-opus-4-7`      | 1M   |
| Claude Opus 4.6      | `claude-opus-4-6`      | 1M   |
| Claude Opus 4.5      | `claude-opus-4-5`      | 198K |
| Claude Sonnet 5      | `claude-sonnet-5`      | 1M   |
| Claude Sonnet 4.6    | `claude-sonnet-4-6`    | 1M   |
| Claude Sonnet 4.5    | `claude-sonnet-4-5`    | 198K |

카탈로그는 시간이 지나면서 변경됩니다. 최신 목록과 한도는 CCR의 **Search models** 또는 [`GET /models?type=text`](/api-reference/endpoint/models/list)를 사용하세요.

<Info>
  Claude Code는 Claude 모델에 최적화되어 있습니다. Venice를 통해 제공되는 다른 모델(GPT, DeepSeek, Grok 등)도 동작할 수 있지만, Claude Code는 extended thinking 등 Claude 고유 기능에 의존하므로 동일한 경험을 보장할 수는 없습니다. 다른 모델의 경우 Venice의 [표준 API](/api-reference/endpoint/chat/completions) 사용을 고려하세요.
</Info>

***

## 기존 설치 업데이트

기존 설치의 문제를 해결하기 전에 CCR을 업데이트하세요:

```bash theme={null}
npm install -g @musistudio/claude-code-router@latest
npm list -g @musistudio/claude-code-router --depth=0
ccr ui
```

최신 CCR 릴리스는 실시간 설정을 `~/.claude-code-router/config.sqlite`에 저장합니다. 데이터베이스가 없는 경우 기존 `config.json`을 가져옵니다. 마이그레이션 후에는 `config.json`을 계속 편집하지 말고 `ccr ui`를 통해 변경하세요.

업데이트 후에도 백그라운드 프로세스가 계속 실행 중이라면 재시작하세요:

```bash theme={null}
ccr stop
ccr start
```

***

## Prompt 캐싱

Venice [prompt 캐싱](/guides/features/prompt-caching)은 Claude Code의 네이티브 캐시 마커와 함께 동작합니다. 일반적인 설정에서는 추가 캐시 transformer가 필요하지 않습니다.

***

## 문제 해결

<AccordionGroup>
  <Accordion title="컨텍스트가 일찍 100%에 도달하거나 압축(compaction)에 실패하는 경우">
    1. `npm install -g @musistudio/claude-code-router@latest`로 CCR을 업데이트하세요.
    2. CCR 프로필에서 새 Claude Code 세션을 실행하세요.
    3. `/model`을 실행하고 **1M context** 표시가 있는 Venice 항목을 선택하세요.
    4. `/context`를 실행해 윈도우가 `200K`가 아니라 `1M`인지 확인하세요.

    이전 CCR 릴리스는 올바른 컨텍스트 윈도우나 토큰 사용량을 Claude Code에 노출하지 못할 수 있습니다.
  </Accordion>

  <Accordion title="CCR이 시작 중에 크래시하는 경우">
    Node.js 22 이상인지 확인하고 CCR을 업데이트하세요:

    ```bash theme={null}
    node --version
    npm list -g @musistudio/claude-code-router --depth=0
    ```

    `ccr serve`를 사용해 포그라운드로 실행하면 원래의 시작 에러를 확인할 수 있습니다. `server.logger.error`에서 발생하는 `Cannot read properties of undefined (reading 'error')` 스택은 CCR 설치가 오래되었다는 의미이므로, 추가 조사에 앞서 먼저 업데이트하세요.
  </Accordion>

  <Accordion title="Claude Code가 ConnectionRefused를 보고하는 경우">
    게이트웨이를 시작하고 상태를 확인하세요:

    ```bash theme={null}
    ccr start
    curl http://127.0.0.1:3456/health
    ```

    상태 확인에 실패하면 로컬 CCR 게이트웨이를 사용할 수 없다는 의미이며, 요청은 Venice에 도달하지 않은 것입니다.
  </Accordion>

  <Accordion title="설정 변경이 무시되는 경우">
    `ccr ui`를 열고 그곳에서 변경하세요. 최신 CCR 릴리스는 설정을 `config.sqlite`에 저장하며, `config.json`은 이전 설치를 위한 마이그레이션 소스일 뿐입니다.
  </Accordion>
</AccordionGroup>

***

## 리소스

<CardGroup cols={3}>
  <Card title="Venice API 문서" icon="book" href="/api-reference/api-spec">
    전체 API 레퍼런스
  </Card>

  <Card title="claude-code-router" icon="brand-github" href="https://github.com/musistudio/claude-code-router">
    소스 코드 및 이슈
  </Card>

  <Card title="CCR 릴리스" icon="history" href="https://github.com/musistudio/claude-code-router/releases">
    최신 버전 및 릴리스 노트
  </Card>
</CardGroup>