FreeLLMAPI 설치·사용법: Claude Code에 무료 AI 모델 연결하기

Claude Code 한도에 도달했을 때, FreeLLMAPI로 다른 회사의 무료 AI 모델을 연결해 작업을 이어가는 방법이 있습니다. Claude Code가 파일을 읽고 작업하는 환경은 유지하면서, 답변을 만드는 모델의 연결 경로를 바꾸는 방식입니다. Claude Opus나 Claude Sonnet을 무료로 제공하거나 Anthropic의 사용 한도를 초기화하는 도구는 아닙니다.

쇼츠에서는 “무료 키를 연결하고, 한 모델이 막히면 다음 모델로 넘긴다”고 소개했는데요. 실제로 따라 하려면 어떤 키를 어디에 넣는지, 주소 끝에 /v1을 붙이는지, 정말 무료 모델이 응답했는지까지 확인해야 합니다. 이 글에서는 설치 순서와 복사용 프롬프트, 직접 실행할 명령어, 연결이 안 될 때의 점검 방법까지 정리했습니다.

FreeLLMAPI란? Claude Code와 무료 AI 모델을 연결하는 도구

FreeLLMAPI는 여러 AI 제공업체의 API를 하나의 주소와 키로 연결하는 오픈소스 라우터입니다. 라우터는 요청을 받아 어디로 보낼지 정하는 중간 관리자라고 생각하면 됩니다. FreeLLMAPI는 Anthropic이 만든 제품이 아닌 별도의 커뮤니티 프로젝트입니다. FreeLLMAPI 공식 저장소

예를 들어 Google Gemini와 Groq, OpenRouter의 API 키를 FreeLLMAPI에 등록합니다. Claude Code에는 각 회사 키 대신 FreeLLMAPI의 주소와 통합 키(Unified API Key)를 알려줍니다.

여기서 Claude Code는 작업 도구, Gemini 등은 답변을 만드는 모델, Groq·OpenRouter 등은 모델 API를 제공하는 서비스입니다. 서비스 이름과 그 안에서 선택하는 모델 이름은 다를 수 있습니다.

왜 필요한가요? 한도에 막혔을 때 작은 작업을 이어가기 위해서입니다

FreeLLMAPI의 장점은 여러 무료 API의 연결과 전환을 한곳에서 관리한다는 점입니다. 서비스를 바꿀 때마다 Claude Code 설정을 다시 수정하는 수고를 줄일 수 있습니다.

예를 들어 개인 프로젝트를 만들다가 Claude 사용 한도에 도달했다고 해보세요. 남은 일이 README 정리, 짧은 함수 설명, 작은 테스트 예시 작성이라면 대체 모델로 진행해볼 만합니다. 반면 프로젝트 전체 설계를 바꾸거나 여러 파일을 동시에 고치는 작업은, 먼저 작은 범위에서 모델의 결과를 확인하는 편이 좋습니다.

설치 전 준비물과 무료 사용 범위

Claude Code, FreeLLMAPI 앱, 제공업체 API 키, 설정 명령을 실행할 터미널이 필요합니다. 아래 실습은 터미널에서 사용하는 Claude Code CLI를 기준으로 합니다.

• Claude Code: 설치되어 있어야 합니다. 공식 설치 안내를 참고하세요.
• FreeLLMAPI: Windows·macOS·Linux용 앱을 설치합니다.
• API 키: 처음에는 한 곳으로 연결을 확인하고, 전환용으로 다른 제공업체를 추가하세요.
• Node.js와 npx: 아래 setup-claude 명령에 필요합니다. CLI 0.7.0의 지원 범위는 Node.js 20.18 이상·25 미만입니다. 이 실습에는 Node.js 24.x를 사용할 수 있습니다. Node.js 다운로드 · CLI 패키지 요구 사항

무료인지 확인할 때는 프로그램 가격과 모델 API 요금을 나눠서 보세요. FreeLLMAPI 라우터는 무료 오픈소스이며, 실시간 모델 카탈로그 업데이트를 위한 선택형 Premium도 있습니다. API 비용은 연결한 제공업체·모델·계정의 요금제에 따릅니다. 유료 API 키나 유료 모델을 연결한다고 무료 호출로 바뀌지는 않습니다. FreeLLMAPI 무료·Premium 구분

Google은 모델마다 무료 티어 제공 여부가 다릅니다. Groq는 분당 요청 수뿐 아니라 토큰 한도도 적용합니다. OpenRouter도 무료 모델에 별도 제한을 둡니다. 그래서 “키 세 개면 하루 종일 무제한”처럼 계산할 수 없습니다. Gemini 가격표 · Groq 한도 · OpenRouter 한도

1단계. FreeLLMAPI 설치하고 Dashboard 열기

공식 Releases에서 운영체제에 맞는 설치 파일을 받은 뒤, 트레이 메뉴에서 Dashboard를 여세요. FreeLLMAPI 다운로드

설치 후 큰 창이 바로 보이지 않아도 앱이 실행 중일 수 있습니다. Windows는 작업표시줄 오른쪽 숨겨진 아이콘 영역을, macOS는 상단 메뉴 막대를 확인하세요. FreeLLMAPI 아이콘에서 Open Dashboard를 선택합니다. 데스크톱 설치 안내

연결에 쓸 로컬 주소도 확인합니다. 예시의 포트 번호를 그대로 입력하지 말고 앱의 Copy URL로 실제 주소를 복사하세요. v0.13.4의 Copy URL은 http://127.0.0.1:실제포트/v1 형태를 복사합니다. Claude Code에 수동으로 설정할 때는 마지막 /v1을 뺀 루트 주소를 사용합니다. 아래 setup-claude CLI 0.7.0도 마지막 /v1을 자동으로 제거하지만, 이 글에서는 혼동을 줄이기 위해 처음부터 루트 주소를 입력합니다. 주소 복사 구현

복사된 주소 예시:       http://127.0.0.1:31415/v1
Claude Code용 루트 주소: http://127.0.0.1:31415

2단계. 무료 API 키 등록하고 모델 테스트하기

제공업체에서 만든 키는 FreeLLMAPI의 Keys 화면에 등록합니다. 세 곳의 키를 한꺼번에 준비하기보다 한 곳씩 저장하고 테스트해야 오류를 찾기 쉽습니다.

1. Google AI Studio의 Create API key에서 키를 만듭니다.
2. FreeLLMAPI의 Keys → Add key에서 Google을 선택해 등록합니다.
3. 제공업체 행의 ⋯ 메뉴 → Test models로 사용할 수 있는 모델을 확인합니다.
4. Groq Console에서 키를 만들고 Keys → Add key에서 Groq를 선택해 등록·테스트합니다.
5. OpenRouter에서도 키를 만든 뒤 같은 방식으로 등록·테스트합니다.

화면이 번역되어 있거나 버전이 다르면 메뉴 이름이 조금 다를 수 있습니다. 핵심은 키 추가 → 올바른 제공업체에 저장 → 모델 응답 확인입니다. Test models는 실제 모델 요청을 보내므로 테스트도 제공업체 사용량에 포함될 수 있습니다. v0.13.4의 키 관리 화면 구현

키 등록 성공과 모델 사용 성공은 다릅니다. 키를 저장했어도 특정 모델에 접근할 수 없거나 무료 한도가 없으면 호출은 실패할 수 있습니다. 테스트를 통과한 사용 가능 모델을 두 개 이상 확보하고, 가능하면 서로 다른 제공업체를 사용하세요. 같은 제공업체의 모델은 일부 한도를 공유할 수 있습니다.

3단계. Fallback Chain으로 자동 전환 설정하기

Fallback Chain은 첫 후보가 요청을 처리하지 못할 때 시도할 다음 모델 목록입니다. Dashboard에서 테스트를 통과한 모델을 활성화하고 순서를 정하세요.

예를 들어 다음처럼 구성할 수 있습니다. 아래는 순서를 설명하기 위한 예시이며, 성능 순위가 아닙니다.

1순위: Groq에서 테스트를 통과한 무료 채팅 모델
2순위: Google Gemini의 사용 가능한 무료 모델
3순위: OpenRouter의 사용 가능한 무료 모델

목록 순서대로 쓰고 싶다면 라우팅 전략에서 Manual을 선택하세요. v0.13.4 화면의 표시 이름은 Manual이며 내부 설정값이 priority입니다. 한국어 화면에서는 번역된 이름으로 보일 수 있습니다. 순서·활성화 상태를 바꾼 뒤에는 Save changes로 저장하고, 여러 체인을 만들었다면 사용할 체인이 활성화되어 있는지 확인하세요. v0.13.4의 라우팅 화면 구현

기본 전략인 balanced는 속도·신뢰도 등을 반영합니다. 이 경우 목록의 첫 모델이 매번 선택된다고 단정할 수 없습니다. Manual도 한도·오류·기능 지원 여부에 따라 사용할 수 없는 후보는 건너뛸 수 있습니다. 라우팅 전략 설명

자동 전환은 429 같은 사용량 제한이나 재시도 가능한 서버 오류 때 다른 후보를 찾는 방식입니다. 모든 후보의 한도가 끝났거나 요청을 처리할 수 없으면 전체 요청도 실패합니다. 이미 출력되던 답변이 끊긴 경우까지 항상 매끄럽게 복구되는 것은 아닙니다. 오류와 대체 경로 처리

4단계. Claude Code에 연결하기

FreeLLMAPI의 루트 URL과 Unified API Key를 준비한 뒤 setup-claude로 설정합니다. 앱의 트레이나 Keys → Unified API key 탭에서 통합 키를 복사하세요. Google·Groq·OpenRouter에서 발급한 키를 여기에 넣는 것이 아닙니다.

이 글의 기본 명령은 사용자 설정을 바꾸므로 다른 프로젝트에도 영향을 줄 수 있습니다. CLI 0.7.0의 기본 설정 대상은 ~/.claude/settings.json입니다. CLAUDE_CONFIG_DIR로 별도 설정 폴더를 쓰는 경우 Claude Code가 읽는 위치와 달라질 수 있으므로, 아래 명령을 그대로 적용하기 전에 대상 파일을 확인하세요. 회사에서 관리하는 설정이 있는 경우에도 해당 정책을 먼저 확인합니다. Claude Code 설정 범위

가장 자주 헷갈리는 주소와 키

Claude Code용 URL 뒤에는 /v1을 직접 붙이지 않습니다. Claude Code는 Anthropic Messages 형식으로 요청 경로를 붙입니다. 다른 OpenAI 호환 클라이언트에 쓰는 /v1 포함 예시와 혼동하기 쉬운 부분입니다. 클라이언트별 주소 구분

방법 A. Claude Code에 복사해서 넣는 연결 프롬프트

Claude Code가 아직 응답할 수 있다면 다음 프롬프트를 사용하세요. 이미 한도가 끝나 응답하지 못하면 방법 B로 바로 이동하면 됩니다.

내 컴퓨터의 Claude Code CLI를 FreeLLMAPI에 연결해줘.
FreeLLMAPI 앱은 실행 중이고 제공업체 API 키 등록과 모델 테스트도 마쳤어.

공식 문서:
https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md

1. 운영체제, Node.js, npx, Claude Code 설치 상태를 확인해줘.
2. 현재 Claude Code 설정과 환경변수 중 연결에 영향을 주는 항목을
   확인하되, 키나 토큰의 실제 값은 출력하지 마.
3. FreeLLMAPI의 실제 루트 URL을 물어봐. /v1은 직접 붙이지 마.
4. Unified API Key는 대화에 붙여넣게 하지 말고
   내가 로컬 터미널에서 직접 입력할 방법을 안내해줘.
5. CLI 0.7.0의 setup-claude에 --model auto와 --dry-run을 쓰는
   로컬 실행 명령을 안내해줘. 출력에는 키가 포함될 수 있으니
   내가 직접 확인하도록 하고 전체 출력을 채팅에 요구하지 마.
6. 관련 없는 기존 설정은 보존하고, 연결 관련 값의 변경 범위를 설명해줘.
   문제가 없으면 백업 후 병합해 적용하고 백업 위치를 알려줘.
7. 재시작 방법과 Dashboard 요청 기록 확인 방법을 안내해줘.

설정 완료와 실제 연결 성공을 구분해줘.
네가 직접 확인하지 못한 항목은 미확인이라고 표시해줘.

방법 B. 한도가 끝났을 때 터미널에서 직접 연결하기

아래 명령은 Claude Code의 대화 입력창이 아니라 일반 터미널에 입력합니다. Windows는 PowerShell, macOS는 기본 터미널의 zsh 기준입니다. 먼저 설치 상태를 확인하세요.

node --version
npx --version
claude --version

node나 npx를 찾을 수 없으면 지원 버전의 Node.js를 설치한 뒤 터미널을 다시 여세요. claude를 찾지 못하면 Claude Code 설치부터 완료합니다.

다음 코드는 URL과 키를 실행 중에 입력받습니다. 한 줄씩 실행하고, URL 질문에는 앱에서 복사한 루트 주소를, 키 질문에는 Unified API Key를 붙여 넣으세요. 입력 중 키 원문은 표시되지 않습니다. PowerShell에서는 가림 문자가 보일 수 있습니다.

$env:FREELLMAPI_URL = (Read-Host "FreeLLMAPI root URL").Trim()
$freeLlmSecret = Read-Host "Unified API Key" -AsSecureString
$env:FREELLMAPI_API_KEY = [System.Net.NetworkCredential]::new('', $freeLlmSecret).Password
npx freellmapi@0.7.0 setup-claude --model auto --dry-run

read -r "FREELLMAPI_URL?FreeLLMAPI root URL: "
read -rs "FREELLMAPI_API_KEY?Unified API Key: "
echo
typeset -x FREELLMAPI_URL FREELLMAPI_API_KEY
npx freellmapi@0.7.0 setup-claude --model auto --dry-run

처음 실행하면 npx가 패키지를 설치할지 물을 수 있습니다. 패키지 이름과 버전을 확인하세요. 예시는 확인한 CLI 버전 0.7.0을 고정했습니다. --dry-run은 변경할 내용을 보여주는 단계이며 설정 파일을 저장하지 않습니다.

출력에서 연결 주소와 모델 선택 등 변경 범위를 확인한 뒤, 같은 터미널에서 적용 명령을 실행합니다. 확인한 CLI 0.7.0의 --dry-run 출력에는 입력한 통합 키가 포함됩니다. 화면 공유 중에 실행하거나 결과 전체를 채팅·게시물에 붙여 넣지 마세요.

npx freellmapi@0.7.0 setup-claude --model auto

이 명령은 기본 구성에서 사용자 설정 파일 ~/.claude/settings.json을 수정합니다. Windows의 기본 경로는 %USERPROFILE%\.claude\settings.json입니다. 실제 변경이 있고 기존 파일이 있으면 백업을 만든 뒤 병합합니다. 변경 사항이 없으면 Unchanged로 끝날 수 있습니다. 병합은 아무 값도 바꾸지 않는다는 뜻이 아닙니다. 연결 주소·인증 토큰·모델 관련 값 등이 FreeLLMAPI용 값으로 바뀝니다. 출력의 Backup: 경로를 기록해 두세요. CLI 안내 · CLI 0.7.0 배포 시점의 설정 생성 코드

통합 키는 이 설정 파일의 인증 값으로 저장됩니다. “입력할 때 가렸다”는 것이 파일에도 암호화해서 저장한다는 뜻은 아닙니다. 설정 파일과 백업을 공개하지 마세요.

입력에 사용한 임시 환경변수는 지워도 됩니다. 설정 파일에 저장한 연결 정보까지 삭제되는 것은 아닙니다.

Remove-Item Env:FREELLMAPI_API_KEY, Env:FREELLMAPI_URL -ErrorAction SilentlyContinue
Remove-Variable freeLlmSecret -ErrorAction SilentlyContinue

unset FREELLMAPI_API_KEY FREELLMAPI_URL

이제 실행 중인 Claude Code를 종료합니다. 첫 연결 확인은 민감한 파일이 없는 새 연습 폴더에서 새 세션으로 시작하세요.

claude --model auto

연결을 확인한 뒤 이전 작업을 이어갈 때는 원래 프로젝트 폴더에서 claude --resume --model auto로 세션을 고를 수 있습니다. --model auto는 이번 실행의 모델을 FreeLLMAPI의 자동 라우팅으로 지정합니다. 이전 세션을 재개하면 과거 대화와 코드·도구 결과도 다음 제공업체에 전달될 수 있으므로, 해당 자료를 외부 API에 보내도 되는지 먼저 확인하세요. Claude Code의 모델 지정·세션 재개 명령

5단계. 답변이 아니라 요청 기록으로 연결 확인하기

Claude Code에서 보낸 새 요청과 FreeLLMAPI에 남은 기록을 함께 확인해야 합니다. AI에게 “너 어떤 모델이야?”라고 물은 답변은 연결을 증명하지 못합니다.

먼저 Claude Code 안에서 /status를 입력하세요. Anthropic base URL이 FreeLLMAPI 주소인지, Auth token 항목이 ANTHROPIC_AUTH_TOKEN을 사용하는지 확인합니다. 이 글의 설정 명령은 이 인증 변수를 사용합니다. 모델 지정은 auto여도 실제 응답 모델은 라우터가 고르므로, 실제 제공업체·모델은 Dashboard 기록에서 확인하세요. 공식 게이트웨이 연결 점검

민감한 파일이 없는 연습 폴더에서 다음 문장을 입력하세요.

연결 확인용 요청이야.
파일을 읽거나 수정하지 말고, CHECK-FREELLMAPI-01만 답해줘.

그다음 Dashboard의 요청 기록이나 Analytics에서 다음을 확인합니다.

1. 시각: 방금 보낸 요청과 맞는 새 기록이 생겼나요?
2. 제공업체·모델: 어떤 서비스의 어떤 모델이 처리했나요?
3. 결과: 성공 여부와 오류 내역을 확인할 수 있나요?

모델 테스트나 Playground 요청도 기록을 만들 수 있으므로, 먼저 보이는 아무 기록이나 연결 성공으로 판단하지 마세요. Claude Code에서 요청한 시간과 새 기록을 비교해야 합니다.

Claude Code는 답하는데 Dashboard 기록이 없다면

기존 Anthropic 연결을 쓰는 경우도 있지만, 다른 FreeLLMAPI 인스턴스를 보거나 Analytics의 시간 범위가 다른 경우도 있습니다. 기록이 없다는 이유만으로 한도가 차감됐다고 단정하지 말고, 연결 주소와 확인 중인 Dashboard부터 대조하세요.

Claude Code는 응답하는데 FreeLLMAPI에 새 요청 기록이 없어.
설정을 바꾸기 전에 원인을 진단해줘.

- 현재 실행에 적용되는 ANTHROPIC_BASE_URL은 무엇인지 확인해줘.
- ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY는 값 대신 설정 여부만 알려줘.
- 사용자·프로젝트·로컬 설정, 환경변수, 실행 옵션의 충돌을 확인해줘.
- 내가 보고 있는 Dashboard와 같은 FreeLLMAPI 주소인지 비교해줘.
- 요청 시각과 Analytics 조회 범위도 확인하게 안내해줘.

키·토큰은 출력하지 마.
확인한 원인과 추정만 가능한 원인을 구분하고,
필요한 변경과 재검증 절차를 제안해줘.

Claude Code에는 여러 설정 범위와 우선순위가 있습니다. 사용자 설정 파일 하나만 확인해서는 실제 적용 값을 놓칠 수 있습니다. 설정 범위와 우선순위

연결 후 바로 해볼 실습: 짧은 JavaScript 함수 개선하기

처음에는 파일 한 개와 검증 가능한 결과로 시작하세요. 작은 작업은 모델의 코드 작성뿐 아니라 파일 읽기·수정·명령 실행이 함께 동작하는지 확인하기 좋습니다.

새 연습 폴더에 practice.cjs 파일을 만들고 아래 내용을 저장합니다. 회사 코드나 개인정보는 필요하지 않습니다.

function totalPrice(items) {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

const items = [
  { name: "노트", price: 3000, quantity: 2 },
  { name: "펜", price: 1000, quantity: 3 },
];

console.log(totalPrice(items)); // 9000

먼저 터미널에서 실행해 9000이 나오는지 확인합니다.

node practice.cjs

그 폴더에서 실행한 Claude Code에 다음 프롬프트를 넣으세요.

practice.cjs만 읽고 totalPrice 함수를 개선해줘.

요구사항:
- 정상 입력은 지금과 같은 합계를 반환해줘.
- 빈 배열은 0을 반환해줘.
- items가 배열이 아니면 TypeError를 던져줘.
- price나 quantity가 유한한 숫자가 아니거나 음수이면 TypeError를 던져줘.
- 외부 패키지를 설치하지 마.
- node:assert/strict로 정상 합계, 빈 배열, 잘못된 타입,
  음수, NaN을 검증하는 코드를 같은 파일에 추가해줘.

수정 후 node practice.cjs를 실행해서 결과를 확인해줘.
실행하지 못했다면 테스트했다고 말하지 말고 이유를 알려줘.
마지막에 바뀐 점과 테스트 결과를 짧게 정리해줘.

확인할 것은 긴 설명이 아닙니다. 파일이 실제로 수정됐는지, 테스트가 통과했는지, Dashboard에 요청이 남았는지를 보세요. 짧은 인사에는 잘 답해도 도구 호출이 필요한 작업에서는 실패할 수 있습니다. 이 경우 도구 호출을 지원하는 다른 모델로 바꿔 같은 작은 과제를 비교하면 됩니다.

작업을 이어받게 할 때 쓰는 프롬프트

모델이 바뀐 뒤 앞선 합의를 놓치는 것 같다면 현재 상태를 짧게 다시 고정하세요.

현재 작업을 이어서 진행해줘.
먼저 이번 대화와 실제 파일을 기준으로 다음 네 가지를 정리해줘.

1. 지금 만들려는 결과
2. 이미 끝낸 변경
3. 아직 남은 작업
4. 마지막에 통과해야 할 검증

확인하지 못한 내용은 추측하지 마.
완료된 작업을 반복하지 말고, 다음 변경 하나만 진행한 뒤 검증해줘.

Claude Code가 전달하는 대화와 파일 정보는 다음 모델이 작업을 이어갈 재료가 됩니다. 하지만 모델 내부의 기억이나 추론 상태를 복사하는 것은 아닙니다. FreeLLMAPI의 선택형 Context Handoff도 전달받지 못한 과거 내용을 복원하지는 못합니다. Context Handoff의 범위

연결 오류가 날 때 확인할 것

앱 실행 → 제공업체 모델 테스트 → Claude Code 설정 → 실제 요청 기록 순서로 확인하세요. 한 번에 여러 설정을 바꾸면 무엇이 원인이었는지 찾기 어려워집니다.

429는 보통 일정 시간의 요청·토큰 제한을 뜻합니다. 무조건 키가 잘못된 것은 아닙니다. 특히 짧은 질문 하나라도 긴 대화 기록과 파일 내용이 함께 전달되면 토큰 한도에 걸릴 수 있습니다. Groq 제한과 429 설명

자주 묻는 질문

마무리: 첫 목표는 무료 모델로 작은 작업 하나 끝내기

FreeLLMAPI는 Claude Code에서 사용할 수 있는 모델 연결 경로를 늘려주는 도구입니다. 개인 프로젝트의 문서 정리나 짧은 코드 실습부터 시작하면, 내 작업에 어느 정도 도움이 되는지 판단하기 쉽습니다.

앱 설치 → 키 등록·테스트 → 전환 후보 설정 → Claude Code 연결 → 요청 기록 확인 순서로 진행하세요. 처음에는 제공업체 한 곳으로 연결을 확인하고, 다음 후보를 추가한 뒤 이 글의 practice.cjs 실습을 끝내보는 것을 권합니다.

대체 모델 연결과 별개로, 전달하는 문서와 대화의 양을 줄이는 것도 도움이 됩니다. PDF를 자주 넣는다면 MarkItDown으로 PDF를 Markdown으로 바꾸는 방법도 함께 참고하세요.