챕터별 상세
Free Claude Code 프로젝트 소개
Claude Code는 훌륭한 도구이지만 장시간 코딩 세션이나 에이전트 작업 시 Anthropic API 비용이 빠르게 누적되는 문제가 있다. Free Claude Code는 Claude Code의 API 요청을 Anthropic 대신 다른 제공자로 라우팅하는 경량 프록시 서버이다. 이를 통해 NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, Ollama 등을 백엔드로 사용할 수 있다. 사용자는 Anthropic API 키 없이도 Claude Code의 워크플로를 그대로 유지하며 비용을 절감할 수 있다.
작동 원리 및 아키텍처
이 시스템은 Claude Code CLI 또는 VS Code 확장 프로그램과 실제 모델 제공자 사이에서 투명 프록시로 작동한다. Claude Code가 보낸 Anthropic API 형식의 요청을 프록시가 수신하여 설정된 백엔드 모델에 맞게 변환하여 전달한다. 결과값은 다시 Anthropic API 스트리밍 형식으로 변환되어 Claude Code로 전달되므로 클라이언트 측의 코드 수정이 필요 없다. 환경 변수에서 API 베이스 URL을 로컬 프록시 주소로 변경하는 것만으로 설정이 완료된다.
지원되는 모델 제공자 및 특징
NVIDIA NIM은 분당 40회 요청의 넉넉한 무료 티어를 제공하여 가장 추천되는 클라우드 백엔드이다. OpenRouter를 통해 수백 개의 모델을 선택하거나 DeepSeek의 저렴한 API를 직접 연결할 수도 있다. 완전한 프라이버시를 원하는 경우 Ollama, LM Studio, llama.cpp를 통해 로컬 머신에서 모델을 실행하는 방식도 지원한다. 각 모델 제공자별로 API 키와 베이스 URL을 설정 파일(.env)에 입력하여 관리할 수 있다.
설치 및 환경 설정 가이드
설치를 위해 Python 3.14와 uv 패키지 매니저가 필요하며 GitHub 저장소를 클론하거나 uv tool 명령어로 직접 설치할 수 있다. 설치 후 fcc-init 명령어를 실행하여 설정 폴더와 .env 템플릿 파일을 생성한다. .env 파일에서 사용할 모델 제공자의 API 키를 입력하고 모델명을 지정한다. 마지막으로 프록시 서버를 실행한 뒤 Claude Code 실행 시 ANTHROPIC_BASE_URL 환경 변수를 로컬 주소로 지정하면 연동이 완료된다.
bash
uv tool install git+https://github.com/Alishahryar1/free-claude-code.git
fcc-initFree Claude Code를 uv 도구를 사용하여 설치하고 초기 설정을 진행하는 명령어
bash
export ANTHROPIC_BASE_URL="http://localhost:8082/v1"
export ANTHROPIC_AUTH_TOKEN="freecc"
claudeClaude Code가 로컬 프록시 서버를 바라보도록 환경 변수를 설정하고 실행하는 방법
고급 기능: 모델 매핑 및 최적화
단순한 중계를 넘어 요청 최적화 기능을 내장하여 쿼터 확인이나 타이틀 생성 같은 사소한 요청은 로컬에서 직접 응답하여 API 소모를 줄인다. Opus, Sonnet, Haiku 등 Claude의 모델 등급별로 서로 다른 백엔드 모델을 매핑할 수 있는 기능을 제공한다. 예를 들어 복잡한 작업은 DeepSeek-R1으로, 간단한 작업은 로컬의 가벼운 모델로 라우팅하여 성능과 비용의 균형을 맞출 수 있다. 또한 무료 API의 속도 제한을 관리하기 위해 지수 백오프 및 동시성 제어 기능을 포함한다.
원격 코딩 세션 및 봇 지원
Discord 및 Telegram 봇 연동을 지원하여 터미널 밖에서도 코딩 에이전트를 제어할 수 있다. 봇을 통해 작업을 할당하고 실시간 진행 상황을 모니터링하며 여러 세션을 동시에 관리하는 것이 가능하다. 특히 음성 메모 기능을 지원하여 스마트폰에서 음성으로 코딩 작업을 지시하면 Whisper 모델이 이를 텍스트로 변환하여 에이전트에게 전달한다. 외부 노출 시 보안을 위해 Anthropic 스타일의 인증 토큰 설정이 권장된다.
용어 해설
- 프록시 서버(Proxy Server)
- — 클라이언트와 서버 사이에서 데이터를 중계하는 중간 서버이다. 이 프로젝트에서는 Claude Code의 API 요청을 가로채어 Anthropic 대신 다른 모델 제공자에게 전달하는 역할을 수행하여 비용 절감과 모델 선택의 유연성을 제공한다.
- 사고 토큰(Thinking Token)
- — 모델이 최종 답변을 내놓기 전 내부적인 추론 과정을 거칠 때 생성되는 토큰이다. Claude 3.5 Sonnet과 같은 최신 모델의 추론 능력을 다른 오픈소스 모델에서 모사하거나 해당 데이터를 처리하는 데 중요한 역할을 한다.
- 속도 제한(Rate Limiting)
- — 정해진 시간 내에 보낼 수 있는 API 요청의 수를 제한하는 기술이다. 무료 API 제공자나 로컬 서버의 부하를 방지하기 위해 필수적이며, 이 프로젝트는 지수 백오프 알고리즘을 통해 이를 효율적으로 관리한다.
언급된 리소스
AI 분석 전체 내용 보기
AI 요약 · 북마크 · 개인 피드 설정 — 무료
출처 · 인용 안내
원문 발행 2026. 04. 27.수집 2026. 04. 27.출처 타입 YOUTUBE
인용 시 "요약 출처: AI Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.
