LobeHub에 Claude·GPT 외부 API 연결하는 법
면책 고지: 아래 예시에서 사용하는 게이트웨이는 제가 운영하는 APIVAI입니다. 설정 방법은 OpenAI 또는 Anthropic 형식을 지원하는 모든 엔드포인트에 동일하게 적용됩니다.
LobeChat은 이제 LobeHub라고 부릅니다. GitHub 저장소 lobehub/lobe-chat은 lobehub/lobehub으로 리디렉션되며, Docker 이미지도 lobehub/lobehub입니다. 웹, 데스크톱 앱, 또는 자체 호스팅으로 실행할 수 있는 오픈소스 채팅 및 에이전트 앱이며, 각 에이전트는 자체 제공자와 모델을 사용할 수 있습니다. 이 가이드는 2026년 10월 기준 LobeHub 문서와 UI 레이블을 따릅니다. 서드파티 API를 추가하는 방법, /v1을 어디에 붙이는지, 그리고 흔한 함정들을 다룹니다.
연결하는 세 가지 방법
| 방법 | URL | 모델 | 권장 용도 |
|---|---|---|---|
| 사용자 정의 제공자, Request Format = OpenAI | https://api.apivai.com/v1 | Claude와 GPT | 권장: 모든 모델에 하나의 제공자를 사용하고, 기본 OpenAI 제공자는 그대로 유지 |
| 내장 Anthropic 제공자 | https://api.apivai.com | Claude만 | Anthropic의 Messages 형식을 사용하는 Claude |
| 내장 OpenAI 제공자 | https://api.apivai.com/v1 | Claude와 GPT | 가장 빠르지만 OpenAI 제공자를 대체함(파일 인덱싱에 영향, 아래 참고) |
/v1 규칙: OpenAI 형식의 URL은 /v1로 끝납니다. Anthropic 형식의 URL은 끝나지 않는데, Anthropic SDK가 스스로 /v1/messages를 붙이기 때문입니다.
사용자 정의 제공자 추가
- 앱 설정 → AI Providers 를 엽니다.
- Add Custom Provider 를 클릭해 Create Custom AI Provider 를 엽니다.
- 아래 항목을 채우고 Create 를 클릭합니다.
| 필드 | 값 |
|---|---|
| Provider ID | apivai (소문자; 나중에 변경할 수 없음) |
| Provider Name | APIVAI |
| Request Format | OpenAI |
| Proxy URL | https://api.apivai.com/v1 |
| API Key | your key |
| Use Client Request Mode | 끔 |
Use Client Request Mode 는 LobeHub 서버를 거치지 않고 브라우저에서 직접 요청을 보냅니다. 특별한 이유가 없다면 끄세요. 켰다가 네트워크 오류가 나면 다시 끄면 됩니다.
그다음 제공자 페이지에서:
- Connectivity Check 를 실행합니다. 모델을 선택하고 Check 를 클릭하면 Check passed 가 보여야 합니다.
- Fetch models 를 클릭해
/v1/models에서 ID를 가져오고, 원하는 항목을 켭니다. 또는 Add Model 을 클릭해claude-sonnet-4-6이나gpt-5.5같은 Model ID 를 직접 입력합니다.
- 에이전트 설정에서 이 제공자와 모델을 선택합니다.
키로 사용할 수 있는 ID를 보려면:
curl https://api.apivai.com/v1/models \
-H "Authorization: Bearer your-key"대안: 내장 Anthropic 제공자
AI Providers 에서 Anthropic 을 선택하고 활성화합니다. 키를 API Key 에 붙여넣고, API Proxy URL 을 https://api.apivai.com으로 설정합니다( /v1 없음 ). Check 를 실행한 뒤 Claude 모델을 활성화합니다. 내장 모델 카드의 ID가 게이트웨이의 ID와 다르면 Add Model 로 올바른 ID를 추가합니다. 여기서 Fetch models 가 아무것도 반환하지 않으면 모델을 수동으로 추가하세요.
대신 내장 OpenAI 제공자를 사용한다면, API Proxy URL 을 https://api.apivai.com/v1로 설정하고 Use Responses API Specification 은 끕니다. LobeHub는 이것이 OpenAI 모델만 지원한다고 안내하지만, Claude 요청도 이 경로로 보내게 되기 때문입니다.
자체 호스팅: Docker 환경 변수
자체 호스팅하는 LobeHub 서버는 환경 변수에서 제공자 설정을 읽습니다. 이미 갖고 있는 데이터베이스와 인증 변수 옆에, lobehub.env에 아래 항목을 추가하세요:
# OpenAI format: Claude and GPT
OPENAI_API_KEY=your-key
OPENAI_PROXY_URL=https://api.apivai.com/v1
OPENAI_MODEL_LIST=-all,+claude-sonnet-4-6,+claude-haiku-4-5,+gpt-5.5
# Or Anthropic format: Claude only
ANTHROPIC_API_KEY=your-key
ANTHROPIC_PROXY_URL=https://api.apivai.com컨테이너는 평소처럼 시작합니다. 예: docker run -d -p 3210:3210 --env-file lobehub.env --name lobehub lobehub/lobehub 그리고 파일을 변경할 때마다 다시 시작하세요.
OPENAI_MODEL_LIST 문법: -all은 기본 OpenAI 모델을 숨기고, +id는 모델을 추가하며, id=Display Name은 이름을 바꿉니다. 여기에 설정한 키는 인스턴스의 모든 사용자가 공유하는 서버 키이므로, 별도의 예산 한도를 두는 것이 좋습니다. LobeHub 문서에 따르면 빈 응답은 종종 OPENAI_PROXY_URL에 /v1이 빠져서 발생하므로, 그대로 유지하세요.
파일과 지식 베이스도 작동하나요?
채팅은 완전히 작동합니다. 파일과 지식 베이스는 문서를 색인하기 위한 임베딩 모델도 필요하며, APIVAI는 임베딩을 제공하지 않습니다.
기본적으로 LobeHub는 OpenAI 제공자를 통해 OpenAI의 text-embedding-3-small로 임베딩을 생성합니다. OPENAI_PROXY_URL을 게이트웨이로 지정하면 파일 인덱싱이 실패합니다. 이것이 채팅을 사용자 정의 제공자를 통해 처리해야 하는 또 다른 이유입니다. 임베딩은 DEFAULT_FILES_CONFIG로 별도로 설정하세요. 예: DEFAULT_FILES_CONFIG=embedding_model=ollama/; 지원되는 제공자는 LobeHub의 지식 베이스 배포 가이드에 나와 있습니다. 파일에 대한 답변은 여전히 선택한 Claude 또는 GPT 모델에서 나옵니다.
어떤 작업에 어떤 모델을 쓸까
- 일반 어시스턴트, 빠른 질문:
claude-haiku-4-5또는gpt-6-luna
- 글쓰기 및 코딩 에이전트:
claude-sonnet-4-6또는claude-sonnet-5-5
- 가장 어려운 분석과 장문 글쓰기: 필요한 경우에만
claude-opus-5-5
- 현재 GPT:
gpt-6-sol
모든 메시지는 지금까지의 대화 내용을 다시 전송하므로, 대화가 길어질수록 메시지당 비용이 더 많이 듭니다. 주제가 바뀌면 새 토픽을 시작하세요.
흔한 오류
- 401 / API key invalid : 키에 공백이 더 있거나, 일부가 빠졌거나, 삭제되었습니다.
- 402 / insufficient_quota : 키의 예산이 소진되었거나, 남은 금액이 비싼 모델을 한 번 요청하기에도 너무 적습니다(Opus, Sonnet 4.6에서 먼저 걸립니다). 키에 예산을 추가하거나 더 저렴한 모델로 바꾸세요. 키는 약간 남아 있어도 작동을 멈추는데, 그 잔액은 사라지지 않습니다. 키를 삭제하면 계정 잔액으로 돌아갑니다.
- 404 :
/v1이 잘못되었습니다. OpenAI 형식(커스텀 제공자, OpenAI 제공자,OPENAI_PROXY_URL)에는https://api.apivai.com/v1를 사용해야 하고, Anthropic 형식에는https://api.apivai.com를 사용해야 합니다./chat/completions나/messages를 추가하지 마세요.
- Model not found : Model ID는 표시 이름이 아니라 게이트웨이의 ID와 정확히 일치해야 합니다. 예를 들어
claude-sonnet-4-6처럼요. Fetch models 또는GET /v1/models로 확인하세요.
- Empty or cut-off replies : thinking은 기본으로 켜져 있고 출력 토큰에 포함됩니다. 에이전트의 모델 설정에서 Enable Max Tokens Limit을 켜고 Max Tokens Limit을 4096 이상으로 설정하세요. OpenAI 형식에서 응답이 비어 있다면 URL이
/v1로 끝나는지도 확인하세요.
- Environment variables ignored :
lobehub.env를 수정한 뒤에는 컨테이너를 재시작하고, 변수 이름이 정확히 일치하는지 확인하세요.
- 429 : 기본 제한은 키당 분당 60개 요청입니다. 공유 인스턴스에서는 이 제한에 걸릴 수 있으니, 키를 나눠 사용하세요.
비용
작성 시점 기준으로, APIVAI의 대부분 Claude 모델은 Anthropic의 정가보다 56~62% 저렴하고 GPT 모델은 OpenAI보다 최대 86% 저렴합니다. 예를 들어 Claude Sonnet 4.6은 입력/출력 토큰 100만 개당 $1.26 / $6.32이고, 공식 가격은 $3 / $15입니다. 선불 방식이며 토큰 단위로 과금되고 구독은 없습니다. 전체 표는 https://apivai.com/pricing?utm_source=devto&utm_campaign=lobechat 에 있습니다.
댓글로 질문해 주셔도 좋습니다.
출처
- 원문: https://dev.to/mupromax/lobechat-lobehub-with-claude-and-gpt-custom-provider-docker-env-vars-and-the-v1-rule-3ee7 (2026-10-19 · APIVAI)