따라 하기 튜토리얼: 하나의 키로 모든 에이전트를 연결하고 오픈소스 magpie로 API 게이트웨이에 통합하기 (Claude Code, Codex, Pi, Hermes를 예로)

작성자 주: 이 튜토리얼은 그대로 따라 하면 설정을 끝낼 수 있어요. 끝까지 읽고 한 번 따라 해 보면 “API 키 하나, 게이트웨이 주소 하나로 설치된 Agent를 모두 연결하는” 구성을 갖추게 됩니다. 앞으로 모델을 바꾸거나 API 키를 교체할 때도 한 곳만 수정하면 돼요.

시작하기 전에, 무엇을 할지 먼저 확인해 보세요

• 목표: 컴퓨터에 설치된 모든 코딩 Agent가 같은 API 키와 업스트림 주소를 사용하도록 설정해요. 이 글에서는 Claude Code, Codex, Pi, Hermes를 예로 들며, 설치된 Agent라면 몇 개든 연결할 수 있어요.
• 소요 시간: 약 30분(가입 및 네트워크 다운로드 시간 제외)
• 준비물: APIYI 토큰(또는 OpenAI / Anthropic 호환 중계 서비스나 공식 API 키), 명령줄을 실행할 수 있는 컴퓨터, 설치된 Agent 한 개 이상
• 난이도: ★★☆☆☆, 마우스로 몇 번 클릭하고 복사·붙여넣기만 할 수 있으면 돼요. 처음부터 끝까지 명령어를 입력할 필요는 없어요.

튜토리얼 진행 순서

3분 만에 이해하기: magpie는 중간에서 무슨 일을 할까요?

“그냥 안내대로 설정하면 돼”라고 생각한다면 이 절은 건너뛰어도 괜찮아요. 하지만 3분만 투자해 읽어 두면 나중에 문제를 해결할 때 훨씬 수월해요.

Agent마다 상위 모델에 요구하는 조건이 크게 달라요. 하나씩 직접 설정하다 보면 도구를 몇 개 설치하느냐에 따라 관리해야 할 설정도 늘어나죠. 가장 흔한 네 가지를 예로 들어볼게요.

magpie(저장소 github.com/yetone/magpie, 슬로건 “Every agent’s model. One place.”)는 바로 이 문제를 해결해요. 어떤 Agent가 어떤 모델을 사용할지, 어떤 Key를 읽을지 한곳에서 관리하고, 각 도구의 기본 설정에 맞게 반영해 줘요.

역할을 한마디로 정리하면 다음과 같아요.

• magpie는 분배를 담당해요: Claude Code와 Codex가 각각 어떤 모델을 사용할지 결정해요
• 게이트웨이는 프로토콜을 담당해요: Anthropic / OpenAI / Gemini 형식의 요청을 실제 모델 제공업체로 전달해요

그렇다면 상위 게이트웨이는 여러 프로토콜을 지원하는 게 좋아요

이상적인 조합은 “magpie가 분배를 맡고, 게이트웨이가 프로토콜을 맡는 것”이에요. 게이트웨이가 OpenAI 호환 형식만 지원한다면 Claude Code를 위해 프로토콜 변환 계층을 하나 더 추가해야 해요. 그러면 요청 경로가 길어지고 도구 호출 형식이 일치하지 않는 문제도 더 쉽게 발생할 수 있어요.

APIYI는 하나의 토큰으로 주요 프로토콜 세 가지를 지원해요. OpenAI 호환 형식, Anthropic 네이티브 형식, Gemini 형식 모두 같은 Key로 호출할 수 있어요(구체적인 지원 범위는 콘솔 안내를 확인해 주세요). 따라서 magpie 뒤에 상위 게이트웨이 하나만 연결하면 모든 Agent를 바로 사용할 수 있고, 모델 제공업체 계정과 청구 내역을 각각 관리할 필요도 없어요.

세 가지 방식, 무엇을 선택할까요?

수동 설정은 가장 간단하지만, 도구가 늘어날수록 Key가 여러 파일에 흩어져 교체와 문제 해결에 드는 비용이 커져요. 환경 변수 스크립트는 별도 의존성 없이 몇십 줄로 만들 수 있지만, Agent마다 다른 모델을 배정할 수는 없어요. “Claude Code에는 Claude, Codex에는 GPT, Hermes에는 저렴한 모델”처럼 사용하려면 magpie와 같은 통합 관리 방식이 훨씬 편리해요.

1단계: API 키를 발급받아 복사하세요

1.1 APIYI 콘솔에서 토큰 만들기

APIYI 콘솔(apiyi.com)에서 토큰을 만든 다음 복사하세요.

이 단계에서는 명령어를 입력할 필요가 없어요. 전체 과정에서 이 API 키를 입력하는 곳은 한 번뿐이에요. 3단계에서 magpie의 ‘공급업체’ 패널에 붙여 넣으면 됩니다. 붙여 넣은 뒤에는 magpie가 각 Agent의 설정 파일을 알아서 작성해 줘요. 환경 변수를 export하거나 config.toml, settings.json 같은 파일을 수정할 필요도 없어요.

🚀 아직 토큰이 없나요? APIYI apiyi.com에 가입해 테스트 사용량을 받아 보세요. 토큰 하나로 늘 사용하는 도구 몇 가지를 먼저 실행해 보고, 장기적으로 어떤 모델을 쓸지 결정하면 됩니다.

1.2 두 주소를 기억해 두세요

3단계에서 공급업체를 설정할 때 다음 중 하나를 선택해 입력하면 돼요.

✅ 단계 확인: 토큰을 클립보드에 복사했고, 3단계에서 어떤 주소를 입력해야 하는지 확인했어요.

2단계: magpie를 설치하고 두 페이지를 확인하세요

magpie의 소스 코드, 설치 방법, 설정 형식은 공식 저장소 README(github.com/yetone/magpie)를 기준으로 확인하세요. 프로젝트 업데이트가 빠르기 때문에 설치 명령어와 필드 이름은 버전에 따라 달라질 수 있어요. 아래에서 안내하는 화면 구성과 작업 순서는 버전이 바뀌어도 참고할 수 있는 내용이에요.

설치하고 실행하면 왼쪽에 탐색 메뉴가 있는 창이 나타나요. 이 튜토리얼에서는 두 페이지, Agent(어떤 모델을 사용할지 설정)와 공급업체(API 키를 등록하는 곳)만 사용하면 됩니다.

① 왼쪽 탐색 메뉴의 Agent는 모든 Agent를 관리하는 ‘중앙 제어판’이에요.

그림 1 · Agent 페이지: 각 도구가 한 줄씩 표시되고, 오른쪽 스위치로 magpie 연결 여부를 설정합니다. 스위치 옆 드롭다운에서는 모델을 선택할 수 있어요.

이 페이지에서 다음 세 가지를 확인하세요.

② 왼쪽 탐색 메뉴의 공급업체는 상위 서비스의 API 키를 등록하는 곳이에요. 자세한 내용은 다음 절에서 살펴볼게요.

magpie의 설정 파일 구조를 먼저 알아보고 싶다면 공식 README의 providers / agents 구조를 살펴보세요. 요약하면 “상위 서비스의 이름을 정하고, base_url과 API 키를 입력한 다음, 각 Agent에 사용할 모델을 지정하는” 방식이에요. 하지만 평소에는 창에서 클릭만 하면 됩니다. magpie가 각 도구의 기본 설정 파일을 대신 작성해 주기 때문에 직접 YAML을 수정하는 것보다 안정적이에요.

✅ 단계 확인: 창이 열리고 왼쪽에 Agent와 공급업체 두 항목이 표시돼요.

3단계: ‘공급업체’에 API 키 연결하기

3.1 공급업체 페이지로 이동하기

왼쪽에서 공급업체(그림 2의 빨간색 상자 ①)를 클릭한 다음, 페이지 오른쪽 위의 + 공급업체 추가(빨간색 상자 ②)를 클릭하세요.

그림 2 · 공급업체 페이지: 왼쪽 메뉴에서 ‘공급업체’로 이동하세요. 오른쪽 위의 ‘+ 공급업체 추가’가 유일한 진입점이에요.

이미 연결된 공급업체는 카드 형태로 여기에 표시돼요. 카드의 두 번째 줄에는 주소와 사용 가능한 모델 수가 표시됩니다(예: api.apiyi.com · 모델 11개). 실제로 사용할 수 있는지 확인하려면 먼저 이 줄에 숫자가 있는지 살펴보세요.

3.2 어떤 공급업체 유형을 선택해야 할까요?

‘+ 공급업체 추가’를 클릭하면 여러 그룹으로 나뉜 선택 패널이 표시돼요(그림 3).

그림 3 · 공급업체 추가 패널: 구독, 공급업체, 중계, 로컬, 다른 컴퓨터의 magpie 등 5가지 출처

패널의 그룹은 서로 다른 다섯 가지 API 키 유형에 해당해요.

APIYI를 사용한다면 OpenAI 호환 엔드포인트는 표준 중계 유형이에요. 중계 그룹에서 해당 항목을 선택하세요. OpenAI 또는 Anthropic 호환 방식의 사용자 지정 API 키를 가지고 있다면 맨 아래의 + 사용자 지정 공급업체(그림 3의 빨간색 상자)를 클릭하고 주소와 API 키를 입력하면 돼요. 주소에는 https://api.apiyi.com/v1을 입력하세요(Anthropic 네이티브 요청을 사용한다면 https://api.apiyi.com을 입력하세요).

다음은 공급업체를 열었을 때 표시되는 전체 설정 패널이에요. 여기서 설정해야 하는 항목은 네 가지뿐이에요.

그림 4 · APIYI 공급업체 설정 페이지: Base URL에서 먼저 프로토콜을 선택한 뒤 주소를 입력하고, Accounts에 API 키를 추가한 다음, Models에서 Agent에 제공할 모델을 선택하세요.

이 화면은 앞서 설명한 “토큰 하나로 여러 프로토콜 사용하기”를 보여주는 좋은 예예요. 주소는 모두 https://api.apiyi.com으로 동일하지만, Anthropic 호환을 선택하면 Claude Code가 사용하는 네이티브 엔드포인트가 되고, OpenAI 호환을 선택하면 Codex / Pi / Hermes가 사용하는 /v1 엔드포인트가 돼요. Gemini 호환도 같은 방식이에요. 공급업체 세 곳을 따로 설정하거나 API 키 세 개를 관리할 필요가 없어요.

입력을 마치고 저장한 다음, 공급업체 목록으로 돌아가 두 가지를 확인하세요. 카드의 두 번째 줄에 모델 수가 표시되고 스위치가 켜져 있어야 해요. · 모델 N개가 표시되면 API 키와 주소가 정상적으로 연결된 것이에요. 이 단계에서 바로 연결 상태를 확인할 수 있으니 별도로 명령어를 실행할 필요는 없어요.

✅ 단계 완료 기준: 공급업체 목록에 카드가 표시되고, · 모델 N개와 같은 문구가 나타나며 ‘설정되지 않음’으로 표시되지 않아야 해요.

4단계: 설치한 Agent를 하나씩 연결하기

Agent 페이지로 돌아가서 설치한 도구마다 같은 세 가지 작업을 진행하세요. 이 페이지에는 magpie가 연결할 수 있는 모든 Agent가 표시돼요. 지원 항목은 계속 늘어나고 있으며, 설치하지 않은 도구에는 ‘CLI를 찾을 수 없음’이 표시됩니다. 설치한 도구만 연결하면 돼요. 아래 표에는 가장 많이 사용하는 네 가지 도구를 예로 들었어요.

1. 오른쪽 스위치를 켜세요(회색에서 밝은색으로 바뀜).
2. 스위치 오른쪽에서 모델을 선택하세요. 선택하지 않으면 기본 모델을 사용해요. 여기서 선택한 모델은 해당 도구의 설정에 기록됩니다.
3. 안내에 따라 도구를 다시 실행하세요. Codex, Claude Code, Pi, Hermes는 새 설정을 읽어오려면 프로세스를 한 번 다시 시작해야 하는 경우가 많아요.

그림 5 · 모델 드롭다운을 클릭해 보세요. 첫 번째 항목인 ‘기본값’을 선택하면 Agent는 magpie를 거치지 않고 자체 모델을 사용해요. 아래 항목에는 모두 ‘magpie를 통해’라는 표시가 붙어 있어요. 항목을 선택하면 해당 Agent가 상위 공급업체의 모델을 사용합니다.

다음과 같은 상태가 표시되면 설정이 올바른 방향으로 진행되고 있는 거예요.

• 연결됨: 설정이 기록됐어요. 도구를 다시 실행하면 적용됩니다.
• 연결되지 않음 · XXX 자체 설정 사용: 스위치가 꺼져 있거나 모델을 선택하지 않았어요.
• XXX 자체 모델만 사용 가능, magpie 연결 불가: Cursor처럼 자체 모델만 사용할 수 있는 도구예요. 설정 오류가 아니라 설계상 제한입니다.
• CLI를 찾을 수 없음: 도구가 설치되어 있지 않거나 PATH에 등록되어 있지 않아요. 설치하거나 PATH를 설정한 뒤 다시 시도하세요.

💡 Agent마다 다른 모델을 사용하고 싶다면(Claude Code는 Claude, Codex는 GPT, Hermes는 저렴한 모델 등) 이 단계에서 각각 모델을 선택하세요. 이것이 magpie가 ‘환경 변수 스크립트’보다 편리한 주요 장점이기도 해요.

✅ 단계 완료 기준: 설치된 도구의 스위치가 모두 켜져 있고, 상태 줄에 더 이상 ‘연결되지 않음’이 표시되지 않아야 해요.

5단계: 각 Agent에서 한 문장씩 입력해 확인하기

설정을 마쳤다고 끝난 게 아니에요. 실제로 실행해 봐야 합니다. 각 도구에서 가장 간단한 작업을 하나씩 입력해 보세요.

요청이 실제로 게이트웨이를 거치는지 확인하려면 APIYI 콘솔에서 해당 토큰의 사용량과 로그를 확인하는 방법이 가장 간단해요. 새로운 호출 기록이 보인다면 모든 Agent의 요청이 같은 API 키로 전달된다는 뜻이에요.

✅ 이 단계의 완료 조건: 모든 Agent가 정상적으로 응답하고, 콘솔에서 해당 호출 기록을 확인할 수 있어요.

부록: 모델 선택 방법(잘 모르겠다면 기본 설정 참고)

💡 같은 작업을 여러 Agent와 모델에서 각각 실행해 보세요. 공통 토큰을 사용하면 모델 이름만 바꿔 비교할 수 있어 비용을 쉽게 확인할 수 있어요.

6단계(선택 사항): magpie가 어떤 설정을 대신 작성했을까요?

이 절은 설정이 제대로 작동하는 데 영향을 주지 않으며, 꼭 따라야 하는 단계도 아니에요. 평소에는 이 파일들을 건드릴 필요가 없어요. 4단계에서 스위치를 켜는 순간, magpie가 아래 내용을 이미 작성해 두었거든요. 여기에 소개하는 이유는 두 가지예요. 문제가 생겼을 때 어느 부분을 확인해야 하는지 알 수 있고, 나중에 magpie를 사용하지 않기로 했을 때 설정을 그대로 복사해 쓸 수도 있어요.

Claude Code: ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_BASE_URL="https://api.apiyi.com"   # Anthropic 기본 엔드포인트
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# 선택 사항: 기본 모델 지정(콘솔의 모델 목록 기준)
# export ANTHROPIC_MODEL="<Claude 모델명>"
claude

~/.claude/settings.json의 env 필드에 입력해도 돼요. 이렇게 하면 터미널 세션에 의존하지 않아요.

Codex: ~/.codex/config.toml의 provider 섹션

# ~/.codex/config.toml
model = "<GPT 계열 모델명>"
model_provider = "apiyi"

[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1"   # OpenAI 호환 엔드포인트
env_key = "APIYI_API_KEY"
wire_api = "responses"                   # 선택한 모델이 Responses를 지원하지 않으면 "chat"으로 변경

wire_api는 가장 실수하기 쉬운 부분이에요. 최신 Codex는 기본적으로 Responses 프로토콜을 사용해요. 게이트웨이에서 해당 모델에 Chat Completions만 제공한다면 반드시 chat으로 변경해야 해요.

Pi와 Hermes: 사용자 지정 OpenAI 호환 provider 선언

설정 방식은 같아요. base_url에는 https://api.apiyi.com/v1을 입력하고, Key는 APIYI_API_KEY를 참조하게 하면 돼요. 버전에 따라 구조가 다를 수 있으니 각 도구의 공식 문서를 확인하세요.

// Pi: 사용자 지정 모델 설정에 provider 선언(구조는 Pi 공식 문서 기준)
{
  "providers": {
    "apiyi": {
      "baseUrl": "https://api.apiyi.com/v1",
      "api": "openai-completions",
      "apiKey": "APIYI_API_KEY",
      "models": [{ "id": "<모델명>" }]
    }
  }
}

# Hermes: hermes model을 실행하고 사용자 지정 OpenAI 호환 엔드포인트를 선택한 다음,
# 안내에 따라 아래 정보를 입력하세요(또는 Hermes 설정 디렉터리의 .env / config에 입력).
#   Base URL : https://api.apiyi.com/v1
#   API Key  : $APIYI_API_KEY
#   Model    : <모델명>

#!/usr/bin/env bash
# agents-env.sh —— magpie가 없을 때 사용하는 대안: 하나의 Key로 모든 Agent 연결
# 사용법: source agents-env.sh
: "${APIYI_API_KEY:?먼저 export APIYI_API_KEY를 실행하세요}"

# Claude Code(Anthropic 프로토콜)
export ANTHROPIC_BASE_URL="https://api.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"

# Codex / Pi / Hermes 등 OpenAI 호환 도구에서 사용하는 공통 변수
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"

# 연결 상태 확인
curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ 모든 Agent가 동일한 게이트웨이를 사용하도록 설정됐어요"

curl -s "https://api.apiyi.com/v1/models" \
  -H "Authorization: Bearer sk-사용자_토큰" | head -c 300

문제가 생기면 여기부터 확인하세요: 자주 발생하는 오류 네 가지

문제는 항상 아래 단계부터 차례로 확인하세요. 먼저 게이트웨이와 토큰이 정상인지 확인하고(공급자 카드에 · 모델 N개가 표시되는지 확인), 다음으로 해당 Agent의 기본 설정을 확인한 뒤, 마지막으로 magpie의 매핑 계층을 확인하세요. 이렇게 세 단계만 확인하면 문제가 상위 서비스, 도구 자체, 통합 설정 중 어디에서 발생했는지 파악할 수 있어요.

자주 묻는 질문(FAQ)

5분 요약

• 역할 분담: magpie는 모델 매핑을 관리하고, 게이트웨이는 프로토콜 전달을 담당해요. 각자 한 가지 역할만 맡아요.
• 토큰 하나로 통합: 여러 프로토콜을 지원하는 상위 서비스를 선택하면 모든 에이전트가 하나의 키와 청구 내역을 공유해요.
• 시작 순서: 콘솔에서 토큰 만들기 → ‘공급업체’에 붙여 넣기 → 에이전트 스위치 켜기 → 하나씩 연결 확인하기. 모든 과정은 창에서 클릭하면 되고, 명령어는 필요 없어요.
• 문제 해결 순서: 게이트웨이 → 에이전트의 기본 설정 → magpie 매핑 계층 순으로 아래에서 위로 확인해요.
• Claude Code 참고 사항: ANTHROPIC_AUTH_TOKEN을 사용하고, base_url 뒤에 /v1을 붙이지 마세요.
• Codex 참고 사항: wire_api는 모델이 지원하는 프로토콜과 일치해야 해요.
• 대안: 환경 변수 스크립트(agents-env.sh) 하나로도 모든 에이전트가 하나의 키를 공유하도록 설정할 수 있어요.

에이전트를 세 개 이상 사용한다면 30분 정도 투자해 이 구성을 설정해 두는 것이 좋아요. 이후 모델을 바꾸거나 키를 교체할 때 한 곳만 수정하면 되니까요. APIYI apiyi.com에서 테스트 크레딧을 받아 자주 사용하는 도구 몇 가지부터 연결해 보고, 작업에 따라 에이전트별 모델을 세분화해 보세요.

함께 읽어보세요

• 📘 Workbuddy는 Claude 네이티브 형식 호출을 지원할까요? 3가지 원인과 6가지 content 오류 해결 방법 실측: Anthropic 네이티브 형식과 OpenAI 호환 형식의 차이가 궁금하다면 이 글을 참고하세요. 이 글의 2단계에서 설명하는 ‘Claude Code는 네이티브 엔드포인트를 사용해야 하는 이유’도 확인할 수 있어요.
• 📊 claude-sonnet-5-5와 claude-opus-5-5 비교: Opus는 더 빠르고 Sonnet은 더 저렴할 뿐일까요? 데이터 6가지로 알아보는 기업용 장문 컨텍스트 Agent의 최적 조합: 4단계에서 Agent별 모델을 나누기 전에 먼저 읽어보세요. 어떤 Agent에 Opus를 쓰고, 어떤 Agent에 저렴한 모델을 쓸지 결정하는 데 도움이 돼요.
• ⚠️ gemini-4-argon AI Studio의 동시 요청 수는 얼마일까요? 429 오류가 자주 발생하는 5가지 원인과 6단계 해결 방법: 여러 Agent가 같은 키를 동시에 사용하다가 속도 제한에 걸렸다면, 여기서 안내하는 6단계에 따라 문제를 해결해 보세요.
• 🧭 OpenAI에서 model not found 오류가 발생하나요? GPT-5.5는 10월 14일 ChatGPT에서 지원이 종료됐어요. 5단계 문제 해결 및 대안: 5단계 검증 중 ‘모델을 찾을 수 없음’ 오류가 발생했다면, 먼저 해당 모델명이 아직 유효한지 확인하세요.

📚 참고 자료

1. GitHub – magpie: 프로젝트 공식 저장소
2. 링크: github.com/yetone/magpie
3. 설명: 설치 방법, 설정 형식, 버전 업데이트는 README를 기준으로 확인하세요.
4. Claude Code 공식 문서: 환경 변수 및 settings 설정
5. 링크: docs.anthropic.com/en/docs/claude-code
6. 설명: ANTHROPIC_BASE_URL 등 환경 변수에 관한 공식 안내예요.
7. OpenAI Codex CLI 저장소: config.toml 및 model_providers 설정
8. 링크: github.com/openai/codex
9. 설명: 사용자 지정 provider 및 wire_api 매개변수에 관한 안내예요.
10. APIYI 문서 센터: 멀티 프로토콜 엔드포인트 및 모델 목록
11. 링크: docs.apiyi.com
12. 설명: OpenAI, Anthropic 등 프로토콜 엔드포인트 연결 방법을 확인할 수 있어요.

작성자: APIYI 기술팀
기술 교류: 댓글로 magpie 설정 경험을 공유해 주세요. 더 많은 연결 자료는 APIYI 문서 센터(docs.apiyi.com)에서 확인할 수 있어요.