Skip to main content
Claude Code는 Anthropic의 에이전트 코딩용 CLI 도구입니다. 이 가이드는 익명화된 토큰 단위 결제로 Claude 모델을 사용할 수 있도록 Venice를 통해 Claude Code를 실행하는 방법을 보여줍니다.

토큰 단위 결제

구독 없이 사용한 만큼만 지불

Claude 모델

Venice를 통해 최신 Opus, Sonnet 및 Fable 모델에 접근

Prompt 캐싱

Venice 캐싱이 Claude Code와 함께 작동

​
라우터가 필요한 이유

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

가로채기

Claude Code의 outgoing 요청이 Anthropic에 도달하기 전에 잡아냅니다

변환

Anthropic Messages 요청을 Venice의 OpenAI 호환 chat 포맷으로 변환합니다

리다이렉트

요청을 api.venice.ai/api/v1/chat/completions로 전달합니다

​
사전 요구사항

Venice 계정

Venice 크레딧이 있는 계정

Node.js

v22 이상

Claude Code

npm으로 설치된 상태

​
설정

1

Claude Code 설치 또는 업데이트

최신 Claude Code CLI를 설치하세요:
2

Claude Code Router 설치

3

API 키 발급

venice.ai/settings/api에서 키를 생성하세요. 다음 단계에서 CCR에 추가하게 됩니다.
4

Venice를 프로바이더로 추가

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개로 제한한 실제 요청을 전송합니다.
5

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 모델로 설정하세요.
프로필을 저장하세요.
6

실행 및 확인

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

​
지원 모델

카탈로그는 시간이 지나면서 변경됩니다. 최신 목록과 한도는 CCR의 Search models 또는 GET /models?type=text를 사용하세요.
Claude Code는 Claude 모델에 최적화되어 있습니다. Venice를 통해 제공되는 다른 모델(GPT, DeepSeek, Grok 등)도 동작할 수 있지만, Claude Code는 extended thinking 등 Claude 고유 기능에 의존하므로 동일한 경험을 보장할 수는 없습니다. 다른 모델의 경우 Venice의 표준 API 사용을 고려하세요.

​
기존 설치 업데이트

기존 설치의 문제를 해결하기 전에 CCR을 업데이트하세요:
최신 CCR 릴리스는 실시간 설정을 ~/.claude-code-router/config.sqlite에 저장합니다. 데이터베이스가 없는 경우 기존 config.json을 가져옵니다. 마이그레이션 후에는 config.json을 계속 편집하지 말고 ccr ui를 통해 변경하세요. 업데이트 후에도 백그라운드 프로세스가 계속 실행 중이라면 재시작하세요:

​
Prompt 캐싱

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

​
문제 해결

  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에 노출하지 못할 수 있습니다.
Node.js 22 이상인지 확인하고 CCR을 업데이트하세요:
ccr serve를 사용해 포그라운드로 실행하면 원래의 시작 에러를 확인할 수 있습니다. server.logger.error에서 발생하는 Cannot read properties of undefined (reading 'error') 스택은 CCR 설치가 오래되었다는 의미이므로, 추가 조사에 앞서 먼저 업데이트하세요.
게이트웨이를 시작하고 상태를 확인하세요:
상태 확인에 실패하면 로컬 CCR 게이트웨이를 사용할 수 없다는 의미이며, 요청은 Venice에 도달하지 않은 것입니다.
ccr ui를 열고 그곳에서 변경하세요. 최신 CCR 릴리스는 설정을 config.sqlite에 저장하며, config.json은 이전 설치를 위한 마이그레이션 소스일 뿐입니다.

​
리소스

Venice API 문서

전체 API 레퍼런스

claude-code-router

소스 코드 및 이슈

CCR 릴리스

최신 버전 및 릴리스 노트