Jiminbox Docs

claude desktop 설치 가이드

16 min read

Claude Desktop

Anthropic이 개발한 데스크톱용 AI 어시스턴트 앱입니다. Jiminbox 사용자는 타사 추론을 통해 Jiminbox에서 제공하는 LLM 모델을 Claude Desktop에서 사용할 수 있습니다.

개요

Claude Desktop에서 Jiminbox의 타사 추론 모델을 연결하고 사용하는 방법을 안내합니다.

설치 요구사항

시스템 요구사항

  • macOS: macOS 12+ (Apple Silicon 및 Intel 모두 지원)
  • Windows: Windows 10/11 64비트
  • 별도의 Node.js나 CLI 설치 불필요

API Key 보안 주의

API Key는 비밀번호처럼 중요한 인증 정보입니다. 설정 파일, 내보낸 프로필, 화면 캡처, 클라이언트에 입력한 API Key를 다른 사람에게 공유하거나 Git 저장소에 커밋하지 마세요. 키의 모양이나 접두사(예: sk-)를 추측해 덧붙이거나 바꾸지 말고, New API에서 실제로 생성·표시된 API Key 값 전체만 사용하세요. 유출되었다고 생각되면 기존 키를 즉시 폐기하고 새 키를 발급받으세요.

설치 가이드

1. Claude Desktop 다운로드 및 설치

  1. Claude 공식 다운로드 페이지에 접속합니다.
  2. 사용 중인 운영체제(macOS 또는 Windows)에 맞는 설치 파일을 다운로드합니다.
  3. 다운로드한 파일을 실행하여 설치합니다.
    • macOS: .dmg 파일을 열고 Claude 아이콘을 Applications 폴더로 드래그
    • Windows: .exe 설치 파일을 실행하고 안내에 따라 진행
  4. 설치가 완료되면 Claude Desktop 앱을 실행합니다.

설치 확인

앱 실행 후 Claude 로그인 화면이 나타나면 설치가 정상적으로 완료된 것입니다.

로그인 화면이 나타나면 다음 단계로 진행합니다.

2. Jiminbox API 키 발급

Claude Desktop에서 Jiminbox 모델을 사용하려면 API 키가 필요합니다.

  1. New API에 접속하여 로그인합니다.
  2. 현재 화면에 표시되는 API Key 관리 메뉴와 생성 버튼을 사용해 새 키를 발급합니다. 메뉴·버튼 이름은 업데이트될 수 있으므로, 이 문서의 표현과 다르면 New API 화면의 실제 안내를 따르세요.
  3. 키의 용도를 구분할 수 있는 이름을 입력합니다. 예: Claude Desktop 개인용 또는 Claude Desktop 팀 배포용.
  4. New API가 표시한 API Key 값 전체를 신뢰할 수 있는 비밀 관리 도구에만 보관하고, 다음 단계에서 필요한 경우에만 복사합니다. 키는 발급 직후 한 번만 전체 표시될 수 있으므로 화면 캡처나 메신저 임시 보관을 사용하지 마세요.

자세한 발급 방법은 jiminbox 빠른 시작 가이드에서 확인합니다.

3. 타사 추론 설정 (필수)

Jiminbox 사용자는 Claude Desktop에서 타사 추론(Third-party Inference) 기능을 활성화하여 Jiminbox의 LLM 모델을 사용해야 합니다.

3-1. 개발자 모드 활성화

Claude Desktop 앱을 엽니다(로그인할 필요가 없음).

  1. 좌측 상단의 메뉴 바에서 도움말 → 문제 해결 → 개발자 모드 활성화를 선택합니다.
  2. 개발자 모드가 활성화되면 메뉴에 개발자 항목이 새로 추가됩니다.

개발자 모드 확인

메뉴 바에 개발자 항목이 보이면 활성화된 것입니다.

3-2. 타사 추론 구성

개발자 모드 활성화 후, 타사 추론 설정 UI를 엽니다.

  1. 메뉴에서 개발자 → 타사 추론 구성으로 이동합니다.
  2. 아래 표의 필수 항목을 하나씩 입력합니다.
필드값설명
추론 공급사gateway타사 API 게이트웨이 사용
게이트웨이 기본 URLhttps://api.jiminbox.comJiminbox API 엔드포인트
게이트웨이 API 키<JIMINBOX_API_KEY>jiminbox 빠른 시작 가이드에서 발급받은 키

설정 팁

API Key 칸에는 New API가 실제로 생성·표시한 값 전체를 그대로 붙여 넣습니다. 접두사나 공백을 임의로 추가·삭제하지 마세요. 언급하지 않은 설정은 기본값을 유지하는 것을 권장합니다.

  1. 모든 필드를 입력한 후 로컬에 적용을 클릭합니다.

설정 예시 (화면에 표시되는 내용)

추론 공급사 (inferenceProvider): gateway
게이트웨이 기본 URL (inferenceGatewayBaseUrl): https://api.jiminbox.com
게이트웨이 API 키 (inferenceGatewayApiKey): <JIMINBOX_API_KEY>

주의

  • 게이트웨이 기본 URL은 반드시 https://api.jiminbox.com으로 입력합니다. /v1이나 /v1beta 접미사는 붙이지 않습니다.
  • 설정 화면이나 설정 파일을 지원 요청에 첨부할 때도 API Key 값은 공유하지 마세요. 오류 화면에는 키가 가려져 있는지 먼저 확인하세요.

3-3. 설정 파일 내보내기 (선택)

설정 UI 하단의 내보내기 버튼을 클릭하면, 배포용 설정 파일을 다운로드할 수 있습니다.

OS내보내기 파일배포 방법
macOS.mobileconfigJamf, Kandji, Mosyle, Intune for Mac 등 MDM 솔루션으로 배포
Windows.reg그룹 정책, Intune, 또는 레지스트리 임포트로 배포

내보낸 파일과 MDM 배포의 키 유출 위험

내보낸 .mobileconfig 또는 .reg 파일에는 게이트웨이 API Key가 평문 또는 복원 가능한 형태로 포함될 수 있습니다. 파일을 받은 사람, MDM 관리자, 백업·로그·동기화 저장소에 접근할 수 있는 사람은 해당 키로 요청할 수 있다고 가정하세요. 개인용 API Key를 팀 공용 프로필에 넣거나, 파일을 이메일·메신저·공개 저장소로 전달하지 마세요.

기업/팀 배포 시

개인 사용자는 이 단계를 건너뛰어도 됩니다. 팀 배포는 IT 관리자와 함께 진행하며, 먼저 관리형 비밀 배포 방식 또는 기기·용도별로 제한한 별도 키를 사용할 수 있는지 확인하세요. 불가피하게 키가 포함된 파일을 사용할 때는 접근이 제한된 MDM만으로 배포하고, 다운로드 파일·백업·로그의 접근 권한과 보존 기간을 최소화하세요.

설정 파일을 공유했거나 의심되는 경우

  1. 해당 내보내기 파일과 복사본의 추가 공유를 즉시 중단하고, 받은 대상과 저장 위치를 확인합니다.
  2. New API의 API Key 관리 화면에서 노출 가능성이 있는 기존 키를 폐기/삭제합니다. 화면의 실제 명칭이 다르면 해당 화면의 폐기·삭제 동작을 사용하세요.
  3. 새 키를 발급해 필요한 개인 설정 또는 관리형 배포에만 다시 적용하고, 이전 키가 들어간 프로필·레지스트리 배포·자동화 설정은 제거하거나 새 키로 교체합니다.
  4. 기존 키가 포함된 내보내기 파일, 메신저 첨부, 클라우드 동기화본, 백업, Git 커밋을 모두 점검합니다. Git에 올라간 경우 파일만 지워도 이미 노출된 키는 안전해지지 않으므로 반드시 폐기·재발급한 뒤 접근 기록을 확인합니다.

3-4. Claude Desktop 재시작

설정을 저장한 후 Claude Desktop을 완전히 종료했다가 다시 실행합니다.

  1. Claude Desktop을 종료합니다 (Cmd + Q 또는 Ctrl + Q).
  2. 앱을 다시 실행합니다.
  3. 왼쪽 탐색 메뉴에 Cowork 탭과 Code 탭이 표시되는지 확인합니다.

탭 구성은 참고만 하세요

Claude Desktop의 탭은 앱 버전, 운영체제와 계정 상태에 따라 달라질 수 있습니다. Chat, Cowork, Code 탭의 유무만으로 연결 성공을 판단하지 않습니다. 실제 모델 응답과 Usage Logs를 기준으로 확인합니다.

3-5. 모델 선택 및 연결 확인

  1. Claude Desktop 하단의 모델 선택 드롭다운을 클릭합니다.
  2. jiminbox에서 제공하는 claude 호환 모델이 표시되는지 확인합니다.
  3. 원하는 모델을 선택하고 간단한 테스트 메시지(예: “안녕하세요”)를 보냅니다.
  4. 응답이 정상적으로 오는지 확인합니다.
  5. New API의 Usage Logs에서 같은 시각의 요청과 실제 모델 ID가 기록되었는지 확인합니다. Claude Desktop의 응답과 해당 로그가 일치하면 연결에 성공한 것입니다.

표시되는 모델 이름

Claude Desktop의 Haiku·Sonnet·Opus 표시는 호환을 위한 별칭일 수 있으며 실제 요청을 처리하는 모델과 다를 수 있습니다. 사용 가능한 모델과 연결 대상은 플랜 및 Jiminbox 운영 설정에 따라 달라지므로 New API에 현재 표시되는 모델 목록과 모델 ID를 확인합니다.

문제 해결

  • “인증 실패” 오류: New API에 실제로 표시된 API Key와 입력한 값이 같은지 확인하고, 키가 폐기·만료·제한되지 않았는지 확인하세요. 키 접두사나 형식을 추측해 수정하지 마세요.
  • “모델을 찾을 수 없음”: New API에 현재 표시되는 모델 ID를 다시 확인하세요. 모델 ID의 대소문자와 하이픈(-)을 포함해 정확히 입력해야 합니다. Jiminbox Pricing에서 최신 모델 목록을 확인하세요.
  • “연결 시간 초과”: 네트워크 상태를 확인하고, 방화벽이 api.jiminbox.com 도메인을 차단하지 않는지 확인하세요.
  • “Quota exceeded”: jiminbox 빠른 시작 가이드에서 사용량 한도를 확인하세요.

4. MCP 서버 설정 (선택 사항)

Claude Desktop의 강력한 기능 중 하나는 MCP(Model Context Protocol) 서버 연동입니다. MCP를 통해 로컬 파일시스템, 데이터베이스, GitHub 등 외부 도구와 연동할 수 있습니다.

최소 권한 작업 폴더 만들기

MCP 파일시스템 서버에는 필요한 파일만 넣은 전용 작업 폴더 하나만 허용하세요. 바탕 화면 전체, 문서 전체, 사용자 홈 폴더, 외장 디스크, 클라우드 동기화 폴더를 허용하면 API Key·SSH 키·브라우저 데이터·개인 문서까지 읽힐 수 있습니다.

  1. macOS: Finder에서 사용자 홈 폴더를 열어 Claude-MCP-Workspace 같은 새 빈 폴더를 만듭니다. Finder의 폴더 정보에서 전체 경로를 확인합니다.
  2. Windows: 파일 탐색기에서 사용자 프로필 폴더를 열어 Claude-MCP-Workspace 같은 새 빈 폴더를 만듭니다. 주소 표시줄에서 전체 경로를 확인합니다.
  3. 분석에 필요한 복사본만 이 폴더에 넣고, .env, 자격 증명 파일, 비밀 관리 파일, SSH 키, 개인 문서는 넣지 않습니다.

기본 설정 예시

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "<위에서 확인한 전용 작업 폴더의 절대 경로>"]
    }
  }
}

MCP 서버 설치 전 준비

일부 MCP 서버는 Node.js가 필요합니다. Node.js가 설치되어 있지 않다면 node.js 설치 가이드에서 설치 방법을 확인합니다.

주의

MCP 서버는 허용한 로컬 파일에 직접 접근할 수 있습니다. 신뢰할 수 있는 서버만 설치하고, 설정을 적용하기 전에 경로가 전용 작업 폴더 하나만 가리키는지 다시 확인하세요. MCP 설정 파일이나 실행 로그에도 키·토큰을 넣거나 남기지 마세요.

마무리

이제 Claude Desktop과 Jiminbox API의 연동을 마쳤습니다.

  • 일반 대화: 바로 Claude와 대화를 시작할 수 있습니다.
  • 파일 분석: 이미지, PDF, 문서를 첨부하여 AI에게 분석을 요청할 수 있습니다.
  • 프로젝트 관리: 사이드바에서 프로젝트별 대화를 관리할 수 있습니다.
  • MCP 확장: MCP 서버를 연동하여 로컬 도구와 연결할 수 있습니다.

추가 가이드

도움이 필요하신가요?

설치나 설정 중 문제가 발생하면 Jiminbox 관리자에게 문의해 주세요.

그래프 뷰

백링크