my-free-code: Claude Code와 Codex 등 코딩 에이전트 9종이 모델 설정을 공유하는 로컬 게이트웨이

9bow · 9월 8, 2026, 12:00오후

my-free-code 소개

터미널 코딩 에이전트를 여러 개 쓰다 보면 같은 설정을 도구마다 다시 하게 됩니다. Claude Code는 Anthropic Messages 형식으로 요청을 보내고 Codex 계열은 OpenAI 형식을 쓰기 때문에, 같은 모델을 붙이려 해도 환경 변수와 엔드포인트를 도구별로 따로 맞춰야 합니다. 여기에 제공자를 바꿔 보고 싶어지면 API 키와 모델 이름이 도구 수만큼 늘어나고, 어느 제공자가 지금 실패하고 있는지도 도구마다 따로 알게 됩니다.

my-free-code는 그 설정을 한곳으로 모으는 로컬 게이트웨이입니다. 내 컴퓨터에서 작은 HTTP 서버 하나를 띄우고, 코딩 도구들은 그 주소를 모델 엔드포인트로 바라보게 만듭니다. 게이트웨이는 Anthropic Messages와 OpenAI Responses 두 형식을 모두 받아 하나로 변환한 뒤, 설정에 적힌 우선순위대로 실제 제공자를 호출합니다. 저장소가 먼저 밝혀 두는 점이 하나 있는데, 이 프로젝트는 독립적으로 만들어진 구현이며 Anthropic과는 무관합니다. 이름과 저장소 주제에 무료라는 표현이 들어가 있지만 모델 사용료를 없애 주는 도구가 아니라, 각 제공자의 무료 구간이나 저렴한 구간을 직접 골라 쓸 수 있게 배선을 정리해 주는 도구입니다.

의존성은 FastAPI와 uvicorn, httpx, python-dotenv 네 개뿐이고 Python 3.10 이상에서 동작합니다. 저장소는 라우팅과 프로토콜 변환, 인증, 추론(reasoning) 처리, 모델 목록, 스트리밍 기본 동작에 대한 결정론적 테스트를 함께 담고 있어서 pytest -q로 확인할 수 있습니다.

my-free-code가 실제로 하는 일

게이트웨이가 맡는 일은 크게 세 가지로 나뉩니다:

첫째는 형식 변환입니다. 게이트웨이는 Anthropic Messages(/v1/messages)와 OpenAI Responses(/v1/responses) 두 계열의 요청을 모두 받고, 토큰 계산(/v1/messages/count_tokens)과 모델 목록(/v1/models), 상태 확인(/health)도 함께 제공합니다. 관리 화면은 /admin에, 인증이 걸린 JSON 엔드포인트는 /api/admin/* 아래에 있습니다.

둘째는 라우팅입니다. Claude Code가 등급으로 모델을 고르는 구조를 그대로 받아, 등급마다 다른 상위 모델을 지정할 수 있습니다. 아래처럼 적으면 Sonnet 등급 요청은 DeepSeek로, Haiku 등급은 Groq로 넘어갑니다:

MODEL=open_router/openrouter/free
MODEL_SONNET=deepseek/deepseek-chat
MODEL_HAIKU=groq/llama-3.3-70b-versatile
MODEL_OPUS=nvidia_nim/meta/llama-3.3-70b-instruct
FALLBACK_MODELS=deepseek/deepseek-chat,ollama/llama3.1

FALLBACK_MODELS에 적은 후보는 순서대로 시도됩니다. 여기서 중요한 단서가 하나 있습니다. 스트리밍 응답이 이미 출력을 내보내기 시작한 뒤에는 게이트웨이가 조용히 제공자를 바꿔 같은 차례를 중복 생성하지 않습니다. 실패 시점이 출력 이전인지 이후인지를 구분해 두었다는 뜻이고, 대체 경로를 가진 프록시에서 흔히 문제가 되는 부분입니다. 요청이 실패한 제공자는 잠시 제외 대상이 되며, 저장소의 providers/runtime.py를 보면 그 회복 대기 시간은 2초로 고정되어 있습니다. 제공자별 동시 실행 수와 요청 창 제한도 같은 파일에서 관리합니다.

셋째는 제공자 연결입니다. 공개 모델 이름은 상위 제공자로 요청이 넘어가도 게이트웨이의 모델 이름으로 유지되므로, 도구 쪽에서는 어느 제공자가 실제로 응답했는지에 관계없이 같은 모델을 쓰는 것처럼 보입니다.

my-free-code의 제공자 목록에서 실제로 쓸 수 있는 것

저장소의 providers/catalog.py에는 제공자 항목이 50개 등록되어 있습니다. NVIDIA NIM, OpenRouter, Groq, OpenAI, xAI, DeepSeek, Mistral, Cohere, Fireworks, Cerebras, SambaNova, Hugging Face, GitHub Models 같은 이름부터 Ollama와 LM Studio, llama.cpp 같은 로컬 실행기까지 들어 있습니다.

다만 목록에 이름이 있다는 것과 지금 동작한다는 것은 다릅니다. 이 가운데 Azure OpenAI와 Google Vertex AI, Amazon Bedrock, Cloudflare Workers AI 네 곳은 카탈로그에 기본 주소가 비어 있고, 실행 시점에 requires a specialized adapter라는 오류를 내며 멈춥니다. 저장소도 이 점을 "제공자 항목은 보편적 지원을 주장하는 허위 표기가 아니며, 특이한 인증이나 프로토콜을 쓰는 제공자는 전용 어댑터가 필요하다" 는 문장으로 미리 밝혀 두었습니다.

반대 방향의 확인도 필요합니다. 저장소의 providers/specialized.py에 전용 어댑터로 등록된 항목은 9개인데, 지금은 모두 OpenAI 호환 어댑터를 상속만 하고 동작을 바꾸지 않은 상태입니다. 결과적으로 현재 동작하는 46개 제공자는 모두 같은 OpenAI 호환 채팅 완성 경로를 지나갑니다. 제공자별 특수 처리를 넣을 자리를 미리 나눠 두었을 뿐 아직 채워지지 않은 구조로 읽는 것이 정확합니다.

my-free-code는 누구에게 맞는가

여러 터미널 코딩 도구를 번갈아 쓰면서 모델과 제공자를 자주 바꿔 보는 사람에게는 my-free-code가 적절한 선택입니다. 실행기가 도구별 환경 변수를 대신 채워 주므로, 새 제공자를 붙일 때 손댈 곳이 .env 한 곳으로 줄어듭니다. 의존성이 네 개뿐이라 설치도 가볍습니다.

반대로 팀이 함께 쓰는 공용 게이트웨이가 필요한 경우에는 my-free-code가 적절한 선택지가 아닙니다. 저장소가 보안 항목에서 이 프로젝트는 로컬 사용을 전제로 한다고 못 박고, HOST=127.0.0.1을 유지하고 관리 엔드포인트를 인터넷에 직접 노출하지 말라고 안내합니다. 팀 단위로 쓰려면 그 전제를 벗어나는 셈이므로 별도의 접근 통제가 필요합니다.

같은 문제를 다루는 프로젝트가 PyTorchKR에도 여러 편 소개되어 있습니다. 로컬 게이트웨이 형태인 OmniRoute, Claude Code 프록시로 제공자를 묶는 Free Claude Code, Codex와 Claude Code를 함께 다루는 opencodex가 인접한 선택지입니다. 어느 것을 고를지는 지원 도구 수와 라우팅 방식, 그리고 실제로 배선된 제공자 범위를 각자 확인해 정하는 편이 좋습니다.

my-free-code 설치와 사용

가상 환경을 만들고 의존성을 설치한 뒤 .env를 준비합니다. macOS와 Linux에서는 다음과 같습니다:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env

실행하면 기본 주소는 http://127.0.0.1:8082입니다:

python -m my_free_code

.env에 모델과 해당 제공자의 API 키를 채운 뒤, 도구를 게이트웨이에 연결합니다. 실행기를 쓰면 환경 변수를 직접 내보내지 않아도 됩니다:

python -m my_free_code.cli.mfc claude
python -m my_free_code.cli.mfc codex
python -m my_free_code.cli.mfc opencode

저장소의 cli/launchers.py에 등록된 도구는 Claude Code, Codex, Pi, OpenCode, Cline, Hermes, DeepSeek Harness, Grok Build, Muse Code의 9종입니다. 실행기는 게이트웨이 주소와 인증 토큰을 환경 변수로 넣고 해당 실행 파일을 그대로 호출하므로, 도구 자체는 미리 설치되어 PATH에 있어야 합니다.

로컬 모델을 쓸 때는 실행기의 주소와 모델 이름을 함께 적습니다:

OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
MODEL=ollama/llama3.1

추론 관련 설정은 정규화된 형태로 받습니다. auto, on, off 가운데 하나를 고르고 필요하면 low, medium, high 강도를 함께 지정하면, 제공자 어댑터가 각자의 상위 필드로 옮깁니다. 전체 구조 설명은 저장소의 ARCHITECTURE.md에 정리되어 있습니다.

my-free-code의 라이선스

my-free-code는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

단, 게이트웨이를 통해 호출하는 각 제공자의 이용 약관은 별개입니다. 특히 무료 구간을 우회 목적으로 쓰는 것을 금지하는 제공자가 있으므로, 사용할 제공자의 약관을 각각 확인해야 합니다.

my-free-code 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임은 이런 글들을 한국어로 정리해 나누고 있습니다. 회원으로 가입하시면 주요 글들을 이메일로 보내드리고, 텔레그램(Telegram)과 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 다음 글을 정리하는 데 힘이 됩니다~