OpenWebUI API 연결: 내 모델로 웹페이지와 채팅하기

OpenWebUI를 운영하고 있다면, 가장 번거로운 고비는 이미 넘기신 셈입니다. 모델 설정도 끝났고 키도 한곳에 모여 있습니다. 홈 서버의 Ollama, 클라우드 제공자 한두 곳, 그리고 직접 다듬어 둔 커스텀 워크스페이스 모델 몇 개까지요.

다만 OpenWebUI가 해주지 못하는 게 하나 있습니다. 지금 보고 있는 페이지 안에서는 작동하지 않는다는 점입니다. 읽고 있는 기사나 PDF, 문서 페이지에 대해 모델에게 물어보려면 여전히 내용을 복사해서 다른 탭에 붙여넣어야 합니다.

바로 여기서 SurfMind가 등장합니다. OpenWebUI는 채팅 화면만 있는 도구가 아닙니다. OpenWebUI API를 통해 API 서버 역할도 하기 때문에, SurfMind가 이를 백엔드로 쓸 수 있습니다. 모델 관리는 계속 OpenWebUI에서 하고, SurfMind는 그 모델들을 브라우저에서 쓰게 해주는 프런트엔드가 됩니다.

이 가이드에서는 OpenWebUI API가 무엇인지, SurfMind와 어떤 관계인지, 정확히 어떤 URL을 붙여넣어야 하는지, 그리고 실제로 많이들 겪는 오류를 어떻게 해결하는지 다룹니다.

OpenWebUI와 SurfMind: 겉보기엔 비슷해도 하는 일이 다릅니다

얼핏 보면 두 도구는 경쟁 관계처럼 보입니다. 둘 다 AI 인터페이스이고, 여러 LLM 제공자에 연결되며, 모델과 채팅할 수 있으니까요. 하지만 용도는 다릅니다:

OpenWebUI는 셀프호스팅 AI 워크스페이스이고, SurfMind는 이미 쓰고 있는 브라우저 안의 AI입니다. 가장 중요한 건 굵게 표시한 행입니다. OpenWebUI가 API로 모델을 제공할 수 있기 때문에 두 도구가 맞물려 돌아갈 수 있습니다.

OpenWebUI를 SurfMind에 연결하는 이유

흔한 구성을 떠올려 봅시다. 홈 서버나 작은 VPS에 OpenWebUI가 있고, 그 뒤에는 이런 것들이 연결되어 있습니다:

• Ollama로 로컬에서 실행 중인 Llama, Qwen, Gemma
• 클라우드 API 키로 쓰는 GPT 또는 Claude 모델
• 내 GPU에서 vLLM으로 제공하는 모델
• OpenWebUI에서 직접 만든 워크스페이스 모델 몇 개(각각 고유한 시스템 프롬프트와 설정 포함)

이 모든 것은 OpenWebUI의 채팅 페이지에서 쓸 수 있습니다. 그런데 이제 브라우저 어시스턴트가 잘하는 일도 하고 싶어집니다. 지금 보는 페이지에 대해 질문하고, 긴 스레드를 요약하고, 여러 탭의 정보를 비교하고, 사이트를 떠나지 않고 답장 초안을 쓰는 일 말이죠.

SurfMind에 제공자를 하나씩 다시 추가할 수도 있습니다. Ollama, 그다음 OpenAI 키, 그다음 vLLM 엔드포인트. 하지만 번거롭고, 키를 중복으로 관리하게 되며, 공들여 만든 워크스페이스 모델은 따라오지 않습니다.

아니면 연결을 하나만 추가하면 됩니다. SurfMind → OpenWebUI. OpenWebUI가 볼 수 있는 모든 모델이 SurfMind의 모델 선택기에 나타납니다. 모델, 사용자, 권한 관리는 지금처럼 OpenWebUI에서 계속하고, SurfMind를 통해 그 모델들을 브라우저에서 바로 쓸 수 있습니다.

팀이 같은 구성을 함께 쓰기에도 편리한 방법입니다. 팀이 OpenWebUI 인스턴스 하나를 운영한다면, 각자 자기 API 키를 만들어 브라우저에서 팀의 모델을 쓸 수 있습니다. 권한은 OpenWebUI에서 가진 것과 똑같고, 누구도 제공자 키를 직접 들고 있을 필요가 없습니다.

1단계: OpenWebUI API 키 만들기

API 키는 기본적으로 꺼져 있어서, 처음에는 활성화하는 데 1분 정도 걸립니다.

관리자라면 API 키를 켜세요:

1. 관리자 계정으로 OpenWebUI에 로그인합니다.
2. Settings → Admin → Authentication으로 이동합니다.
3. API Keys를 켜고 Save를 클릭합니다.

관리자가 아니라면, 관리자에게 API Keys 기능 권한을 달라고 요청하세요. 관리자는 Admin Panel → Users → Groups에서 이 권한을 설정할 수 있으며, 전체 사용자용 Default Permissions나 특정 그룹에 부여할 수 있습니다.

그다음 키를 생성하세요:

1. 왼쪽 아래의 프로필 아이콘을 클릭합니다.
2. Settings → Account를 엽니다.
3. API keys 섹션에서 Secrets 옆의 Show를 클릭합니다. 이 섹션은 기본적으로 접혀 있으니, 비어 보여도 정상입니다.
4. Create new secret key를 클릭하고 키를 복사합니다. 키는 sk-로 시작합니다.

OpenWebUI의 API 키 문서에서 알아둘 만한 점 몇 가지:

• 계정당 키는 하나입니다. 새 키를 만들면 기존 키가 대체되고, 기존 키는 즉시 작동을 멈춥니다. 다른 도구가 이미 그 키를 쓰고 있다면, SurfMind용으로 새 키를 만드는 순간 그 도구가 먹통이 됩니다. SurfMind 전용 비관리자 계정을 따로 두면 이 문제를 피할 수 있습니다.
• 키에는 내 계정과 같은 권한이 부여됩니다. 키를 만든 계정과 똑같은 모델을 보고, 똑같은 권한을 갖습니다.
• 같은 패널에서 관리자에게 표시되는 JWT 토큰은 쓰지 마세요. 그건 브라우저 세션 토큰이라 만료됩니다.

2단계: SurfMind에 OpenWebUI 추가하기

SurfMind 패널 하단의 모델 이름을 클릭한 뒤 Show all → Custom → Add Custom Models로 이동하세요. 범용 OpenAI-compatible 프리셋을 고르고 다음과 같이 입력합니다:

OpenWebUI가 브라우저와 같은 컴퓨터에서 실행 중이라면, 호스트는 보통 http://localhost:3000(Docker의 일반적인 포트 매핑)이나 http://localhost:8080(pip 또는 직접 설치)입니다:

• API URL: http://localhost:3000/api/chat/completions
• Models URL: http://localhost:3000/api/models

저장한 뒤 목록에서 OpenWebUI 모델 하나를 고르고, 아무 기사나 열어 SurfMind에게 요약해 달라고 해보세요.

피해야 할 경로 실수 두 가지. 호스트만 넣거나 /api까지만 넣지 말고, /api/chat/completions로 끝나는 전체 엔드포인트를 붙여넣으세요. SurfMind의 API URL 필드는 경로를 대신 붙여주지 않습니다. 그리고 어디에도 /v1을 넣지 마세요. /api/v1/chat/completions와 /v1/chat/completions는 OpenWebUI의 채팅 엔드포인트가 아닙니다.

문제 해결: "모델은 불러와지는데 채팅이 안 돼요"

OpenWebUI 관련해서 가장 많이 들어오는 문의라 따로 섹션을 마련했습니다. 드롭다운에 모델 목록이 표시된다면 호스트, 키, 네트워크 경로는 모두 정상입니다. 채팅 요청을 처리하는 과정에 문제가 있다는 뜻입니다. 아래 순서대로 확인해 보세요.

먼저 SurfMind 밖에서 테스트하세요. 터미널에서 간단히 curl을 실행해 보면 문제가 OpenWebUI 쪽인지 SurfMind 설정 쪽인지 알 수 있습니다. 호스트, 키, 모델 id는 본인 것으로 바꾸세요:

curl -X POST https://openwebui.example.com/api/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama3.2:latest", "messages": [{"role": "user", "content": "Say hi"}]}'

모델 id는 SurfMind 모델 목록(또는 GET /api/models)에 나오는 그대로 정확히 쓰세요. 이게 작동한다면 SurfMind 필드를 다시 확인하세요. 이것도 실패한다면, 반환된 오류가 아래 원인 중 하나를 가리킬 겁니다.

1. 채팅 경로가 틀렸습니다. Models URL과 API URL은 별개의 필드라서, 하나는 맞고 다른 하나는 틀릴 수 있습니다. API URL이 정확히 /api/chat/completions로 끝나는지, /v1이나 끝의 슬래시, 오타가 없는지 확인하세요.

2. 엔드포인트 제한이 채팅을 막고 있습니다. 관리자는 API 키가 호출할 수 있는 경로의 허용 목록인 API Key Endpoint Restrictions를 켤 수 있습니다. 여기에 /api/models는 있는데 /api/chat/completions가 없다면 바로 이런 문제가 발생하며, 보통 403으로 돌아옵니다. 관리자에게 /api/chat/completions를 추가해 달라고 요청하세요.

3. 모델 설정이 스트리밍 모드를 강제합니다. OpenWebUI에는 Stream Chat Response 설정이 있는데, 모델별 고급 파라미터에서 지정하거나 Settings → Admin → Models에서 관리자 기본값으로 지정할 수 있습니다. OpenWebUI 문서에 따르면 이 설정은 클라이언트가 무엇을 요청했든 상관없이 응답을 스트리밍할지 결정합니다. 클라이언트가 예상하지 못한 모드로 강제되면, 응답이 클라이언트가 읽을 수 없는 형태로 돌아올 수 있습니다. 특정 모델에서만 채팅이 실패한다면 해당 모델의 이 설정을 확인하고 Default로 되돌리세요.

4. 리버스 프록시가 Authorization 헤더를 가로챕니다. OpenWebUI가 자체 로그인에 Authorization을 쓰는 게이트웨이(basic auth, SSO, API 게이트웨이) 뒤에 있다면, 키가 OpenWebUI까지 도달하지 못합니다. OpenWebUI는 커스텀 헤더로도 키를 받으며, 기본값은 x-api-key입니다. 이럴 땐 SurfMind의 API Key Header로 x-api-key를 선택하세요. 관리자가 CUSTOM_API_KEY_HEADER로 헤더 이름을 바꿨다면, 프록시가 그 헤더를 그대로 통과시켜야 합니다.

5. 모델 id가 일치하지 않습니다. 직접 입력하지 말고 드롭다운에서 고르세요. Ollama 모델의 OpenWebUI id에는 태그가 포함되며(llama3.2:latest), 워크스페이스 모델은 표시 이름이 아니라 직접 지정한 id를 씁니다.

6. OpenWebUI 뒤의 제공자가 실패하고 있습니다. 업스트림 제공자가 요청을 거부하면 OpenWebUI는 그 상태 코드를 그대로 전달합니다. 429는 OpenWebUI나 SurfMind가 아니라 제공자의 속도 제한에서 오는 것입니다. 같은 모델을 OpenWebUI 자체 채팅에서 써보세요. 거기서도 실패한다면 문제는 업스트림에 있습니다.

그 밖의 오류 빠르게 훑어보기

모든 커스텀 엔드포인트에 공통으로 적용되는 규칙(포트, http vs https, 베이스 URL vs 전체 엔드포인트)은 커스텀 AI 연결 가이드를 참고하세요.

OpenWebUI, SurfMind, 아니면 둘 다?

둘 중 하나만 골라야 하는 문제가 아닙니다.

• OpenWebUI만 쓰는 게 좋은 경우: AI를 주로 전용 탭에서 긴 대화로 쓸 때입니다. 지식 베이스의 문서와 채팅하고, 파이프라인을 돌리고, 팀을 위해 모델을 관리하는 식이죠.
• SurfMind만 쓰는 게 좋은 경우: AI 사용이 대부분 화면에 떠 있는 내용에서 시작되고, 제공자나 Ollama 같은 로컬 러너를 직접 연결해도 괜찮을 때입니다.
• 둘 다 쓰는 게 좋은 경우: OpenWebUI 구성에 이미 공을 들였고, 모든 걸 두 번 설정하지 않고도 모든 페이지에서 쓰고 싶을 때입니다.

역할 분담은 간단합니다. OpenWebUI는 모델을 관리하고, SurfMind는 그 모델을 브라우저에서 활용할 수 있게 합니다.

자주 묻는 질문

OpenWebUI에 API가 있나요? 네. OpenWebUI API는 Bearer 토큰으로 인증하는 REST API입니다. 대부분의 도구에 필요한 엔드포인트는 두 가지로, 모델 목록을 가져오는 GET /api/models와 OpenAI 스타일 요청을 받는 채팅용 POST /api/chat/completions입니다.

OpenWebUI API는 OpenAI 호환인가요? 요청과 응답 형식은 호환됩니다. 다만 경로가 표준과 다릅니다. OpenWebUI는 /v1/chat/completions 대신 /api/chat/completions를 씁니다. SurfMind처럼 전체 엔드포인트 URL을 직접 지정할 수 있는 클라이언트라면 어디서든 쓸 수 있습니다.

OpenWebUI API 키는 어디서 찾나요? Settings → Account → API keys로 가서 Show를 클릭한 뒤 Create new secret key를 누르세요. 섹션이 보이지 않는다면 관리자가 Settings → Admin → Authentication에서 API Keys를 켜고, 내 계정에 API Keys 권한을 줘야 합니다.

OpenWebUI 워크스페이스 모델을 SurfMind에서 쓸 수 있나요? 네. 워크스페이스 모델도 다른 모델처럼 /api/models에 나열됩니다. 호출하면 OpenWebUI가 저장된 설정을 적용합니다.

OpenWebUI를 연결하면 내 데이터가 SurfMind 서버로 전송되나요? 커스텀 엔드포인트를 쓰면 SurfMind는 설정한 URL, 여기서는 내 OpenWebUI 서버로 요청을 보냅니다. 그러면 OpenWebUI 서버가 선택한 모델로 요청을 전달합니다. 그 모델이 로컬에서 실행된다면 페이지 내용은 내가 관리하는 하드웨어 밖으로 나가지 않습니다.

무료인가요? 네. SurfMind의 커스텀 엔드포인트는 무료이며, 저희 쪽에서 거는 사용량 제한도 없습니다. 비용은 내가 쓰는 제공자가 청구하는 만큼만 들고, 로컬 모델이라면 0원입니다.

그래도 안 되나요?

curl 테스트는 되는데 SurfMind가 여전히 OpenWebUI 모델과 채팅하지 못한다면 wave@surfmind.ai 로 이메일을 보내주세요. API URL(키는 빼고), HTTP 상태 코드, 그리고 특정 모델만 실패하는지 전부 실패하는지를 알려주세요. 셀프호스팅 환경은 구성이 제각각이라, 이런 제보가 SurfMind를 다양한 환경에서 매끄럽게 작동하도록 만드는 데 큰 도움이 됩니다.

SurfMind 받기 →