cd ..

Free-Claude-Code: Claude Code를 무료로 사용하는 방법

# AI Agent # Claude Code # Open Source # Data & Infrastructure # Developer Tools
정석

Free-Claude-Code

Claude Code는 강력한 AI 코딩 어시스턴트지만, 비용이 부담스러울 수 있습니다. API 사용량이 늘어날수록 비용도 함께 증가하죠. 무료 티어는 있지만, 복잡한 프로젝트에서는 금방 한계에 도달합니다.

Free-Claude-Code는 이 문제를 우아하게 해결합니다. Claude Code와 호환되는 프록시 서버를 로컬에 띄우고, 다양한 무료 및 저렴한 모델 프로바이더로 요청을 라우팅해줍니다. 환경 변수 2개만 설정하면 바로 사용할 수 있습니다.

1. 왜 Free-Claude-Code인가

Claude Code의 비용 문제

Claude Code는 Anthropic API를 사용합니다. Opus, Sonnet, Haiku 모델별로 가격이 다르지만, 집중적인 코딩 세션에서는 비용이 금방 쌓입니다. 특히:

Free-Claude-Code의 접근 방식

Free-Claude-Code는 Claude Code가 Anthropic API에 요청을 보낼 때, 이를 가로채서 다른 프로바이더로 전달합니다. 마치 Claude Code가 Anthropic 서버와 대화하는 것처럼 보이지만, 실제로는:

이와 통신하게 됩니다.

2. 지원 프로바이더: 4가지 선택지

🟢 NVIDIA NIM — 1분당 40회 무료 요청

NVIDIA NIM API는 놀라울 정도로 관대한 무료 티어를 제공합니다:

Claude Code의 Haiku 수준 작업에 완벽합니다. 코드 리뷰, 간단한 리팩토링, 문서 작성 같은 가벼운 작업은 NVIDIA NIM으로 처리하고, 복잡한 아키텍처 결정만 유료 모델로 남겨둘 수 있습니다.

🔵 OpenRouter — 수백 개 모델의 통합 게이트웨이

OpenRouter는 하나의 API로 수백 개의 LLM에 접근할 수 있는 통합 게이트웨이입니다:

특히 무료 또는 저렴한 모델들이 많아, 비용을 크게 줄이면서도 다양한 모델을 실험해볼 수 있습니다.

🟣 LM Studio — 완전 로컬, 완전 무료

LM Studio는 로컬 머신에서 LLM을 실행하는 가장 쉬운 방법입니다:

로컬 서버를 http://localhost:1234에 띄우면 Free-Claude-Code가 자동으로 연결됩니다. 민감한 코드베이스 작업에 이상적입니다.

🟠 llama.cpp — 경량 로컬 추론

llama.cpp는 C++로 작성된 초경량 LLM 추론 엔진입니다:

Raspberry Pi나 오래된 노트북에서도 AI 코딩 어시스턴트를 돌릴 수 있습니다.

3. 드롭인 리플레이스먼트: 환경 변수 2개면 끝

터미널에서 실행

Free-Claude-Code의 가장 큰 장점은 설정의 단숨함입니다. Claude Code 쪽은 전혀 건드릴 필요가 없습니다.

# 설치
pipx install free-claude-code

# 초기화 (설정 파일 생성)
fcc-init

# 프록시 서버 시작
free-claude-code

# 다른 터미널에서 Claude Code 실행
ANTHROPIC_AUTH_TOKEN="freecc" \
ANTHROPIC_BASE_URL="http://localhost:8082" \
claude

이게 전부입니다. ANTHROPIC_BASE_URL이 Claude Code에게 “Anthropic 대신 이 서버에 물어봐”라고 알려주고, ANTHROPIC_AUTH_TOKEN은 프록시가 요청을 인식하는 데 사용됩니다.

4. 모델 매핑: Opus/Sonnet/Haiku를 다른 모델로 라우팅

Claude Code는 내부적으로 Opus, Sonnet, Haiku 세 가지 모델을 사용합니다. Free-Claude-Code는 이를 다른 프로바이더의 모델로 매핑합니다:

Claude 모델기본 매핑 (NVIDIA NIM)대안
Opusmeta/llama-3.1-405b-instructGPT-4o, Claude 3.5 Sonnet (OpenRouter)
Sonnetmeta/llama-3.1-70b-instructMistral Large, Gemini Pro
Haikumeta/llama-3.1-8b-instructPhi-3, Gemma 2

설정 파일에서 이 매핑을 자유롭게 변경할 수 있습니다:

# ~/.config/free-claude-code/config.yaml
providers:
  nvidia:
    models:
      opus: "meta/llama-3.3-70b-instruct"
      sonnet: "meta/llama-3.1-70b-instruct"
      haiku: "meta/llama-3.2-3b-instruct"

5. Thinking Token 지원: 추론 과정을 Claude 포맷으로 변환

최신 모델들은 “thinking” 또는 “reasoning” 토큰을 지원합니다. DeepSeek-R1, o1, o3 같은 모델들이 대표적입니다. 이 모델들은 답변 전에 긴 사고 과정을 거칩니다.

Free-Claude-Code는 이를 Claude가 이해할 수 있는 형식으로 변환합니다:

덕분에 DeepSeek-R1 같은 강력한 추론 모델을 Claude Code에서 마치 Claude Opus처럼 사용할 수 있습니다.

6. 휴리스틱 툴 파서: 텍스트로 된 툴 콜을 자동 파싱

일부 오픈 모델들은 툴 콜을 JSON 형식으로 반환하지 않고, 텍스트로 반환하는 경우가 있습니다:

I'll read the file for you.
[TOOL_CALL: read_file]
path: src/main.ts
[/TOOL_CALL]

Free-Claude-Code는 이런 비표준 출력을 자동으로 감지하고, Claude Code가 이해할 수 있는 표준 툴 콜 포맷으로 변환합니다. 정규식 기반 휴리스틱을 사용하여:

이 기능 덕분에 툴 콜이 지원되지 않는 모델도 Claude Code와 함께 사용할 수 있습니다.

7. 요청 최적화: 5가지 Trivial 요청 로컬 처리

Claude Code는 때로 매우 단순한 요청도 API로 보냅니다. Free-Claude-Code는 이를 로컬에서 처리하여 API 호출을 아예 만들지 않습니다:

요청 타입로컬 처리 방식
Quota Probes”API 키가 유효한가?” 같은 쿼타 확인 → 항상 “yes” 반환
Title Generation대화 제목 생성 → 첫 메시지에서 자동 생성
Prefix Detection”이 파일은 어떤 언어인가?” → 파일 확장자로 판별
Suggestions다음에 물어볼 만한 것 → 정적 템플릿에서 선택
Filepath Extraction”이 경로의 파일을 읽어줘” → 경로만 파싱

이 5가지는 전체 요청의 상당 부분을 차지합니다. 이를 로컬에서 처리함으로써 실제 API 호출을 30-50%까지 줄일 수 있습니다.

8. 스마트 레이트 리미팅: Proactive + Reactive

무료 API에는 항상 레이트 리밋이 따라옵니다. Free-Claude-Code는 이를 스마트하게 관리합니다:

Proactive Rolling-Window Throttle

Reactive 429 Exponential Backoff

rate_limiting:
  proactive:
    enabled: true
    safety_margin: 0.9  # 90%만 사용
  reactive:
    max_retries: 5
    base_delay_ms: 1000
    max_delay_ms: 60000

9. Discord/Telegram 봇: 원격 자율 코딩

Free-Claude-Code는 단순한 프록시를 넘어, 원격 코딩 플랫폼으로도 작동합니다:

Discord 봇

!code 이 프로젝트의 README를 작성해줘

Discord에서 명령을 보내면, Free-Claude-Code가:

  1. 메시지를 파싱
  2. 적절한 모델로 요청 전송
  3. 결과를 Discord로 스레드 형태로 반환

Telegram 봇

/commit 현재 변경사항을 커밋해줘

Telegram에서도 동일하게 작동합니다.

주요 기능

출장 중이나 회의에서도 폰으로 코딩 작업을 지시할 수 있습니다.

10. 서브에이전트 제어: Task Tool Interception

Claude Code는 복잡한 작업을 하위 에이전트에게 위임하는 Task 툴을 사용합니다. Free-Claude-Code는 이를 가로채서:

subagent:
  model_mapping:
    default: haiku  # 서브에이전트는 기본적으로 Haiku 사용
  max_concurrent: 3  # 동시에 최대 3개만
  log_to_file: true

11. 확장 가능한 아키텍처: BaseProvider와 MessagingPlatform

Free-Claude-Code는 확장성을 염두에 두고 설계되었습니다:

BaseProvider ABC

새로운 모델 프로바이더를 추가하려면 BaseProvider를 상속받아 몇 가지 메서드만 구현하면 됩니다:

class MyProvider(BaseProvider):
    async def complete(self, messages, model, tools):
        # API 호출 로직
        pass
    
    async def stream(self, messages, model, tools):
        # 스트리밍 응답
        pass

MessagingPlatform ABC

Discord나 Telegram 외에 다른 플랫폼도 추가할 수 있습니다:

class SlackPlatform(MessagingPlatform):
    async def send_message(self, channel, content):
        # Slack API 호출
        pass
    
    async def receive_messages(self):
        # 메시지 수신 루프
        pass

12. 실전 설정 예시

개발자용 기본 설정

# ~/.config/free-claude-code/config.yaml
provider: nvidia

providers:
  nvidia:
    api_key: "${NVIDIA_API_KEY}"
    base_url: "https://integrate.api.nvidia.com/v1"
    models:
      opus: "meta/llama-3.3-70b-instruct"
      sonnet: "meta/llama-3.1-70b-instruct"
      haiku: "meta/llama-3.2-3b-instruct"

rate_limiting:
  proactive:
    enabled: true
  reactive:
    max_retries: 5

optimizations:
  local_trivial_handling: true
  tool_call_parsing: true

프라이버시 중심 설정

provider: lmstudio

providers:
  lmstudio:
    base_url: "http://localhost:1234/v1"
    models:
      opus: "local-model"
      sonnet: "local-model"
      haiku: "local-model"

messaging:
  enabled: false  # 외부 통신 비활성화

하이브리드 설정

# 복잡한 건 OpenRouter, 간단한 건 NVIDIA NIM
provider: openrouter

providers:
  openrouter:
    api_key: "${OPENROUTER_API_KEY}"
    models:
      opus: "anthropic/claude-3.5-sonnet"  # 유료지만 강력
      sonnet: "google/gemini-2.0-flash-exp:free"  # 무료
      haiku: "meta-llama/llama-3.2-3b-instruct:free"  # 무료

fallback_provider: nvidia  # OpenRouter 실패 시 NVIDIA로

13. 설치 및 빠른 시작

pipx로 설치 (권장)

pipx install free-claude-code
fcc-init
free-claude-code

uv로 설치

uv tool install free-claude-code
fcc-init
free-claude-code

소스에서 설치

git clone https://github.com/your-repo/free-claude-code.git
cd free-claude-code
pip install -e .
fcc-init
free-claude-code

Claude Code와 함께 실행

# 터미널 1: 프록시 서버
free-claude-code

# 터미널 2: Claude Code
ANTHROPIC_AUTH_TOKEN="freecc" \
ANTHROPIC_BASE_URL="http://localhost:8082" \
claude

마치며: Claude Code의 진입 장벽을 낮추다

Free-Claude-Code는 Claude Code를 “부자 전용 도구”에서 “모두의 도구”로 만듭니다. NVIDIA NIM의 관대한 무료 티어, OpenRouter의 다양한 모델, LM Studio의 완전 로컬 실행 — 이 모든 것을 환경 변수 2개만으로 연결합니다.

특히 인상적인 것은 휴리스틱 툴 파서와 로컬 trivial 처리입니다. 이 기능들은 단순히 비용을 아끼는 것을 넘어, Claude Code의 사용성 자체를 개선합니다. API 호출이 줄어들면 응답도 빨라지고, 레이트 리밋 걱정도 줄어듭니다.

로컬 모델로 완전히 무료로 사용하든, 유료 모델과 무료 모델을 섞어서 사용하든 — 선택은 사용자의 몫입니다. Free-Claude-Code는 그 선택을 가능하게 합니다.

Claude Code를 써보고 싶었지만 비용이 걱정되셨다면, 지금 바로 Free-Claude-Code를 설치해보세요.

🔗 관련 정보

# AI Agent # Claude Code # Open Source # Data & Infrastructure # Developer Tools
Compartir
이전
LLMFit: 당신의 하드웨어에 맞는 LLM을 찾아주는 도구
다음
CocoIndex-Code: 70% 토큰을 절약하는 AST 기반 코드 검색 MCP