Skip to main content
적용 버전: Claude Desktop 2025.6 이상 (기본 제3자 추론/Gateway 지원, 패키지 변경 또는 프록시 없이 사용 가능).

​
1. 설정 단계

​
1단계: 개발자 모드 활성화

  1. Claude Desktop을 엽니다.
  2. 상단 메뉴 → Help → Troubleshooting → Enable Developer Mode.
  3. 활성화 후 Claude Desktop이 자동 재시작되며, 상단 메뉴에 Developer 메뉴가 나타납니다.

​
2단계: 제3자 추론 설정 진입

  1. 메뉴 → Developer → Configure third-party inference.
  2. 팝업 창에서 연결 방식을 Gateway로 선택합니다.
개발자 모드 활성화 및 제3자 추론 설정 진입 연결 방식 Gateway 선택

​
3단계: Gateway 정보 입력

Gateway 정보 입력
Gateway base URL 입력 규칙 (가장 흔한 실수):
  • 최종 요청 = 입력한 base URL + "/v1/messages"
  • 실제 수신 주소가 https://api.gravitex.ai/v1/messages인 경우, base URL은 https://api.gravitex.ai로 입력
  • /v1/messages 접미사를 직접 추가하지 마세요. 그렇게 하면 .../v1/messages/v1/messages가 되어 404 오류가 발생합니다.

​
4단계: 모델 구성 (Model)

2가지 방식 중 하나를 선택하세요: 첫 번째 (권장): Model discovery 활성화:
  • 시작 시 {base URL}/v1/models에서 모델 선택기를 자동 채우는 옵션을 체크합니다.
  • Test model discovery를 클릭하여 지원 모델 목록을 가져올 수 있는지 확인합니다.
  • 모델 드롭다운에 지원 모델만 자동으로 표시되어 모델명 입력 오류를 방지합니다.
두 번째: 수동 지정. Model list에서 + Add를 클릭하여 다음과 같이 입력합니다: 모델 Model discovery 구성 Tier alias가 중요한 이유: Claude Desktop 내부에서는 opus / sonnet / haiku / fable 티어 별칭을 사용하여 다양한 유형의 호출을 할당합니다 (예: 가벼운 요약 작업은 haiku, 복잡한 추론은 opus). claude-opus-4-8의 Tier alias를 opus로 설정하면 클라이언트가 이를 Opus 티어로 인식합니다. 비워두거나 잘못 선택하면 “Invalid: Model list” 오류가 발생합니다. 📌 Model list의 첫 번째 항목이 기본 모델입니다. 가장 자주 사용하는 모델(예: Sonnet)을 맨 위에 두는 것을 권장합니다.
일반적인 오류: 하단에 “Invalid: Model list” 표시보통 다음 이유 중 하나입니다:
  • Tier alias가 선택되지 않음;
  • Model ID가 기존 항목과 중복됨;
  • Model ID 형식이 클라이언트에서 수용되지 않음 (공백, 특수 문자 등 포함).
수정 후 Save Changes를 먼저 클릭한 다음 Apply Changes를 클릭하세요.

​
5단계: 적용 및 재시작

  1. Apply Changes를 클릭합니다.
  2. Claude Desktop을 완전히 종료합니다 (macOS: Claude 메뉴 → Quit Claude / Cmd+Q, 활동 모니터에서 Claude 프로세스가 없는지 확인).
  3. Claude Desktop을 다시 엽니다.
  4. 테스트 메시지를 보내어 검증합니다.

​
2. 성공 여부 확인

  • Claude Desktop이 정상적으로 시작되며, 왼쪽 하단에 계정 이름 · Gateway가 표시됩니다.
  • 메시지 전송 후 authentication / invalid api key / gateway unavailable / model_not_found 등의 오류가 없습니다.

​
3. 문제 해결

​
4. 보안 안내

  • API Key는 비밀번호와 동일하므로 공개 문서, 스크린샷 또는 코드 저장소에 작성하지 마세요.
  • 내보낸 설정 파일(.mobileconfig / .reg / .json)은 평문 키를 포함할 수 있습니다. 신뢰할 수 있는 장치에만 단기간 저장하고 사용 후 삭제하세요.
  • 키가 채팅, 스크린샷 또는 로그에 노출된 경우 즉시 폐기하고 재생성하세요.