타사 및 자체 호스팅 공급자 연결

Libre WebUI 0.16.0에서는 설정 > 플러그인에 집중형 공급자 연결 워크스페이스가 추가되었습니다. 여기에서 번들 공급자를 활성화하거나, 호환 플러그인을 다른 API로 연결하거나, 실제 적용되는 모델 카탈로그를 확인하거나, 신뢰할 수 있는 네트워크의 자체 호스팅 게이트웨이에 연결할 수 있습니다.

공급자 검색과 선택, 연결 제어, 모델 새로 고침, 공급자별 기능 카탈로그를 표시하는 Libre WebUI 공급자 연결 화면

Libre WebUI는 현재 다음 공급자 통신 형식을 지원합니다.

OpenAI Chat Completions
OpenAI Responses
Anthropic Messages
Google Gemini 콘텐츠 및 함수 호출

번들 Anthropic 및 Gemini 정의는 해당 공급자 ID에 따라 선택되는 전용 어댑터를 사용합니다. 새로 가져온 공급자는 OpenAI Chat Completions 또는 OpenAI Responses 의미 체계를 사용합니다. 이를 Anthropic 또는 Gemini 호환 API로 지정해도 해당 번들 어댑터가 선택되지는 않습니다. 요청, 스트리밍, 도구 호출 또는 응답 형식이 다른 공급자에는 백엔드 어댑터가 필요합니다. 플러그인 JSON은 라우팅과 구성을 설명할 뿐 관련 없는 프로토콜을 변환하지 않습니다.

공급자 연결 열기

로그인하고 설정 > 플러그인을 엽니다.
왼쪽 창에서 공급자 목록을 검색합니다.
공급자를 선택해 활성 상태와 실제 모델 카탈로그를 확인합니다.
계정에 해당 공급자를 활성화합니다.
자격 증명을 저장하거나 연결 설정을 재정의해야 할 때만 구성을 선택합니다.

공급자 구성은 기본적으로 닫혀 있습니다. 관리자의 경우 연결 설정이 먼저 표시되며, 온도와 토큰 한도 같은 샘플링 제어 기능은 별도로 접혀 있는 고급 매개변수 섹션 아래에 유지됩니다. 상속된 기본값은 계정 재정의에 미리 채워지지 않고 힌트로 표시됩니다.

플러그인 정의는 인스턴스 공유 구성이므로 관리자만 가져오고, 설치하고, 업데이트하거나 삭제할 수 있습니다. 인증된 각 사용자는 자신의 활성 상태, 자격 증명과 허용된 생성 설정을 관리합니다.

빠르게 연결 추가하기

설정 > 연결은 OpenAI 호환 엔드포인트 하나와 API 키 하나를 사용하는 일반적인 경우를 위한 더 짧은 경로입니다. 관리자는 로컬 Ollama 런타임의 상태와 버전을 보여 주는 카드, 기존 OpenAI 호환 연결 목록과 새 연결을 추가하는 간단한 양식을 볼 수 있습니다.

연결을 추가하려면 표시 이름, 전체 채팅 완성 URL과 선택적 API 키를 입력합니다. Libre WebUI는 이름에서 연결 ID를 생성하고, 공급자 정의를 설치하고, 서버 측에 키를 저장하고, 연결을 활성화한 뒤 엔드포인트에서 제공하는 모델을 요청합니다. 검색된 모델은 자리 표시자 카탈로그를 대체하고 채팅 모델 선택기에 나타납니다.

각 행에는 엔드포인트, 모델 수, 키 저장 여부, 활성 토글, 모델 새로 고침과 삭제가 표시됩니다. 응답 API 모드, Base URL 재정의, 기능별 카탈로그, 생성 매개변수 정책 같은 고급 설정은 위에서 설명한 전체 설정 > 플러그인 워크스페이스에 그대로 있습니다.

Codex (ChatGPT 로그인)

번들 Codex (ChatGPT) 공급자에는 API 키가 필요하지 않습니다. 서버 운영 체제 사용자가 Codex CLI에 로그인한 상태(codex login)라면 관리자에게 이 공급자가 나타나고, ChatGPT 세션을 통해 문서화된 Codex 모델 제품군을 제공합니다. 액세스 토큰은 CLI 자체의 auth.json에서 읽고, CLI와 같은 OAuth 클라이언트로 갱신한 뒤 CLI가 계속 작동하도록 다시 기록됩니다. 토큰 값은 로그에 절대 표시되지 않습니다.

요청은 작업 컨테이너 내부가 아니라 항상 백엔드에서 이루어지므로, 이 모델은 일반적인 샌드박스 도구 루프를 통해 Work에도 사용될 수 있습니다. 모든 호출이 서버 소유자의 ChatGPT 구독을 사용하므로 이 공급자는 관리자만 이용할 수 있습니다. 완전히 숨기려면 CODEX_OAUTH_MODELS_ENABLED=false를 설정하고, 다른 로그인 위치를 사용하려면 CODEX_HOME을 지정하세요.

번들 또는 가져온 공급자 선택하기

Libre WebUI에는 OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Moonshot AI의 Kimi Code, Hugging Face, GitHub Models, 로컬 MLX LM과 기타 모델 또는 미디어 서비스의 정의가 포함되어 있습니다. 사용하려는 서비스의 프로토콜과 인증 계약에 맞으면 번들 항목부터 사용하세요.

다른 호환 서비스의 경우 관리자가 플러그인 JSON 정의를 가져올 수 있습니다. 다음은 OpenAI 호환 게이트웨이를 설명하는 최소 예제입니다.

{
  "id": "private-ai-gateway",
  "name": "Private AI Gateway",
  "type": "completion",
  "endpoint": "http://ai-gateway:8080/v1/chat/completions",
  "api_mode": "chat_completions",
  "auth": {
    "header": "Authorization",
    "prefix": "Bearer ",
    "key_env": "PRIVATE_AI_GATEWAY_API_KEY"
  },
  "model_map": ["gateway-chat"]
}

설정 > 플러그인에서 파일을 가져와 활성화한 다음, 연결을 사용할 계정의 API 키를 저장합니다. 관리자가 편집 가능한 Base URL, 경로, 검색 또는 기능별 엔드포인트 필드가 필요하면 정의에 연결 변수를 추가하세요. 번들 plugins/openai.json이 완전한 예제입니다.

신뢰할 수 있는 네트워크에서 의도적으로 인증 없는 게이트웨이를 사용하려면 auth.header와 auth.key_env를 모두 빈 문자열로 설정하고 auth.prefix를 생략합니다. 그러면 Libre WebUI는 해당 플러그인에 API 키를 요구하거나 전송하지 않습니다.

Chat Completions 또는 Responses 선택하기

OpenAI 호환 완성 플러그인은 두 API 모드 중 하나를 사용할 수 있습니다.

API 모드	기본 요청 경로	일반적인 요청 필드
`chat_completions`	`/chat/completions`	`messages`
`responses`	`/responses`	`input`

번들 OpenAI 공급자는 구성에 API 모드를 제공합니다. Libre WebUI는 추론과 도구 호출을 위한 제한된 재생 상태를 포함해 완료된 출력과 스트리밍 Responses 출력을 채팅과 Work에 다시 매핑합니다.

모드를 변경하면 기본 작업 경로가 바뀝니다. 업스트림 서버가 사용하는 프로토콜 자체가 바뀌는 것은 아니므로, 서버가 호환되는 Responses 요청과 이벤트 형식을 구현한 경우에만 Responses를 선택하세요.

Base URL 또는 전체 엔드포인트 구성하기

Libre WebUI는 다음 순서로 완성 경로를 결정합니다.

기본값이 아닌 전체 endpoint 재정의
base_url과 선택적 api_path
플러그인 정의에서 선언한 엔드포인트

API 루트에는 Base URL을 사용합니다.

https://gateway.example/v1

사용자 지정 경로가 없으면 Chat Completions 모드는 다음 주소로 요청을 보냅니다.

https://gateway.example/v1/chat/completions

Responses 모드는 대신 다음 주소를 사용합니다.

https://gateway.example/v1/responses

공급자가 해당 루트의 다른 상대 경로에서 호환 작업을 제공할 때는 API 경로를 사용합니다. 전체 작업 URL을 제공해야 할 때만 레거시 전체 엔드포인트를 사용하세요. 실제 전체 엔드포인트는 Base URL과 API 경로보다 우선합니다.

알려진 /chat/completions, /completions, /responses 엔드포인트 접미사도 요청 의미 체계를 식별합니다. 인식되지 않는 사용자 지정 작업 경로에서는 명시적으로 선택한 API 모드가 유지됩니다.

경로나 API 키를 변경한 후 채팅에서 테스트하기 전에 공급자를 다시 저장하세요. 플러그인에서 인증을 선언한 경우 사용자 지정 연결 경로에는 같은 계정이 저장한 자격 증명이 필요합니다. 의도적으로 인증을 사용하지 않는 플러그인은 두 인증 필드를 모두 비워 둘 수 있습니다. Libre WebUI는 운영자가 관리하는 환경 키를 사용자가 정의한 대상으로 보내지 않습니다. 환경 대체 값은 신뢰할 수 있는 번들 경로에만 사용됩니다.

모델 ID 검색 또는 유지 관리하기

활성 채팅 공급자를 선택하고 모델 새로 고침을 사용해 검색을 실행합니다. Libre WebUI는 선택한 공급자의 카탈로그와 채팅의 모델 목록을 모두 다시 로드합니다.

검색은 요청하지 않아도 실행됩니다. 활성 공급자의 카탈로그가 없거나 PLUGIN_MODEL_DISCOVERY_TTL_MS보다 오래되면 다시 검색하므로, 표시되는 모델은 공급자를 활성화한 시점이 아니라 현재 공급자 상태를 따릅니다. 모델 새로 고침은 즉시 확인을 강제하고 결과를 보고합니다.

결과	의미
카탈로그 업데이트됨	공급자가 응답했으며 모델 목록이 저장된 목록과 다름
카탈로그가 이미 최신 상태임	공급자가 같은 목록으로 응답함
API 키 필요	사용할 수 있는 키가 없어 요청하지 않았으며 이전 카탈로그는 계속 표시됨
카탈로그를 불러올 수 없음	공급자에 연결할 수 없거나 사용 가능한 항목을 반환하지 않음

환경에만 설정된 키는 번들 정의 대신 설치된 정의로 실행되는 공급자에 사용되지 않습니다. 이 경우 메시지에 해당 사실이 표시됩니다. 공급자 카탈로그에서 찾은 음성, 이미지와 임베딩 모델은 기능 레이블과 함께 여기에 표시되지만 채팅 모델 선택기에는 포함되지 않습니다.

OpenAI 호환 경로의 경우 모델 목록 URL은 다음과 같이 선택됩니다.

/models로 끝나는 경로는 그대로 사용합니다.
/chat/completions, /completions, /responses, /embeddings, /messages 같은 알려진 작업 접미사는 /models로 대체합니다.
그 외에는 경로에 /models를 추가합니다.

예를 들어 다음 두 완성 경로는 동일한 검색 URL을 생성합니다.

https://gateway.example/v1/chat/completions
https://gateway.example/v1/responses

-> https://gateway.example/v1/models

경로 계산으로 올바른 전체 URL을 만들 수 없으면 플러그인의 variables 배열에 models_endpoint를 공개합니다.

{
  "name": "models_endpoint",
  "type": "string",
  "label": "Models Endpoint",
  "default": "https://gateway.example/v1/models"
}

상속된 기본값 또는 관리자가 저장한 값이 계산된 주소보다 우선합니다. 최상위 models_endpoint 매니페스트 속성은 읽지 않습니다. 검색에서는 data 배열에 모델 객체가 들어 있는 OpenAI 호환 응답을 기대합니다.

{
  "data": [{ "id": "gateway-chat" }, { "id": "gateway-code" }]
}

검색된 ID는 사용자별로 저장되며 공유 플러그인 파일을 다시 쓰지 않습니다. 공급자가 호환 검색을 구현하지 않았다면 플러그인 JSON의 model_map에 대체 모델 ID를 유지하세요. 공급자 연결의 카탈로그는 읽기 전용입니다. 기능 레이블은 모델을 나열하는 플러그인 경로를 설명하며 상태 확인 기능이 아닙니다.

모델 ID는 전역적으로 고유하지 않습니다. 채팅은 원래 모델 ID와 정확한 Ollama 또는 플러그인 공급자 ID를 함께 저장하므로, Ollama 모델과 여러 플러그인이 이름이 같은 모델을 안전하게 공개할 수 있습니다. 저장된 공급자를 사용할 수 없게 되면 Libre WebUI는 요청을 다른 공급자로 조용히 라우팅하지 않고 해당 선택 항목을 사용할 수 없음으로 표시합니다.

이미지 생성을 별도로 구성하기

번들 OpenAI 공급자는 https://api.openai.com/v1/images/generations를 통해 이미지 생성을 제공하며, 현재 새 구성의 기본값은 gpt-image-2입니다. 이전 GPT Image ID도 호환되는 기존 배포를 위해 대체 카탈로그에 남아 있습니다.

채팅과 이미지 경로는 의도적으로 분리되어 있습니다. 사용자 지정 채팅 Base URL로 이미지 요청이 자동 전송되지는 않습니다. 플러그인에서 선언한 이미지 엔드포인트를 사용하려면 image_endpoint를 비워 두고, 공급자에서 호환되는 Image API 작업을 제공하면 완전한 URL로 설정하세요.

이미지 선택 항목도 채팅 선택 항목처럼 공급자로 한정됩니다. 두 활성 플러그인이 같은 이미지 모델 ID를 제공하더라도 Libre WebUI는 이미지 패널에서 선택한 공급자에만 요청을 보냅니다.

HTTP 게이트웨이를 안전하게 연결하기

공급자 엔드포인트에는 절대 HTTP 또는 HTTPS URL을 사용할 수 있습니다. HTTP는 신뢰할 수 있는 LAN, Tailscale 네트워크 또는 비공개 컨테이너 네트워크의 자체 호스팅 게이트웨이에 유용하지만, API 키, 프롬프트, 도구 결과와 생성 콘텐츠가 전송 암호화 없이 전달됩니다. 경로가 네트워크 경계를 넘거나 게이트웨이가 TLS를 지원하면 항상 HTTPS를 우선하세요.

요청은 브라우저가 아니라 Libre WebUI 백엔드에서 시작됩니다. 해당 백엔드가 접근할 수 있는 주소를 선택하세요.

백엔드 위치	공급자 루트 예시
네이티브 프로세스, 같은 머신	`http://127.0.0.1:8081/v1`
Docker Compose 서비스	`http://ai-gateway:8080/v1`
컨테이너에서 지원 호스트로	`http://host.docker.internal:8081/v1`
신뢰할 수 있는 LAN/Tailscale 호스트	`http://192.168.1.20:8081/v1`

컨테이너 안에서 localhost는 Libre WebUI 컨테이너 자체를 가리킵니다. 다른 Compose 서비스를 가리키거나 호스트에 자동으로 연결되지 않습니다.

Libre WebUI는 HTTP 및 HTTPS 공급자 URL만 허용하고, 자격 증명을 선택하기 전에 최종 대상을 검증하며, 공급자 또는 검색 요청의 리디렉션을 따르지 않습니다. 최종 작업 URL을 직접 구성하세요.

활성화하기 전에 게이트웨이 검증하기

Libre WebUI 백엔드를 실행하는 머신이나 컨테이너에서 모델 검색을 테스트합니다.

curl http://ai-gateway:8080/v1/models \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY'

그런 다음 선택한 API 모드에 맞는 작업을 테스트합니다.

Chat Completions:

curl http://ai-gateway:8080/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "messages": [{"role": "user", "content": "Reply with: ready"}],
    "stream": false
  }'

Responses:

curl http://ai-gateway:8080/v1/responses \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "input": "Reply with: ready",
    "store": false
  }'

두 호출이 모두 작동하면 공급자 연결에서 같은 경로, 모드, 자격 증명과 모델 ID를 구성합니다. 공급자를 활성화하고 모델 새로 고침을 선택한 다음, 채팅에서 해당 공급자로 한정된 모델을 선택합니다. 모델이 도구 호출을 안정적으로 지원하면 Work에서도 사용할 수 있습니다.

문제 해결

증상	확인할 사항
요청이 계속 번들 엔드포인트로 전송됨	오래된 전체 엔드포인트 재정의를 제거한 뒤 원하는 Base URL과 API 경로를 저장합니다.
공급자가 잘못된 페이로드를 받음	API 모드를 업스트림 Chat Completions 또는 Responses 프로토콜과 맞추고 최종 접미사를 확인합니다.
모델 새로 고침에서 ID가 반환되지 않음	`/models`를 테스트하고 `data[].id` 형식을 확인하며, `models_endpoint` 변수를 공개/구성하거나 `model_map`을 유지합니다.
경로를 편집한 뒤에도 이전 모델이 남아 있음	연결 변경 사항을 저장합니다. Libre WebUI가 새로 고치기 전에 해당 사용자의 오래된 검색 카탈로그를 지웁니다.
API 키가 없다고 보고됨	사용자 지정 경로의 사용자별 자격 증명을 저장합니다. 번들 환경 대체 값은 재정의된 경로를 따르지 않습니다.
Docker 배포에서 localhost에 접근할 수 없음	게이트웨이의 Compose 서비스 이름, 지원되는 호스트 별칭 또는 접근 가능한 비공개 네트워크 주소를 사용합니다.
채팅은 되지만 이미지 생성이 되지 않음	별도의 전체 `image_endpoint`를 구성하고 해당 이미지 기능에서 공개하는 모델을 선택합니다.
채팅은 되지만 Work가 모델을 거부함	모델이 호환되는 도구 호출을 지원하는지 확인합니다. 일반 텍스트 완성만으로는 충분하지 않습니다.
공급자가 리디렉션을 반환함	검증된 최종 URL을 직접 구성합니다. Libre WebUI는 의도적으로 공급자 리디렉션을 따르지 않습니다.

라우팅, 자격 증명, 재생 상태와 권한 부여 동작에 대한 자세한 내용은 플러그인을 참조하세요. 배포별 오류는 문제 해결을 참조하세요.

커뮤니티 감사의 말

이 가이드와 Libre WebUI 0.16.0의 공급자 연결 환경은 ZhengJin(@fangzhengjin)의 도움으로 완성되었습니다. 자세한 타사 공급자 피드백과 #163의 AI 보조 UX 개념은 이 작업 흐름을 정의하는 데 기여했습니다.

공급자 연결 열기​

빠르게 연결 추가하기​

Codex (ChatGPT 로그인)​

번들 또는 가져온 공급자 선택하기​

Chat Completions 또는 Responses 선택하기​

Base URL 또는 전체 엔드포인트 구성하기​

모델 ID 검색 또는 유지 관리하기​

이미지 생성을 별도로 구성하기​

HTTP 게이트웨이를 안전하게 연결하기​

활성화하기 전에 게이트웨이 검증하기​

문제 해결​

커뮤니티 감사의 말​

관련 문서​