문서
LibreChat
LibreChat에서는 librechat.yaml에 블록 형태로 게이트웨이를 설정합니다. 필수 필드 네 개, 키를 위한 환경 변수, 그리고 재시작이 필요합니다. 그러면 선택기에서 하나의 엔드포인트 이름 아래 Claude 및 GPT ID를 사용할 수 있습니다.
LibreChat은 librechat.yaml의 endpoints.custom 블록으로 게이트웨이를 추가합니다 — 필수 필드 네 개, .env에서 가져오는 키, 선택기에 표시되기 전 재시작이 필요합니다
# librechat.yaml — project root, beside your .env
version: 1.3.5 # the value the documentation's own example carries
endpoints:
custom:
# Required: name, apiKey, baseURL, models. The name must be unique and
# must not reuse a built-in endpoint name such as openAI or anthropic.
- name: "Kunavo"
apiKey: "${KUNAVO_API_KEY}" # resolved from .env, not written here
# Keep the /v1. LibreChat appends /chat/completions to this by default.
baseURL: "https://api.kunavo.com/v1"
models:
default: ["claude-sonnet-5", "claude-haiku-4-5"]
fetch: true # fills the picker from GET /v1/models
titleConvo: true
titleModel: "claude-haiku-4-5" # titles are a separate call — pin a cheap id
modelDisplayLabel: "Kunavo"
# Optional but worth the four lines: without it LibreChat prices your
# traffic from a table it ships. prompt/completion are USD per million
# tokens; context is that model's own window. All three required.
tokenConfig:
claude-sonnet-5:
prompt: 1.4
completion: 7
context: 1000000
claude-haiku-4-5:
prompt: 0.7
completion: 3.5
context: 200000baseURL에는 /v1가 포함됩니다. 문서의 설명으로 확인할 수 있습니다. 기본 URL이 이미 전체 완성 엔드포인트인 경우 directEndpoint을 사용하며, “앱이 기본적으로 baseURL에 ‘/chat/completions’ 또는 ‘/completion’을 추가하기 때문에 필요하다”고 설명합니다. 따라서 https://api.kunavo.com/v1는 요청 경로인 /v1/chat/completions로 연결되고, directEndpoint은 설정하지 않습니다. 사이트의 자체 예시 두 개도 같은 형식으로 끝납니다. https://api.mistral.ai/v1, https://openrouter.ai/api/v1입니다. 여기에 기본 주소만 입력하면 인증 오류가 아니라 404가 발생합니다.librechat.yaml이 프로젝트 루트에 있어야 하고 API 컨테이너에 마운트해야 하며, 변경 사항이 UI에 반영되기 전에 LibreChat을 재시작해야 한다고 명시되어 있습니다. 선택기에 새 엔드포인트가 표시되지 않는다면 자격 증명보다 이 설정이 원인일 가능성이 큽니다. 자격 증명은 아래의 curl로 따로 확인하세요.tokenConfig 블록은 이를 재정의하기 위한 것입니다. 노출하는 각 ID마다 설정하거나, 장부를 추정치로 보고 /app/billing의 잔액을 실제 금액으로 확인하세요.curl이며, 클라이언트 동작에 관한 사항은 사용자와 LibreChat 사이에서 다룰 문제입니다.sk-kn-로 시작합니다) $10부터 크레딧을 추가하세요. 호출 비용은 해당 잔액에서 차감되며 실패한 호출에는 요금이 부과되지 않습니다. 그러면 대시보드가 LibreChat 설정 화면에서 열립니다.단계별 안내
/app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.- Docker에서는 먼저 설정을 마운트합니다. 빠른 시작 안내에 따라
docker-compose.override.yml.example을docker-compose.override.yml로 복사하고librechat.yaml볼륨 설정의 주석을 해제하세요. 베어메탈 설치에서는 이 단계를 건너뜁니다. - 프로젝트 루트, 즉
.env과 같은 디렉터리에librechat.yaml를 만들거나 수정하고 위의endpoints.custom항목을 추가합니다. - 키를
.env에KUNAVO_API_KEY=sk-kn-...로 저장합니다. YAML의${KUNAVO_API_KEY}자리표시자는 여기서 값을 가져오므로, 커밋하는 설정 파일에 비밀 키가 들어가지 않습니다. - LibreChat을 재시작한 다음 엔드포인트 선택기를 엽니다. Kunavo가 내장 엔드포인트 옆에 독립 항목으로 표시됩니다. 모델 목록은
GET /v1/models에서 가져오거나, 가져오기에 실패하면models.default배열을 사용합니다. - 메시지를 하나 보내고 모델 선택기가 실제로 모델을 전환하는지 확인하세요. ID는 엔드포인트에서 확인되므로 하나의 항목 아래 Claude ID와 GPT ID가 함께 있어도 정상이며, 잘못된 설정이 아닙니다.
LibreChat 사용자 지정 엔드포인트 객체 참조에서 확인했습니다(2026년 9월 21일 기준). 서드파티 설정은 변경될 수 있으므로, 여기의 필드 이름이 실제 화면과 다르면 이 문서가 아니라 해당 페이지를 기준으로 삼으세요.
클라이언트를 디버깅하기 전에 확인할 사항
한 번의 요청으로 문제가 엔드포인트, 키 또는 구성 파일 중 어디에 있는지 판단할 수 있습니다. 이 요청에서 JSON이 반환되면 동일한 base URL과 키가 LibreChat에서 작동합니다.
# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
-H "Authorization: Bearer sk-kn-..."필드에 입력할 model id
모든 텍스트 모델은 model id로 접근할 수 있습니다. 현재 목록은 GET /v1/models이며, 가격이 포함된 카탈로그는 모델 페이지에서 확인할 수 있습니다. 요금은 토큰 100만 개당 USD 기준이며 입력 / 출력 순서입니다.
| 모델 ID | Kunavo 입력/출력 | LibreChat에서의 위치 |
|---|---|---|
claude-sonnet-5 | $1.40 / $7.00 | models. |
claude-opus-5 | $3.50 / $17.50 | 긴 분석에 전환할 ID — 더 나은 답변을 위해 요청을 더 사용할 가치가 있는 경우 |
claude-haiku-4-5 | $0.70 / $3.50 | 공유 인스턴스의 트래픽량 및 titleModel — LibreChat은 별도의 요청으로 모든 대화에 제목을 붙입니다 |
gpt-5-6-terra | $0.70 / $4.20 | 컨텍스트 창이 결정적인 요소인 긴 붙여넣기 문서 |
게이트웨이에서 다르게 동작하는 세 가지 선택 필드
이 표의 모든 내용은 위 날짜에 확인한 동일한 필드 참조 문서에서 가져왔습니다. LibreChat 자체 설정에 관한 설명이지, Kunavo 테스트 결과나 요청이 클라이언트를 벗어난 뒤 특정 모델 ID가 어떻게 동작하는지에 대한 주장이 아닙니다.
| 필드 | 참조 문서의 설명 | 게이트웨이에서 중요한 이유 |
|---|---|---|
provider | 사용자 지정 엔드포인트를 네이티브 공급자 클라이언트를 통해 라우팅합니다. 현재 지원되는 값은 Anthropic입니다. | 통신 프로토콜을 전환할 뿐 공급자는 바꾸지 않습니다. 같은 블록을 사용해 채팅 완성 대신 Anthropic Messages 프로토콜로 통신할 수 있습니다. 이 경로에서는 OpenAI 방식의 모델 가져오기를 사용하지 않으므로 models. |
models.fetch | true인 경우 API에서 모델 목록을 가져오려고 시도하며, 응답이 지연되면 최초 사용 시 속도가 느려질 수 있습니다. | Kunavo는 GET /v1/models 요청에 응답하므로 선택기가 자동으로 채워집니다. 해당 호출이 실패하면 models. |
tokenConfig | 비용 추적 및 사용량 계산을 위해 모델별 컨텍스트 창과 토큰 100만 개당 요금을 정의합니다. | 설정하지 않으면 LibreChat에 포함된 가격표에서 ID를 대조해 트래픽 비용을 산정합니다. 해당 가격표가 그 ID를 기준으로 작성되지 않았을 수 있습니다. 설정하면 UI에 표시되는 금액은 직접 입력한 값이 됩니다. |
마운트, 설정, 환경 변수 지정, 재시작으로 이어지는 4단계 안내는 게이트웨이를 예시로 사용하는 LibreChat 사용자 지정 엔드포인트 빠른 시작 페이지에 있습니다.
자주 묻는 질문
LibreChat에 사용자 지정 엔드포인트를 어떻게 추가하나요?
프로젝트 루트에서 .env 옆에 librechat.yaml을 만들고 endpoints.custom 아래에 name, apiKey, baseURL, models의 필수 필드 네 개를 입력합니다. name은 고유해야 하며 openAI 또는 anthropic 같은 내장 엔드포인트 이름을 재사용해서는 안 됩니다. 자격 증명은 .env에 저장하고 YAML에서 ${YOUR_ENV_VAR}로 참조한 다음 재시작합니다. Docker에서는 docker-compose.override.yml을 통해 파일을 API 컨테이너에도 마운트해야 하며, 재시작 후에 새 항목이 엔드포인트 선택기에 표시됩니다.
LibreChat baseURL 끝에 /v1을 붙여야 하나요?
OpenAI 호환 게이트웨이라면 붙여야 합니다. LibreChat의 필드 참조 문서에 따르면 directEndpoint 옵션은 기본 URL이 이미 전체 완성 엔드포인트인 경우에 사용하며, 앱이 기본적으로 baseURL에 /chat/completions 또는 /completion을 추가하기 때문에 필요합니다. 따라서 기본 URL은 /v1 접미사가 붙은 API 루트인 https://api.kunavo.com/v1이어야 하며, directEndpoint는 설정하지 않습니다. LibreChat 사이트의 두 예시도 같은 형식입니다. 잘못 설정하면 인증 실패가 아니라 404가 발생하므로 잘못된 키와 구별할 수 있습니다.
LibreChat에 표시되는 비용이 공급자 청구액과 다른 이유는 무엇인가요?
LibreChat은 공급자의 청구액이 아니라 자체 가격표를 사용해 요청 비용을 산정하고, 모델 ID와 대조하기 때문입니다. 가격표 항목과 유사한 게이트웨이 ID에는 해당 항목의 요금이 적용되고, 일치하는 항목이 없으면 고정 요금이 적용됩니다. 사용자 지정 엔드포인트 아래에 노출하는 각 ID의 prompt, completion, context를 토큰 100만 개당 USD로 선언하는 tokenConfig 블록을 추가하면 됩니다. LibreChat은 자체 가격표보다 먼저 이 재정의 설정을 확인합니다. 앱 내 장부는 추정치로 보고 공급자 잔액을 실제 기록으로 확인하세요.
LibreChat에서 사용자 지정 엔드포인트를 통해 Claude 모델을 사용할 수 있나요?
예, 두 가지 방식으로 사용할 수 있습니다. 일반 OpenAI 호환 사용자 지정 엔드포인트는 모델 ID를 baseURL로 그대로 전달하므로 Claude ID는 LibreChat 내부가 아니라 해당 엔드포인트에서 확인되며 Anthropic 계정은 필요하지 않습니다. 또는 provider 필드를 사용해 같은 블록을 LibreChat의 네이티브 Anthropic Messages 클라이언트로 라우팅할 수 있습니다. 현재 지원되는 값은 anthropic입니다. 이 경로에서는 OpenAI 방식의 모델 가져오기를 사용하지 않으므로 fetch에 의존하지 말고 원하는 ID를 models.default 아래에 나열하세요.
Kunavo는 LibreChat을 테스트했나요?
아니요. 이 페이지의 구성은 표시된 날짜에 확인한 LibreChat의 자체 사용자 지정 엔드포인트 문서에서 옮겨 적은 것이며, 실행 결과가 아닙니다. 대화, 스트리밍 응답, 도구 왕복, Agents 실행을 수행하지 않았습니다. 여기에서 문서화한 모든 클라이언트에 해당하며, 설정 안내를 게시했다고 해서 테스트한 것은 아닙니다. 이 페이지의 curl 요청을 사용하면 기본 URL과 키가 작동하는지 10초 안에 직접 확인할 수 있습니다. 그 이후의 동작은 선택한 모델 ID에 대한 LibreChat의 처리에 달려 있습니다.