AI 튜토리얼

Magpie로 AI 에이전트 모델 및 공급자 관리

Magpie 설치 방법, 모델 공급자 연결, Claude Code와 Codex 같은 도구의 모델 전환, 재사용 가능한 프로필 저장, 로컬 게이트웨이를 통한 OpenAI·Anthropic·Gemini 호환 애플리케이션 라우팅 방법을 알아보세요.

2026년 9월 24일약 18분 소요

Magpie의 기능

Magpie는 컴퓨터에 설치된 AI 에이전트가 사용하는 모델을 한곳에서 확인하고 변경할 수 있도록 합니다. 메뉴 막대 애플리케이션, 일반 데스크톱 창, 터미널 사용자 인터페이스, 명령줄 도구로 제공됩니다.

여러 JSON, TOML, YAML 및 환경 파일을 직접 수정하는 대신 에이전트를 선택하고 필드를 고른 다음 모델을 지정할 수 있습니다. Magpie는 관련 설정만 수정하며, 가능한 경우 주석, 순서, 들여쓰기를 보존합니다. 모든 쓰기 작업은 원자적으로 수행됩니다.

Magpie는 현재 Claude Code, Codex, Gemini CLI, OpenCode, Pi, Goose, Cursor CLI, Copilot CLI 및 Crush를 인식합니다. 설치되었거나 구성된 에이전트만 인터페이스에 표시됩니다.

주요 기능

다양한 인터페이스: 데스크톱 애플리케이션, 메뉴 막대 패널, 터미널 UI 또는 일반 CLI를 사용할 수 있습니다.
정밀한 구성 편집: Magpie는 에이전트 구성의 나머지 부분을 다시 작성하지 않고 선택한 키만 변경합니다.
통합 로컬 게이트웨이: 에이전트는 단일 루프백 엔드포인트를 통해 여러 공급업체의 모델에 액세스할 수 있습니다.
API 변환: 게이트웨이는 스트리밍과 도구 호출을 포함하여 OpenAI Chat Completions, OpenAI Responses, Anthropic Messages 및 Google Gemini 호환 요청을 지원합니다.
공유 구독: 기존 Claude Code, Codex 및 Copilot 로그인을 다른 에이전트의 공급자로 사용할 수 있습니다.
실시간 모델 카탈로그: Magpie는 공급자로부터 모델 목록을 가져오고 models.dev의 데이터로 보완합니다.
공급자 프리셋: Anthropic, OpenAI, Gemini, DeepSeek, Kimi, GLM, MiniMax, Qwen, Mistral, Groq, xAI, OpenRouter, Together, Ollama 및 LM Studio를 비롯한 공급업체와 서비스의 프리셋을 사용할 수 있습니다.
프로필: 현재 모든 에이전트 설정을 이름으로 저장하고 나중에 한꺼번에 복원할 수 있습니다.
작은 네이티브 빌드: 데스크톱 빌드는 브라우저 런타임을 번들로 포함하지 않고 운영 체제의 웹뷰를 사용합니다.

Magpie 설치

사전 빌드 릴리스 설치

usemagpie.ai에서 macOS, Windows 또는 Linux용 데스크톱 애플리케이션을 다운로드하세요. 설치 스크립트를 실행할 수도 있습니다.

curl -fsSL https://usemagpie.ai/install.sh | sh

Linux에서는 WebKitGTK 4.1을 사용할 수 있으면 설치 프로그램이 데스크톱 애플리케이션을 선택하고, 그렇지 않으면 명령줄 빌드를 설치합니다. macOS 릴리스는 서명 및 공증됩니다. Windows와 Linux 빌드는 현재 서명되지 않았으므로 Windows SmartScreen이 처음 실행할 때 경고를 표시할 수 있습니다.

Magpie는 백그라운드에서 업데이트를 확인합니다. 데스크톱 애플리케이션은 재시작하거나 종료할 때 업데이트를 설치하며, 터미널 사용자는 다음 명령으로 업데이트할 수 있습니다.

magpie update

Go 소스에서 설치

Go가 설치되어 있다면 다음 명령으로 최신 버전을 직접 설치하세요.

go install github.com/yetone/magpie@latest

저장소를 로컬에서 빌드

저장소는 다음과 같은 Make 대상을 제공합니다.

make build            # 데스크톱 애플리케이션 바이너리
make app              # macOS 메뉴 막대 애플리케이션
make cli              # cgo가 없는 터미널 전용 빌드
make release          # 네이티브 앱 및 크로스 플랫폼 CLI 빌드
make release-windows  # Windows amd64 및 arm64 애플리케이션 빌드
make release-linux    # 현재 아키텍처용 Linux 애플리케이션

Linux 데스크톱 애플리케이션을 빌드하려면 libgtk-3-dev 및 libwebkit2gtk-4.1-dev가 필요합니다. 일반 Go 빌드에서는 gtk3 빌드 태그를 사용해야 합니다. Windows는 운영 체제에 포함된 WebView2 런타임을 사용합니다.

인터페이스 열기

작업 방식에 맞는 인터페이스를 선택하세요.

magpie          # 창과 메뉴 막대 아이콘 열기
magpie tray     # 메뉴 막대 아이콘만 실행
magpie tui      # 터미널 인터페이스 열기
magpie ls       # 감지된 에이전트와 현재 설정 나열

데스크톱 인터페이스에서는 현재 값 중 하나를 클릭하여 필터링된 선택기를 열 수 있습니다. 입력하여 검색하거나 사용자 지정 값을 입력하고, esc를 눌러 선택기를 닫으세요.

터미널 인터페이스에서는 화살표 키로 에이전트와 필드를 선택하고 Enter를 눌러 선택기를 연 다음, 입력하여 사용 가능한 항목을 필터링하세요. 종료하려면 q를 누르세요.

모델 공급자 추가

사용 가능한 프리셋 확인

먼저 Magpie가 이미 알고 있는 공급자를 나열하세요.

magpie presets

프리셋은 공급업체, 릴레이 및 로컬 서비스로 그룹화됩니다. 호스팅 프리셋에는 일반적으로 API 키만 필요합니다.

magpie provider add deepseek sk-…

Ollama와 같은 로컬 공급자는 키가 필요하지 않습니다.

magpie provider add ollama

Magpie는 셸 환경 변수에서 공급자 키를 읽지 않습니다. 애플리케이션이나 공급자 명령을 통해 키를 추가하세요.

사용자 지정 OpenAI 호환 공급자 추가

사용자 지정 공급자는 이름, 기본 URL, 키 및 명시적인 모델 목록으로 구성할 수 있습니다.

magpie provider add "My Relay" url=https://relay.example.com/v1 key=sk-… models=gpt-5.5,claude-sonnet-5

사용자 지정 공급자는 OpenAI 호환 기본 주소에 url=을, Anthropic 호환 기본 주소에 anthropic=을 사용하거나 둘 다 사용할 수 있습니다. 공급자에 별도의 Responses 엔드포인트가 있으면 responses=를 사용하세요. 선택적 catalog= 인수로 models.dev 공급자의 메타데이터를 가져올 수 있습니다.

공급자 확인 및 테스트

다음 명령을 사용하여 공급자를 검토하고, 모델 목록을 새로 고치고, API를 테스트하고, 키를 교체하거나, 항목을 삭제할 수 있습니다.

magpie providers
magpie provider deepseek
magpie provider models deepseek
magpie provider test deepseek
magpie provider key deepseek sk-…
magpie provider rm deepseek
magpie models

magpie provider test는 지원되는 각 API에 작은 요청을 하나씩 보내고 지연 시간을 보고합니다. 데스크톱 애플리케이션에서는 Providers 탭에서 키 변경, 노출할 모델 선택, 프로바이더 테스트, 에이전트에 모델 할당을 동일하게 제어할 수 있습니다.

에이전트 모델 전환

게이트웨이를 통해 노출되는 모델은 provider/model 형식을 사용합니다. 네이티브 에이전트 모델은 일반적인 이름으로도 선택할 수 있습니다.

기본 CLI 예시

magpie claude opus
magpie codex gpt-5.6-sol
magpie codex effort high
magpie codex xhigh
magpie codex deepseek/deepseek-chat
magpie claude moonshot/kimi-k2.5
magpie gemini auth api-key
magpie opencode anthropic/claude-sonnet-5
magpie oc small anthropic/claude-haiku-4-5

에이전트 이름에는 cc, oc, gem과 같은 접두사를 사용할 수 있습니다. OpenCode, Pi, Goose, Crush를 비롯한 프로바이더 범위 에이전트는 provider/model 식별자를 사용합니다.

Claude Code 등급 구성

Claude Code에서는 opus, sonnet, haiku, fable과 같은 등급에 별도의 모델을 할당할 수 있습니다. 예를 들어 DeepSeek 모델을 haiku 등급에만 할당하려면 다음과 같이 입력합니다.

magpie claude haiku deepseek/deepseek-v4-flash

해당 등급별 선택을 지워 Claude Code의 기본 모델로 되돌리려면 다음과 같이 입력합니다.

magpie claude haiku ""

게이트웨이 모델을 선택하면 Magpie가 Claude Code의 settings.json에서 Anthropic 기본 URL, 토큰, 모델 변수를 관리합니다. 네이티브 모델을 선택하면 Magpie의 게이트웨이 설정이 제거되고 이전 값이 복원됩니다.

전환 후 에이전트 재시작

에이전트는 시작할 때 구성을 읽습니다. 이미 실행 중인 세션은 새 세션을 시작할 때까지 이전 모델을 계속 사용합니다.

이는 시작 시 모델 카탈로그를 읽는 Codex에서 특히 중요하며, 전환 후 Codex를 재시작해야 합니다.

프로필 저장 및 복원

프로필에는 감지된 모든 에이전트의 현재 설정이 저장됩니다. 업무, 실험, 로컬 추론 또는 비용을 중시하는 작업을 위해 별도의 구성을 유지할 때 유용합니다.

magpie save work
magpie use work
magpie profiles
magpie rm work

데스크톱 애플리케이션에서는 기본 화면 하단에 프로필이 칩으로 표시됩니다. 칩을 클릭하면 적용되고, 삭제 컨트롤을 사용하면 제거되며, + save current를 선택하면 프로필이 생성됩니다.

터미널 인터페이스에서는 s를 눌러 현재 설정을 저장하고, p를 눌러 프로필을 적용하거나 삭제합니다.

로그인된 에이전트를 프로바이더로 사용

Magpie는 기존 Claude Code, Codex, Copilot 구독을 프로바이더로 노출할 수 있습니다. 원래 에이전트를 통해 로그인하면 사용 가능한 모델이 magpie providers와 다른 에이전트의 모델 선택기에 표시됩니다.

Claude Code 모델은 claude/claude-sonnet-5와 같은 식별자를 사용합니다.
Codex 구독 모델은 codex/gpt-5.5와 같은 식별자를 사용합니다.
Copilot 모델은 copilot/claude-sonnet-4.5와 같은 식별자를 사용합니다.

Magpie는 필요할 때 에이전트의 기존 인증 정보를 읽으며, 이를 자체 프로바이더 저장소에 복사하지 않습니다. 원래 에이전트가 토큰을 갱신하면 Magpie는 해당 에이전트의 갱신 절차를 따르고 에이전트가 지정한 위치에 갱신된 토큰을 기록합니다. 로그아웃하면 해당 프로바이더가 제거됩니다.

Claude 구독을 사용하려면 정식 로컬 claude 바이너리가 설치되어 있고 로그인되어 있어야 합니다. Magpie는 해당 바이너리를 실행하고 MCP를 통해 호출자의 도구를 활성 턴으로 연결합니다. Gemini CLI의 Google 로그인 지원은 계획되어 있지만 현재 공유 프로바이더로는 사용할 수 없습니다.

다른 애플리케이션을 게이트웨이에 연결

Magpie의 게이트웨이는 기본적으로 127.0.0.1:3425에서 수신하며 애플리케이션과 함께 시작됩니다. 게이트웨이만 실행하려면 다음을 사용합니다.

magpie serve

수신 주소를 변경하려면 MAGPIE_ADDR를 설정합니다. 기본 루프백 바인딩을 사용하면 게이트웨이가 컴퓨터 내부에서만 작동합니다.

지원되는 API 엔드포인트

OpenAI Chat Completions용 /v1/chat/completions.
OpenAI Responses용 /v1/responses.
Anthropic Messages용 /v1/messages.
Anthropic 토큰 수 계산용 /v1/messages/count_tokens.
스트리밍 및 토큰 수 계산 변형을 지원하는 Gemini 생성용 /v1beta/models/{model}:generateContent.
모델 카탈로그용 /v1/models 및 /v1beta/models.

API 키에는 magpie라는 리터럴 값을 사용할 수 있습니다. 기본적으로 게이트웨이가 루프백에서 수신하므로 어떤 값이든 작동합니다. 모델은 항상 provider/model 형식으로 지정합니다.

OpenAI 호환 환경

export OPENAI_BASE_URL=http://127.0.0.1:3425/v1
export OPENAI_API_KEY=magpie

Anthropic 호환 환경

export ANTHROPIC_BASE_URL=http://127.0.0.1:3425
export ANTHROPIC_API_KEY=magpie

Gemini 호환 환경

export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:3425
export GEMINI_API_KEY=magpie

데스크톱 애플리케이션의 Gateway 탭에서는 셸, curl, Python, Node용 설정과 스니펫을 복사할 수 있습니다. 또한 모델 ID와 최근 호출도 표시합니다.

모델 카탈로그 새로 고침

Magpie는 구성된 프로바이더에서 실제 모델 목록을 가져옵니다. models.dev 카탈로그는 자체 카탈로그를 제공하지 않는 프로바이더에 이름, 추론 수준, 대체 목록을 제공합니다.

models.dev 데이터와 모든 라이브 프로바이더 목록을 새로 고치려면 전체 동기화를 실행합니다.

magpie sync

터미널 인터페이스에서는 S를 눌러 같은 작업을 수행할 수 있습니다. magpie provider models PROVIDER를 사용하면 특정 제공업체 하나만 새로 고칠 수도 있습니다.

제공업체 링크를 안전하게 가져오기

공급업체와 릴레이는 미리 입력된 제공업체 정의를 가져오기 링크로 배포할 수 있습니다. Magpie는 저장하기 전에 제안된 제공업체 이름, 엔드포인트, 대상 호스트, 모델을 표시합니다.

magpie import 'magpie://import?preset=deepseek&key=sk-…'

사용자 지정 릴레이 링크에는 OpenAI와 Anthropic용 엔드포인트를 별도로 포함할 수 있습니다.

magpie://import?name=Acme%20Relay&chat=https://api.acme.example/v1&anthropic=https://api.acme.example&key=sk-…&models=gpt-5.5,claude-sonnet-5

사용자가 가져오기를 확인하기 전까지는 아무것도 저장되지 않습니다. 웹 페이지에서는 https://usemagpie.ai/import# 뒤에 동일한 매개변수를 붙여 사용할 수 있습니다. 값이 URL 프래그먼트에 남아 있으므로 브라우저는 해당 값을 웹사이트 서버로 전송하지 않습니다. 전체 매개변수 참조와 링크 빌더는 Magpie 가져오기 가이드를 참조하세요.

고급 팁

노출할 모델 제한하기

제공업체가 반환하는 모든 모델을 노출할 필요는 없습니다. 에이전트 선택기에 표시할 모델만 선택하세요. 이렇게 하면 대규모 카탈로그를 관리하기 쉬워지고 모델을 실수로 선택하는 일을 줄일 수 있습니다.

게이트웨이 변환 확인하기

게이트웨이가 변환하는 내용을 확인하려면 디버그 로깅을 활성화하세요.

MAGPIE_DEBUG=1 magpie serve

공급업체가 호출자의 API를 이미 지원하는 경우 요청은 직접 전달됩니다. 그렇지 않은 경우 Magpie가 지원되는 스트리밍, 도구 호출, 추론 동작을 유지하면서 요청과 응답을 변환합니다.

데이터 저장 위치 확인하기

~/.config/magpie/profiles.json에는 저장된 프로필이 저장됩니다.
~/.config/magpie/providers.json에는 파일 모드 0600으로 제공업체와 키가 저장됩니다.
~/.config/magpie/stash.json에는 교체된 값이 저장되어 복원할 수 있습니다.
~/.cache/magpie/models.json에는 models.dev 카탈로그가 저장됩니다.
~/.cache/magpie/models/<provider>.json에는 제공업체에서 가져온 모델 목록이 저장됩니다.

Magpie는 XDG_CONFIG_HOME과 XDG_CACHE_HOME을 따릅니다.

격리된 개발용 홈 디렉터리 사용하기

기여자는 평소 사용하는 에이전트 구성에 영향을 주지 않고 개발 빌드를 실행할 수 있습니다.

HOME=/tmp/magpie-home XDG_CONFIG_HOME=/tmp/magpie-home/.config make dev

make dev는 internal/gui/assets에서 직접 인터페이스를 제공하며 프런트엔드 파일이 변경되면 다시 로드합니다. 게이트웨이는 DEV_ADDR를 사용하고 기본값은 127.0.0.1:3426이므로 일반 Magpie 인스턴스와 함께 실행할 수 있습니다. 팔레트를 강제하려면 MAGPIE_THEME=light 또는 MAGPIE_THEME=dark를 설정하세요.

결론

Magpie는 분산된 모델 구성을 하나의 일관된 워크플로로 통합합니다. 설치한 후 제공업체를 추가하거나 기존 에이전트 구독을 사용하고, 각 에이전트에 사용할 모델을 선택한 다음, 유용한 조합을 프로필로 저장하세요. 또한 로컬 게이트웨이를 사용하면 다른 OpenAI, Anthropic, Gemini 호환 도구도 동일한 제공업체 카탈로그를 공유할 수 있으므로 각 애플리케이션에 공급업체 자격 증명을 저장할 필요가 없습니다.