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

# Claude Code

> Venice AI의 Claude 모델과 함께 Claude Code CLI를 사용하세요

[Claude Code](https://docs.anthropic.com/en/docs/claude-code)는 Anthropic의 에이전트 코딩용 CLI 도구입니다. 이 가이드는 Venice AI를 통해 토큰 단위 결제로 Claude Opus 4.5/4.6 및 Sonnet 4.5/4.6을 사용하는 방법을 보여줍니다.

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

  <Card title="Claude 모델" icon="microchip">
    Venice를 통해 Opus 4.5/4.6 및 Sonnet 4.5/4.6에 접근
  </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">
    Claude Code의 outgoing 요청이 Anthropic에 도달하기 전에 잡아냅니다
  </Step>

  <Step title="변환" icon="arrows-rotate">
    요청 포맷을 변환하고 모델 ID(예: `claude-opus-4-5`)를 매핑합니다
  </Step>

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

***

## 사전 요구사항

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

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

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

***

## 설정

<Steps>
  <Step title="Claude Code 설치">
    아직 설치하지 않았다면 Anthropic의 Claude Code CLI를 설치하세요:

    ```bash theme={"dark"}
    npm install -g @anthropic-ai/claude-code
    ```
  </Step>

  <Step title="라우터 설치">
    ```bash theme={"dark"}
    npm install -g @musistudio/claude-code-router
    ```
  </Step>

  <Step title="API 키 발급">
    [venice.ai/settings/api](https://venice.ai/settings/api)에서 키를 생성하세요. 다음 단계에서 설정 파일에 직접 붙여넣게 됩니다.
  </Step>

  <Step title="설정 파일 생성">
    config 디렉터리를 만드세요:

    ```bash theme={"dark"}
    mkdir -p ~/.claude-code-router
    ```

    그런 다음 원하는 에디터로 `~/.claude-code-router/config.json`을 만드세요:

    ```bash theme={"dark"}
    # nano 사용
    nano ~/.claude-code-router/config.json

    # 또는 VS Code 사용
    code ~/.claude-code-router/config.json
    ```

    다음 설정을 붙여넣으세요:

    ```json theme={"dark"}
    {
      "APIKEY": "",
      "LOG": true,
      "LOG_LEVEL": "info",
      "API_TIMEOUT_MS": 600000,
      "HOST": "127.0.0.1",
      "Providers": [
        {
          "name": "venice",
          "api_base_url": "https://api.venice.ai/api/v1/chat/completions",
          "api_key": "your-venice-api-key-here",
          "models": [
            "claude-opus-4-5",
            "claude-sonnet-4-5",
            "claude-opus-4-6",
            "claude-opus-4-6-fast",
            "claude-sonnet-4-6"
          ],
          "transformer": {
            "use": ["anthropic"]
          }
        }
      ],
      "Router": {
        "default": "venice,claude-opus-4-5",
        "think": "venice,claude-opus-4-5",
        "background": "venice,claude-opus-4-5",
        "longContext": "venice,claude-opus-4-5",
        "longContextThreshold": 100000
      }
    }
    ```

    <Note>
      라우터 실행 중에 `config.json`을 수정한 경우 `ccr restart`로 재시작해 변경 사항을 적용하세요.
    </Note>
  </Step>

  <Step title="실행">
    라우터를 시작한 다음 Claude Code를 실행하세요:

    ```bash theme={"dark"}
    ccr start
    ccr code
    ```

    또는 activate 방식을 사용하세요:

    ```bash theme={"dark"}
    eval "$(ccr activate)" && claude
    ```
  </Step>
</Steps>

***

## 지원 모델

| Model                | Venice ID              | Best For            |
| -------------------- | ---------------------- | ------------------- |
| Claude Opus 4.5      | `claude-opus-4-5`      | 복잡한 추론, 대규모 리팩토링    |
| Claude Sonnet 4.5    | `claude-sonnet-4-5`    | 빠른 반복, 일상적인 코딩      |
| Claude Opus 4.6      | `claude-opus-4-6`      | 복잡한 추론, 대규모 리팩토링    |
| Claude Opus 4.6 Fast | `claude-opus-4-6-fast` | 더 낮은 지연 시간으로 복잡한 추론 |
| Claude Sonnet 4.6    | `claude-sonnet-4-6`    | 빠른 반복, 일상적인 코딩      |

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

***

## 라우터 기능

라우터는 기본 라우팅 외에도 몇 가지 유용한 기능을 제공합니다:

<AccordionGroup>
  <Accordion title="실시간으로 모델 전환">
    Claude Code 내부에서 `/model` 명령으로 재시작 없이 모델을 전환할 수 있습니다:

    ```
    /model venice,claude-sonnet-4-5
    ```

    복잡한 작업에는 Opus, 빠른 반복에는 Sonnet 같은 식으로 활용하기 좋습니다.
  </Accordion>

  <Accordion title="UI 모드로 시각적 설정">
    GUI를 선호하시나요? 웹 기반 설정 편집기를 실행하세요:

    ```bash theme={"dark"}
    ccr ui
    ```

    파일을 직접 만지지 않고 `config.json`을 편집할 수 있는 브라우저 인터페이스가 열립니다.
  </Accordion>

  <Accordion title="라우터 시나리오 설명">
    `Router` 설정 섹션은 어떤 모델이 어떤 작업 유형을 처리할지 제어합니다:

    | Scenario      | When it's used                            |
    | ------------- | ----------------------------------------- |
    | `default`     | 일반 요청                                     |
    | `think`       | 추론이 많은 작업(Plan Mode)                      |
    | `background`  | 백그라운드 작업                                  |
    | `longContext` | context가 `longContextThreshold` 토큰을 초과할 때 |

    각 시나리오를 다른 모델로 라우팅할 수 있습니다. 예를 들어 백그라운드 작업에는 Sonnet을 사용해 비용을 절약할 수 있습니다.
  </Accordion>

  <Accordion title="로그로 디버깅">
    동작이 잘 안 된다면 로그를 확인하세요:

    ```bash theme={"dark"}
    # 서버 로그 (HTTP, API 호출)
    ~/.claude-code-router/logs/ccr-*.log

    # 애플리케이션 로그 (라우팅 결정)
    ~/.claude-code-router/claude-code-router.log
    ```

    더 자세한 출력을 보려면 설정에서 `"LOG_LEVEL": "debug"`로 설정하세요.
  </Accordion>
</AccordionGroup>

***

## 캐싱 동작

Venice [prompt 캐싱](/guides/features/prompt-caching)은 Claude Code의 네이티브 캐시 마커와 함께 동작합니다. Venice는 Claude Code가 `cache_control` 필드를 보낼 때 이를 자동으로 감지하고 캐싱 전략을 그에 맞게 조정합니다.

| Scenario                    | Cache TTL | Who Controls         |
| --------------------------- | --------- | -------------------- |
| 기본(권장)                      | 5분        | Claude Code + Venice |
| `cleancache` transformer 사용 | 1시간       | Venice 단독            |

<AccordionGroup>
  <Accordion title="cleancache를 사용하지 말아야 할 때(대부분의 사용자)">
    기본 설정은 두 시스템이 협력하도록 합니다:

    * Claude Code가 네이티브 `cache_control` 마커를 전송
    * Venice가 5분 TTL로 그 주변에 캐싱을 추가
    * 두 시스템이 4블록 캐시 한도를 공유

    빈번한 요청이 발생하는 활발한 코딩 세션에 잘 맞습니다.
  </Accordion>

  <Accordion title="cleancache를 사용해야 할 때">
    다음 경우에는 transformer에 `cleancache`를 추가하세요:

    * 4블록 캐시 한도 에러를 만나는 경우
    * 이상한 캐싱 동작을 경험하는 경우
    * 더 긴 세션을 위해 Venice의 1시간 TTL을 선호하는 경우

    ```json theme={"dark"}
    "transformer": {
      "use": ["anthropic", "cleancache"]
    }
    ```

    이렇게 하면 Claude Code의 캐시 마커가 제거되고 Venice가 더 긴 TTL로 완전한 제어권을 갖습니다.
  </Accordion>
</AccordionGroup>

***

## 리소스

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

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