magpie

macOS 및 Windows의 Codex Desktop 연결 절차는 다음 가이드를 참고하세요: Codex Desktop。

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`

WorkBuddy 사용자 지정 모델에서 바로 정상 작동한다면 직접 연결 가이드를 사용하세요. 프로토콜 변환이 필요할 때 magpie를 적용합니다. 이미지 커넥터는 WorkBuddy-이미지 생성을 참고하세요.

2. 사전 조건

WorkBuddy 설치 및 한 번 이상 실행.
GravitexAI 콘솔에서 API 키 생성.
모델 목록에서 계정 사용 가능 모델과 인터페이스 확인.
magpie와 WorkBuddy를 같은 컴퓨터에서 실행. 기본 게이트웨이 포트는 3425입니다.

3. magpie 설치

macOS
Windows

공식 설치 스크립트를 실행합니다.

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

또는 공식 사이트에서 Apple Silicon/Intel 패키지를 다운로드합니다. 앱을 열고 확인하세요.

magpie --version
magpie ls

명령을 찾지 못하면 터미널을 다시 열거나 ~/.local/bin을 셸 PATH에 추가합니다.

공식 사이트 또는 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로 바꿉니다.

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

4. GravitexAI 제공자 설정

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

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

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 한 줄 명령:

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`	표시 이름

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

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

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

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

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

magpie provider set gravitex responses=https://api.gravitex.ai/v1 anthropic=https://api.gravitex.ai

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

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

magpie provider test gravitex
magpie models workbuddy

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

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`

아래는 WorkBuddy 중국판 기준입니다. WORKBUDDY_CONFIG_DIR을 지정했다면 실제 경로를 사용하세요. Windows의 ~는 사용자 홈 폴더입니다.

2단계: 종료 및 백업

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

macOS
Windows PowerShell

cp ~/.workbuddy/models.json ~/.workbuddy/models.json.bak-$(date +%Y%m%d-%H%M%S)

$workbuddyModels = Join-Path $HOME '.workbuddy/models.json'
Copy-Item $workbuddyModels "$workbuddyModels.bak-$(Get-Date -Format 'yyyyMMdd-HHmmss')"

3단계: 모델 선택 및 연결

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

magpie workbuddy gravitex/claude-sonnet-5-5

magpie workbuddy gravitex/gpt-6-sol

두 명령 중 하나만 실행합니다. 모델은 provider-id/model-id 형식이며 magpie가 WorkBuddy 모델 파일에 연결 설정을 기록합니다. 데스크톱에서는 Agent 페이지에서 WorkBuddy를 찾아 연결 스위치를 켜고 GravitexAI 모델을 선택해도 됩니다. 아래는 페이지 구조 예시입니다. WorkBuddy는 보이는 영역 밖에 있으므로 목록에서 더 찾아야 합니다.

4단계: WorkBuddy 재실행 및 검증

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

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

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

6. 검증과 문제 해결

로컬 게이트웨이 확인

macOS
Windows PowerShell

lsof -nP -iTCP:3425 -sTCP:LISTEN

리스닝 프로세스가 없으면 앱을 엽니다.

open -a magpie

Get-NetTCPConnection -LocalPort 3425 -State Listen

리스닝하지 않으면 다운로드한 데스크톱 프로그램을 엽니다.

도구 호출과 추론 확인

대화는 되지만 도구 작업에 400이 나오면 tools와 reasoning_effort 관련 오류인지 확인합니다. responses=https://api.gravitex.ai/v1과 모델의 Responses 지원 여부를 확인하세요. 목록에 모델이 보이는 것만으로 성공은 아닙니다. 실제 대화와 도구 작업을 모두 확인해야 합니다. 추론 모델이 HTTP 200이지만 빈 응답을 주면 출력 예산 부족도 확인합니다.

WorkBuddy 모델 목록이 바뀌지 않음

완전히 종료하고 다시 여세요. 국제판이나 CodeBuddy Code가 아니라 workbuddy 중국판을 연결했는지 magpie ls로 클라이언트와 경로를 확인합니다.

magpie 모델 선택 후 연결 실패

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

Claude의 404

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

GPT 도구 호출과 추론을 함께 쓰면 400

responses=https://api.gravitex.ai/v1을 추가하고 모델 및 계정 지원을 확인합니다. 이 조합을 지원하지 않는 Chat Completions 경로로 전달하지 않도록 하세요.

401 / 403

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

원하는 모델이 목록에 없음

계정 권한을 확인한 뒤 magpie provider models gravitex +model-id로 추가하세요. 필요하면 WorkBuddy를 다시 연결하고 완전히 재시작합니다.

7. 복구와 유지 관리

WorkBuddy 연결 해제

magpie workbuddy default

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

로그인 시 자동 실행

magpie autostart on

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

대화형 AI

프로그래밍 개발

AI 에이전트

기술 엔지니어링

번역

1. 제품 소개

2. 사전 조건

3. magpie 설치

4. GravitexAI 제공자 설정

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

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

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

5. WorkBuddy 연결 예시

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

2단계: 종료 및 백업

3단계: 모델 선택 및 연결

4단계: WorkBuddy 재실행 및 검증

6. 검증과 문제 해결

로컬 게이트웨이 확인

도구 호출과 추론 확인

7. 복구와 유지 관리

WorkBuddy 연결 해제

로그인 시 자동 실행

8. 관련 자료

​1. 제품 소개

​2. 사전 조건

​3. magpie 설치

​4. GravitexAI 제공자 설정

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

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

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

​5. WorkBuddy 연결 예시

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

​2단계: 종료 및 백업

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

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

​6. 검증과 문제 해결

​로컬 게이트웨이 확인

​도구 호출과 추론 확인

​7. 복구와 유지 관리

​WorkBuddy 연결 해제

​로그인 시 자동 실행

​8. 관련 자료

1. 제품 소개

2. 사전 조건

3. magpie 설치

4. GravitexAI 제공자 설정

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

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

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

5. WorkBuddy 연결 예시

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

2단계: 종료 및 백업

3단계: 모델 선택 및 연결

4단계: WorkBuddy 재실행 및 검증

6. 검증과 문제 해결

로컬 게이트웨이 확인

도구 호출과 추론 확인

7. 복구와 유지 관리

WorkBuddy 연결 해제

로그인 시 자동 실행

8. 관련 자료