> ## 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.

# LobeHub

> LobeHub 오픈 소스 AI 채팅 클라이언트 연동 가이드 - 맞춤 제공자 및 로컬 지식 베이스 지원

> 오픈 소스 AI 채팅 클라이언트 연동 가이드 - 맞춤 제공자 및 로컬 지식 베이스 지원

## 1. 제품 소개

LobeHub는 오픈 소스, 크로스 플랫폼 AI 채팅 클라이언트(구 Lobe Chat)입니다. 다중 모델, 다중 모달리티, 플러그인 시스템, 로컬 지식 베이스를 지원합니다. GravitexAI를 통해 LobeHub에서 하나의 API 키로 100+ 주류 AI 모델에 접속할 수 있어, 각 제공업체별로 개별 가입 및 결제할 필요가 없습니다.

<CardGroup cols={3}>
  <Card title="오픈 소스 및 자체 호스팅" icon="github">
    데스크톱, 웹, Docker, Vercel 배포 가능 - 완전한 데이터 제어
  </Card>

  <Card title="플러그인 및 다중 모달리티" icon="plug">
    내장 웹 검색, 코드 인터프리터, 이미지 이해, 비디오 생성 플러그인
  </Card>

  <Card title="로컬 지식 베이스" icon="database">
    PDF / Markdown 업로드하여 RAG 구축 - 대화에서 프라이빗 문서 참조
  </Card>
</CardGroup>

## 2. 빠른 시작

### 1단계: GravitexAI API Key 발급

1. [GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에 접속
2. 「API 키 새로 만들기」클릭 후 이름 지정·저장
3. `sk-`로 시작하는 키를 복사해 보관

### 2단계: LobeHub 설치

LobeHub는 세 가지 사용 방식을 제공합니다:

<Tabs>
  <Tab title="데스크톱">
    **방법 1: 공식 사이트에서 다운로드**

    1. [https://app.lobehub.com/downloads](https://app.lobehub.com/downloads) 에 접속하여 설치 프로그램 다운로드

    **방법 2: GitHub Releases에서 다운로드**

    1. [https://github.com/lobehub/lobe-chat/releases](https://github.com/lobehub/lobe-chat/releases) 로 이동
    2. 최신 버전을 찾아 해당 시스템용 설치 프로그램 다운로드:

    * Windows: .exe
    * macOS: .dmg
    * Linux: .AppImage / .deb / .rpm
  </Tab>

  <Tab title="웹 (공식)">
    `lobechat.com`에 직접 접속하여 가입·로그인 후 사용 - 자체 배포 불필요
  </Tab>

  <Tab title="자체 호스팅">
    Docker / Vercel / 로컬 소스 코드를 통한 배포 - 기업 또는 프라이버시 시나리오에 적합
  </Tab>
</Tabs>

<Tip>
  개인 사용자는 공식 웹 또는 데스크톱 버전을 먼저 사용하는 것이 권장됩니다. 데이터 프라이버시 또는 컴플라이언스 요구 사항이 있는 경우 Docker 자체 호스팅을 권장합니다 (환경 변수에서 GravitexAI 구성).
</Tip>

### 3단계: LobeHub 설정 열기

1. 왼쪽 상단의 「개인 아바타 → 앱 설정」을 클릭하여 설정 페이지로 이동
2. 왼쪽 내비게이션에서 「에이전트 → AI 제공자」를 선택
3. 오른쪽 상단의 `+` 버튼을 클릭하여 맞춤 제공자 추가

<img src="https://mintcdn.com/gravitexai/1w6qMcPexYzhP5k_/images/lobehub1.png?fit=max&auto=format&n=1w6qMcPexYzhP5k_&q=85&s=622e758b529c3d167d50246a78e6838f" alt="LobeHub 설정 열고 맞춤 제공자 추가" width="2400" height="1692" data-path="images/lobehub1.png" />

### 4단계: 맞춤 AI 제공자 생성

| 필드          | 입력값                          | 설명                                                        |
| ----------- | ---------------------------- | --------------------------------------------------------- |
| **제공자 ID**  | `gravitexai`                 | 제공자 고유 식별자, 생성 후 변경 불가                                    |
| **제공자 이름**  | `gravitexai`                 | 맞춤 제공자 이름                                                 |
| **제공자 설명**  | `gravitexai`                 | 맞춤 설명                                                     |
| **제공자 로고**  | (비움)                         | 선택 사항, 맞춤 로고 URL                                          |
| **요청 형식**   | `OpenAI`                     | GravitexAI는 OpenAI 프로토콜과 완전 호환                            |
| **프록시 URL** | `https://api.gravitex.ai/v1` | Base URL, **반드시 `/v1`로 끝나야 함**                            |
| **API Key** | GravitexAI API Key           | [GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에서 발급 |

오른쪽 하단의 **생성** 버튼을 클릭하여 저장합니다.

<img src="https://mintcdn.com/gravitexai/1w6qMcPexYzhP5k_/images/lobehub2.png?fit=max&auto=format&n=1w6qMcPexYzhP5k_&q=85&s=b426609b24b782760a15da26dbd72c28" alt="맞춤 AI 제공자 생성" width="2400" height="1692" data-path="images/lobehub2.png" />

<Tip>
  **구성 포인트**

  * 「프록시 URL」은 반드시 `/v1`로 끝나야 합니다. 그렇지 않으면 요청 라우팅이 실패합니다
  * 「API Key」를 붙여넣을 때 앞뒤 공백을 제거하세요
  * 「요청 형식」에서 `OpenAI`를 선택하면 GravitexAI의 전체 100+ 모델에 접속할 수 있습니다
  * 하나의 키로 여러 모델을 동시에 활성화할 수 있으며, 사용량에 따라 청구됩니다 - 모델별로 개별 결제할 필요 없음
</Tip>

### 5단계: 연결성 확인

생성이 완료되면 제공자 세부 정보 페이지로 이동합니다. 다음을 수행할 수 있습니다:

1. **API Key 및 프록시 URL 입력**: 설정을 다시 확인하거나 수정
2. **고급 옵션 활성화** (선택 사항):
   * 「Responses API 사양 사용」: 활성화하면 차세대 OpenAI 요청 형식 사용 (OpenAI 모델만 지원)
   * 「클라이언트 요청 모드 사용」: 브라우저가 직접 요청을 전송하여 응답 속도 향상
3. **연결성 확인**: 드롭다운에서 모델을 선택하고 **확인** 버튼을 클릭하여 연결성을 테스트
4. **모델 목록 가져오기**: **모델 목록 가져오기** 버튼을 클릭하여 GravitexAI가 제공하는 전체 모델을 자동으로 가져오기

성공적으로 가져오면 「모델 목록」에 GravitexAI에서 현재 판매 중인 모든 모델이 유형별로 그룹화되어 표시됩니다: 채팅, 이미지, 비디오, 임베딩, TTS.

<img src="https://mintcdn.com/gravitexai/1w6qMcPexYzhP5k_/images/lobehub3.png?fit=max&auto=format&n=1w6qMcPexYzhP5k_&q=85&s=4db45efc3f29c87016ac4e7c7bdc9a90" alt="연결성 확인 및 모델 목록 가져오기" width="2400" height="1692" data-path="images/lobehub3.png" />

<Warning>
  「연결성 확인」이 실패하면 다음 순서로 문제를 해결하세요:

  * 프록시 URL 끝에 `/v1`이 포함되어 있는지 확인
  * API Key가 유효한지 확인 (GravitexAI 콘솔에서 확인 가능)
  * HTTPS를 차단하는 방화벽 / 프록시 설정이 있는지 확인
</Warning>

### 6단계: 모델 선택하고 대화 시작

채팅 인터페이스의 모델 드롭다운에서 사용할 모델을 선택하세요 (예: `claude-opus-5`, `gpt-5.6-luna`, `deepseek-v4-pro`)하고 대화를 시작하세요.

<Card title="인기 모델 추천 보기" icon="star" href="https://maas.gravitex.ai/#/api-models">
  최신 모델 추천, 성능 비교, 시나리오별 사용 제안을 확인하세요 - 텍스트 생성, 코딩, 빠른 응답, 이미지 생성, 비디오 생성 등 전 영역을 다룹니다.
</Card>

<Info>
  **여기에 구체 모델을 나열하지 않는 이유**

  AI 모델은 매우 빠르게 반복됩니다. 가장 정확한 모델 추천 정보를 제공하기 위해, [모델 추천 페이지](https://maas.gravitex.ai/#/api-models)에서 최신 모델 목록, 성능 데이터 및 사용 제안을 유지합니다.
</Info>

## 3. 100+ 모델 원스톱 접속

LobeHub는 여러 제공자의 공식 채널을 내장하고 있어 각각 API 키를 입력해야 합니다. GravitexAI에 연결하려면 **하나의** 맞춤 제공자를 생성하여 전체 모델을 커버할 수 있습니다:

| 채널                         | 적용 모델                                           | 핵심 장점                      | API 주소                       |
| -------------------------- | ----------------------------------------------- | -------------------------- | ---------------------------- |
| **OpenAI 호환 (GravitexAI)** | 전체 100+ 모델 (Claude, Gemini, GPT, DeepSeek 등 포함) | 하나의 키로 모든 모델 사용, 가장 간단한 구성 | `https://api.gravitex.ai/v1` |

<Tip>
  **하나의 GravitexAI 채널로 Claude / Gemini / GPT / DeepSeek 등 모든 모델 접속**

  GravitexAI는 Claude, Gemini, GPT, DeepSeek 등 주류 모델을 OpenAI 호환 프로토콜로 통일하여 래핑합니다. 따라서 LobeHub에서 하나의 `GravitexAI` 맞춤 제공자를 생성하기만 하면, 모델 드롭다운에서 100+ 모델을 모두 선택할 수 있으며, 각 제공업체별로 개별 채널을 구성할 필요가 없습니다.
</Tip>

## 4. LobeHub 주요 기능

### 플러그인 시스템

LobeHub는 풍부한 플러그인 마켓을 제공합니다 (설정 → 플러그인). 권장 플러그인:

* **웹 검색**: 모델이 실시간으로 인터넷에서 최신 정보를 가져오도록 함
* **코드 인터프리터**: 대화에서 Python 코드를 실행하고 데이터 시각화 수행
* **차트 생성**: 자동으로 순서도, 마인드맵 생성
* **이미지 생성**: `gpt-image-2`, `gemini-3-pro-image` 등 모델로 이미지 생성

### 로컬 지식 베이스 (RAG)

LobeHub는 파일을 업로드하여 로컬 벡터 데이터베이스를 구축하는 것을 지원합니다:

1. 「지식 베이스」페이지로 이동하여 새 지식 베이스 생성
2. PDF, Markdown, Word, Excel, TXT 등 파일 업로드
3. 시스템이 자동으로 슬라이싱 및 벡터화 수행
4. 대화 시 지식 베이스를 선택하면 모델이 프라이빗 자료를 기반으로 답변

<Warning>
  지식 베이스의 「벡터화」 단계는 Embedding 모델을 호출합니다 (유료). GravitexAI의 `text-embedding-3-large` 등 임베딩 모델 사용을 권장합니다.
</Warning>

### 다중 모달리티 대화

시각 이해, 이미지 인식, OCR을 위해 이미지 업로드 지원:

* 권장 시각 모델: `gemini-3.6-flash`, `claude-opus-5`, `gpt-5.6-terra`
* 채팅창에 이미지를 직접 드래그하면 모델이 자동으로 인식

### 에이전트 마켓 (Agent Market)

LobeHub는 풍부한 프리셋 에이전트 (번역, 글쓰기, 코딩, 인터뷰 등)를 내장하고 있습니다. 또한 다음을 수행할 수 있습니다:

* 「에이전트 마켓」에서 커뮤니티 공유 에이전트를 원클릭으로 활성화
* 맞춤 에이전트 생성: 페르소나, 프롬프트, 시작 메시지, 지식 베이스, 플러그인 정의

### 대화 관리 및 내보내기

* 다중 브랜치 대화, 메시지 편집 및 재생성
* 대화 내보내기: Markdown, PNG, JSON
* 채팅 기록 전역 검색

## 5. 고급 구성

### 네트워크 프록시 및 자체 호스팅

프록시 사용 또는 LobeHub 자체 호스팅이 필요한 경우:

1. **데스크톱**: 설정 → 네트워크 → HTTP/HTTPS 프록시 구성
2. **자체 호스팅 (Docker)**: 환경 변수를 통해 GravitexAI 구성 주입:
   ```bash theme={null}
   OPENAI_API_KEY=sk-your-gravitex-key
   OPENAI_PROXY_URL=https://api.gravitex.ai/v1
   CUSTOM_MODELS=gpt-5.6-terra,claude-opus-5,deepseek-v4-pro
   ```
3. **클라이언트 요청 모드**: 활성화하면 브라우저가 API에 직접 연결 (브라우저가 GravitexAI에 접속할 수 있어야 함)

### 키보드 단축키

| 단축키                    | 기능     |
| ---------------------- | ------ |
| `Ctrl/Cmd + N`         | 새 대화   |
| `Ctrl/Cmd + K`         | 빠른 검색  |
| `Ctrl/Cmd + /`         | 명령 팔레트 |
| `Ctrl/Cmd + Shift + M` | 모델 전환  |

## 6. 모바일

LobeHub 데스크톱은 Windows / macOS / Linux를 지원합니다. 모바일에서는 브라우저를 통해 `lobechat.com` 웹 버전에 접속할 수 있습니다 (반응형 디자인) - 별도 앱 설치 불필요.

## 7. 문제 해결

<AccordionGroup>
  <Accordion title="연결 실패 / 연결성 확인 실패">
    | 현상           | 해결 방향                                                                                     |
    | ------------ | ----------------------------------------------------------------------------------------- |
    | 401 / 403 안내 | API Key가 유효하지 않거나 잔액이 부족합니다. [GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에서 확인하세요 |
    | 404 안내       | 프록시 URL이 `/v1`로 끝나지 않았습니다. `/v1` 접미사 누락                                                   |
    | 타임아웃 안내      | 네트워크 환경 문제. 프록시 또는 방화벽 설정 확인                                                              |
    | CORS 오류 안내   | 「클라이언트 요청 모드 사용」을 끄거나 서버를 통해 중계                                                           |
  </Accordion>

  <Accordion title="모델 목록이 비어 있음">
    * **모델 목록 가져오기** 버튼을 클릭하여 수동으로 가져오기
    * 1-2초 대기 후 페이지 새로고침
    * GravitexAI 콘솔에서 API Key 상태가 정상인지 확인
  </Accordion>

  <Accordion title="응답 느림 또는 스트림 끊김">
    * 더 빠른 모델로 전환 (예: `gemini-3.6-flash`, `claude-haiku-4-5`, `deepseek-v4-flash`)
    * 불필요한 플러그인 끄기
    * 네트워크 지연 확인
    * 컨텍스트 길이 줄이기 (긴 이전 대화 닫기)
  </Accordion>

  <Accordion title="웹 버전과 데스크톱 버전의 데이터가 동기화되나요?">
    동일한 LobeHub 계정으로 로그인할 때 일부 설정과 세션이 동기화됩니다. 로컬 데이터는 정기적으로 내보내어 백업하는 것이 권장됩니다.
  </Accordion>

  <Accordion title="LobeChat과 LobeHub의 관계는 무엇인가요?">
    LobeChat은 오픈 소스 프로젝트 이름이며, LobeHub은 제품 / 클라우드 플랫폼 이름입니다. 둘은 기본 코드가 동일하며, 데스크톱 및 자체 호스팅 버전은 일반적으로 LobeChat 저장소를 기반으로 빌드됩니다.
  </Accordion>

  <Accordion title="자체 호스팅 후 모델을 호출할 수 없는 이유는 무엇인가요?">
    API Key가 올바른지, Base URL에 접근할 수 있는지, 서버 아웃바운드 접근이 제한되지 않았는지, 컨테이너 내 DNS 해석이 정상인지 확인하세요.
  </Accordion>
</AccordionGroup>

## 8. 모범 사례

### 모델 선택 전략

작업별로 다른 모델을 사용하고, 복잡도에 따라 선택:

* **일상 채팅 / 단순 Q\&A**: `gemini-3.1-flash-lite`, `claude-haiku-4-5`, `deepseek-v4-flash`
* **복잡한 추론 / 긴 문서 분석**: `claude-opus-5`, `gpt-5.6-sol`, `deepseek-v4-pro`
* **코딩**: `claude-opus-5`, `gpt-5.6-sol`, `claude-sonnet-5`
* **이미지 이해**: `gemini-3.6-flash`, `claude-opus-5`, `gpt-5.6-terra`
* **이미지 생성**: `gpt-image-2`, `gemini-3-pro-image`

전체 모델 목록과 성능 비교는 [모델 추천 페이지](https://maas.gravitex.ai/#/api-models)를 참조하세요.

### 컨텍스트 관리

* 사용하지 않는 이전 대화를 정기적으로 정리
* 복잡한 작업을 여러 짧은 대화로 분해
* 「대화 분기」 기능을 활용하여 다른 답변 탐색

### 보안 및 프라이버시

* 공공 장소에서 API Key를 공유하지 않기
* 키를 정기적으로 교체
* 민감한 대화는 LobeHub 자체 호스팅을 권장 - 데이터 완전 로컬 저장

### 자체 호스팅 권장 사항

* 프로덕션 환경에서는 Docker + PostgreSQL 사용 - 내장 데이터베이스 사용 금지
* Cloudflare를 역방향 프록시로 사용 권장
* 환경 변수를 통해 키를 중앙 집중식으로 관리하여 다중 인스턴스 배포 용이

## 9. 세 가지 방식 비교

| 차원         | 데스크톱              | 웹 (공식)                | 자체 호스팅              |
| ---------- | ----------------- | --------------------- | ------------------- |
| 설치 난이도     | 낮음 (설치 프로그램 다운로드) | 매우 낮음 (웹페이지 열기)       | 중간\~높음 (배포 필요)      |
| 데이터 소유권    | 로컬 중심             | 공식 클라우드               | 완전 자율               |
| 네트워크 요구 사항 | 모델 API 접속만 필요     | 공식 사이트 및 모델 API 접속 필요 | 배포 위치에 따라 다름        |
| 다중 사용자 협업  | 약함                | 중간                    | 강함 (계정 권한 구성 가능)    |
| 대상 사용자     | 개인 생산성 사용자        | 캐주얼 / 경량 사용자          | 기업, 팀, 프라이버시 민감 사용자 |
| 비용         | 무료 (API Key自备)    | 무료 플랜 + 유료 플랜         | 서버 비용 + API Key自备   |

<Info>
  **더 많은 도움말**: [bd@gravitex.ai](mailto:bd@gravitex.ai)로 문의하거나 13603055233으로 전화 주세요.
</Info>