Open WebUI를 커스텀 OpenAI 호환 엔드포인트에 연결하기.

빠른 답: Admin Settings의 연결 하나.

관리자로서 Admin Settings를 열고 Connections로 이동한 다음, OpenAI API 섹션에서 연결 추가를 클릭하세요. 중요한 필드는 두 가지입니다: https://api.apisrouter.com/v1로 설정하는 URL, 그리고 API 키. 저장하면 Open WebUI가 엔드포인트의 /v1/models 목록을 조회해 모델 선택기를 채웁니다. 연결의 확인 컨트롤로 검증한 다음, 새 채팅에서 카탈로그의 아무 id나 선택하세요. 이렇게 추가한 연결은 워크스페이스 전체에 적용됩니다: Open WebUI 인스턴스의 모든 사용자가 여러분이 설정한 모델 접근 제어에 따라 그 모델들을 보게 됩니다. 같은 값을 대신 배포 시점의 환경 변수, 즉 OPENAI_API_BASE_URL과 OPENAI_API_KEY로 전달할 수도 있는데, 인스턴스를 클릭으로 구성하는 대신 compose 파일로 프로비저닝할 때는 이쪽이 더 깔끔한 경로입니다.

URL:      https://api.apisrouter.com/v1
API Key:  sk-YOUR-APISROUTER-KEY

Save → models auto-populate from /v1/models
(optional) Model IDs allowlist to curate the selector

Open WebUI가 OpenAI 연결을 사용하는 방법.

Open WebUI(GitHub 스타 약 14.5만 개)는 셀프 호스팅 AI 채팅 프론트엔드의 사실상 기본값입니다: 사용자·권한 관리, RAG와 지식 컬렉션, 툴 호출, 모델 관리를 갖춘 완전한 기능의 웹 클라이언트이며, 전통적으로 로컬 모델을 위해 Ollama와 짝을 이루지만 원격 API와 통신하는 데도 똑같이 능숙합니다. 연결 모델은 누적되는 방식입니다. Ollama 섹션은 로컬 런타임을 다루고, OpenAI API 섹션은 표준 chat-completions 방언으로 말하는 어떤 엔드포인트든 다루며, 여러 연결을 나란히 추가할 수 있습니다. 각 연결은 자신의 모델 목록을 공유 선택기에 기여하고, 각자 자체 키를 가지며, 설정을 삭제하지 않고도 개별적으로 끌 수 있습니다. 요청은 모델 id를 그대로 문자열로 담아 그것을 제공하는 연결로 전달됩니다. 이 설계 덕분에 게이트웨이 연결이 기존의 무엇도 대체하지 않습니다: 로컬 모델은 토큰당 비용 없이 Ollama를 통해 계속 실행되고, claude-sonnet-4-6, gpt-5.5, gemini-3.5-flash, deepseek-v4-pro는 프론티어급 품질이 필요한 대화를 위한 선택기 항목이 됩니다. 키 하나가 이 모두를 처리하며, 클라우드 트래픽이 정확히 한곳으로만 나가므로 관리자 쪽 사용량도 읽기 쉽게 유지됩니다.

배포 시점 설정: 환경 변수.

docker-compose와 Kubernetes 배포에서는 연결을 매니페스트의 일부로 만들 수 있습니다. OPENAI_API_BASE_URL이 엔드포인트를, OPENAI_API_KEY가 키를 받습니다. 인스턴스는 연결이 이미 준비된 상태로 시작됩니다. 여러 원격 소스를 운영한다면 복수형(세미콜론으로 구분한 값을 쓰는 OPENAI_API_BASE_URLS와 OPENAI_API_KEYS)을 통해 여러 엔드포인트를 지원합니다. 운영상의 참고사항 두 가지. 첫째, UI를 통해 설정한 값은 Open WebUI의 데이터베이스에 저장되며 첫 부팅 이후에는 환경 변수 기본값보다 우선합니다. 이는 문서화된 동작이지만, env를 바꿨는데 아무 일도 일어나지 않는 것을 본 운영자들을 종종 놀라게 합니다. Admin Settings에서 기존 연결을 조정하거나, 환경 변수가 계속 우선하기를 원한다면 ENABLE_PERSISTENT_CONFIG=false를 설정하세요. 둘째, 엔드포인트의 모델 목록이 크다면, 연결의 Model IDs 허용 목록을 사용해 사용자에게 보여줄 것을 정리하세요. 네 개짜리 선택기는 실제로 쓰이지만, 200개짜리는 그냥 스크롤되어 지나칩니다. 버전 참고: 프로젝트의 빠른 릴리스 주기에 따라 메뉴 문구가 바뀌어 왔으므로(Settings 대 Admin Settings, Connections 내의 섹션 이름), 오래된 빌드에서는 연결이 있는 곳 어디서든 OpenAI API 베이스 URL과 키 쌍을 찾아보세요.

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    environment:
      - OPENAI_API_BASE_URL=https://api.apisrouter.com/v1
      - OPENAI_API_KEY=sk-YOUR-APISROUTER-KEY
    ports:
      - "3000:8080"

멀티 유저 워크스페이스를 위한 모델 선택.

모든 클라우드 모델이 키 하나로 청구되므로, A/B 테스트는 선택기에서의 선택일 뿐입니다. 같은 팀 업무량을 2주 간격으로 두 후보 기본값에서 돌려보고, 벤치마크로 추측하는 대신 APIsRouter 콘솔의 모델별 사용량 뷰가 모델별·일별로 심판 역할을 하게 하세요.

• 공유 인스턴스에서는 기본 모델 선택이 가장 큰 영향을 미칩니다. claude-haiku-4-5-20251001이나 gemini-3.5-flash를 워크스페이스 기본값으로 두면 가벼운 사용의 대화당 비용을 낮게 유지할 수 있습니다.
• claude-sonnet-4-6과 gpt-5.5는 초안 작성, 분석, 코드 질문을 위해 선택기에 있어야 합니다. 작업이 그럴 가치가 있을 때 사용자가 상위 모델로 올라갑니다.
• RAG 파이프라인은 입력 토큰을 배가시킵니다: 모든 답변이 검색된 청크를 담고 있습니다. deepseek-v4-pro는 RAG 작업용으로 테스트해볼 가치가 있습니다 — 소모한 토큰당 긴 컨텍스트 처리 능력이 결정적인 특성입니다.
• 정말로 비공개여야 할 자료는 Ollama를 통한 로컬 모델에 두고, 나머지는 게이트웨이로 라우팅하세요. 선택기는 두 차선을 정직하게 함께 담아냅니다.
• Model IDs 허용 목록을 정책으로 활용하세요: 선택기에 없는 것은 사용량 로그에서 놀랄 일도 만들지 않습니다.

사용한 만큼 지불 · 공식 요금보다 저렴

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Open WebUI 특유의 실패 패턴.

연결을 추가한 뒤 모델이 나타나지 않는 것이 가장 흔한 보고입니다. 원인 순서는: 키가 /v1/models 조회에서 실패함(연결의 확인 컨트롤로 확인하세요), URL에 /v1 접미사가 빠짐, 또는 연결 토글이 꺼져 있음. Open WebUI는 목록 조회 결과로 선택기를 구성하므로, 빈 선택기는 목록 조회가 실패했거나 아무것도 반환하지 않았다는 뜻입니다. 환경 변수를 바꿨는데 무시되는 것처럼 보이는 것은 위에서 설명한 영구 설정 규칙 때문입니다: 첫 부팅 이후에는 UI가 관리하는 설정에 대해 데이터베이스가 환경 변수를 이깁니다. Admin Settings에서 연결을 수정하거나, 영구 설정을 명시적으로 비활성화하세요. 목록에는 나오지만 채팅에서 오류가 나는 모델은 대개 목록에는 노출되지만 여러분의 키로는 쓸 수 없는 id이거나, Model IDs 허용 목록을 손으로 수정하다 생긴 오타입니다. 원본 /v1/models 출력과 비교해 보세요. 그리고 디버깅할 때는 차선을 명확히 구분하세요: Ollama 연결 문제와 OpenAI 연결 문제는 채팅 창에서는 똑같아 보입니다. Connections 페이지가 어떤 모델이 어느 차선에 속하는지 보여줍니다. 인스턴스 전체가 다운됐다고 단정하기 전에 실패한 차선을 직접 테스트하세요.

어떤 사람들이 게이트웨이를 통해 Open WebUI를 쓰는가.

• 모두를 위해 채팅 프론트엔드 하나를 셀프 호스팅하며, 개별 사용자에게 벤더 키를 발급하지 않고도 프론티어 모델을 제공하고 싶은 팀.
• 비공개 작업에는 로컬 모델을 유지하지만, 필요한 대화에는 같은 선택기에서 Claude와 GPT 수준의 품질을 원하는 Ollama 사용자.
• 클라우드 청구서를 명확하게 파악해야 하는 관리자 — 네 벤더의 영수증 대신 연결 하나, 키 하나, 모델별 사용량 로그.
• 일부 벤더 가입이 까다로운 지역의 운영자. 카드 없이 충전만으로 접근할 수 있어 프로바이더별 의존성이 사라집니다.
• 가정용으로 Open WebUI를 운영하는 홈랩 사용자 — 어떤 구독보다도 선불 잔액 하나가 파악하기 쉽습니다.

엔드포인트 검증 및 첫 채팅 디버깅.

먼저 서버에서 엔드포인트를 검증하세요. 특히 컨테이너의 네트워크가 여러분의 노트북과 다른 컨테이너화된 배포에서는 더욱 그렇습니다. 호스트 안에서 모델 목록과 chat completion 하나를 확인하면 Open WebUI가 등장하기 전에 게이트웨이 쪽이 검증됩니다. 그다음 연결을 추가하고 선택기가 채워지는지 지켜보세요. 인증 오류는 키 필드 문제입니다. 빈 선택기는 목록 조회 호출 문제입니다. 서버 로그에서 경로가 중복된 것(/v1/v1/...)은 URL 필드에 이미 /v1이 있는데 무언가가 하나를 더 붙였다는 뜻이니, 저장된 그대로의 URL을 확인하세요. 채팅이 순조롭게 흐르면, APIsRouter 콘솔이 요청별 모델, 토큰 수, 지출을 보여줍니다. 멀티 유저 인스턴스에서는 이것이 중요한 숫자입니다: 사용자가 실제로 어떤 모델을 고르는지, 그리고 워크스페이스 일주일이 실제로 얼마나 드는지를 모델별·일별로 한 페이지에서 보여줍니다.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001",
       "messages":[{"role":"user","content":"ping"}]}'

자주 묻는 질문