Claude에게 질문

FreeLLMAPI로 무료 AI 모델 635개를 코딩 에이전트에 연결하기

34곳의 무료 AI 공급자를 하나의 API로 묶는 오픈소스 도구를 설치하고 Claude Code에 연결합니다. 공급자 키 발급부터 첫 테스트까지 그대로 따라 하시면 됩니다.

빠른 확인
  • 준비: 클로드 데스크톱 앱의 Code 탭(유료 요금제)
  • 비용: FreeLLMAPI 소스와 공급자 무료 등급은 무료, Claude Code 구독은 별도
  • 주의: 개인 실험과 학습 목적으로 만들어진 도구이며 프로덕션용이 아닙니다(README Disclaimer)
  • 확인일: 2026년 10월 23일

FreeLLMAPI란

FreeLLMAPI가 여러 AI 공급자를 하나의 API로 묶어 Claude Code에 연결하는 구조도
여러 공급자의 무료 모델이 FreeLLMAPI 라우터 하나를 거쳐 Claude Code로 들어갑니다

FreeLLMAPI는 GitHub에 공개된 오픈소스 도구입니다(MIT 라이선스). README에 따르면 Google, Groq, Mistral, NVIDIA, OpenRouter 등 34곳의 무료 AI 공급자가 제공하는 635개 모델 엔드포인트를 하나의 OpenAI 호환 API로 묶습니다.[1]

한 공급자의 무료 한도가 차면 라우터(router, 요청을 적합한 모델로 보내주는 중간 서버)가 자동으로 다음 공급자의 모델로 넘어갑니다. 공급자 API 키는 AES-256-GCM으로 암호화돼 로컬 SQLite 데이터베이스에 저장되고, 외부에는 통합 키(unified key) 하나만 나갑니다.[1]

README에 기재된 FreeLLMAPI 주요 수치
항목수치
무료 공급자34곳
모델 종류(model families)474개
공급자별 엔드포인트635개(채팅 584, 임베딩 41, 전사 7, 비디오 3)
월간 무료 토큰 총량(README 기재)약 74억

영상 대본에서 "600개 이상"이라고 말한 숫자는 공급자별 엔드포인트 수(635개)입니다. 중복을 빼면 모델 종류는 474개입니다.[1]

별도 설치: FreeLLMAPI 데스크톱 앱

Mac과 Windows에서 FreeLLMAPI 데스크톱 앱을 설치하는 화면
Code 탭이 대신 설치할 수 없는 앱이라 직접 내려받아 설치합니다

FreeLLMAPI 데스크톱 앱은 라우터와 대시보드를 메뉴 바에서 실행하는 독립 앱입니다. Docker 없이도 쓸 수 있어서 이 가이드에서는 데스크톱 앱 경로를 안내합니다.[2]

README에 따르면 계정이나 비밀번호 설정 없이 바로 사용할 수 있습니다. 필요한 것은 대시보드에서 확인하는 통합 API 키뿐입니다.[1]

성공 확인: 메뉴 바(Mac) 또는 시스템 트레이(Windows)에 FreeLLMAPI 아이콘이 나타나면 설치 완료입니다.

01 무료 공급자 키 발급

주요 AI 공급자 네 곳에서 무료 API 키를 발급받아 FreeLLMAPI에 모으는 흐름
공급자마다 공식 사이트에서 무료 가입 후 API 키를 발급받습니다

FreeLLMAPI가 공급자에 접속하려면 각 공급자의 무료 API 키가 필요합니다. 모든 곳에 가입할 필요는 없습니다. 한두 곳부터 시작해서 늘려가면 됩니다. 아래는 README에 이름이 나오는 주요 공급자입니다.[1]

README에 이름이 나오는 주요 무료 공급자
공급자참고
Google (Gemini)구글 계정으로 AI Studio에서 발급
Groq공식 사이트에서 무료 가입 후 발급
OpenRouter공식 사이트에서 무료 가입 후 발급
NVIDIA Build공식 사이트에서 무료 가입 후 발급
Mistral공식 사이트에서 무료 가입 후 발급
Cerebras공식 사이트에서 무료 가입 후 발급
HuggingFace공식 사이트에서 무료 가입 후 발급
Cloudflare Workers AICloudflare 계정으로 발급

전체 34곳과 모델별 한도는 freellmapi.co/models에서 확인할 수 있습니다.[5] 34곳 중 한국에서 접근이 막히는 곳이 있을 수 있습니다. README에 따르면 ModelScope는 중국 Aliyun 계정 바인딩이 필요합니다.[1]

API 키를 공개하지 마세요

발급받은 키는 Git 저장소, 대화창, 공유 문서에 넣지 않습니다. 나중에 Claude Code 프로젝트에서 쓸 때도 .env 파일에 넣고 .gitignore에 추가해서 올라가지 않게 합니다.

02 대시보드에서 키 등록

FreeLLMAPI 대시보드 Keys 페이지에서 공급자 키를 추가하고 통합 키를 확인하는 화면
Keys 페이지에서 공급자 키를 추가하고 통합 API 키를 확인합니다

FreeLLMAPI 트레이 아이콘에서 Open Dashboard를 누르면 대시보드가 열립니다. README FAQ에 따르면 데스크톱 앱의 대시보드 주소는 http://127.0.0.1:31415 입니다.[1]

Keys 페이지에서 1단계에서 발급받은 공급자 키를 하나씩 추가합니다. 등록된 키는 AES-256-GCM으로 암호화돼 로컬에 저장됩니다.[1]

성공 확인: 추가한 키 옆에 상태 표시 점이 나타나면 등록 완료입니다.

Keys 페이지 상단에 표시되는 통합 API 키(unified API key, freellmapi-... 형식)를 메모해 둡니다. 이 키를 다음 단계에서 Claude Code에 넣습니다.

03 Claude Code에 연결

Claude 데스크톱 앱 Code 탭에서 FreeLLMAPI 연결 설정을 요청하는 화면
Code 탭 입력창에 설정 요청을 붙여넣으면 Claude가 명령을 실행합니다

Code 탭 입력창에 아래 요청을 붙여넣으세요. <unified-key> 부분은 2단계에서 확인한 통합 API 키로 바꿉니다.

아래 명령을 실행해서 FreeLLMAPI를 Claude Code에 연결해줘:
npx freellmapi setup-claude --url http://localhost:3001 --api-key <unified-key>

README에 따르면 이 명령은 기존 Claude Code 설정을 백업한 뒤 FreeLLMAPI 카탈로그를 읽어 설정에 병합합니다.[3]

Code 탭이 명령 실행 전에 허용을 물으면, FreeLLMAPI 설정 도구가 Claude Code 설정 파일을 수정하는 것을 허용합니다.

데스크톱 앱의 대시보드 주소가 http://127.0.0.1:31415 이면 --url 값도 같은 주소로 바꿔야 할 수 있습니다. 대시보드가 열리는 주소를 확인하세요.

성공 확인: 설정 완료 메시지가 나오고 오류가 없으면 연결 성공입니다.

04 첫 테스트

FreeLLMAPI를 통해 첫 테스트 응답을 받은 Code 탭 화면
응답과 함께 어떤 공급자가 처리했는지 확인할 수 있습니다

Code 탭에 아래 요청을 붙여넣으세요.

FreeLLMAPI가 잘 연결됐는지 테스트해줘.
http://localhost:3001/v1 으로 model "auto"를 지정해서
"한국의 수도는?" 이라는 질문을 보내고,
응답 내용과 X-Routed-Via 헤더를 알려줘.

성공 확인: 응답이 돌아오고 X-Routed-Via에 실제 공급자와 모델 이름(예: groq/llama-...)이 표시되면 FreeLLMAPI를 통한 첫 요청이 성공한 것입니다.[1]

자동 전환과 맥락 전달

한 모델이 429 오류를 보내면 자동으로 다음 모델로 넘어가는 흐름도
한도가 차면 라우터가 자동으로 다음 모델에 요청을 보냅니다

자동 전환(failover): README에 따르면 라우터는 여섯 가지 전략으로 공급자를 고릅니다. 한 공급자가 429(한도 초과)나 5xx(서버 오류)를 보내면 해당 키를 쿨다운 상태로 두고 자동으로 다음 모델에 요청을 보냅니다.[1]

맥락 전달(context handoff): README에 따르면 대화는 "sticky sessions"로 같은 모델에 30분간 붙어 있고, 모델이 바뀔 때 맥락 요약을 넘겨주는 선택 기능("context handoff")이 있습니다.[3] 단, 이 기능의 기본 상태와 .env 설정 방식은 이 가이드에서 직접 확인하지 못했습니다. 정확한 설정법은 공식 클라이언트 문서를 참고하세요.[3]

Anthropic 관련 안내

공식 지원 여부를 확인하지 못했습니다

FreeLLMAPI README에는 Anthropic Messages API 형식(/v1/messages)을 지원해서 Claude Code가 이 라우터를 통해 무료 모델에 접근할 수 있다고 적혀 있습니다.[1] 그러나 Anthropic이 서드파티 게이트웨이를 통한 비Claude 모델 라우팅을 공식 지원하는지는 이 가이드에서 확인하지 못했습니다. README Disclaimer에 따르면 각 공급자의 이용약관은 계정을 만들 때 동의한 조건이 그대로 적용됩니다.[6]

무료의 범위

FreeLLMAPI 소스(MIT 라이선스)와 공급자 무료 등급 자체는 무료입니다. Claude Code 구독(Pro, Max, Team, Enterprise)은 별도 비용입니다. FreeLLMAPI 프리미엄 실시간 카탈로그(새 모델을 당일 반영)를 쓰려면 연 $19 또는 평생 $49가 필요하지만, 없어도 월간 스냅샷으로 사용할 수 있습니다.[1] README Disclaimer에 따르면 무료 등급은 최신 모델을 포함하지 않고, 응답 속도가 고르지 않으며, SLA가 없습니다. 하루 후반에는 상위 모델이 일일 한도를 채워 품질이 떨어질 수 있고, UTC 자정에 초기화됩니다.[6]

막혔을 때

체크리스트

공식 출처

  1. FreeLLMAPI GitHub 저장소 README
  2. FreeLLMAPI 설치 문서(데스크톱 앱, Docker, 소스 빌드)
  3. FreeLLMAPI 클라이언트 연결 및 맥락 전달 문서
  4. FreeLLMAPI 지원 에이전트 목록과 설정 명령
  5. FreeLLMAPI 모델 카탈로그(전체 공급자, 한도, 컨텍스트 길이)
  6. FreeLLMAPI 아키텍처, 한계, 이용약관 검토

2026년 10월 23일 확인. 이 가이드는 README와 공식 문서를 기준으로 작성했으며, 도구를 직접 설치하거나 실행해보지 않았습니다. 설치 방식과 공급자 한도는 빠르게 바뀔 수 있으므로 각 공식 출처의 최신 내용을 우선하세요.

가이드가 도움이 되셨다면 여기도 확인해보세요.

제가 직접 만든 작업물, 지침, 템플릿을 올리고 있습니다. (무료임)

무료 자료실 보러가기

Instagram 릴스의 댓글 키워드 클로드에 연결되는 공개 실행 문서입니다.

가이드가 도움이 됐다면 무료 자료실 가기