[AI 활용팁] 무료 API 34곳을 한 번에 설치해 쓰는 FreeLLMAPI 사용법, 클로드 코드 연결까지

이 기사, AI에게 물어보기

클로드 코드(Claude Code)는 터미널에서 AI에게 코드 작성과 수정을 맡기는 도구다. 오래 사용하면 사용량 한도에 도달하거나 상위 요금제를 고민하게 된다. 오픈소스 프로젝트 FreeLLMAPI는 여러 AI 기업이 제공하는 무료 API를 내 컴퓨터의 주소 하나로 모아, 클로드 코드가 그 주소에 요청을 보내도록 설정해 준다. 저장소 설명 기준으로 무료 제공사 34곳, 무료 모델 엔드포인트 635개, 월 약 74억 토큰 규모다.

1. FreeLLMAPI의 작동 방식과 라이선스

구글과 그록(Groq), 세레브라스(Cerebras), Z.ai, 엔비디아, 미스트랄, 클라우드플레어 같은 기업은 각자 무료 API를 제공한다. 제공사마다 분당·일별 요청 수나 토큰 수에 한도가 있어 한 곳만으로는 작업량을 감당하기 어렵다. FreeLLMAPI는 이 무료 티어를 내 컴퓨터의 주소(http://localhost:3001) 하나로 연결하고, 요청이 들어올 때마다 한도가 남아 있고 상태가 정상인 모델을 골라 전달한다. 무료 티어는 제공사가 결제 없이 허용하는 사용 범위를 말한다.

한 제공사가 한도 초과나 서버 오류로 응답하지 못하면 라우터가 해당 키를 잠시 쉬게 하고 다음 순서의 모델로 요청을 다시 보낸다. 라우터는 요청을 받아 적절한 모델로 전달하는 중계 프로그램이다. 클로드 코드는 앤트로픽 서버와 대화하는 것처럼 동작하지만, 실제 답변은 그 순간 선택된 무료 모델이 생성한다.

항목	내용
저장소	github.com/tashfeenahmed/freellmapi
홈페이지	freellmapi.co
라이선스	MIT(라우터는 무료)
규모	무료 제공사 34곳, 모델 계열 474종, 무료 엔드포인트 635개
실행 환경	윈도우, 맥OS, 리눅스, 라즈베리파이(Node.js 20 이상)

MIT 라이선스는 저작권 표시만 유지하면 수정과 재배포를 허용하는 오픈소스 라이선스다. 저장소 스타 수는 2만 9,000개를 넘는다.

2. 사용 전 제약 사항

목록에 있는 GPT 계열은 오픈AI가 가중치를 공개한 GPT-OSS 120B와 20B다. 챗GPT나 GPT-6 같은 유료 모델이 포함된 것은 아니다. 제미나이 3.5 플래시, GLM-4.7, 키미 K2.6 같은 모델은 카탈로그에 이름 그대로 올라 있다.

저장소는 스스로 ‘개인 실험 전용(Personal experimentation only)’이라고 밝히고 있다. 한 사람이 자기 컴퓨터에서 쓰도록 설계됐으며, 회사 서비스에 연결하는 용도가 아니다. 저장소가 제시한 한계는 다음과 같다.

한계	내용
모델 수준	최상위 상용 모델은 포함되지 않는다
응답 속도	제공사와 시간대에 따라 편차가 크다
서비스 보증	가동 시간을 보장하는 약정(SLA)이 없다
하루 중 품질	상위 모델이 일일 한도에 도달하는 오후 늦게 품질이 떨어지고, 세계 표준시(UTC) 자정에 초기화된다

3. 설치 방법

윈도우와 맥에서는 깃허브 릴리스 페이지에서 데스크톱 앱을 내려받아 설치할 수 있다. 윈도우는 .exe, 맥은 .dmg 파일을 받아 실행하면 되며, 도커나 소스 설치보다 절차가 간소하다. 데스크톱 앱은 숨은 로컬 계정으로 자동 로그인하므로 비밀번호를 만들 필요가 없고, 대시보드는 트레이 아이콘의 Open Dashboard 메뉴로 연다.

도커(Docker)를 사용한다면 아래 명령으로 설치할 수 있다. 도커는 프로그램을 독립된 실행 환경에 담아 실행하는 도구다.

curl -fsSL https://freellmapi.co/install.sh | bash

이 명령은 ~/freellmapi 폴더와 암호화 키를 생성한 뒤 이미지를 내려받아 컨테이너를 실행한다. 설치가 끝나면 브라우저에서 http://localhost:3001 을 연다. 도커 설치판은 데스크톱 앱과 달리 이메일과 비밀번호 계정을 생성하는 단계가 추가된다. 스크립트 내용을 먼저 확인하고 싶다면 freellmapi.co/install.sh 주소를 열어 읽어 볼 수 있다.

소스 코드로 직접 실행하려면 Node.js 20 이상이 필요하다.

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi

# 맥OS·리눅스
./scripts/dev-bootstrap.sh

# 윈도우 파워셸
.\scripts\dev-bootstrap.ps1

npm run dev

개발 환경 준비 스크립트는 기존 .env 파일이 있으면 그대로 유지한다. 실행하면 서버는 3001번 포트, 대시보드는 5173번 포트에서 실행된다.

4. 무료 API 키 등록

제공사 키는 각 기업 사이트에서 직접 무료로 발급받아 대시보드에 등록한다. FreeLLMAPI가 키를 대신 발급해 주지는 않는다. 처음에는 아래 여섯 곳으로 시작하는 편이 좋다.

제공사	키 발급 위치	주요 모델
구글	aistudio.google.com → Get API key	제미나이 플래시 계열
그록(Groq)	console.groq.com → API Keys	GPT-OSS 120B·20B, 라마
세레브라스	cloud.cerebras.ai → API Keys	GLM, 큐원3
오픈라우터	openrouter.ai → Keys	이름에 :free가 표시된 모델
클라우드플레어	dash.cloudflare.com → Workers AI	라마, 키미 K2.6
엔비디아	build.nvidia.com → Get API Key	네모트론, GLM, 키미

1) 대시보드 상단의 Keys 탭을 연다
2) 제공사를 선택하고 발급받은 키를 붙여넣은 뒤 저장한다. 여섯 곳이면 여섯 번 반복한다
3) Models 탭에서 등록한 제공사의 모델이 목록에 표시되는지 확인한다. 상단의 월간 토큰 예산 막대가 여러 색으로 채워지면 정상이며, 색 하나가 제공사 하나를 뜻한다
4) Keys 탭 상단에 표시된 freellmapi-로 시작하는 통합 키를 복사한다

클로드 코드에는 이 통합 키 하나만 입력한다. 제공사별 키는 AES-256-GCM 방식으로 암호화돼 내 컴퓨터의 데이터베이스에 저장되고, 요청할 때만 메모리에서 해독된다. 모델 순서는 Models 탭의 대체 순서(Fallback Chain)에서 조정할 수 있으니, 어려운 코드 작업이 많다면 GPT-OSS 120B나 GLM-4.7 같은 큰 모델을 위쪽에 두자.

5. 클로드 코드 연결

터미널에서 아래 명령을 실행한다. <통합 키> 자리에는 4단계에서 복사한 키를 넣는다.

# 변경 내용만 미리 확인
npx freellmapi setup-claude --url http://localhost:3001 --api-key <통합 키> --dry-run

# 실제 적용
npx freellmapi setup-claude --url http://localhost:3001 --api-key <통합 키>

setup-claude 명령은 기존 클로드 코드 설정을 날짜가 표시된 사본으로 백업하고, 라우터에서 사용할 수 있는 모델 목록을 가져온 뒤, 클로드 코드 설정에 FreeLLMAPI 주소와 통합 키를 병합한다. –dry-run 옵션은 설정 파일을 변경하지 않고 바뀔 내용만 보여 준다.

설정 파일에 키를 남기고 싶지 않다면 아래 명령으로 클로드 코드를 실행한다. 이 경우 키는 그 순간 실행되는 클로드 코드에만 전달되고 파일에는 기록되지 않는다.

npx freellmapi launch

주소 끝에 /v1은 입력하지 말자. 클로드 코드는 기본 주소(http://localhost:3001)를 받아 스스로 /v1/messages 경로를 추가한다. 코덱스 CLI나 에이더(Aider) 같은 오픈AI 호환 도구는 반대로 /v1까지 포함한 주소를 사용한다.

6. 모델 전환 시 대화 인수인계 설정

한 모델이 한도에 도달해 라우터가 다른 모델로 넘기면, 새 모델은 앞선 대화 흐름을 모른 채 작업을 이어받는다. 이미 정한 사항을 다시 묻거나 작업을 처음부터 시작할 수 있다. FreeLLMAPI 폴더의 .env 파일에 아래 설정을 추가하고 라우터를 다시 실행하면 이 문제를 줄일 수 있다.

FREELLMAPI_CONTEXT_HANDOFF=on_model_switch

이 설정을 켜면 모델이 바뀌는 순간 라우터가 새 모델에게 짧은 안내 메시지를 먼저 전달한다. 다른 모델이 진행하던 작업을 이어받는 중이니 처음부터 다시 시작하거나 이미 답한 질문을 반복하지 말라는 내용과 최근 대화 요약이 포함된다. 대화 기록은 라우터 메모리에 3시간 동안만 보관되고 디스크나 로그에는 저장되지 않는다.

같은 대화는 기본적으로 30분 동안 같은 모델에 배정된다. 안내 메시지는 이 기간 안에 모델이 바뀔 때만 전달되며, 첫 요청이나 같은 모델로 이어지는 요청에는 추가되지 않는다.

7. 작동 확인과 유의 사항

클로드 코드를 실행해 간단한 작업을 요청한 뒤 대시보드의 Analytics 탭을 열면, 요청이 어느 제공사의 어느 모델로 전달됐는지 확인할 수 있다. 응답 헤더의 X-Routed-Via 항목에도 실제로 답변한 제공사와 모델 이름이 표시된다.

무료 티어의 한도와 모델 목록은 제공사가 예고 없이 바꿀 수 있다. 라우터는 하루 두 차례 서명된 모델 카탈로그를 내려받아 스스로 갱신하지만, 무료 설치판에는 새 모델이 실시간 카탈로그 등록 30일 뒤에 반영된다. 당일 반영을 원하면 연 19달러(약 2만 6,000원)의 프리미엄을 이용할 수 있으며, 라우터 자체는 계속 무료다.

제공사 키는 내 컴퓨터에만 저장되고, 라우터가 외부로 보내는 것은 각 제공사에 전달하는 요청뿐이다. 다만 각 제공사의 무료 티어 약관에서 허용하는 사용 범위는 가입할 때 따로 확인해 보자.

클로드 코드의 사용 한도를 넘긴 뒤에도 가벼운 코딩 작업을 이어 가고 싶은 개인 개발자라면, 데스크톱 앱 설치와 키 여섯 개 등록부터 시작해 보자.

자세한 내용은 FreeLLMAPI 깃허브에서 확인할 수 있다.

이미지 출처: FreeLLMAPI