AI 튜토리얼

My Free Code로 멀티 프로바이더 코딩 에이전트 게이트웨이 구축

My Free Code v0.8 설치, 프로바이더 기반 또는 로컬 모델 구성, 코딩 에이전트 연결, 티어 라우팅 및 순서 기반 폴백 관리, 관리자 UI 확인, 로컬 사용을 위한 게이트웨이 보안 설정 방법을 알아보세요.

2026년 8월 28일약 14분 소요

My Free Code가 하는 일

My Free Code v0.8은 Claude Code 및 기타 코딩 에이전트를 위한 독립적인 멀티 프로바이더 게이트웨이입니다. 로컬 FastAPI 게이트웨이를 실행하여 에이전트 요청을 받고, 구성된 모델을 선택하고, 관련 프로바이더에 맞게 요청을 변환한 다음 응답을 클라이언트로 스트리밍합니다. 이 프로젝트는 Anthropic과 제휴 관계가 없습니다.

게이트웨이는 /v1/messages의 Anthropic Messages 프로토콜, /v1/messages/count_tokens의 Anthropic 토큰 수 계산, /v1/responses의 OpenAI Responses 호환 엔드포인트를 지원합니다. 또한 /v1/models를 통한 모델 검색, /health의 상태 확인 엔드포인트, /admin의 로컬 Admin UI, 인증이 필요한 /api/admin/* 하위 관리 API를 제공합니다.

주요 기능

다중 에이전트 프로토콜: 하나의 게이트웨이에서 Anthropic Messages 및 OpenAI Responses 호환 요청을 처리합니다.
에이전트 기능: 스트리밍 Server-Sent Events, 도구 정의, 도구 호출, 도구 결과, 이미지, 추론 메타데이터 전달을 처리합니다.
Claude 등급 라우팅: Fable, Opus, Sonnet, Haiku 요청에 서로 다른 업스트림 모델을 할당합니다.
복원력 있는 라우팅: 순서가 지정된 모델 폴백, 프로바이더 상태 기반 백오프, 프로바이더별 동시성 제어, 속도 제한 윈도우 제어를 사용합니다.
안정적인 모델 식별자: 라우터가 요청을 다른 프로바이더로 전송하더라도 공개 게이트웨이 모델 식별자를 유지합니다.
추론 정규화: Claude 스타일의 사고 의도를 프로바이더별 요청 필드와 분리합니다.
로컬 모델 지원: OpenAI 호환 엔드포인트를 통해 Ollama, LM Studio 또는 llama.cpp에 연결합니다.
에이전트 실행 도구: Claude Code, Codex, Pi, OpenCode, Cline, Hermes, DeepSeek Harness, Grok Build, Muse Code의 프록시 환경을 준비합니다.

프로바이더 카탈로그에는 다양한 클라우드 서비스와 로컬 런타임이 포함되어 있습니다. 일반적인 OpenAI 호환 프로바이더는 공유 전송 계층을 사용하지만, 인증 방식이나 프로토콜이 특수한 프로바이더에는 전용 어댑터가 필요합니다. 따라서 카탈로그 항목만으로 프로바이더별 구성 없이 보편적으로 지원된다고 해석해서는 안 됩니다.

아키텍처 작동 방식

             코딩 에이전트 / IDE
                      |
          +-----------+-----------+
          |                       |
    Anthropic Messages       OpenAI Responses
          |                       |
          +-----------+-----------+
                      |
                FastAPI 게이트웨이
                      |
                  모델 라우터
                      |
          +-----------+-----------+
          |                       |
       기본 경로                  폴백
          |                       |
          +-----------+-----------+
                      |
                프로바이더 런타임
                      |
       +--------------+--------------+
       |              |              |
 OpenAI 호환       특수 어댑터       로컬
    어댑터             |            런타임
       |          프로바이더 API   Ollama/LM Studio
     API

이 설계는 수신 와이어 프로토콜을 라우팅 및 프로바이더 통합과 분리합니다. HTTP 어댑터가 요청을 수신하면 애플리케이션 계층이 경로를 선택하고 실행하며, 프로바이더 런타임은 공유 OpenAI 호환 전송 계층, 특수 어댑터 또는 로컬 런타임과 통신합니다. CLI 실행 도구는 별도의 계층으로 유지되며, 클라이언트 환경을 구성하고 설치된 코딩 에이전트에 실행을 위임합니다.

게이트웨이 설치

사전 요구 사항

Python 3.10 이상.
저장소의 로컬 복사본.
사용하려는 원격 프로바이더의 인증 정보.
실행하려는 코딩 에이전트 클라이언트가 설치되어 있고 PATH에서 사용할 수 있어야 합니다.

1. 가상 환경 생성

python -m venv .venv

2. 가상 환경 활성화 및 종속성 설치

Windows PowerShell에서는 다음을 실행합니다.

.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
copy .env.example .env

macOS 또는 Linux에서는 다음을 실행합니다.

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

3. My Free Code 시작

python -m my_free_code

기본적으로 게이트웨이는 http://127.0.0.1:8082에서 사용할 수 있습니다. http://127.0.0.1:8082/health를 통해 서비스를 확인하고, http://127.0.0.1:8082/admin에서 로컬 Admin UI를 열 수 있습니다.

모델 및 프로바이더 구성

생성된 .env 파일을 편집하여 기본 모델을 선택하고, Claude 등급에 모델을 할당하고, 순서가 지정된 폴백을 정의합니다. 다음 예제는 여러 프로바이더의 모델을 사용합니다.

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

해당 프로바이더 API 키를 .env에 추가합니다. 지원되는 구성 필드는 .env.example을 참고하세요. 환경을 변경한 후에는 게이트웨이를 다시 시작합니다.

MODEL은 일반 게이트웨이 모델을 선택합니다. MODEL_SONNET, MODEL_HAIKU, MODEL_OPUS와 같은 등급별 변수는 라우터가 Claude 모델 등급을 서로 다른 업스트림 서비스로 전달하도록 합니다. FALLBACK_MODELS는 대체 모델을 쉼표로 구분해 순서대로 나열한 목록입니다.

Claude Code 연결

옵션 1: 환경을 수동으로 설정

Windows PowerShell에서 Claude Code가 로컬 Anthropic 호환 게이트웨이를 가리키도록 설정합니다.

$env:ANTHROPIC_BASE_URL="http://127.0.0.1:8082"
$env:ANTHROPIC_AUTH_TOKEN="local"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
claude

기본 URL은 Claude Code 요청을 My Free Code로 리디렉션하며, 모델 검색을 사용하면 클라이언트가 게이트웨이 모델 카탈로그를 조회할 수 있습니다.

옵션 2: 실행기 어댑터 사용

python -m my_free_code.cli.mfc claude

실행기는 로컬 프록시 환경을 준비한 후 설치된 Claude Code 클라이언트에 인수를 전달합니다. 실행기 자체가 클라이언트를 설치하지는 않습니다.

다른 코딩 에이전트 실행

동일한 실행기 추상화는 다음과 같은 추가 클라이언트도 지원합니다.

python -m my_free_code.cli.mfc codex
python -m my_free_code.cli.mfc pi
python -m my_free_code.cli.mfc opencode
python -m my_free_code.cli.mfc cline
python -m my_free_code.cli.mfc hermes
python -m my_free_code.cli.mfc deepseek-harness
python -m my_free_code.cli.mfc grok
python -m my_free_code.cli.mfc muse

이 명령 중 하나를 실행하기 전에 해당 클라이언트가 설치되어 있고 PATH에서 접근 가능한지 확인하세요. 실행기는 게이트웨이 환경만 설정하고 기존 프로그램을 호출합니다.

순서가 있는 폴백 이해하기

환경에 다음 라우팅 구성이 있다고 가정해 보겠습니다.

MODEL_SONNET=deepseek/deepseek-chat
FALLBACK_MODELS=groq/llama-3.3-70b-versatile,ollama/llama3.1

Sonnet 요청은 먼저 deepseek/deepseek-chat으로 전송됩니다. 출력이 생성되기 전에 이 시도가 실패하면 라우터는 groq/llama-3.3-70b-versatile를 시도합니다. 두 번째 시도도 출력 전에 실패하면 ollama/llama3.1을 시도합니다.

Claude Code
    |
    v
deepseek/deepseek-chat
    |
    | failure before output
    v
groq/llama-3.3-70b-versatile
    |
    | failure before output
    v
ollama/llama3.1

스트리밍 응답이 출력을 커밋한 후에는 게이트웨이가 공급자를 자동으로 변경하지 않습니다. 이를 통해 한 턴이 중복되거나 서로 다른 모델의 부분 응답이 결합되는 것을 방지합니다.

로컬 모델 사용

Ollama

Ollama 서비스를 별도로 시작한 다음 OpenAI 호환 기본 URL과 모델을 구성하세요.

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

LM Studio

LM Studio 로컬 서버를 시작하고 다음을 사용하세요.

LM_STUDIO_BASE_URL=http://127.0.0.1:1234/v1
MODEL=lmstudio/qwen3.5-coder

llama.cpp

llama.cpp 서버를 실행하고 다음을 구성하세요.

LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
MODEL=llamacpp/my-model

로컬 런타임을 FALLBACK_MODELS에 포함할 수도 있습니다. 그러면 원격 요청이 출력을 내보내기 전에 실패할 때 로컬 모델을 대안으로 사용할 수 있습니다.

추론 동작 구성

게이트웨이는 Claude 스타일의 사고 의도를 받아들이고, 공급자 어댑터가 요청을 변환하기 전에 이를 정규화합니다. 지원되는 모드는 다음과 같습니다.

auto
on
off

선택적 추론 수준은 다음과 같습니다.

low
medium
high

이러한 분리를 통해 에이전트 대상 추론 정책을 공급자별 필드와 독립적으로 유지할 수 있습니다. 각 공급자 어댑터는 정규화된 모드와 추론 수준을 해당 상위 공급자가 문서화한 필드에 매핑할 수 있습니다.

게이트웨이 모니터링

로컬에서 Admin UI를 다음 주소로 여세요.

http://127.0.0.1:8082/admin

인증이 필요한 JSON Admin API에는 다음이 포함됩니다.

GET /api/admin/status
GET /api/admin/models
GET /api/admin/providers

이 엔드포인트를 사용하여 게이트웨이 상태, 모델 카탈로그 및 구성된 공급자를 확인하세요. 관리 엔드포인트에는 인증이 필요하며 비공개로 유지해야 합니다.

고급 팁

공개 모델 ID를 안정적으로 유지

요청은 특정 티어 모델이나 폴백 공급자로 라우팅될 수 있지만, 게이트웨이는 공개 모델 ID를 안정적으로 유지합니다. 따라서 클라이언트 애플리케이션은 모든 상위 라우팅 결정을 추적하지 않고도 게이트웨이 모델과 상호 작용할 수 있습니다.

폴백 순서를 의도적으로 설계

FALLBACK_MODELS에는 시도할 정확한 순서대로 모델을 배치하세요. 공급자 가용성과 로컬 런타임을 마지막 옵션으로 사용할지 고려하세요. 폴백은 스트리밍 출력이 커밋되기 전에만 발생한다는 점을 기억하세요.

공급자별 차이 고려

많은 공급자가 공통 OpenAI 호환 전송 방식을 사용하지만, 특수한 인증 방식이나 프로토콜에는 전용 어댑터가 필요합니다. 모든 카탈로그 항목이 동일하게 동작한다고 가정하지 말고 관련 공급자 어댑터와 인증 정보가 준비되어 있는지 확인하세요.

필요한 경우 프로토콜 엔드포인트 직접 사용

Anthropic Messages 요청은 /v1/messages로 전송합니다.
/v1/messages/count_tokens를 통해 Anthropic 형식 토큰을 계산합니다.
/v1/responses에서 OpenAI Responses 호환 인터페이스를 사용합니다.
/v1/models를 통해 모델을 검색합니다.
/health를 통해 서비스 상태를 확인합니다.

테스트 스위트 실행

pytest -q

이 저장소에는 라우팅, 프로토콜 변환, 인증, 추론, 모델 카탈로그 및 스트리밍 기본 기능을 검증하는 결정론적 테스트가 포함되어 있습니다. 게이트웨이, 라우팅 또는 공급자 코드를 변경한 후 실행하세요.

보안 지침

My Free Code는 로컬 사용을 목적으로 합니다. 다음 주의사항을 적용하세요.

서비스가 로컬 머신에 바인딩되도록 HOST=127.0.0.1을 유지하세요.
추측하기 어려운 PROXY_AUTH_TOKEN을 설정하세요.
.env 파일을 소스 관리 시스템에 절대 커밋하지 마세요.
Admin 엔드포인트를 인터넷에 직접 노출하지 마세요.
공급자 인증 정보는 환경 또는 구성에 보관하세요. 게이트웨이는 한 공급자의 인증 정보를 다른 공급자에게 전송하지 않습니다.

결론

My Free Code는 코딩 에이전트와 여러 클라우드 또는 로컬 모델 제공업체 사이에서 로컬 호환성 및 라우팅 계층을 제공합니다. Python 종속성을 설치하고 모델과 자격 증명을 구성한 후 게이트웨이를 시작하면 Claude Code 또는 기타 지원 클라이언트를 연결하고, Claude 등급별로 모델을 할당하며, 제어된 폴백 체인을 구축할 수 있습니다. 또한 프로토콜, 라우팅, 제공업체, 실행기 계층이 분리되어 있어 프로젝트를 더 쉽게 검토하고 테스트할 수 있습니다.