문서

문서

LobeChat

자체 호스팅한 LobeChat에서 Kunavo와 통신하려면 키, 프록시 URL, 선택 목록에 표시할 모델 ID 목록 등 세 가지 환경 변수가 필요합니다.

OPENAI_API_KEY를 sk-kn-… 키로, OPENAI_PROXY_URL를 https://api.kunavo.com/v1로 설정하고, 사용할 ID를 OPENAI_MODEL_LIST에 지정하세요. 그러면 Claude와 GPT를 하나의 선택 목록과 하나의 잔액으로 이용할 수 있습니다.

.env
OPENAI_API_KEY=sk-kn-...
OPENAI_PROXY_URL=https://api.kunavo.com/v1

# LobeChat only shows models it knows about, so name the ones you want.
OPENAI_MODEL_LIST=claude-sonnet-5,claude-haiku-4-5,claude-opus-5,gpt-5-6-terra
/v1 접미사는 OPENAI_PROXY_URL에 포함되어야 합니다. LobeChat은 OpenAI 경로를 재구성하지 않고 지정된 URL로 요청을 전달합니다. 따라서 LobeChat 문서의 .env.example에는 접미사를 포함한 기본값 https://api.openai.com/v1가 기재되어 있습니다.

단계별 안내

  1. /app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.
  2. 배포 환경에 변수 세 개를 추가하세요. 기본 설치라면 .env 파일에, Docker라면 environment 블록에 추가하면 됩니다.
  3. 새 환경 변수를 적용하려면 컨테이너를 다시 시작하세요.
  4. LobeChat을 열고 세션을 시작한 다음 OPENAI_MODEL_LIST에 지정한 ID 중 하나를 선택하세요.
docker-compose.yml
services:
  lobe-chat:
    image: lobehub/lobe-chat
    ports:
      - "3210:3210"
    environment:
      OPENAI_API_KEY: sk-kn-...
      OPENAI_PROXY_URL: https://api.kunavo.com/v1
      OPENAI_MODEL_LIST: claude-sonnet-5,claude-haiku-4-5,gpt-5-6-terra

이 변수에 관한 LobeChat 자체 참고 자료는 모델 공급자 환경 변수 페이지입니다.

컨테이너를 디버깅하기 전에 확인하세요

요청 한 번이면 문제가 엔드포인트, 키, LobeChat의 모델 목록 중 어디에 있는지 확인할 수 있습니다. 이 요청에서 모델 ID의 JSON 목록이 반환된다면 같은 URL과 키가 작동하는 것입니다. 그 뒤에도 선택 목록이 비어 있다면 원인은 엔드포인트가 아니라 OPENAI_MODEL_LIST입니다.

# Settles whether a failure is the endpoint, the key, or LobeChat.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

목록에 넣을 ID

Kunavo의 모든 텍스트 모델을 OPENAI_MODEL_LIST에 지정할 수 있습니다. 전체 목록은 모델 페이지에 있으며, GET /v1/models에서 실시간으로 가져옵니다. 요금은 입력/출력 토큰 1M개당 USD입니다.

모델 IDKunavo 입력/출력적합한 용도
claude-haiku-4-5$0.70 / $3.50가장 저렴한 Claude — 턴당 비용이 중요한 긴 채팅 세션에 적합
claude-sonnet-5$1.40 / $7.00품질과 가격의 균형을 이루는 기본 선택
claude-opus-5$3.50 / $17.50최고 품질의 Claude 등급
gpt-5-6-terra$0.70 / $4.20같은 키로 다른 모델군도 사용 — 두 번째 공급자를 설정할 필요 없음
채팅 클라이언트는 매 턴마다 전체 대화를 다시 전송하므로, LobeChat의 토큰 사용량은 메시지마다 일정하게 유지되는 것이 아니라 세션이 길어질수록 증가합니다. 이러한 사용 패턴에서는 프롬프트 캐싱이 가장 중요한 비용 절감 수단입니다. 월 요금 없이 선불 잔액에서 토큰당 과금되므로, 한 달 동안 사용하지 않으면 비용이 들지 않습니다. 자세한 내용은 결제을 참조하세요.

자주 묻는 질문

LobeChat에서 사용자 지정 OpenAI 호환 엔드포인트를 사용하려면 어떻게 하나요?

배포 환경에서 OPENAI_PROXY_URL을 엔드포인트 기본 URL로, OPENAI_API_KEY를 본인의 키로 설정하세요. Kunavo의 경우 기본 URL은 https://api.kunavo.com/v1입니다. LobeChat의 자체 .env.example은 해당 변수의 예시 값으로 https://api.openai.com/v1을 사용합니다. 이 예시는 /v1 접미사를 값에 포함해야 하며 별도로 추가해 주지 않는다는 점을 보여줍니다.

사용자 지정 모델이 LobeChat 모델 목록에 표시되지 않는 이유는 무엇인가요?

LobeChat은 엔드포인트가 제공할 수 있는 모든 모델이 아니라, 전달받은 모델을 표시합니다. 따라서 엔드포인트가 해당 모델 ID에 응답하더라도 목록에 없는 모델 ID는 보이지 않습니다. OPENAI_MODEL_LIST에 ID를 쉼표로 구분해 지정하세요. LobeChat 문서에서는 이 변수의 접두사 구문도 정의합니다. 앞에 +를 붙이면 모델을 추가하고, -를 붙이면 숨기며, model_name=display_name 형식으로 선택 목록에서 표시 이름을 바꿀 수 있습니다.

LobeChat에서 OpenAI 공급자를 통해 Claude 모델을 사용할 수 있나요?

네, OpenAI 호환 엔드포인트를 통해 제공되는 경우 사용할 수 있습니다. LobeChat의 OpenAI 공급자는 OPENAI_PROXY_URL에 지정된 곳으로 모델 ID를 전송하므로, Claude ID는 LobeChat 내부가 아니라 게이트웨이에서 확인됩니다. Anthropic 인증 정보는 필요하지 않습니다. Kunavo에서는 Claude와 GPT ID가 하나의 키 뒤에 있으므로, 모델군을 추가하려면 OPENAI_MODEL_LIST에 ID를 추가하면 됩니다.

사용자 지정 엔드포인트를 통해 LobeChat의 이미지 생성 기능을 사용할 수 있나요?

이는 LobeChat이 아니라 엔드포인트가 어떤 경로를 구현하는지에 따라 달라집니다. 채팅 공급자에는 /v1/chat/completions가 필요하고, 이미지 생성은 별도의 경로를 사용합니다. Kunavo는 자체 엔드포인트에서 이미지와 동영상 생성을 제공하며, 관련 문서는 images와 video 아래에 있습니다. 따라서 안정적인 방법은 채팅에는 LobeChat을 사용하고 미디어 엔드포인트는 직접 호출하는 것입니다. 하나의 공급자 설정이 두 기능을 모두 처리한다고 가정하지 마세요.