메인 콘텐츠로 건너뛰기

​
Magpie가 APIYI에 연결되는 방식

Magpie는 AI 코딩 도구의 모델과 제공업체를 관리하는 오픈 소스 애플리케이션입니다. Magpie에 APIYI를 추가하면 Codex, Claude Code 및 기타 도구에서 사용할 모델을 하나의 인터페이스에서 선택할 수 있습니다. Magpie는 각 도구의 설정 파일에 설정을 기록합니다. 요청은 APIYI에 도달하기 전에 로컬 게이트웨이를 통과합니다.
Magpie의 제공업체 설정에 APIYI URL과 실제 API 키를 입력합니다. Magpie는 코딩 도구를 기본적으로 127.0.0.1:3425에서 수신 대기하는 로컬 게이트웨이에 연결합니다. 도구를 사용하는 동안 Magpie를 실행 상태로 유지합니다. 프로젝트: github.com/yetone/magpie; 공식 시작 가이드: usemagpie.ai/docs/start.

​
시작하기 전에

  1. usemagpie.ai에서 macOS, Windows 또는 Linux용 데스크톱 앱을 다운로드한 다음 설치하고 실행합니다.
  2. 사용할 코딩 도구를 설치합니다. Codex 구성 가이드 또는 Claude Code 구성 가이드의 설치 섹션을 참조하십시오.
  3. APIYI token 페이지에서 API 키를 준비합니다. 계정에 사용 가능한 잔액이 있고 tokens로 선택한 모델에 접근할 수 있는지 확인합니다.
이 가이드에서는 APIYI와 APIYI Claude, 두 가지 제공자 항목을 다룹니다. 코딩 도구를 하나만 사용하는 경우 해당 도구에 대응하는 항목만 구성합니다. 두 항목을 모두 생성하려면 서로 다른 두 개의 tokens를 사용합니다. 첫 번째 항목에는 GPT 모델에 접근할 수 있는 token을 사용하고, 두 번째 항목에는 ClaudeCode 그룹의 token을 사용합니다. Magpie는 동일한 호스트에서 동일한 키를 사용하는 구성을 중복 제공자로 간주합니다.
Magpie는 터미널에서 API 키 환경 변수를 자동으로 읽지 않습니다. 제공자 양식에 키를 붙여넣거나 아래 CLI 명령으로 추가합니다.

​
데스크톱 인터페이스에서 구성

​
Codex용 제공자 구성

1

사용자 지정 제공자 추가

제공자 → 제공자 추가 → 사용자 지정 제공자를 열고 다음을 입력합니다.URL은 /v1에서 끝나야 합니다. Magpie가 요청 경로를 추가하므로 전체 /chat/completions 경로를 입력하지 마세요.
2

GPT 모델용 Responses 엔드포인트 추가

추가 엔드포인트를 펼치고 Responses URL을 https://api.apiyi.com/v1로 설정합니다.이 가이드에서는 APIYI에서 Chat Completions와 Responses를 모두 지원하는 gpt-5.4을 사용합니다. Codex는 Magpie를 통해 이 모델에 액세스할 때 Responses 엔드포인트를 사용할 수 있습니다.APIYI가 선택한 모델에 대해 해당 프로토콜을 지원하는 경우에만 엔드포인트를 구성하세요. Magpie의 로컬 게이트웨이에서 Responses를 지원한다고 해서 APIYI의 모든 모델이 기본 Responses를 지원하는 것은 아닙니다.
3

모델 가져오기 및 선택

모델 가져오기를 클릭하고 모델 목록에서 gpt-5.4을 선택한 다음 제공자를 저장합니다.초기 설정에서는 이 모델만 선택합니다. 다른 GPT 모델을 추가하기 전에 APIYI에서 동일한 엔드포인트를 지원하는지 확인하세요. 이미지, 임베딩 또는 기타 비채팅 모델은 코딩 도구의 모델 목록에 추가하지 마세요.필요한 모델이 목록에 없으면 모델에서 정확한 모델 ID를 직접 추가합니다. 제공자의 모델 필드에 gpt-5.4을 입력하되 apiyi/ 접두사는 제외합니다.

​
Claude Code용 제공자 구성

ClaudeCode 그룹의 다른 token을 사용하여 사용자 지정 제공자를 하나 더 추가합니다. 여기 URL에는 /v1가 포함되지 않습니다. Magpie가 /v1/messages을 추가합니다. 모델을 가져온 다음 사용할 Claude 모델만 선택합니다. claude-sonnet-4-6을 직접 입력한 후 저장할 수도 있습니다.
제공자 항목을 분리하면 모델, 프로토콜, token 그룹을 각각 관리할 수 있습니다. ClaudeCode 그룹에 대한 자세한 내용은 token 그룹을 참조하세요.

​
각 코딩 도구에 사용할 모델 선택

  1. 에이전트를 열고 설치된 Codex 또는 Claude Code 도구를 찾습니다.
  2. 도구의 현재 모델을 클릭한 다음, 방금 추가한 제공자 아래에서 모델을 찾아 선택합니다. Codex에는 APIYI → gpt-5.4, Claude Code에는 APIYI Claude → claude-sonnet-4-6을 선택합니다.
  3. 도구의 이전 세션을 닫고 도구를 다시 시작한 다음 새 세션을 열어 Magpie가 기록한 구성을 읽도록 합니다.
Magpie는 모델을 내부적으로 provider-id/model-id으로 식별합니다. 예를 들면 apiyi/gpt-5.4과 같습니다. 제공자 양식에 입력하는 원시 모델 ID와 에이전트에서 선택하는 전체 식별자는 용도가 다릅니다.
Magpie는 관리하는 도구의 API 설정을 기록합니다. 문제를 해결할 때는 기존 환경 변수, 프로젝트 설정 및 다른 구성 관리자도 확인하여 이전 서비스 URL이 다시 설정되지 않도록 하세요.

​
연결 확인

먼저 공급자 페이지에서 테스트를 실행한 다음, 코딩 도구에서 다음과 같이 짧은 요청을 보냅니다.
응답을 받은 후 Magpie의 요청 또는 사용량 기록과 APIYI 콘솔의 호출 로그를 확인합니다. 요청에 의도한 모델과 공급자가 사용되었는지 확인합니다. 그런 다음 도구에 프로젝트의 작은 파일을 설명하도록 요청해 일상적인 코딩 워크플로를 검증합니다. 모델을 성공적으로 가져왔다는 것은 모델 목록 엔드포인트에 연결할 수 있다는 것만 확인합니다. 채팅 요청에는 일치하는 모델, 토큰 권한, 요청 프로토콜도 필요합니다. 공급자 테스트는 실제 API 요청을 소량 전송하며, 모델 사용량에 따라 과금됩니다.

​
CLI를 통한 구성

터미널을 선호하는 경우, 인터페이스를 통해 공급자를 추가하는 대신 다음 명령을 사용합니다. 먼저 magpie 명령이 설치되어 있는지 확인하고 데스크톱 앱을 실행된 상태로 유지합니다.
인터페이스에서 이미 공급자를 생성했다면 provider add을 다시 실행하지 마십시오. magpie providers를 실행하여 실제 공급자 ID를 확인한 다음, 테스트 또는 모델 선택 명령에 해당 ID를 대신 입력합니다. 인터페이스를 통해 생성된 ID는 공급자 이름에서 생성됩니다. 명령에서 id=를 사용하면 특정 ID를 요청합니다. ID가 이미 사용 중인 경우 Magpie가 접미사를 추가할 수 있으므로, CLI를 통해 공급자를 추가한 후에도 실제 ID를 확인하십시오.

​
두 공급자 추가

첫 번째 명령의 sk-your-api-key을 GPT 모델에 사용할 token으로 바꿉니다.
두 번째 명령의 sk-your-api-key를 ClaudeCode 그룹의 다른 token으로 바꿉니다.

​
모델 나열 및 도구 연결

설치했고 구성하려는 도구에 해당하는 명령만 실행한 다음, 해당 도구에서 새 세션을 시작합니다. 이 명령은 구성을 업데이트합니다. 도구를 사용할 때에도 Magpie 게이트웨이는 계속 실행 중이어야 합니다.

​
업스트림 공급자 및 로컬 게이트웨이 테스트

provider test은 구성된 업스트림 엔드포인트에 실제 요청을 소수 전송합니다. healthcheck은 로컬 게이트웨이만 확인하므로, 이것만으로는 APIYI에 대한 모델 요청이 정상적으로 작동하는지 확인할 수 없습니다.

​
문제 해결

Magpie 제공업체에 저장된 API 키가 완전하고 유효한지, APIYI 계정에 사용 가능한 잔액이 있는지, 토큰에 대상 모델에 대한 액세스 권한이 있는지 확인합니다. Claude Code 구성에는 ClaudeCode 그룹의 토큰을 사용합니다. 터미널 환경 변수를 변경해도 Magpie에 이미 저장된 키는 자동으로 업데이트되지 않습니다. 제공업체를 수정한 후 저장합니다.
선택한 프로토콜에 맞는 URL인지 확인합니다. OpenAI 호환 및 Responses에는 https://api.apiyi.com/v1을, Anthropic 호환에는 https://api.apiyi.com를 사용합니다. 전체 요청 경로를 덧붙이지 마세요. 대상 모델이 해당 엔드포인트를 지원하는지 확인하고, Chat Completions만 지원하는 모델에 Responses 엔드포인트를 구성하지 마세요.
제공업체에서 모델을 선택하고 저장했는지 확인한 다음, 에이전트 자체의 표시 모델 목록을 확인합니다. magpie models을 실행하여 Magpie에서 현재 제공하는 모델을 확인합니다. 모델을 직접 추가할 때는 원시 모델 ID를 확인하고, 도구에서 모델을 선택할 때는 제공업체 접두사와 ID를 확인합니다.
Magpie는 호스트 및 키와 같은 정보를 사용하여 중복 제공업체를 감지합니다. 이 가이드의 두 항목에는 서로 다른 두 개의 APIYI 토큰이 필요합니다. 제공업체 이름이나 프로토콜만 변경해도 중복 경고가 표시될 수 있습니다.
도구가 설치되어 있는지 확인한 다음 Magpie를 다시 열어 도구가 감지되는지 확인합니다. 모델을 선택한 후 도구에서 새 세션을 시작합니다. 기존 환경 변수, 프로젝트 설정 또는 다른 구성 관리자가 구성을 재정의하는지 확인합니다. 도구 설치 방법은 이 사이트의 해당 가이드를 참조합니다.
코딩 도구는 이제 로컬 게이트웨이에 연결됩니다. 다른 게이트웨이 프로세스가 실행 중이지 않은 상태에서 Magpie를 종료하면 요청 전달이 중단됩니다. Magpie를 다시 연 다음 magpie healthcheck를 실행하여 로컬 게이트웨이가 온라인인지 확인합니다.

​
모델 선택 및 관련 리소스

이 가이드의 모델 ID는 구성 절차를 보여주는 예시입니다. 다른 모델을 추가하기 전에 엔드포인트 지원 여부와 token 권한을 확인하십시오. 최신 모델 추천 및 가격은 다음 페이지에서 확인할 수 있습니다.

모델 추천

코딩 작업에 적합한 모델을 선택하고 사용 권장 사항을 확인하십시오.

모델 가격

최신 APIYI 모델 가격과 사용 가능한 모델을 확인하십시오.

Codex 구성 가이드

도구 설치, 모델 구성 및 사용 지침을 확인하십시오.

Claude Code 구성 가이드

설치, token 그룹 및 문제 해결 방법을 확인하십시오.
공식 구성 참조: github.com/yetone/magpie/blob/main/docs/reference.md. 이 가이드의 구성 단계는 프로젝트 문서 및 소스 코드와 대조하여 확인했습니다. 선택한 모델 및 프로토콜로 실제 요청을 보내 모델 목록 조회, 스트리밍 및 도구 호출을 확인하십시오.