이 페이지에서
Claude Desktop
개발자 모드의 서드파티 추론 설정에 HiAPI를 입력해 Claude 데스크톱 앱에서 HiAPI를 통해 Claude 모델을 사용합니다.
Claude 데스크톱 앱의 개발자 모드에는 서드파티 추론 설정(Configure third-party inference)이 있습니다. HiAPI 주소와 키를 입력하면 HiAPI를 통해 Claude 모델을 사용할 수 있습니다. 아래 단계는 claude-opus-5-5를 예로 사용하며, 이 튜토리얼은 Windows 11에서 Claude Desktop 4.29.0으로 검증했습니다. 클라이언트 버전에 이 설정 항목이 있어야 하며, HiAPI API 키를 미리 준비해야 합니다.
1. 클라이언트 준비
Claude 데스크톱 앱을 열고, 아래 설정을 마칠 때까지 로그인 페이지에 그대로 머물러 있으세요.
이미 Claude 계정으로 로그인되어 있다면 먼저 로그아웃한 뒤, 클라이언트를 완전히 종료했다가 다시 열고 로그인 페이지가 표시되는지 확인하세요. 서드파티 추론을 설정하기 전에 로그인하지 마세요.
2. 개발자 모드 활성화
Help → Troubleshooting → Enable developer mode를 클릭합니다. Windows에서는 창 왼쪽 위 메뉴에 Help가 있고, Mac에서는 화면 위쪽 메뉴 막대에 있습니다.
활성화하면 메뉴 막대에 Developer 메뉴가 나타납니다. 나타나지 않으면 클라이언트를 재시작하고 다시 확인하세요.
서드파티 추론 설정은 Developer 메뉴에 있습니다. 먼저 개발자 모드를 활성화한 다음 Configure third-party inference를 엽니다.
3. 서드파티 추론 설정
Developer → Configure third-party inference를 열고 왼쪽에서 Connection을 선택한 뒤 아래 표를 채우세요:
| 항목 | 값 |
|---|---|
| Connection | Gateway |
| Credential kind | Static API key |
| Gateway base URL | https://api.hiapi.ai (/v1 없이. 클라이언트가 경로를 직접 덧붙임) |
| Gateway API key | 자신의 HiAPI API 키 |
| Gateway auth scheme | 비워 두면 클라이언트 기본값 Authorization: Bearer 사용 |
| Artifact preview iframe origin | 비워 둠 |
Connection 페이지에 Model list 항목이 있으면 사용할 모델(예: claude-opus-5-5)을 추가하고, 없으면 연결 테스트를 바로 실행하세요.
설정 저장 및 적용
- Test connection을 클릭하고 클라이언트에 연결 테스트 통과가 표시될 때까지 기다립니다.
- Apply Changes를 클릭해 설정을 적용합니다.
- Claude 데스크톱 앱을 완전히 종료한 뒤 다시 엽니다.
연결 테스트는 게이트웨이 설정만 확인합니다. 적용한 뒤에도 실제 채팅으로 모델을 호출할 수 있는지 확인하세요.
4. 확인
설정이 적용되면 클라이언트가 채팅 인터페이스를 엽니다. 설정한 모델(예: claude-opus-5-5)을 선택하고 “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내세요. 정상적으로 답하면 연결이 된 것입니다.
HiAPI 콘솔의 요청 로그에서 요청이 HiAPI를 거쳐 가는지도 확인할 수 있습니다. 로그인 페이지가 계속 보이거나 답이 없다면 아래 문제 해결 항목을 따라 해결하세요.
외부 도구나 데이터 소스를 연결하려면 Connectors(MCP)를 사용하세요. MCP 설정 가이드의 Claude Desktop 섹션을 참고하세요.
5. 문제 해결
여기에는 Claude Desktop에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.
| 오류 | 원인 | 해결 방법 |
|---|---|---|
| 연결 테스트 실패 | Gateway base URL이 잘못되었거나, 유효하지 않은 HiAPI API 키를 입력했거나, 네트워크 문제 | Gateway base URL이 /v1 없이 https://api.hiapi.ai인지 확인하고, 키와 네트워크를 점검하세요 |
| 재시작 후에도 로그인 페이지가 표시됨 | 서드파티 추론 설정이 적용되지 않았거나 클라이언트가 원래 로그인 상태를 유지함 | 원래 계정에서 로그아웃하고 Apply Changes를 클릭했는지 확인한 뒤 클라이언트를 완전히 종료했다가 다시 여세요 |
| 메뉴 막대에 Developer 메뉴가 없음 | 개발자 모드가 활성화되지 않았거나 이 버전에 해당 기능이 없음 | Help → Troubleshooting에서 개발자 모드를 확인하고, 클라이언트 버전이 서드파티 추론을 지원하는지 확인하세요 |
| 404 / model not available | 모델 이름이 틀렸거나 Gateway base URL에 경로가 더 붙음 | 텍스트 모델 목록에서 모델 이름을 확인하세요. Gateway base URL은 https://api.hiapi.ai여야 합니다 |