무료 LLM을 쓰다 보면 생각보다 자주 흐름이 끊깁니다.
어떤 날은 Gemini CLI가 잘 되고,
어떤 날은 Claude Code가 더 낫고,
또 어떤 순간에는 rate limit이나 로그인 상태 때문에 지금 쓰던 도구가 바로 막히기도 합니다.
문제는 이때마다 사용자가 직접 갈아타야 한다는 점입니다.
명령어도 다르고, 옵션도 다르고, 어떤 건 CLI고 어떤 건 API고, 결국 "지금 되는 걸 찾아서 다시 붙이는 일"이 생각보다 번거롭습니다.
그래서 만든 게 Free-API입니다.
Free-API는 설치된 AI CLI들을 감지해서 하나의 CLI로 묶고,
하나가 실패하면 다음 provider로 자동 전환하는 도구입니다.
단순히 모델 하나를 더 잘 부르는 도구라기보다,
무료 LLM 선택지를 덜 끊기게 쓰기 위한 인터페이스에 가깝습니다.
Free-API가 하는 일
핵심은 단순합니다.
- 설치된 AI CLI를 자동으로 감지합니다
- 하나의 명령어로 LLM을 호출할 수 있습니다
- 현재 provider가 실패하거나 막히면 다음 provider로 넘어갑니다
- 원하면 API 모드도 연결할 수 있습니다
- 로컬 HTTP 서버로도 노출할 수 있습니다
- 대화 기록을 저장하고 내보낼 수 있습니다
현재 감지 대상은 다음과 같습니다.
- Gemini CLI
- Claude Code
- Codex CLI
- Copilot CLI
- OpenCode
즉 이미 이 중 하나라도 설치되어 있다면,
CLI 모드에서는 별도 API 키 없이 바로 사용할 수 있습니다.
이걸 왜 만들었냐면
요즘 AI CLI는 꽤 많아졌는데, 실제 사용 경험은 아직 분산되어 있습니다.
각 도구는 제각각 괜찮은데,
개발자가 체감하는 현실은 보통 이런 쪽에 가깝습니다.
- 지금 내 환경에 뭐가 설치돼 있는지 기억해야 한다
- 도구마다 호출 방식이 다르다
- 막히면 다른 도구로 수동 전환해야 한다
- 무료 플랜이나 로그인 상태 때문에 흐름이 자주 끊긴다
저는 여기서 "최고의 모델 하나를 고르는 일"보다
지금 되는 무료 선택지를 계속 이어서 쓰는 일이 더 중요하다고 봤습니다.
Free-API는 바로 그 지점을 줄이려는 도구입니다.
동작 방식은 이렇게 잡았습니다
Free-API는 크게 두 가지 모드로 동작합니다.
1. CLI 모드
설치된 AI CLI를 감지해서 래핑합니다.
예를 들어 Gemini CLI가 있으면 먼저 그쪽으로 시도하고,
실패하면 Claude Code, 그다음 Codex CLI처럼 다음 후보로 넘어가는 식입니다.
이 방식의 장점은 분명합니다.
- 이미 로그인해둔 CLI를 그대로 활용할 수 있다
- API 키 없이 시작할 수 있다
- 사용자는 어느 CLI를 직접 호출할지 매번 고민하지 않아도 된다
2. API 모드
원하면 API provider도 붙일 수 있습니다.
즉 CLI만 쓰는 구조가 아니라,
필요할 때는 API 기반 provider까지 연결해서 fallback 체인을 더 길게 가져갈 수 있습니다.
개인적으로 이 부분이 중요하다고 생각했습니다.
CLI만 바라보면 편하지만 한계가 있고,
API만 바라보면 키 관리와 설정 진입장벽이 생깁니다.
그래서 Free-API는 둘 중 하나만 강요하지 않고,
CLI로 가볍게 시작하고 필요하면 API까지 확장하는 구조로 잡았습니다.
제가 생각하는 포인트는 "통합"보다 "복구력"입니다
겉으로 보면 이 프로젝트는 AI CLI 통합 도구처럼 보일 수 있습니다.
그런데 제가 더 중요하게 본 건 통합 자체보다 복구력입니다.
지금 쓰던 provider가 막혀도 바로 다음 선택지로 넘어갈 수 있어야 하고,
사용자는 그 과정을 매번 손으로 다시 조립하지 않아야 합니다.
즉 이 도구의 핵심은
- 여러 AI 도구를 예쁘게 한데 모은 것
이 아니라 - 무료 선택지가 흔들려도 작업 흐름이 끊기지 않게 만드는 것
에 더 가깝습니다.
사용 예시는 이런 느낌입니다
설치 후 먼저 어떤 CLI를 쓸 수 있는지 확인할 수 있습니다.
freeapi scan그다음 바로 질문을 던질 수 있습니다.
freeapi "Go의 장점을 설명해줘"대화를 이어가고 싶다면 이렇게 쓸 수 있습니다.
freeapi chat -c "그럼 단점은?"특정 provider를 강제로 고르는 것도 가능합니다.
freeapi chat -p gemini-cli "hello"
freeapi chat -p claude-cli "hello"그리고 이건 개인적으로 꽤 유용한 지점인데,
파이프 입력도 자연스럽게 받을 수 있습니다.
cat error.log | freeapi chat "이 에러 분석해줘"
git diff | freeapi chat "이 변경사항 리뷰해줘"즉 단순 챗봇 용도만이 아니라,
터미널 작업 흐름에 AI를 붙이는 용도로도 꽤 잘 맞습니다.
로컬 HTTP 서버도 넣었습니다
CLI만 있는 도구로 끝내고 싶지는 않았습니다.
그래서 freeapi server로 로컬 HTTP 서버를 띄우고,
Swagger UI와 OpenAPI 스펙도 같이 볼 수 있게 했습니다.
이렇게 해두면 Free-API를 단순한 개인용 CLI가 아니라
로컬에서 돌리는 AI 게이트웨이처럼 쓸 수 있습니다.
예를 들어 이런 식입니다.
- 개인 스크립트에서 HTTP로 호출
- 로컬 툴과 연동
- 간단한 자동화 파이프라인 연결
- CLI가 설치된 환경을 API처럼 재사용
결국 "설치된 AI CLI"와 "API처럼 호출 가능한 인터페이스" 사이를 이어주는 셈입니다.
대화 기록과 내보내기도 지원합니다
계속 쓰다 보면 대화가 쌓이는데,
그걸 단순히 한 번 쓰고 날리는 형태로 두고 싶지 않았습니다.
그래서 대화 기록을 보고, 삭제하고,
필요하면 마크다운이나 텍스트로 내보낼 수 있게 했습니다.
freeapi history list
freeapi history show <id>
freeapi export <id> > conversation.md운영 쪽도 최소한으로 챙겼습니다.
- 설정은 YAML 파일로 관리
- 대화 기록은 SQLite에 저장
- 로그는 JSONL로 남김
- 기본적으로 프롬프트와 응답 원문은 저장하지 않음
이건 화려한 기능이라기보다
실제로 계속 쓸 수 있게 만드는 바닥 기능이라고 생각합니다.
이 도구가 잘 맞는 사람
이런 분들에게 특히 맞을 거라고 생각합니다.
1. 무료 LLM 선택지를 자주 바꿔가며 쓰는 사람
Gemini CLI, Claude Code, Codex, Copilot, OpenCode를 왔다 갔다 쓰는 경우
명령어를 하나로 줄여주는 것만으로도 피로도가 꽤 내려갑니다.
2. 막히면 바로 다른 선택지로 넘어가고 싶은 사람
지금 되는 걸 빨리 쓰고 싶지,
rate limit이나 인증 문제 때문에 흐름이 끊기는 건 피하고 싶은 경우에 잘 맞습니다.
3. CLI와 API를 같이 쓰고 싶은 사람
처음엔 CLI 기반으로 가볍게 시작하고,
필요하면 API provider를 붙여서 fallback 폭을 넓히고 싶은 경우 유용합니다.
4. 로컬 자동화나 툴 연동이 필요한 사람
CLI만으로 끝내지 않고,
로컬 HTTP API까지 열어서 다른 도구와 연결하고 싶은 경우에도 쓸 수 있습니다.
아직 더 듣고 싶은 피드백
이 프로젝트는 완성 선언보다,
실제로 많이 부딪혀보면서 다듬고 싶은 쪽에 가깝습니다.
특히 이런 부분이 궁금합니다.
- 어떤 provider 순서가 실제로 가장 실용적인지
- CLI 모드와 API 모드의 분리가 지금 형태로 적절한지
- 로컬 HTTP 서버를 어떤 용도로 연결하면 가장 유용한지
- 대화 기록과 내보내기 기능에서 더 필요한 게 있는지
- 무료 선택지를 "덜 끊기게" 쓰는 방향으로 무엇이 더 필요할지
무료 LLM을 자주 쓰는 분들이나,
여러 AI CLI를 같이 쓰는 분들이 써보고 의견 주시면 정말 도움이 됩니다.
마무리
Free-API는 거창하게 말하면 AI provider router일 수도 있지만,
제가 만들 때 가장 크게 생각한 건 더 단순했습니다.
무료 LLM을 쓰는 흐름이 자꾸 끊기는데, 그 끊김을 줄이고 싶다.
그 문제를 해결하기 위해
설치된 AI CLI 감지, 자동 전환, 선택적 API 모드, 로컬 HTTP 서버, 대화 기록 기능을 한데 묶었습니다.
아직 다듬을 부분은 많겠지만,
비슷한 불편을 느껴본 분들에게는 꽤 현실적인 도구가 될 수 있다고 생각합니다.
피드백 주시면 적극 반영해보겠습니다.
링크
- GitHub: https://github.com/bssm-oss/Free-API
- 시연 영상: https://youtu.be/-CiyOkuwNSI
