From 9d7f6db92d74b5ca77fe1e3cbb37f4c307e7375a Mon Sep 17 00:00:00 2001 From: Jakob Gruber <27028174+Classic298@users.noreply.github.com> Date: Tue, 24 Mar 2026 11:30:16 +0100 Subject: [PATCH] builtin tools and new env vars --- docs/features/ai-knowledge/knowledge.md | 24 +++++- .../extensibility/plugin/tools/index.mdx | 86 +++++++++---------- docs/reference/env-configuration.mdx | 45 +++++++++- docs/troubleshooting/connection-error.mdx | 2 + docs/troubleshooting/sso.mdx | 10 +++ 5 files changed, 117 insertions(+), 50 deletions(-) diff --git a/docs/features/ai-knowledge/knowledge.md b/docs/features/ai-knowledge/knowledge.md index 136edb9f..e02fd685 100644 --- a/docs/features/ai-knowledge/knowledge.md +++ b/docs/features/ai-knowledge/knowledge.md @@ -49,8 +49,8 @@ Autonomous knowledge base exploration works best with frontier models (GPT-5, Cl ::: - **`list_knowledge`**: List all knowledge bases, files, and notes attached to the current model with file details. **Use this first** to discover what knowledge is available. Only available when the model has attached knowledge. -- **`query_knowledge_files`**: Search file contents using vector search (with hybrid search and reranking when enabled in admin settings). When a KB is attached to the model, searches are automatically scoped. This should be the model's first choice for finding information before searching the web. -- **`search_knowledge_files`**: Search files by filename. Auto-scopes to attached KBs when the model has attached knowledge. +- **`query_knowledge_files`**: Search file contents using retrieval over the configured RAG pipeline (including hybrid search/reranking when `ENABLE_RAG_HYBRID_SEARCH` is enabled). When a KB is attached to the model, searches are automatically scoped. This should be the model's first choice for finding information before searching the web. +- **`search_knowledge_files`**: Search files by filename. Available in both modes; auto-scopes to attached KBs when the model has attached knowledge. - **`list_knowledge_bases`**: Browse available knowledge bases with file counts. Only available when the model has **no** attached knowledge. - **`search_knowledge_bases`**: Find specific knowledge bases by name or description. Only available when the model has **no** attached knowledge. - **`query_knowledge_bases`**: Search KB names/descriptions by semantic similarity. Only available when the model has **no** attached knowledge. @@ -67,6 +67,22 @@ When native function calling is enabled, the model's access to knowledge bases d | **No KB attached** | Model can access **all** knowledge bases the user has access to (public KBs, user's own KBs) | | **KB attached to model** | Model is **limited** to only the attached knowledge base(s) | +Knowledge tool availability at a glance: + +| Tool | Model has attached knowledge | Model has no attached knowledge | +|------|------------------------------|---------------------------------| +| `list_knowledge` | ✅ | ❌ | +| `list_knowledge_bases` | ❌ | ✅ | +| `search_knowledge_bases` | ❌ | ✅ | +| `query_knowledge_bases` | ❌ | ✅ | +| `search_knowledge_files` | ✅ (auto-scoped) | ✅ (all accessible KBs) | +| `query_knowledge_files` | ✅ (auto-scoped) | ✅ | +| `view_file` | ✅ (when attached items include files/collections) | ❌ | +| `view_knowledge_file` | ✅ (when attached items include files/collections) | ✅ | +| `view_note` | ✅ (when attached items include notes) | ❌ | + +Quick rule: `list_knowledge` and `list_knowledge_bases` are mutually exclusive. + :::warning Knowledge is NOT Auto-Injected with Native Function Calling **Important behavioral difference:** When using Native Function Calling, attached knowledge is **not automatically injected** into the conversation. Instead, the model must actively call the knowledge tools to search and retrieve information. @@ -74,7 +90,7 @@ When native function calling is enabled, the model's access to knowledge bases d **If your model isn't using attached knowledge:** 1. **Add instructions to your system prompt** telling the model to discover and query knowledge bases. For example: - > "When users ask questions, first use list_knowledge to see what knowledge is available, then use query_knowledge_files to search the relevant knowledge base before answering." + > "When users ask questions, first use list_knowledge to see what knowledge is available, then use query_knowledge_files to search the relevant knowledge base before answering. If no knowledge is attached to this model, use list_knowledge_bases first to discover available KBs." 2. **Or disable Native Function Calling** for that model to restore the automatic RAG injection behavior from earlier versions. @@ -94,7 +110,7 @@ When attaching files, notes, or knowledge bases to a model, you can choose betwe - Uses **RAG (Retrieval Augmented Generation)** to find relevant chunks - Only injects the most relevant portions of documents based on the user's query -- When **hybrid search** is enabled (`ENABLE_RAG_HYBRID_SEARCH`), retrieval uses BM25 keyword search combined with vector search, plus reranking for improved accuracy — this applies to both the standard RAG pipeline and the native knowledge tools +- When **hybrid search** is enabled (`ENABLE_RAG_HYBRID_SEARCH`), retrieval uses BM25 keyword search combined with vector search, plus reranking for improved accuracy — this applies to both the standard RAG pipeline and native knowledge tool retrieval paths - Best for large documents or knowledge bases where only specific sections are relevant - With native function calling enabled, the model decides when to search diff --git a/docs/features/extensibility/plugin/tools/index.mdx b/docs/features/extensibility/plugin/tools/index.mdx index 519f7328..13fb99e8 100644 --- a/docs/features/extensibility/plugin/tools/index.mdx +++ b/docs/features/extensibility/plugin/tools/index.mdx @@ -206,14 +206,14 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `search_web` | Search the public web for information. Best for current events, external references, or topics not covered in internal documents. | | `fetch_url` | Visits a URL and extracts text content via the Web Loader. | | **Knowledge Base** | *Requires per-model "Knowledge Base" category enabled (default: on). Which tools are injected depends on whether the model has attached knowledge — see note below.* | -| `list_knowledge` | List all knowledge bases, files, and notes attached to the current model. **Use this first** to discover what knowledge is available. When no knowledge is attached, this tool is not available — use the browsing tools instead. | -| `list_knowledge_bases` | List the user's accessible knowledge bases with file counts. Only available when the model has **no** attached knowledge. | -| `query_knowledge_bases` | Search KB *names and descriptions* by semantic similarity. Use to find which KB is relevant when you don't know which one to query. Only available when the model has **no** attached knowledge. | -| `search_knowledge_bases` | Search knowledge bases by name/description (text match). Only available when the model has **no** attached knowledge. | -| `query_knowledge_files` | Search *file contents* inside KBs using vector search (with hybrid search and reranking when enabled). **This is your main tool for finding information.** When a KB is attached to the model, searches are automatically scoped to that KB. | -| `search_knowledge_files` | Search files by filename. When the model has attached knowledge, searches are automatically scoped to attached KBs and files. When no knowledge is attached, searches all accessible KBs. | -| `view_file` | Read the content of any user-accessible file by its ID. Supports pagination for large files via `offset` and `max_chars` parameters. Only injected when the model has attached knowledge files. | -| `view_knowledge_file` | Read the content of a file from a knowledge base. Supports pagination for large files via `offset` and `max_chars` parameters. | +| `list_knowledge` | List attached knowledge (KBs, files, notes). Start here when attachments exist. | +| `list_knowledge_bases` | List accessible knowledge bases with file counts. | +| `query_knowledge_bases` | Semantic search over KB names/descriptions to find the right KB. | +| `search_knowledge_bases` | Text search over KB names/descriptions. | +| `query_knowledge_files` | Search file contents via the RAG retrieval pipeline (hybrid + rerank when enabled). Main tool for finding answers in docs. | +| `search_knowledge_files` | Search files by filename. | +| `view_file` | Read a user-accessible file by ID with pagination (`offset`, `max_chars`). | +| `view_knowledge_file` | Read a knowledge-base file by ID with pagination (`offset`, `max_chars`). | | **Image Gen** | *Requires image generation enabled (per-tool) AND per-chat "Image Generation" toggle enabled.* | | `generate_image` | Generates a new image based on a prompt. Requires `ENABLE_IMAGE_GENERATION`. | | `edit_image` | Edits existing images based on a prompt and image URLs. Requires `ENABLE_IMAGE_EDIT`. | @@ -239,11 +239,29 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `view_channel_message` | View a specific message or its details in a channel. | | `view_channel_thread` | View a full message thread/replies in a channel. | | **Skills** | *Requires at least one skill to be attached to the model via **Workspace/Admin Panel → Models → Edit → Skills**. The model receives a summary of attached skills in its system prompt and can call `view_skill` to load full instructions on demand. No separate builtin tools category checkbox is needed — attaching a skill is the only requirement.* | -| `view_skill` | Load the full instructions of a skill by name. Only skills attached to the current model (via the Model Editor's Skills selector) are accessible. | +| `view_skill` | Load the full instructions of a skill by name. The tool is injected when skills are attached; resolving a skill still follows normal ownership/access-grant checks. | | **Time Tools** | *Requires per-model "Time & Calculation" category enabled (default: on).* | | `get_current_timestamp` | Get the current UTC Unix timestamp and ISO date. | | `calculate_timestamp` | Calculate relative timestamps (e.g., "3 days ago"). | +#### Knowledge Tool Availability (At a Glance) + +Use this quick matrix instead of memorizing per-row caveats. + +| Tool | Model has attached knowledge | Model has no attached knowledge | +|------|------------------------------|---------------------------------| +| `list_knowledge` | ✅ | ❌ | +| `list_knowledge_bases` | ❌ | ✅ | +| `search_knowledge_bases` | ❌ | ✅ | +| `query_knowledge_bases` | ❌ | ✅ | +| `search_knowledge_files` | ✅ (auto-scoped) | ✅ (all accessible KBs) | +| `query_knowledge_files` | ✅ (auto-scoped) | ✅ | +| `view_file` | ✅ (when attached items include files/collections) | ❌ | +| `view_knowledge_file` | ✅ (when attached items include files/collections) | ✅ | +| `view_note` | ✅ (when attached items include notes) | ❌ | + +Quick rule: `list_knowledge` and `list_knowledge_bases` are mutually exclusive. + #### Tool Reference | Tool | Parameters | Output | @@ -256,7 +274,7 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `list_knowledge_bases` | `count` (default: 10), `skip` (default: 0) | Array of `{id, name, description, file_count}` | | `query_knowledge_bases` | `query` (required), `count` (default: 5) | Array of `{id, name, description}` by similarity | | `search_knowledge_bases` | `query` (required), `count` (default: 5), `skip` (default: 0) | Array of `{id, name, description, file_count}` | -| `query_knowledge_files` | `query` (required), `knowledge_ids` (optional), `count` (default: 5) | Array of `{id, filename, content_snippet, knowledge_id}` | +| `query_knowledge_files` | `query` (required), `knowledge_ids` (optional), `count` (default: 5) | Array of chunks like `{content, source, file_id, distance?}`; note hits include `{note_id, type: "note"}` | | `search_knowledge_files` | `query` (required), `knowledge_id` (optional), `count` (default: 5), `skip` (default: 0) | Array of `{id, filename, knowledge_id, knowledge_name}` | | `view_file` | `file_id` (required), `offset` (default: 0), `max_chars` (default: 10000, cap: 100000) | `{id, filename, content, updated_at, created_at}` — includes `truncated`, `total_chars`, `next_offset` when paginated | | `view_knowledge_file` | `file_id` (required), `offset` (default: 0), `max_chars` (default: 10000, cap: 100000) | `{id, filename, content, knowledge_id, knowledge_name}` — includes pagination metadata when truncated | @@ -264,7 +282,7 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `generate_image` | `prompt` (required) | `{status, message, images}` — auto-displayed | | `edit_image` | `prompt` (required), `image_urls` (required) | `{status, message, images}` — auto-displayed | | **Code Interpreter** | | | -| `execute_code` | `language` (required), `code` (required) | `{output, status}` | +| `execute_code` | `code` (required) | `{status, stdout, stderr, result}` | | **Memory** | | | | `search_memories` | `query` (required), `count` (default: 5) | Array of `{id, date, content}` | | `add_memory` | `content` (required) | `{status: "success", id}` | @@ -280,10 +298,10 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo | `search_chats` | `query` (required), `count` (default: 5), `start_timestamp`, `end_timestamp` | Array of `{id, title, snippet, updated_at}` | | `view_chat` | `chat_id` (required) | `{id, title, messages: [{role, content}]}` | | **Channels** | | | -| `search_channels` | `query` (required), `count` (default: 5) | Array of `{id, name, description}` | -| `search_channel_messages` | `query` (required), `count` (default: 10), `start_timestamp`, `end_timestamp` | Array of `{id, channel_id, content, user_name, created_at}` | +| `search_channels` | `query` (required), `count` (default: 5) | Array of `{id, name, description, type}` | +| `search_channel_messages` | `query` (required), `count` (default: 10), `start_timestamp`, `end_timestamp` | Array of `{channel_id, channel_name, message_id, content_snippet, is_thread_reply, parent_id, created_at}` | | `view_channel_message` | `message_id` (required) | `{id, content, user_name, created_at, reply_count}` | -| `view_channel_thread` | `parent_message_id` (required) | Array of `{id, content, user_name, created_at}` | +| `view_channel_thread` | `parent_message_id` (required) | `{channel_id, channel_name, thread_id, message_count, messages: [...]}` | | **Skills** | | | | `view_skill` | `name` (required) | `{name, content}` | | **Time Tools** | | | @@ -294,34 +312,12 @@ These models excel at multi-step reasoning, proper JSON formatting, and autonomo Open WebUI automatically detects and stores your timezone when you log in. This allows time-related tools and features to provide accurate local times without any manual configuration. Your timezone is determined from your browser settings. ::: -:::warning Knowledge Tools Change Based on Attached Knowledge -The set of knowledge tools injected into a model **changes depending on whether the model has knowledge attached** (via the Model Editor). The model gets different tool sets — one for scoped access, one for open exploration. +:::warning Knowledge Tool Injection Depends on Attachments +Knowledge tool availability changes based on whether the model has attached knowledge. Use the **Knowledge Tool Availability** matrix above as the source of truth. -**Model with attached knowledge** (files, collections, or notes): - -| Tool | When Available | -|------|---------------| -| `list_knowledge` | Always — lists all attached KBs, files, and notes with file details | -| `search_knowledge_files` | Always — auto-scoped to attached KBs and files | -| `query_knowledge_files` | Always — auto-scoped to attached KBs | -| `view_file` | When attached knowledge includes files or collections | -| `view_knowledge_file` | When attached knowledge includes files or collections | -| `view_note` | When attached knowledge includes notes | - -The model **does not** get the browsing tools (`list_knowledge_bases`, `search_knowledge_bases`, etc.) because it doesn't need to discover KBs — the search is automatically scoped to its attachments. Use `list_knowledge` to see what's available. - -**Model without attached knowledge** (general-purpose): - -| Tool | Purpose | -|------|---------| -| `list_knowledge_bases` | Discover available KBs | -| `search_knowledge_bases` | Search KBs by name/description (text match) | -| `query_knowledge_bases` | Search KBs by name/description (semantic similarity) | -| `search_knowledge_files` | Search files by filename (all accessible KBs) | -| `query_knowledge_files` | Search file contents (vector search) | -| `view_knowledge_file` | Read a file from a KB (with pagination) | - -This model has the full browsing set to autonomously discover and explore any KB the user has access to. +- With attachments: the model gets scoped knowledge tools. +- Without attachments: the model gets KB discovery tools. +- `list_knowledge` and `list_knowledge_bases` are mutually exclusive. ::: :::caution Attached Knowledge Still Requires User Access @@ -362,7 +358,7 @@ The native `query_knowledge_files` tool uses **hybrid search + reranking** when **Important:** When using Native Function Calling, attached knowledge is **not automatically injected** into the conversation. The model must actively call knowledge tools to search and retrieve information. **If your model isn't using attached knowledge:** -1. **Add instructions to your system prompt** telling the model to discover and query knowledge bases. Example: *"When users ask questions, first use list_knowledge to see what knowledge is available, then use query_knowledge_files to search the relevant knowledge base before answering."* +1. **Add instructions to your system prompt** telling the model to discover and query knowledge bases. Example: *"When users ask questions, first use list_knowledge to see what knowledge is available, then use query_knowledge_files to search the relevant knowledge base before answering. If no knowledge is attached to this model, use list_knowledge_bases first to discover available KBs."* 2. **Or disable Native Function Calling** for that model to restore automatic RAG injection. 3. **Or use "Full Context" mode** for attached knowledge (click on the attachment and select "Use Entire Document") which always injects the full content. @@ -402,7 +398,7 @@ When the **Builtin Tools** capability is enabled, you can further control which | **Memory** | `search_memories`, `add_memory`, `replace_memory_content`, `delete_memory`, `list_memories` | Search and manage user memories | | **Chat History** | `search_chats`, `view_chat` | Search and view user chat history | | **Notes** | `search_notes`, `view_note`, `write_note`, `replace_note_content` | Search, view, and manage user notes | -| **Knowledge Base** | `list_knowledge` / `list_knowledge_bases`, `search_knowledge_bases`, `query_knowledge_bases`, `search_knowledge_files`, `query_knowledge_files`, `view_file`, `view_knowledge_file` | Browse and query knowledge bases | +| **Knowledge Base** | `list_knowledge`, `list_knowledge_bases`, `search_knowledge_bases`, `query_knowledge_bases`, `search_knowledge_files`, `query_knowledge_files`, `view_file`, `view_knowledge_file` | Browse and query knowledge bases | | **Web Search** | `search_web`, `fetch_url` | Search the web and fetch URL content | | **Image Generation** | `generate_image`, `edit_image` | Generate and edit images | | **Code Interpreter** | `execute_code` | Execute code in a sandboxed environment | @@ -411,10 +407,10 @@ When the **Builtin Tools** capability is enabled, you can further control which All categories are **enabled by default**. Disabling a category prevents those specific tools from being injected, while keeping other categories active. :::info Skills / view_skill — Not a Category Toggle -The `view_skill` tool does **not** appear in the Builtin Tools category checkboxes. It is injected automatically when at least one skill is **attached to the model** via **Workspace → Models → Edit → Skills**. When skills are attached: +The `view_skill` tool does **not** appear in the Builtin Tools category checkboxes. It is injected when at least one skill is **attached to the model** via **Workspace → Models → Edit → Skills**. When skills are attached: 1. The model receives a summary of each attached skill (name + description) in its system prompt via `` tags -2. The `view_skill` tool is injected so the model can load the full instructions of any attached skill on demand +2. The `view_skill` tool is injected so the model can load full instructions on demand 3. If no skills are attached, `view_skill` is not available Users can also select skills per-chat (via the chat input bar), which injects the skill's full content directly into the system prompt instead of requiring a `view_skill` call. diff --git a/docs/reference/env-configuration.mdx b/docs/reference/env-configuration.mdx index 749bbb84..ec28941a 100644 --- a/docs/reference/env-configuration.mdx +++ b/docs/reference/env-configuration.mdx @@ -633,6 +633,18 @@ See the [Model List Loading Issues](/troubleshooting/connection-error#️-model- - Type: `int` - Description: Sets the timeout in seconds for fetching the model list. This can be useful in cases where network latency requires a longer timeout duration to successfully retrieve the model list. +#### `AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER` + +- Type: `int` +- Default: Inherits `AIOHTTP_CLIENT_TIMEOUT` when unset +- Description: Sets the timeout in seconds for executing tool server API calls (OpenAPI/MCP proxy calls made by Open WebUI). Use this to control how long Open WebUI waits for actual tool execution responses. + +:::info + +If this variable is unset or invalid, Open WebUI falls back to `AIOHTTP_CLIENT_TIMEOUT`. + +::: + #### `AIOHTTP_CLIENT_SESSION_SSL` - Type: `bool` @@ -643,7 +655,7 @@ See the [Model List Loading Issues](/troubleshooting/connection-error#️-model- - Type: `int` - Default: `10` -- Description: Sets the timeout in seconds for retrieving data from tool servers via AIOHTTP client. +- Description: Sets the timeout in seconds for retrieving tool server metadata/configuration (for example, loading server data/spec information). #### `AIOHTTP_CLIENT_SESSION_TOOL_SERVER_SSL` @@ -5205,6 +5217,37 @@ This is useful when you need a JWT access token for downstream validation or whe ::: +#### `OAUTH_AUTHORIZE_PARAMS` + +- Type: `str` (JSON object) +- Default: `{}` +- Description: Passes extra parameters directly to the OAuth provider's authorization endpoint during login. Use this when your provider requires custom authorize-time parameters that are not covered by dedicated variables. + +Common examples include parameters like `prompt`, `login_hint`, `domain_hint`, `resource`, `audience`, or provider-specific flags. + +```bash +# Example (.env) +OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com"} +``` + +```yaml +# Example (docker-compose) +environment: + - OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com"} +``` + +:::warning + +`OAUTH_AUTHORIZE_PARAMS` must be valid JSON and must be a JSON object (key/value map). If parsing fails, Open WebUI ignores it and logs a warning. + +::: + +:::info + +If you set both `OAUTH_AUDIENCE` and `OAUTH_AUTHORIZE_PARAMS` containing an `audience` key, the value from `OAUTH_AUTHORIZE_PARAMS` takes precedence. + +::: + #### `OAUTH_REFRESH_TOKEN_INCLUDE_SCOPE` - Type: `bool` diff --git a/docs/troubleshooting/connection-error.mdx b/docs/troubleshooting/connection-error.mdx index 4536aee5..395b0266 100644 --- a/docs/troubleshooting/connection-error.mdx +++ b/docs/troubleshooting/connection-error.mdx @@ -295,6 +295,8 @@ Manual database manipulation should be a last resort. Always back up your databa | Variable | Default | Description | |----------|---------|-------------| +| `AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER` | Inherits `AIOHTTP_CLIENT_TIMEOUT` | Timeout (seconds) for executing tool server API calls | +| `AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA` | `10` | Timeout (seconds) for loading tool server metadata/spec data | | `AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST` | `10` | Timeout (seconds) for fetching model lists | | `AIOHTTP_CLIENT_TIMEOUT` | `300` | General API request timeout | | `RESET_CONFIG_ON_START` | `false` | Reset database config to env var values on startup | diff --git a/docs/troubleshooting/sso.mdx b/docs/troubleshooting/sso.mdx index 36658ddf..75951819 100644 --- a/docs/troubleshooting/sso.mdx +++ b/docs/troubleshooting/sso.mdx @@ -48,6 +48,10 @@ ENABLE_OAUTH_SIGNUP=true OAUTH_PROVIDER_NAME=Your Provider Name OAUTH_SCOPES=openid email profile OPENID_REDIRECT_URI=https://your-domain/oauth/oidc/callback + +# Optional: pass provider-specific authorize params (JSON object) +# e.g. force consent screen, prefill user/email hint +OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com"} ``` #### ✅ Correct Microsoft Variables: @@ -68,6 +72,12 @@ ENABLE_OAUTH_SIGNUP=true - If self-hosting, confirm these variables are present in your Docker Compose, Kubernetes manifest, or `.env` file - Restart your backend/app after changing variables so the new values are loaded +:::info + +If your provider needs extra parameters at the `/authorize` step (for example `prompt`, `login_hint`, `domain_hint`, or `resource`), set them via `OAUTH_AUTHORIZE_PARAMS` as a JSON object. + +::: + :::tip Most OAUTH errors (loops, 401s, unresponsiveness) are due to an environment variable incorrectly named, missing entirely, or using outdated variable names!