> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Magpie

> 데스크톱 인터페이스를 통해 Magpie를 APIYI에 연결하고, Codex 및 Claude Code의 모델, API URL, 키를 구성하며, CLI 예제로 문제를 해결합니다.

## Magpie가 APIYI에 연결되는 방식

Magpie는 AI 코딩 도구의 모델과 제공업체를 관리하는 오픈 소스 애플리케이션입니다. Magpie에 APIYI를 추가하면 Codex, Claude Code 및 기타 도구에서 사용할 모델을 하나의 인터페이스에서 선택할 수 있습니다. Magpie는 각 도구의 설정 파일에 설정을 기록합니다.

요청은 APIYI에 도달하기 전에 로컬 게이트웨이를 통과합니다.

```text theme={null}
Coding tool → Magpie gateway → APIYI → Model
```

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 구성 가이드](https://docs.apiyi.com/ko/scenarios/programming/codex-cli.md) 또는 [Claude Code 구성 가이드](https://docs.apiyi.com/ko/scenarios/programming/claude-code.md)의 설치 섹션을 참조하십시오.
3. [APIYI token 페이지](https://api.apiyi.com/token)에서 API 키를 준비합니다. 계정에 사용 가능한 잔액이 있고 tokens로 선택한 모델에 접근할 수 있는지 확인합니다.

이 가이드에서는 **APIYI**와 **APIYI Claude**, 두 가지 제공자 항목을 다룹니다. 코딩 도구를 하나만 사용하는 경우 해당 도구에 대응하는 항목만 구성합니다. 두 항목을 모두 생성하려면 **서로 다른 두 개의 tokens**를 사용합니다. 첫 번째 항목에는 GPT 모델에 접근할 수 있는 token을 사용하고, 두 번째 항목에는 `ClaudeCode` 그룹의 token을 사용합니다. Magpie는 동일한 호스트에서 동일한 키를 사용하는 구성을 중복 제공자로 간주합니다.

> [!NOTE]
>
> Magpie는 터미널에서 API 키 환경 변수를 자동으로 읽지 않습니다. 제공자 양식에 키를 붙여넣거나 아래 CLI 명령으로 추가합니다.

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

### Codex용 제공자 구성

**1. 사용자 지정 제공자 추가**

**제공자 → 제공자 추가 → 사용자 지정 제공자**를 열고 다음을 입력합니다.

| 필드 | 값 |
| - | - |
| 이름 | `APIYI` |
| 기본 프로토콜 | **OpenAI 호환** |
| 기본 URL | `https://api.apiyi.com/v1` |
| API 키 | GPT 모델용 APIYI token |

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을 사용하여 **사용자 지정 제공자**를 하나 더 추가합니다.

| 필드 | 값 |
| - | - |
| 이름 | `APIYI Claude` |
| 기본 프로토콜 | **Anthropic 호환** |
| 기본 URL | `https://api.apiyi.com` |
| API 키 | `ClaudeCode` 그룹의 다른 APIYI token |
| 모델 | `claude-sonnet-4-6` |

여기 URL에는 **`/v1`가 포함되지 않습니다**. Magpie가 `/v1/messages`을 추가합니다. 모델을 가져온 다음 사용할 Claude 모델만 선택합니다. `claude-sonnet-4-6`을 직접 입력한 후 저장할 수도 있습니다.

> [!TIP]
>
> 제공자 항목을 분리하면 모델, 프로토콜, token 그룹을 각각 관리할 수 있습니다. `ClaudeCode` 그룹에 대한 자세한 내용은 [token 그룹](https://docs.apiyi.com/ko/faq/groups-explained.md)을 참조하세요.

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

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와 에이전트에서 선택하는 전체 식별자는 용도가 다릅니다.

> [!NOTE]
>
> Magpie는 관리하는 도구의 API 설정을 기록합니다. 문제를 해결할 때는 기존 환경 변수, 프로젝트 설정 및 다른 구성 관리자도 확인하여 이전 서비스 URL이 다시 설정되지 않도록 하세요.

## 연결 확인

먼저 공급자 페이지에서 테스트를 실행한 다음, 코딩 도구에서 다음과 같이 짧은 요청을 보냅니다.

```text theme={null}
Reply with only: Connection successful.
```

응답을 받은 후 Magpie의 요청 또는 사용량 기록과 [APIYI 콘솔](https://api.apiyi.com)의 호출 로그를 확인합니다. 요청에 의도한 모델과 공급자가 사용되었는지 확인합니다. 그런 다음 도구에 프로젝트의 작은 파일을 설명하도록 요청해 일상적인 코딩 워크플로를 검증합니다.

**모델을 성공적으로 가져왔다는 것은 모델 목록 엔드포인트에 연결할 수 있다는 것만 확인합니다.** 채팅 요청에는 일치하는 모델, 토큰 권한, 요청 프로토콜도 필요합니다. 공급자 테스트는 실제 API 요청을 소량 전송하며, 모델 사용량에 따라 과금됩니다.

## CLI를 통한 구성

터미널을 선호하는 경우, 인터페이스를 통해 공급자를 추가하는 대신 다음 명령을 사용합니다. 먼저 `magpie` 명령이 설치되어 있는지 확인하고 데스크톱 앱을 실행된 상태로 유지합니다.

> [!NOTE]
>
> 인터페이스에서 이미 공급자를 생성했다면 `provider add`을 다시 실행하지 마십시오. `magpie providers`를 실행하여 실제 공급자 ID를 확인한 다음, 테스트 또는 모델 선택 명령에 해당 ID를 대신 입력합니다. 인터페이스를 통해 생성된 ID는 공급자 이름에서 생성됩니다. 명령에서 `id=`를 사용하면 특정 ID를 요청합니다. ID가 이미 사용 중인 경우 Magpie가 접미사를 추가할 수 있으므로, CLI를 통해 공급자를 추가한 후에도 실제 ID를 확인하십시오.

### 두 공급자 추가

첫 번째 명령의 `sk-your-api-key`을 GPT 모델에 사용할 token으로 바꿉니다.

```bash theme={null}
magpie provider add APIYI id=apiyi url=https://api.apiyi.com/v1 responses=https://api.apiyi.com/v1 key=sk-your-api-key models=gpt-5.4
```

두 번째 명령의 `sk-your-api-key`를 `ClaudeCode` 그룹의 **다른** token으로 바꿉니다.

```bash theme={null}
magpie provider add "APIYI Claude" id=apiyi-claude anthropic=https://api.apiyi.com key=sk-your-api-key models=claude-sonnet-4-6
```

### 모델 나열 및 도구 연결

```bash theme={null}
magpie providers
magpie models
magpie codex model apiyi/gpt-5.4
magpie claude model apiyi-claude/claude-sonnet-4-6
```

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

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

```bash theme={null}
magpie provider test apiyi
magpie provider test apiyi-claude
magpie healthcheck
```

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

## 문제 해결

> **인증에 실패하고 401 또는 403 오류가 발생합니다**
>
> Magpie 제공업체에 저장된 API 키가 완전하고 유효한지, APIYI 계정에 사용 가능한 잔액이 있는지, 토큰에 대상 모델에 대한 액세스 권한이 있는지 확인합니다. Claude Code 구성에는 `ClaudeCode` 그룹의 토큰을 사용합니다. 터미널 환경 변수를 변경해도 Magpie에 이미 저장된 키는 자동으로 업데이트되지 않습니다. 제공업체를 수정한 후 저장합니다.

> **요청에 404 또는 엔드포인트를 찾을 수 없다는 오류가 반환됩니다**
>
> 선택한 프로토콜에 맞는 URL인지 확인합니다. OpenAI 호환 및 Responses에는 `https://api.apiyi.com/v1`을, Anthropic 호환에는 `https://api.apiyi.com`를 사용합니다. 전체 요청 경로를 덧붙이지 마세요. 대상 모델이 해당 엔드포인트를 지원하는지 확인하고, Chat Completions만 지원하는 모델에 Responses 엔드포인트를 구성하지 마세요.

> **모델 목록은 로드되지만 Agents에 모델이 표시되지 않습니다**
>
> 제공업체에서 모델을 선택하고 저장했는지 확인한 다음, 에이전트 자체의 표시 모델 목록을 확인합니다. `magpie models`을 실행하여 Magpie에서 현재 제공하는 모델을 확인합니다. 모델을 직접 추가할 때는 원시 모델 ID를 확인하고, 도구에서 모델을 선택할 때는 제공업체 접두사와 ID를 확인합니다.

> **두 번째 제공업체를 추가하면 중복 경고가 표시됩니다**
>
> Magpie는 호스트 및 키와 같은 정보를 사용하여 중복 제공업체를 감지합니다. 이 가이드의 두 항목에는 서로 다른 두 개의 APIYI 토큰이 필요합니다. 제공업체 이름이나 프로토콜만 변경해도 중복 경고가 표시될 수 있습니다.

> **Agents에 도구가 표시되지 않거나 새 모델에 이전 구성이 계속 적용됩니다**
>
> 도구가 설치되어 있는지 확인한 다음 Magpie를 다시 열어 도구가 감지되는지 확인합니다. 모델을 선택한 후 도구에서 새 세션을 시작합니다. 기존 환경 변수, 프로젝트 설정 또는 다른 구성 관리자가 구성을 재정의하는지 확인합니다. 도구 설치 방법은 이 사이트의 해당 가이드를 참조합니다.

> **Magpie를 종료하면 코딩 도구가 연결되지 않습니다**
>
> 코딩 도구는 이제 로컬 게이트웨이에 연결됩니다. 다른 게이트웨이 프로세스가 실행 중이지 않은 상태에서 Magpie를 종료하면 요청 전달이 중단됩니다. Magpie를 다시 연 다음 `magpie healthcheck`를 실행하여 로컬 게이트웨이가 온라인인지 확인합니다.

## 모델 선택 및 관련 리소스

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

> **[모델 추천](https://docs.apiyi.com/ko/api-capabilities/model-info.md)**
>
> 코딩 작업에 적합한 모델을 선택하고 사용 권장 사항을 확인하십시오.

> **[모델 가격](https://docs.apiyi.com/ko/models/index.md)**
>
> 최신 APIYI 모델 가격과 사용 가능한 모델을 확인하십시오.

> **[Codex 구성 가이드](https://docs.apiyi.com/ko/scenarios/programming/codex-cli.md)**
>
> 도구 설치, 모델 구성 및 사용 지침을 확인하십시오.

> **[Claude Code 구성 가이드](https://docs.apiyi.com/ko/scenarios/programming/claude-code.md)**
>
> 설치, token 그룹 및 문제 해결 방법을 확인하십시오.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.