Open WebUI가 도구를 호출하지 않을 때: Native Mode, Tool Search, 모델 호환성 점검

도구를 켰고 모델도 사용하겠다고 답했지만 실제 tool call은 보이지 않을 수 있습니다. 이 증상만으로는 모델, Open WebUI, MCP/OpenAPI 서버 중 어디가 원인인지 알 수 없습니다. 부작용이 없는 작은 reverse_string으로 기준선을 만든 뒤 Native Mode, Tool Search, 모델 연결을 한 번에 하나씩 바꾸면 문제 지점을 빠르게 좁힐 수 있습니다.

원래 연결은 삭제하지 않습니다. 마지막에는 실제 호출과 실행 기록이 포함된 네 가지 조건표를 얻게 됩니다. 그 결과에 따라 Tool Search를 끌지, 중요한 도구를 Always Loaded에 둘지, 검증을 통과한 다른 연결로 도구 작업을 보낼지 결정할 수 있습니다.

도구 호출을 다섯 단계로 나눠 보기

UI에서 도구가 활성화되어 보인다는 사실은 UI 상태만 확인해 줍니다. 실제 실행이 성공하려면 다섯 단계가 모두 통과해야 합니다.

단계	확인할 내용	오해하기 쉬운 증상
1. 표시와 접근 권한	현재 사용자가 도구를 보고 읽을 수 있음	관리자에게는 되지만 다른 사용자에게는 조용히 사라짐
2. 채팅, 모드, capability	채팅이 Native이고 대상 도구가 켜져 있음. 내장 시스템 도구라면 Workspace → Models → Capabilities → Builtin Tools와 관련 category도 켜져 있음	Builtin Tools가 꺼져 있거나 Workspace/MCP/OpenAPI 전체를 제어하는 공통 master switch로 오해함
3. 요청 payload	backend가 전체 도구 정의 또는 설치 버전이 지원하는 deferred-tool helper를 받음	Tool Search가 schema를 지연했지만 UI에서는 계속 활성화로 보임
4. 모델 backend	올바른 대상의 구조화된 call과 유효한 arguments를 반환함	모델이 본문에서 호출했다고 말하거나, 다른 operation을 고르거나, 잘못된 arguments를 보냄
5. 실행	Open WebUI, MCP 또는 OpenAPI server가 올바른 call을 실행하고 결과를 반환함	올바른 call은 있지만 인증, route, protocol 또는 server에서 실패함

위에서 아래로 확인하세요. 접근 권한과 실제 대상 call을 보지 않고 MCP를 다시 만들면 유용한 증거를 잃을 수 있습니다.

변경 전에 원래 상태를 기록하기

최소한 다음을 저장합니다.

• Open WebUI version과 deployment 방식
• connection 이름, 정확한 Model ID, UI 표시 이름, 실제 provider, gateway, Base URL 또는 route
• Model Settings → Advanced Params → Function Calling의 실제 적용값
• 내장 시스템 도구라면 Workspace → Models → Capabilities → Builtin Tools 및 관련 category 상태
• 현재 채팅에서 Integrations → Tools로 활성화한 도구와 테스트 사용자의 read 권한
• Settings → Admin → Interface → Chat에 실제 표시되는 네 값: Tool Search, Defer Built-in Tools, Deferral Threshold (characters), Always Loaded Tools
• 대응하는 전체 설정 이름: ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD, TOOL_SEARCH_ALWAYS_LOADED
• 문제가 내장 시스템 도구, Workspace Tool, MCP, OpenAPI 중 어디에 있는지
• 실패한 prompt, timestamp, chat export/screenshot, 같은 시간대의 Open WebUI/tool-server logs

connection은 toggle로 잠시 끌 수 있으며 설정을 삭제할 필요가 없습니다. 비교할 때는 control-tool-test처럼 별도 이름의 connection을 추가하고 production connection을 덮어쓰지 마세요.

두 주장을 구분합니다.

1. 일반 채팅이 된다: text request가 완료됐다는 뜻뿐입니다.
2. 도구 호출이 된다: 대상 구조화 call, 유효한 arguments, 실행 기록, 반환 결과가 모두 필요합니다.

모델이 본문에서 reverse_string을 사용했다고 말해도 증거가 아닙니다.

현재 채팅이 Native Mode인지 확인하기

현재 Open WebUI 문서는 Native를 기본이자 지원되는 tool-calling mode로 설명합니다. Legacy는 이전 동작을 위한 미지원 옵션으로 남아 있습니다.

서로 덮어쓸 수 있는 세 위치를 확인합니다.

1. global Model Defaults
2. 선택한 model의 Advanced Params
3. 현재 채팅의 Chat Controls

테스트에서는 실제 적용값을 Native로 고정합니다. Tool Search는 Native Mode에 적용되므로 Legacy 실험과 섞지 마세요.

누락된 기능이 Open WebUI 내장 시스템 도구라면 Workspace → Models에서 선택한 모델을 편집하고 Capabilities를 확인합니다. Builtin Tools와 필요한 category가 모두 켜져 있어야 합니다. 이 switch는 Native Mode에서 내장 시스템 도구를 주입하는 기능만 제어하며, Workspace의 reverse_string, MCP, OpenAPI를 함께 제어하는 master switch가 아닙니다.

Workspace, MCP, OpenAPI는 각각의 별도 control을 확인합니다.

• 입력창 옆 Integrations를 엽니다.
• Tools에서 진단 도구나 외부 도구를 이 채팅에 활성화합니다.
• 도구가 model에 attach되어 있어도 현재 사용자의 read 권한을 확인합니다.

Workspace Tool을 model에 attach해도 access control을 우회하지 못합니다. read 권한이 없으면 Open WebUI가 모델에 전달하지 않을 수 있습니다.

부작용 없는 최소 도구 만들기

Workspace Tools는 Open WebUI 환경 안에서 Python을 실행합니다. 신뢰할 수 있는 관리자만 만들거나 import해야 합니다. 진단에는 파일, 네트워크, 데이터베이스, system command를 사용하지 않는 함수를 씁니다.

Workspace → Tools에서 다음 도구를 만듭니다.

"""
title: Read-only Tool Check
description: Reverses a string for tool-call diagnostics
version: 1.0.0
"""

class Tools:
    async def reverse_string(self, string: str) -> str:
        """
        외부 데이터를 읽거나 바꾸지 않고 입력 문자열의 순서를 뒤집습니다.

        :param string: 정확히 뒤집어야 하는 문자열.
        :return: 역순 문자열.
        """
        return string[::-1]

저장한 뒤 테스트 사용자에게 권한을 주고 Integrations → Tools에서 활성화합니다.

새 채팅마다 같은 prompt를 사용합니다.

문자열 tool-check-7은 반드시 reverse_string 도구로 처리하세요.
직접 뒤집거나 추측하지 마세요.
도구가 반환된 뒤에는 도구 결과만 출력하세요.

기대 결과:

7-kcehc-loot

같은 문자열이 보였다는 이유만으로 PASS 처리하면 안 됩니다. 다음 네 가지가 모두 필요합니다.

• trace 또는 tool activity에 구조화된 reverse_string call이 있음
• argument에 tool-check-7이 있음
• Open WebUI 또는 서버 로그에 대응하는 실행 기록이 있음
• 도구가 7-kcehc-loot을 반환했고 최종 답변이 그 결과를 사용함

채팅, call details, 같은 시각의 로그를 저장하세요. 이후 조건은 모두 새 채팅에서 동일한 도구와 prompt로 실행합니다.

네 가지 조건을 비교하기

한 번에 변수 하나만 바꾸고, 환경 변수 이름만 보지 말고 기존 Admin UI에서 실제로 설정합니다.

1. Settings → Admin → Interface → Chat을 엽니다.
2. 각 조건에 맞게 Tool Search, Defer Built-in Tools, Deferral Threshold (characters), Always Loaded Tools를 설정합니다.
3. 저장한 뒤 페이지를 다시 열어 실제 표시값을 기록합니다.
4. 새 채팅에서 같은 고정 prompt를 실행합니다.

네 항목은 각각 ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD, TOOL_SEARCH_ALWAYS_LOADED에 대응하며 모두 ConfigVar입니다. 기본값인 ENABLE_PERSISTENT_CONFIG=True에서는 Admin UI/database에 저장된 값이 환경 변수보다 우선합니다. 따라서 .env를 수정하고 재시작해도 조건이 바뀌었다고 보장할 수 없습니다. 배포가 의도적으로 ENABLE_PERSISTENT_CONFIG=False를 쓴다면 기록하세요. 시작 시 환경 변수가 우선하고 UI 변경은 현재 실행 session에만 적용되며 재시작하면 사라집니다.

조건	Native	Tool Search	Defer Built-in Tools	Threshold	Always Loaded	목적
A	On	Off	현재값 기록. 이 Workspace Tool에는 영향 없음	해당 없음	해당 없음	전체 reverse_string 정의로 기본 경로 확인
B	On	On	On으로 기록. 내장 도구에 적용되며 reverse_string을 제어하지 않음	0	모델에 보이는 정확한 이름	Always Loaded 경로 확인
C	On	On	On으로 기록	0	비움	deferred 경로를 강제하고 search_tools와 대상 call 관찰
D	On	C와 동일	C와 동일	0	비움	두 번째 connection을 먼저 A, 필요하면 B로 검증한 뒤 C 반복

Threshold 0이 중요합니다. 일반 규칙은 직렬화된 정의 길이가 설정값보다 긴 경우만 지연합니다. 작은 reverse_string은 기본 threshold 아래라 완전히 로드될 수 있고, 그러면 C가 deferred 경로를 시험하지 않습니다. 진단 후 production 값을 복원하세요.

조건 A: 먼저 기본 Native 경로 증명

Settings → Admin → Interface → Chat에서 Tool Search를 Off로 바꾸고 저장한 다음 페이지를 다시 열어 실제 적용값을 확인합니다. 새 채팅에서 고정 prompt를 실행하세요. 재시작만으로 설정 변경을 증명하지 마세요.

• A 통과: 사용자 접근, Native, 이 model route, Workspace Tool 실행이 최소 사례에서 작동합니다.
• 대상 구조화 call 없음: 채팅의 tool 선택, read 권한, 실제 Function Calling, backend의 native structured-call 지원을 확인합니다.
• call은 있지만 실행 실패: 모델은 call 단계까지 왔습니다. arguments, schema, Open WebUI execution logs를 확인합니다.

A가 통과하기 전에는 Tool Search를 진단하지 마세요.

조건 B: Always Loaded 경로 검증

같은 UI에서 Tool Search를 On, Defer Built-in Tools를 On으로 바꾸고 기록합니다. **Deferral Threshold (characters)**를 0, Always Loaded Tools에는 모델에 보이는 정확한 도구 이름을 넣습니다. 저장하고 다시 열어 확인한 뒤 새 채팅을 사용합니다.

Always Loaded matching은 대소문자를 구분하며 exact name 또는 glob을 쓸 수 있습니다. MCP의 model-visible name은 보통 <server ID>_<tool name>입니다. 내부 method 이름으로 추측하지 말고 실제 tool list나 trace에서 복사하세요.

• B 통과: Tool Search가 켜져 있어도 전체 schema가 request에 남으면 호출됩니다.
• A 통과, B 실패: 저장 후 다시 읽은 UI 값, 이름과 대소문자, 실제 설정 source, 테스트한 instance를 확인합니다.

조건 C: 지연 경로 강제 검증

Tool Search와 Defer Built-in Tools를 On, threshold를 0으로 유지하고 Always Loaded Tools를 비웁니다. 저장 후 실제 값을 다시 확인하고 새 채팅에서 같은 prompt를 실행합니다.

두 단계를 따로 기록합니다.

• search_tools call이 있었는가
• reverse_string definition을 반환했는가
• 이후 대상 구조화 call이 나타났는가
• Open WebUI v0.12.2 이상에서는 call_tool이 나타났고 tool_name과 JSON arguments가 reverse_string, tool-check-7을 가리키는가
• reverse_string이 실제 실행되어 기대값을 반환했는가
• 다른 도구 선택, 본문에 가짜 call 출력, 호출 없음이 있었는가

A/B가 통과했는데 C에서 search_tools조차 없다면 실제 UI 값, threshold, version, 모델/route가 Tool Search helper를 선택할 수 있는지 확인합니다. search_tools는 성공하지만 대상 call이 없다면 model capability, visible name/schema, 실제 provider route, version, deferred compatibility를 계속 후보로 둡니다.

strict backend 해석은 version에 따라 달라집니다. Open WebUI v0.12.2 이상에서는 이미 선언된 call_tool을 tool_name과 JSON arguments로 사용해 deferred tool을 호출하므로 현재 tools list에 있는 도구만 허용하는 backend도 지원할 수 있습니다. 이전 version은 지연된 도구 이름을 직접 호출했고 strict backend가 거절할 수 있었습니다. 오래된 Issue를 적용하기 전에 설치 version을 확인하세요. 공개 Issue는 특정 deployment와 backend family의 사용자 보고이며 보편적 규칙이 아닙니다.

조건 D: 모델 연결만 변경

Native label만으로 두 번째 connection을 deferred compatibility control로 인정할 수 없습니다. 정확한 Model ID, 실제 provider/gateway, Base URL 또는 route, Open WebUI version을 기록합니다. Tool Search를 Off로 한 상태에서 같은 read-only 도구로 A baseline을 먼저 실행하고 필요하면 B도 실행합니다. 일반 경로와 Always Loaded가 통과한 뒤에만 tool, prompt, UI 값, threshold, 비어 있는 Always Loaded를 바꾸지 않고 C를 D로 반복합니다.

• D 통과, C 실패: 원래 model route가 차이입니다. 일반 채팅용으로 유지하고 deferred-tool 작업은 검증된 route를 사용합니다.
• 두 번째 connection이 A 또는 B 실패: 아직 유효한 control이 아닙니다. baseline을 먼저 수정하거나 교체합니다.
• 두 connection 모두 A/B 통과, C/D 실패: 두 실제 backend/route 모두 설치 version의 deferred flow를 지원하지 않을 수 있다는 분기를 유지합니다. 다른 model 이름도 같은 strict provider, gateway, router를 공유할 수 있습니다. 실제 route와 version을 확인하고 search_tools 성공 여부와 대상 call 유무에 따라 다음 단계를 정하세요. 결과를 설정, 이름, 실행 문제로만 단정하지 마세요.
• C/D 통과: production tool의 visible definition, operation 선택, arguments, 권한, server가 더 유력합니다.

증거에 따라 가장 작은 수정 선택

증거	다음 단계
A 실패, 대상 call 없음	접근, chat tool toggle, Native 또는 실제 native call 지원 backend 수정
A/B 통과, C에 search_tools 없음	실제 UI 값, threshold, version, helper 선택 능력 확인
search_tools 성공, 대상 call 없음	capability, visible name/schema, 실제 route, version, compatibility 확인. 최소 fallback은 Always Loaded 또는 Tool Search Off
대상 call은 있지만 reverse_string 미실행	Open WebUI logs와 call_tool target/arguments 확인
A–C 통과, production tool 실패	model-visible definition, operation, arguments, Tool Search 처리, route, access, server evidence 확인
검증된 connection 하나만 실패	text용으로 유지하고 같은 A/B/C를 통과한 connection을 tool용으로 사용
검증된 두 connection 모두 C/D 실패	두 backend 또는 공유 route 비호환 분기를 유지하고 search_tools, 대상 call, route, version 비교

도구가 적다면 실험적인 Tool Search를 끄는 것이 가장 단순하고 안정적입니다. 큰 schema가 많다면 자주 쓰고 위험이 낮은 도구를 Always Loaded로 두고 각 connection을 따로 검증하세요.

로컬 기준선 통과 후 MCP/OpenAPI 확인

reverse_string 성공은 이 route가 단일 string의 단순한 Workspace schema를 호출할 수 있다는 뜻뿐입니다. 같은 모델이 복잡한 외부 도구, 올바른 operation, 유효한 arguments, multi-step workflow까지 처리한다는 뜻은 아닙니다. Open WebUI의 MCP/OpenAPI 문서도 connection이 작동해도 이러한 model limitation을 명시합니다.

server 진단 전에 모델이 실제로 보는 production tool definition과 대상 call 증거를 확보합니다.

• 대상 call 없음, operation 오선택, arguments 오류: model capability, tool name/description/schema, Tool Search, 실제 model/provider route 분기를 유지합니다.
• 올바른 구조화 call은 생성됐지만 server에 도달하지 않거나 transport/auth error: URL, access control, authentication, protocol, proxy, TLS, server를 확인합니다.
• server가 올바른 operation을 받았지만 arguments 거부 또는 application error: call을 노출된 schema와 비교하고 server 처리를 확인합니다.

MCP: transport, 권한, 표시 이름

Open WebUI native MCP connection은 MCP (Streamable HTTP)를 사용합니다. stdio만 제공하는 local server는 적절한 bridge/proxy가 필요합니다.

확인 사항:

• Type이 MCP이고 OpenAPI가 아님
• Streamable HTTP URL이 Open WebUI host/container에서 접근 가능
• authentication이 현재 사용자에게 유효
• Access Control에 테스트 사용자가 포함됨
• model-visible 전체 definition과 name이 <server ID>_<tool name> 형식
• 모델이 올바른 target과 유효한 arguments를 선택함
• 올바른 call이 MCP server logs에 도달함
• protocol result이며 HTTP/auth/application error가 아님

올바른 대상 call이 없으면 model/schema/Tool Search/route 분기에 남습니다. call은 있지만 server에 도달하지 않으면 URL, proxy, certificate, network를 확인합니다. server가 올바른 operation을 받았지만 arguments를 거부하면 모델에 보인 schema와 비교합니다.

OpenAPI: operation discovery 검증

Open WebUI는 OpenAPI 3.x path-item 구조에서 operation을 발견합니다. 표준 HTTP method, 사용 가능한 parameter, 대상 operation을 구분할 수 있는 안정적인 name/description을 확인합니다.

저장할 항목:

• spec URL과 tested version
• Open WebUI가 모델에 실제 노출한 tool names/definitions
• 모델이 선택한 operation과 구조화 arguments
• server access log와 response status
• Open WebUI가 모델에 돌려준 body

connection 저장은 실행 증거가 아닙니다. /models verification 실패도 자동으로 비호환을 뜻하지 않습니다. 표준 /models를 구현하지 않는 compatible provider도 있습니다. 정확한 Model ID를 입력하고 A/B/C 및 production tool의 실제 call로 판단하세요.

BetterToken 비교 연결을 추가하는 경우

원래 연결을 유지하고 OpenAI-compatible 비교 연결을 추가할 수 있습니다. BetterToken API Base URL:

https://www.bettertoken.ai/v1

현재 카탈로그에서 supported_endpoint_types에 openai가 포함된 정확한 Model ID를 선택하고 자신의 API key를 사용하세요. 표시 이름으로 ID를 추측하지 마세요. 일반 chat 성공은 Tool Search 호환 증거가 아닙니다.

이 연결에서도 A–D를 실행합니다. 여기서 BetterToken은 다른 모델 API 경로와 request usage 관찰 수단일 뿐, Open WebUI·모델·Tool Search 수정 보장이 아닙니다.

참고:

• Open WebUI Tools
• Workspace Tool development
• OpenAI-compatible connections
• Open WebUI MCP
• OpenAPI Tool Servers
• BetterToken Chat Completions
• BetterToken model protocol catalog

재현 가능한 진단 기록 남기기

Open WebUI version:
Deployment:
Connection:
Exact model ID:
Actual provider/gateway route:
Function Calling:
Builtin Tools capability/categories:
Tool Search UI value:
Defer Built-in Tools UI value:
Deferral Threshold UI value:
Always Loaded Tools UI value:
ENABLE_PERSISTENT_CONFIG mode:
ENABLE_TOOL_SEARCH:
TOOL_SEARCH_DEFER_BUILTIN_TOOLS:
TOOL_SEARCH_DEFER_THRESHOLD:
TOOL_SEARCH_ALWAYS_LOADED:
Tool visible name:
Prompt:
search_tools call observed:
target call_tool / structured invocation observed:
reverse_string execution log observed:
Returned value:
Timestamp:

Open WebUI 업데이트, 모델 변경, 서버 이전 후 같은 기록을 회귀 테스트로 사용할 수 있습니다.

첫 단계

연결을 삭제하거나 MCP 전체를 다시 만들기 전에 현재 채팅을 Native로 두고 Tool Search를 끈 상태에서 tool-check-7을 reverse_string으로 처리하세요. 구조화 call, 실행 로그, 7-kcehc-loot이 모두 확인된 뒤에만 강제 지연과 다른 연결을 비교합니다.

이렇게 하면 모델의 본문 주장에 의존하지 않고 권한, 모드, Tool Search, 모델 backend, MCP/OpenAPI 실행 중 어디를 최소한으로 고쳐야 하는지 판단할 수 있습니다.