채팅 도구

채팅에서 모델이 도구를 호출하도록 허용할 수 있습니다. 도구를 활성화한 턴은 네이티브 다중 라운드 루프를 실행합니다. 모델이 도구를 요청하면 Libre WebUI가 호출 사용자의 신원과 권한으로 실행하고, 결과를 모델에 돌려보내며, 모델이 답할 때까지 계속합니다. 턴당 최대 8라운드, 라운드당 최대 8회 호출입니다. 중지를 누르면 모델 호출, 진행 중인 도구 호출, 보류 중인 승인 대기가 모두 취소됩니다.

도구 호출은 정규화 이벤트(chat.tool-call.v1, chat.tool-result.v1, chat.approval.v1)로 기록됩니다. 비공개 WebSocket 경로와 영구 이벤트 스트림에서 동일하게 흐르므로 새로 고침 또는 재연결 후에도 같은 상태가 재생됩니다. 완료된 턴은 결과 미리보기를 제한해 호출 내역을 어시스턴트 메시지에 저장합니다.

도구 활성화

도구는 기본적으로 꺼져 있습니다. 관리자가 설정 → 사용자 관리에서 관리자 전용 또는 모든 사용자에게 열 수 있습니다. 이후 각 턴은 작성기의 렌치 버튼으로 명시적으로 활성화합니다. 선택기에는 전체 스위치와 내장 도구 및 등록 서버별 확인란이 있어 정확히 선택한 도구만 해당 턴에서 실행됩니다. 선택기는 프로필에 연결된 범위를 좁힐 수만 있고 넓힐 수 없습니다. 비공개(시크릿) 채팅은 도구를 제공하지 않습니다. 도구 호출은 외부 작업이며 승인 및 감사 기록을 남길 수 있기 때문입니다.

어시스턴트 프로필(페르소나)은 제공 도구의 범위를 제한할 수 있습니다. 연결된 도구 서버, 내장 도구 일부, 연결된 스킬, 연결된 지식 컬렉션이 해당 프로필을 사용하는 세션에서 모델에 보이는 항목을 제한합니다.

내장 도구

채팅에는 자사 도구 13개가 포함됩니다. 노트 및 캘린더 변경 도구를 제외하면 모두 읽기 전용이며, 변경 도구는 부작용 승인 흐름을 거칩니다.

• web_search — 관리자가 설정한 검색 엔진. 웹 검색 접근 모드를 준수합니다.
• search_documents — 사용자 업로드 문서와 공유받은 컬렉션을 포함한 지식 컬렉션의 하이브리드 검색. 프로필 연결이 컬렉션 범위를 제한할 수 있으며, 각 구절에 청크와 출처 위치가 인용됩니다.
• list_documents — 이 채팅 범위의 문서를 ID, 유형, 크기와 함께 나열해 모델이 읽을 내용을 정할 수 있게 합니다.
• read_document — 검색만으로 답할 수 없는 파일을 순차적으로 살필 수 있도록, ID와 오프셋으로 사용 가능한 문서의 제한된 창을 출처 위치와 함께 읽습니다.
• load_skill — 슬러그로 스킬의 전체 지침을 불러옵니다. 도구 설명에는 사용자가 활성화한 스킬의 매니페스트가 있어 모델이 필요로 할 때까지 지연 로드됩니다. 스킬에 보조 파일이 있으면 불러온 지침 끝에 파일 목록이 추가됩니다.
• read_skill_file — 스킬에 포함된 보조 파일 하나를 슬러그와 상대 경로로 읽습니다. 큰 참고 문서는 모델이 실제로 열 때만 문맥을 사용합니다.
• list_notes — 사용자의 노트와 공유 노트를 ID와 함께 나열합니다.
• read_note — ID로 노트 전체 내용을 읽습니다.
• create_note — 노트를 생성합니다(부작용, 승인 필요).
• update_note — 노트 내용을 교체하고 이전 상태를 복원 가능한 버전으로 보관합니다. 모델 편집을 언제나 되돌릴 수 있습니다(부작용, 승인 필요).
• list_calendar_events — epoch-millisecond 범위에서 사용자의 소유 및 공유 캘린더 이벤트를 나열합니다.
• create_calendar_event — 캘린더 이벤트를 생성합니다(부작용, 승인 필요).
• delete_calendar_event — ID로 캘린더 이벤트 하나를 삭제합니다(부작용, 승인 필요).

도구 서버

관리자는 설정 → 도구에서 외부 도구 서버를 등록합니다. 시작 템플릿은 안전한 공개 데모 API를 포함해 양식을 미리 채웁니다.

• OpenAPI: JSON OpenAPI 3.x 사양을 한 번 가져와 SHA-256 다이제스트로 고정합니다. 각 작업이 도구가 됩니다. 관리자가 도구별 분류를 재정의하기 전까지 GET 작업은 읽기 전용, 나머지는 부작용으로 분류됩니다. 실행은 고정된 작업에서 호출을 재구성하므로 모델 인수가 목적지를 선택할 수 없습니다.
• MCP (Streamable HTTP): JSON-RPC를 통해 서버 도구 목록을 가져와 같은 방식으로 고정합니다. annotations.readOnlyHint가 도구를 읽기 전용으로 표시합니다. stdio MCP 서버는 의도적으로 지원하지 않습니다. 외부 프로세스가 웹 프로세스 안에서 실행되지 않습니다.

변경된 목록은 관리자가 서버를 새로 고쳐 고정 버전을 올린 뒤에만 적용되며, 도구별 재정의는 유지됩니다. 서버별 사용 가능 범위는 관리자 전용, 모든 사용자 또는 도구 서버의 사용자·그룹에 공통 리소스 권한을 부여하는 방식입니다.

자격 증명

인증이 필요한 서버는 사용자별 자격 증명(Bearer 토큰 또는 이름 있는 헤더)을 사용합니다. 각 시크릿은 정확한 사용자와 서버를 묶는 추가 인증 데이터로 암호화됩니다. 각 사용자가 설정 → 도구에서 입력하며 계정 간에 공유되지 않습니다.

외부 통신 정책

각 도구 요청은 목적지를 직접 해석하고, 사설·루프백·메타데이터 주소 공간을 거부하며, DNS 재바인딩으로 호출을 돌릴 수 없도록 해석된 주소에 연결을 고정합니다. 리디렉션 응답은 거부합니다. 응답 크기는 제한되고 모든 호출에 강제 타임아웃이 적용됩니다. 정확한 내부 호스트 이름은 TOOLS_PRIVATE_NETWORK_ALLOWLIST(쉼표로 구분)로 허용할 수 있습니다. 허용된 호스트도 고정 및 크기 제한을 유지합니다. 도구 출력은 신뢰할 수 없는 텍스트로 모델에 다시 들어갑니다.

승인

읽기 전용 도구는 묻지 않고 실행됩니다. 부작용이 있는 도구는 턴을 일시 중지하고 사용자에게 이번만 허용, 이 채팅에서 허용, 이 서버의 이 도구를 항상 허용 또는 거부를 요청합니다. 결정은 영구적입니다. "항상" 권한은 재시작 후에도 유지되고 설정 → 도구에서 취소할 수 있습니다. 보류 요청은 2분 후 만료되며 모델에는 거부로 전달됩니다. 거부와 타임아웃에서는 호출을 실행하지 않습니다. 모든 결정과 호출은 민감 정보를 제거한 보안 감사 이벤트를 남깁니다.

예시

먼저 작성기에서 렌치 스위치를 켭니다. 아래 예시는 모두 일반 채팅 메시지입니다.

web_search — 정보 검색

최신 SQLite 릴리스에서 무엇이 바뀌었나요? 답하기 전에 웹을 검색하세요.

모델은 {"query": "SQLite latest release changelog"} 같은 쿼리로 web_search를 호출합니다. 호출 카드에는 받은 결과의 발췌문이 표시되고 답변은 찾은 내용을 인용합니다. 웹 검색이 설정되고 계정에 허용되어야 합니다.

search_documents — 내 파일에 질문

PDF를 업로드하거나 지식 컬렉션에 문서를 추가한 뒤:

내 문서에서 해지 조항을 찾아 정확히 인용하세요.

모델은 {"query": "termination clause"}로 search_documents를 호출하고 출처 문서가 표시된 일치 구절을 받으므로 답변에서 인용하고 출처를 밝힐 수 있습니다.

load_skill — 저장된 스킬 적용

설정 → 스킬에서 스킬을 만듭니다(예: $release-notes — 원하는 릴리스 노트 작성 방식). 그런 다음:

이 차이를 바탕으로 $release-notes를 사용해 릴리스 노트를 작성하세요.

모델은 매니페스트에서 스킬을 확인하고 load_skill {"slug": "release-notes"}을 호출해 전체 지침을 가져와 따릅니다. 작성기에 $를 입력하면 스킬 슬러그를 자동 완성합니다.

OpenAPI 서버 — 날씨 API 예시

1. 설정 → 도구 → 서버 등록: 이름 Weather, 종류 OpenAPI, 기본 URL https://api.example-weather.dev, 사양 URL https://api.example-weather.dev/openapi.json, 인증 모드 bearer.

2. 사양이 고정되고 작업이 도구로 표시됩니다. 예를 들어 getForecast(GET, 읽기 전용), createAlert(POST, 부작용).

3. 사용하려는 각 사용자가 서버 카드에 자신의 API 키를 저장합니다.

4. 채팅에서:

   이번 주말 몬트리올의 일기 예보는 어떤가요?

   모델이 weather__getForecast {"city": "Montreal"}을 호출하면 즉시 실행됩니다. 읽기 전용 도구는 묻지 않습니다.

   오늘 밤 -20 아래로 내려가면 알려 주세요.

   weather__createAlert는 부작용이 있으므로 승인 카드와 함께 턴이 일시 중지됩니다. 이번만 허용, 이 채팅에서 허용, 항상 허용, 거부 중에서 선택할 때까지 아무것도 전송되지 않습니다.

MCP 서버 — 이슈 추적기 예시

1. 설정 → 도구 → 서버 등록: 이름 Issues, 종류 MCP, 기본 URL https://mcp.example-tracker.dev/mcp, 인증 모드 header, 헤더 이름 X-Api-Key.

2. 도구 목록이 고정됩니다. 서버가 읽기 전용으로 표시한 search_issues 같은 도구는 바로 실행되고, create_issue 같은 나머지 도구는 먼저 묻습니다.

3. 채팅에서:

   "database lock"을 언급한 열린 이슈를 찾고 패턴을 요약하는 새 이슈를 등록하세요.

   issues__search_issues는 즉시 실행됩니다. issues__create_issue는 승인 카드에 정확한 인수를 표시하므로 허용하기 전에 등록될 내용을 읽을 수 있습니다.

환경 변수

변수	효과
TOOLS_ACCESS_MODE	도구 기능을 admins 또는 all-users로 고정하고 관리자 스위치를 잠급니다.
TOOLS_PRIVATE_NETWORK_ALLOWLIST	도구 서버가 사설 주소로 해석할 수 있는 정확한 호스트 이름(쉼표 목록).

경계

• 도구 호출은 WebSocket 경로(비공개 세션 전송은 의도적으로 제외)와 영구 채팅에 사용하는 영구 생성 경로에서 실행됩니다. 기존 REST 스트리밍 엔드포인트는 도구 루프를 실행하지 않습니다.
• Work 에이전트도 같은 게이트웨이를 통해 같은 서버를 호출합니다. 네트워크가 활성화된 실행에만 제공되고, 자격 증명이 없는 서버는 제공 시점에 걸러지며, 부작용이 있는 도구는 Work 승인의 통제를 받습니다.
• Gemini 및 agent CLI 모델에는 도구가 전달되지 않습니다. Ollama, OpenAI 호환, Responses-API, Anthropic 제공자는 도구를 받습니다.
• MCP 서버는 정적 사용자별 자격 증명으로 인증합니다. 대화형 OAuth만 지원하는 MCP 서버는 아직 등록할 수 없습니다.