FreeLLMAPI로 무료 AI 모델 635개를 코딩 에이전트에 연결하기
34곳의 무료 AI 공급자를 하나의 API로 묶는 오픈소스 도구를 설치하고 Claude Code에 연결합니다. 공급자 키 발급부터 첫 테스트까지 그대로 따라 하시면 됩니다.
- 준비: 클로드 데스크톱 앱의 Code 탭(유료 요금제)
- 비용: FreeLLMAPI 소스와 공급자 무료 등급은 무료, Claude Code 구독은 별도
- 주의: 개인 실험과 학습 목적으로 만들어진 도구이며 프로덕션용이 아닙니다(README Disclaimer)
- 확인일: 2026년 10월 23일
FreeLLMAPI란
FreeLLMAPI는 GitHub에 공개된 오픈소스 도구입니다(MIT 라이선스). README에 따르면 Google, Groq, Mistral, NVIDIA, OpenRouter 등 34곳의 무료 AI 공급자가 제공하는 635개 모델 엔드포인트를 하나의 OpenAI 호환 API로 묶습니다.[1]
한 공급자의 무료 한도가 차면 라우터(router, 요청을 적합한 모델로 보내주는 중간 서버)가 자동으로 다음 공급자의 모델로 넘어갑니다. 공급자 API 키는 AES-256-GCM으로 암호화돼 로컬 SQLite 데이터베이스에 저장되고, 외부에는 통합 키(unified key) 하나만 나갑니다.[1]
| 항목 | 수치 |
|---|---|
| 무료 공급자 | 34곳 |
| 모델 종류(model families) | 474개 |
| 공급자별 엔드포인트 | 635개(채팅 584, 임베딩 41, 전사 7, 비디오 3) |
| 월간 무료 토큰 총량(README 기재) | 약 74억 |
영상 대본에서 "600개 이상"이라고 말한 숫자는 공급자별 엔드포인트 수(635개)입니다. 중복을 빼면 모델 종류는 474개입니다.[1]
별도 설치: FreeLLMAPI 데스크톱 앱
FreeLLMAPI 데스크톱 앱은 라우터와 대시보드를 메뉴 바에서 실행하는 독립 앱입니다. Docker 없이도 쓸 수 있어서 이 가이드에서는 데스크톱 앱 경로를 안내합니다.[2]
- Mac: GitHub Releases에서 .dmg 파일을 내려받고 FreeLLMAPI 아이콘을 Applications 폴더로 드래그합니다. macOS 12 Monterey 이상, Apple Silicon(arm64)과 Intel(x64) 모두 지원합니다.
- Windows: GitHub Releases에서 .exe 설치 파일을 내려받아 실행합니다.
README에 따르면 계정이나 비밀번호 설정 없이 바로 사용할 수 있습니다. 필요한 것은 대시보드에서 확인하는 통합 API 키뿐입니다.[1]
성공 확인: 메뉴 바(Mac) 또는 시스템 트레이(Windows)에 FreeLLMAPI 아이콘이 나타나면 설치 완료입니다.
01 무료 공급자 키 발급
FreeLLMAPI가 공급자에 접속하려면 각 공급자의 무료 API 키가 필요합니다. 모든 곳에 가입할 필요는 없습니다. 한두 곳부터 시작해서 늘려가면 됩니다. 아래는 README에 이름이 나오는 주요 공급자입니다.[1]
| 공급자 | 참고 |
|---|---|
| Google (Gemini) | 구글 계정으로 AI Studio에서 발급 |
| Groq | 공식 사이트에서 무료 가입 후 발급 |
| OpenRouter | 공식 사이트에서 무료 가입 후 발급 |
| NVIDIA Build | 공식 사이트에서 무료 가입 후 발급 |
| Mistral | 공식 사이트에서 무료 가입 후 발급 |
| Cerebras | 공식 사이트에서 무료 가입 후 발급 |
| HuggingFace | 공식 사이트에서 무료 가입 후 발급 |
| Cloudflare Workers AI | Cloudflare 계정으로 발급 |
전체 34곳과 모델별 한도는 freellmapi.co/models에서 확인할 수 있습니다.[5] 34곳 중 한국에서 접근이 막히는 곳이 있을 수 있습니다. README에 따르면 ModelScope는 중국 Aliyun 계정 바인딩이 필요합니다.[1]
발급받은 키는 Git 저장소, 대화창, 공유 문서에 넣지 않습니다. 나중에 Claude Code 프로젝트에서 쓸 때도 .env 파일에 넣고 .gitignore에 추가해서 올라가지 않게 합니다.
02 대시보드에서 키 등록
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에 연결
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 첫 테스트
Code 탭에 아래 요청을 붙여넣으세요.
FreeLLMAPI가 잘 연결됐는지 테스트해줘.
http://localhost:3001/v1 으로 model "auto"를 지정해서
"한국의 수도는?" 이라는 질문을 보내고,
응답 내용과 X-Routed-Via 헤더를 알려줘. 성공 확인: 응답이 돌아오고 X-Routed-Via에 실제 공급자와 모델 이름(예: groq/llama-...)이 표시되면 FreeLLMAPI를 통한 첫 요청이 성공한 것입니다.[1]
자동 전환과 맥락 전달
자동 전환(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]
막혔을 때
- FreeLLMAPI 앱이 열리지 않는다: Mac은 macOS 12 이상인지 확인합니다. Windows는 .exe를 관리자 권한으로 실행해 봅니다.
- npx 명령이 없다는 오류: Code 탭에 "Node.js가 설치돼 있는지 확인하고 없으면 설치 방법을 알려줘"라고 요청합니다. Node.js 20 이상이 필요합니다.[1]
- setup-claude 뒤에 모델이 안 보인다: 대시보드의 Fallback Chain 페이지에서 모델이 활성화돼 있는지 확인합니다.
- 테스트 응답이 오류다: 대시보드 Keys 페이지에서 키 상태 점이 정상인지 확인합니다. 오류 문장을 Code 탭에 그대로 붙여넣고 해결해 달라고 하세요.
- 429 오류가 계속 난다: 등록된 공급자의 무료 한도를 모두 썼을 수 있습니다. 공급자를 더 추가하거나 UTC 자정(한국 시간 오전 9시)까지 기다립니다.
- 대시보드 비밀번호를 잊었다: 데스크톱 앱에서는 비밀번호가 없습니다. Docker나 서버 설치에서 잊었다면 로그인 화면의 Forgot password를 누르고 서버 로그에 나오는 코드를 입력합니다.[1]
체크리스트
- FreeLLMAPI 데스크톱 앱을 설치하고 대시보드가 열리는지 확인했는가
- 공급자 최소 한 곳의 무료 키를 발급받아 대시보드에 등록했는가
- 통합 API 키와 공급자 키를 Git이나 대화에 남기지 않았는가
- Claude Code에 연결하고 테스트 요청이 성공했는가
- 각 공급자의 이용약관과 무료 한도를 확인했는가
- 이 도구가 개인 실험 용도임을 이해했는가
공식 출처
- FreeLLMAPI GitHub 저장소 README
- FreeLLMAPI 설치 문서(데스크톱 앱, Docker, 소스 빌드)
- FreeLLMAPI 클라이언트 연결 및 맥락 전달 문서
- FreeLLMAPI 지원 에이전트 목록과 설정 명령
- FreeLLMAPI 모델 카탈로그(전체 공급자, 한도, 컨텍스트 길이)
- FreeLLMAPI 아키텍처, 한계, 이용약관 검토
2026년 10월 23일 확인. 이 가이드는 README와 공식 문서를 기준으로 작성했으며, 도구를 직접 설치하거나 실행해보지 않았습니다. 설치 방식과 공급자 한도는 빠르게 바뀔 수 있으므로 각 공식 출처의 최신 내용을 우선하세요.
Instagram 릴스의 댓글 키워드 클로드에 연결되는 공개 실행 문서입니다.