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

# magpie

> magpie로 GravitexAI 다중 프로토콜 게이트웨이를 설정하고 WorkBuddy에 연결하는 가이드

> [!NOTE]
>
> macOS 및 Windows의 Codex Desktop 연결 절차는 다음 가이드를 참고하세요: [Codex Desktop](https://docs.gravitex.ai/ko/integrations/codex-desktop.md)。

## 1. 제품 소개

**magpie**는 오픈소스 로컬 모델 게이트웨이 및 Agent 설정 관리 도구입니다. 여러 클라이언트에서 제공자 설정을 공유하고 Chat Completions, Responses, Anthropic Messages 사이를 변환할 수 있습니다.

이 문서는 **WorkBuddy**를 예로 듭니다. WorkBuddy가 로컬 magpie에 Chat Completions 요청을 보내면 magpie가 모델과 상위 엔드포인트 설정에 맞게 변환해 GravitexAI로 전달합니다.

| 연결 | 주소 또는 프로토콜 |
| - | - |
| WorkBuddy → magpie | `http://127.0.0.1:3425/v1/chat/completions` |
| magpie → GravitexAI GPT | `/v1/responses` |
| magpie → GravitexAI Claude | `/v1/messages` |
| magpie → Chat Completions 지원 모델 | `/v1/chat/completions` |

> [!NOTE]
>
> WorkBuddy 사용자 지정 모델에서 바로 정상 작동한다면 [직접 연결 가이드](https://docs.gravitex.ai/ko/integrations/workbuddy.md)를 사용하세요. 프로토콜 변환이 필요할 때 magpie를 적용합니다. 이미지 커넥터는 [WorkBuddy-이미지 생성](https://docs.gravitex.ai/ko/integrations/workbuddy-image-generation.md)을 참고하세요.

## 2. 사전 조건

* WorkBuddy 설치 및 한 번 이상 실행.
* [GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에서 API 키 생성.
* [모델 목록](https://maas.gravitex.ai/#/api-models)에서 계정 사용 가능 모델과 인터페이스 확인.
* magpie와 WorkBuddy를 같은 컴퓨터에서 실행. 기본 게이트웨이 포트는 `3425`입니다.

## 3. magpie 설치

> [tab] macOS
>
> 공식 설치 스크립트를 실행합니다.
>
> ```bash theme={null}
> curl -fsSL https://usemagpie.ai/install.sh | sh
> ```
>
> 또는 [공식 사이트](https://usemagpie.ai/)에서 Apple Silicon/Intel 패키지를 다운로드합니다. 앱을 열고 확인하세요.
>
> ```bash theme={null}
> magpie --version
> magpie ls
> ```
>
> 명령을 찾지 못하면 터미널을 다시 열거나 \~/.local/bin을 셸 PATH에 추가합니다.

> [tab] Windows
>
> [공식 사이트](https://usemagpie.ai/) 또는 [Releases](https://github.com/yetone/magpie/releases)에서 시스템 아키텍처에 맞게 다운로드합니다.
>
> | 패키지 | 실행 방식 |
> | - | - |
> | magpie-windows-amd64.exe / magpie-windows-arm64.exe | 데스크톱 및 트레이 |
> | magpie-cli-windows-amd64.exe / magpie-cli-windows-arm64.exe | CLI 전용 |
>
> 데스크톱 버전을 열어 게이트웨이를 실행합니다. 폴더를 PATH에 추가하고 PowerShell에서 magpie.exe를 사용하거나 실제 실행 파일 경로를 입력하세요. 아래 명령의 magpie는 환경에 맞게 magpie.exe로 바꿉니다.

> [!NOTE]
>
> 이 가이드는 GravitexAI API 키만 사용합니다. Claude, ChatGPT 등 구독 자격 증명을 가져올 필요가 없습니다.

## 4. GravitexAI 제공자 설정

### 1단계: 세 프로토콜 엔드포인트 추가

macOS에서 자리표시자 키를 바꾸고 실행합니다.

```bash theme={null}
magpie provider add gravitex \
  url=https://api.gravitex.ai/v1 \
  responses=https://api.gravitex.ai/v1 \
  anthropic=https://api.gravitex.ai \
  key=sk-your-api-key \
  name=GravitexAI
```

PowerShell 한 줄 명령:

```powershell theme={null}
magpie.exe provider add gravitex url=https://api.gravitex.ai/v1 responses=https://api.gravitex.ai/v1 anthropic=https://api.gravitex.ai key=sk-your-api-key name=GravitexAI
```

| 필드 | 값 | 용도 |
| - | - | - |
| `gravitex` | 제공자 ID | 이후 명령에서 참조 |
| `url=` | `https://api.gravitex.ai/v1` | Chat Completions 기본 주소 |
| `responses=` | `https://api.gravitex.ai/v1` | Responses 기본 주소 |
| `anthropic=` | `https://api.gravitex.ai` | Anthropic Messages 기본 주소 |
| `key=` | GravitexAI API 키 | 상위 서비스 인증 |
| `name=` | `GravitexAI` | 표시 이름 |

> [!WARNING]
>
> 기본 주소를 입력합니다. url=과 responses=는 /v1을 포함하지만 /chat/completions나 /responses는 붙이지 않습니다. anthropic=에는 /v1이 없으며 magpie가 Messages 경로를 추가합니다.

데스크톱의 **공급자(Providers)** 페이지에서도 GravitexAI를 편집할 수 있습니다. **Base URL**에 OpenAI 호환, OpenAI Responses, Anthropic 호환 주소를 각각 입력하고 키를 넣은 뒤 저장합니다. 아래 중국어 UI 스크린샷은 Responses 주소 설정입니다.

![magpie에서 GravitexAI Responses 엔드포인트 설정](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/magpie-provider.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=9eb8729dedb6ce51f789ff58a5c961b7)

> [!NOTE]
>
> 스크린샷 ID는 gravitexai, 명령 예시는 gravitex입니다. 실제 ID를 일관되게 사용하세요. 스크린샷의 ID라면 모델은 `gravitexai/model-id` 형식입니다.

### 2단계: 기존 제공자에 프로토콜 추가

gravitex가 이미 있다면 다시 만들지 않고 빠진 경로만 추가합니다.

```bash theme={null}
magpie provider set gravitex responses=https://api.gravitex.ai/v1 anthropic=https://api.gravitex.ai
```

> [!NOTE]
>
> 도구 호출과 추론을 함께 사용할 GPT 모델에는 Responses를 설정하세요. `Function tools with reasoning_effort are not supported`가 나오면 추론을 끄기 전에 이 경로부터 확인합니다.

### 3단계: 테스트 및 모델 선택

```bash theme={null}
magpie provider test gravitex
magpie models workbuddy
```

원하는 모델이 빠졌다면 계정에서 사용 가능한 ID를 공개 목록에 추가합니다.

```bash theme={null}
magpie provider models gravitex +gpt-6-sol +claude-sonnet-5-5 +deepseek-v4-pro
```

ID는 예시이며 계정 사용 가능 목록에 맞게 바꾸세요. 테스트는 실제 요청을 보내므로 소량의 API 비용이 발생할 수 있습니다.

## 5. WorkBuddy 연결 예시

### 1단계: 클라이언트와 설정 경로 확인

`magpie ls`로 올바른 클라이언트가 감지되는지 확인합니다.

| 클라이언트 | 기본 설정 |
| - | - |
| WorkBuddy 중국판 | `~/.workbuddy/models.json` |
| WorkBuddy AI 국제판 | `~/.workbuddy-ai/models.json` |
| CodeBuddy Code | `~/.codebuddy/models.json` 및 `settings.json` |

> [!NOTE]
>
> 아래는 WorkBuddy 중국판 기준입니다. WORKBUDDY\_CONFIG\_DIR을 지정했다면 실제 경로를 사용하세요. Windows의 \~는 사용자 홈 폴더입니다.

### 2단계: 종료 및 백업

macOS는 Cmd+Q, Windows는 트레이에서 종료한 뒤 프로세스가 멈췄는지 확인합니다.

> [tab] macOS
>
> ```bash theme={null}
> cp ~/.workbuddy/models.json ~/.workbuddy/models.json.bak-$(date +%Y%m%d-%H%M%S)
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $workbuddyModels = Join-Path $HOME '.workbuddy/models.json'
> Copy-Item $workbuddyModels "$workbuddyModels.bak-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
> ```

### 3단계: 모델 선택 및 연결

계정에서 사용할 수 있는 모델 하나를 선택합니다.

```bash Claude 사용 theme={null}
magpie workbuddy gravitex/claude-sonnet-5-5
```

```bash GPT 사용 theme={null}
magpie workbuddy gravitex/gpt-6-sol
```

두 명령 중 하나만 실행합니다. 모델은 provider-id/model-id 형식이며 magpie가 WorkBuddy 모델 파일에 연결 설정을 기록합니다.

데스크톱에서는 **Agent** 페이지에서 WorkBuddy를 찾아 연결 스위치를 켜고 GravitexAI 모델을 선택해도 됩니다. 아래는 페이지 구조 예시입니다. WorkBuddy는 보이는 영역 밖에 있으므로 목록에서 더 찾아야 합니다.

![magpie Agent의 연결 스위치와 모델 선택기](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/magpie-agents.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=cd688814d6f5bf73982985cabbd48919)

### 4단계: WorkBuddy 재실행 및 검증

1. magpie를 실행 상태로 둡니다.
2. WorkBuddy를 다시 엽니다.
3. 모델 선택기에서 magpie의 `gravitex/…` 모델을 선택합니다.
4. 새 작업에 간단한 메시지를 보내 응답을 확인합니다.
5. 테스트 폴더에서 파일 읽기/도구 작업을 시도해 도구 호출과 추론을 확인합니다.

아래는 gpt-6-luna로 인사를 보내 정상 응답을 받은 예시입니다. 입력창 오른쪽 아래에 선택 모델이 표시됩니다. 대화가 되면 도구 작업도 확인하세요.

![WorkBuddy에서 gpt-6-luna로 정상 응답 수신](https://mintcdn.com/gravitexai/QXITE-rsvJBzaoaP/images/magpie-workbuddy-chat.png?fit=max\&auto=format\&n=QXITE-rsvJBzaoaP\&q=85\&s=3a53795d7e0d5ac43e30ddc062b490e7)

> [!TIP]
>
> 새 연결이나 클라이언트 모델 목록 변경 후에는 WorkBuddy를 완전히 재시작합니다. magpie의 상위 경로만 바꿨다면 보통 클라이언트 파일을 다시 쓸 필요 없이 새 요청으로 검증할 수 있습니다.

## 6. 검증과 문제 해결

### 로컬 게이트웨이 확인

> [tab] macOS
>
> ```bash theme={null}
> lsof -nP -iTCP:3425 -sTCP:LISTEN
> ```
>
> 리스닝 프로세스가 없으면 앱을 엽니다.
>
> ```bash theme={null}
> open -a magpie
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> Get-NetTCPConnection -LocalPort 3425 -State Listen
> ```
>
> 리스닝하지 않으면 다운로드한 데스크톱 프로그램을 엽니다.

### 도구 호출과 추론 확인

대화는 되지만 도구 작업에 400이 나오면 tools와 reasoning\_effort 관련 오류인지 확인합니다. responses=[https://api.gravitex.ai/v1과](https://api.gravitex.ai/v1과) 모델의 Responses 지원 여부를 확인하세요.

목록에 모델이 보이는 것만으로 성공은 아닙니다. 실제 대화와 도구 작업을 모두 확인해야 합니다. 추론 모델이 HTTP 200이지만 빈 응답을 주면 출력 예산 부족도 확인합니다.

> [accordion] WorkBuddy 모델 목록이 바뀌지 않음
>
> 완전히 종료하고 다시 여세요. 국제판이나 CodeBuddy Code가 아니라 workbuddy 중국판을 연결했는지 magpie ls로 클라이언트와 경로를 확인합니다.

> [accordion] magpie 모델 선택 후 연결 실패
>
> magpie 실행, 3425 포트 리스닝, 프록시의 127.0.0.1 가로채기 여부를 확인합니다. 로컬 게이트웨이와 상위 GravitexAI 모두 연결 가능해야 합니다.

> [accordion] Claude의 404
>
> anthropic=[https://api.gravitex.ai로](https://api.gravitex.ai로) 설정하고 /v1을 붙이지 마세요. url=만 설정했다고 네이티브 Messages 경로가 설정된 것은 아닙니다.

> [accordion] GPT 도구 호출과 추론을 함께 쓰면 400
>
> responses=[https://api.gravitex.ai/v1을](https://api.gravitex.ai/v1을) 추가하고 모델 및 계정 지원을 확인합니다. 이 조합을 지원하지 않는 Chat Completions 경로로 전달하지 않도록 하세요.

> [accordion] 401 / 403
>
> 로컬 게이트웨이와 상위 GravitexAI 인증을 구분하세요. 상위 키는 magpie provider key gravitex sk-new-api-key로 갱신 후 테스트합니다. 수동 로컬 요청은 상위 키가 아닌 해당 게이트웨이 자격 증명을 사용합니다.

> [accordion] 원하는 모델이 목록에 없음
>
> 계정 권한을 확인한 뒤 magpie provider models gravitex +model-id로 추가하세요. 필요하면 WorkBuddy를 다시 연결하고 완전히 재시작합니다.

## 7. 복구와 유지 관리

### WorkBuddy 연결 해제

```bash theme={null}
magpie workbuddy default
```

실행 후 앱을 완전히 재시작합니다. 또는 클라이언트 종료 상태에서 백업 models.json을 복구할 수 있습니다.

### 로그인 시 자동 실행

```bash theme={null}
magpie autostart on
```

magpie 모델을 쓰려면 게이트웨이를 계속 실행해야 합니다. 정상 작동하는 직접 연결 모델도 남겨 두면 필요할 때 돌아갈 수 있습니다.

## 8. 관련 자료

* [공식 사이트](https://usemagpie.ai/)
* [공식 프로젝트](https://github.com/yetone/magpie)
* [시작 안내](https://usemagpie.ai/docs/start)
* [공식 Reference](https://github.com/yetone/magpie/blob/main/docs/reference.md)
* [WorkBuddy 직접 연결](https://docs.gravitex.ai/ko/integrations/workbuddy.md)
* [GravitexAI 키 관리](https://maas.gravitex.ai/#/api-keys)


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