Skip to main content

Essentials for Open WebUI

You have installed Open WebUI, connected a provider, and had your first conversation. This page covers the key things that turn a basic chat UI into a setup that works well day-to-day. None of them are required, but most users end up reaching for all of them within the first week.

Work through in order, or jump to the section you need:

  1. Plugins
  2. Tool Calling
  3. Task models
  4. Context management
  5. Basic RAG
  6. Web Search
  7. Open Terminal
  8. Open WebUI Computer
  9. Troubleshooting
Deploying for a team?

If you are setting up Open WebUI for multiple users, also read the Scaling Open WebUI guide. It covers infrastructure decisions (PostgreSQL, Redis, external vector databases, shared storage) that are separate from the feature-level essentials on this page. The two guides are additive: work through the essentials here for day-to-day usage, and the scaling guide for multi-user infrastructure.

Plugins​

Open WebUI ships with a lot out of the box, but its real power is that it is designed to be extended. Many of the advanced capabilities people show in demos (auto-translation, token/cost tracking, custom post-processing, niche provider integrations) are plugins built on top of the platform. Understanding the plugin landscape is the single biggest unlock for a new user.

There are two plugin families: Tools and Functions.

Tools give the model abilities it can call during a response:

SourceWhat it doesExamples
Built-inSystem tools that ship with Open WebUI. Enable in the admin panel, no install needed.Web Search, Code Interpreter, Image Generation, Memory, Notes, Knowledge retrieval
Custom
  ↳ ToolCode you write yourself or install from the community site. Manage in Workspace > Tools.Langfuse / OpenLit observability, Home Assistant, arXiv / PubMed lookups, Wolfram Alpha, Jira / Linear, SQL queries
  ↳ Tool serverExternal services connected via MCP or OpenAPI. Configure in Settings > Admin > Tools.Your own microservices, third-party APIs, existing MCP servers

Functions run at the platform level and modify how Open WebUI itself behaves. There are three types:

TypeWhat it doesExamples
PipesAdd a new "model" to the model picker, backed by custom codeModel-routing (cheap vs. expensive based on prompt), multi-step agent loops, custom LLM backends
FiltersModify every request and/or response as it passes through, automatically on every chat turnContext trimming, PII scrubbing, token / cost counting, Langfuse tracing, response reformatting
ActionsAdd a button under each message that runs custom code when the user clicks it"Regenerate follow-ups", "Translate reply", "Pin message", "Save to Knowledge"

Installing plugins​

Both Tools and Functions are browsed and installed from the Open WebUI Community site, a one-click catalog of thousands of community-built plugins. Pick one, click "Get", paste it into the admin panel, enable it, and configure its valves (the plugin's settings). You can also write your own from scratch in the admin panel.

New to the catalog? The Community Plugins guide is the beginner's map: how to find a plugin by what you want to do, and how to import it safely. One rule to internalize now: a plugin being featured or popular is not a security or quality review, and plugins run real code on your server, so read the source before you import.

Before you build, browse

Whenever you think "it would be nice if Open WebUI did X," it almost certainly already does via a plugin. There are thousands of plugins already written, and the one you need is usually already there. Even if nothing matches exactly, the closest hit is usually only about 20 lines off from what you want and you can fork it from the admin panel.

Reference reading:

Tool Calling (Native vs Legacy)​

Almost everything else on this page (Web Search, Knowledge retrieval, Memory, Code Interpreter, Open Terminal) reaches the model as a tool it can call mid-answer. One instance-wide switch decides how the model calls those tools, and it changed in v0.10.0.

Native is now the default. Every model that has not explicitly picked a mode uses Native (Agentic) Mode, which relies on the model's own built-in function-calling. This is what lets the model decide on its own when to search the web, look something up in a knowledge base or save a memory, instead of you toggling each tool by hand. It is faster, keeps the KV cache warm and is the only mode that unlocks the built-in system tools (Memory, Notes, Knowledge, Channels, Agentic Research).

Legacy is the opt-out. The old prompt-injection approach (previously called "Default") is renamed Legacy and is unsupported. Any model that depended on the old behavior now runs Native unless you switch it back. If a model struggles with Native, the right fix is a stronger tool-calling model, not Legacy. For reliable tool use, prefer frontier models like GPT-5, Claude 4.5 Sonnet, Gemini 3 Flash or MiniMax M2.5.

More detail, including how to switch one model or your whole instance to Legacy:

Task models​

Good to know

By default, background tasks (titles, tags, autocomplete) use your main chat model. Setting a dedicated task model is the easiest way to improve speed and reduce unnecessary API costs.

Every time Open WebUI needs a short piece of "thinking" for a UI feature (writing a chat title for the sidebar, generating tags, suggesting follow-up questions, powering the autocomplete in the prompt box) it calls a Task Model. By default that task model is whatever main model you are currently chatting with, which means:

  • Your expensive flagship model gets invoked every time you open a new chat just to write "Groceries list."
  • On a slow local model, every keystroke feels laggy because autocomplete is waiting on a 30B-parameter model.
  • A reasoning model (o1, r1, Claude with extended thinking) spends five seconds thinking before producing a three-word title.

These run in the background, so they are easy to overlook. A dedicated task model is a small change that makes a noticeable difference.

Fix: In Settings > Admin > Experience > Interface, set a dedicated Task Model. There are two fields, because the right choice depends on what your main chat model is:

Recommended task models
  • Task Model (External): Set to a fast, cheap, non-reasoning cloud model like gpt-5-nano, gemini-2.5-flash-lite, or llama-3.1-8b-instant.
  • Task Model (Local): Set to a tiny local model like qwen3:1b, gemma3:1b, or llama3.2:3b.

The main chat experience does not change. The background chores just stop dragging.

While you are in the Interface settings, you can also disable these chores entirely if you are on a low-spec machine or simply do not want them. Each one has both an admin toggle in the same page and an environment variable:

ChoreAdmin toggle (Settings > Interface)Env var
Autocomplete (fires on every keystroke)Autocomplete GenerationENABLE_AUTOCOMPLETE_GENERATION=False
Follow-up suggestionsFollow-up GenerationENABLE_FOLLOW_UP_GENERATION=False
Chat title generationTitle GenerationENABLE_TITLE_GENERATION=False
Tag generationTags GenerationENABLE_TAGS_GENERATION=False
Performance on weak hardware

Autocomplete is the single biggest "make it snappy" toggle on weak hardware. It fires on every keystroke, so a slow task model turns the whole prompt box into molasses. Disable it first if the UI feels sluggish.

More detail: Performance & RAM: Dedicated Task Models.

Context management​

After enough back-and-forth you will eventually see:

The prompt is too long: 207601, model maximum context length: 202751

This is not an Open WebUI bug

This error comes from your model provider, not from Open WebUI. Every time you send a message, the entire conversation (system prompt, all previous turns, attached files, tool call results, and your new message) is sent as the "prompt." When the sum exceeds the model's context window, the provider rejects the request.

Open WebUI intentionally does not ship a built-in trimmer, because:

  • Every model uses a different tokenizer (GPT, Claude, Gemini, GLM, Llama all differ).
  • Every model has a different context window (8k to 1M+).
  • Every deployment wants a different policy (trim by tokens, by turns, by message count, drop attachments first, summarize older messages, etc.).

There is no single correct answer. The supported approach is to install a filter Function that trims the conversation on your terms.

Quick fix

Community filters for most common policies already exist and can be installed with one click. If none fits, the code is short enough to copy and adapt. See the full guide including a minimal "newest N turns" filter: Troubleshooting: Context Window / Prompt Too Long.

Basic RAG​

RAG (Retrieval-Augmented Generation) is the feature that lets you say "Here's a 400-page PDF, answer my questions about it" without the model having to read the whole thing every turn. Open WebUI splits your documents into chunks, embeds them as vectors, stores them in a vector database, and at chat time retrieves just the relevant pieces to pass to the model.

Two ways to use it, in order of simplicity:

  1. One-off attachments. Drag a file into any chat input and ask questions. The file is chunked and embedded just for that chat.
  2. Knowledge bases. For documents you want to reuse across many chats (company handbook, codebase, research library, user manual), go to Workspace > Knowledge and create a knowledge base. You can then attach the entire knowledge base to a chat (via the # shortcut in the input), or bind it to a model in Workspace > Models so that model always has it available.

The defaults are reasonable for getting started. When you outgrow them, there are three knobs that matter most:

  • Embedding engine. The default (SentenceTransformers all-MiniLM-L6-v2) runs locally on CPU and consumes roughly 500 MB of RAM per worker. For any multi-user deployment, point at an external embeddings API (OpenAI, or Ollama with nomic-embed-text) via RAG_EMBEDDING_ENGINE.
  • Content extraction engine. The default uses pypdf, which leaks memory during heavy ingestion. For anything beyond casual use, switch to Tika or Docling via CONTENT_EXTRACTION_ENGINE.
  • Vector database. The default ChromaDB (local SQLite-backed) does not tolerate multi-worker deployments. At scale, switch to PGVector. It is the only vector database officially supported and maintained by the Open WebUI team. Milvus, Qdrant, and MariaDB Vector are also available as non-core integrations: they may break on upgrades, and fixes come from outside the core Open WebUI maintenance path. See the env-configuration reference for setup and the integration disclaimers on each provider.
When to worry about this

None of these matter for "a single user with a handful of PDFs." All of them start mattering the moment you have 100 documents or 10 concurrent users.

If you just want RAG to work well out of the box, these settings are a solid general-purpose starting point. They are not fine-tuned for every use case, but they will produce noticeably better results than the defaults for most document types.

Set these in Settings > Admin > Tools > Documents:

SettingDefaultRecommended valueWhy
Text SplittercharactertokenToken-based splitting produces more consistent chunk sizes across document types
Markdown Header SplittingOnOnRespects document structure by splitting at headings, keeping sections coherent
Chunk Size10002000Larger chunks preserve more surrounding context per retrieval hit
Chunk Overlap100200More overlap means less chance of cutting a key sentence in half
Top K315Retrieves more candidate chunks, giving the model a wider pool of relevant context. If you are working with local models that have constrained context sizes, lower this to 5 to avoid filling the context window with retrieved chunks
Embedding Modelall-MiniLM-L6-v2 (local CPU)External (OpenAI or Ollama)The default works for a single user but consumes ~500 MB RAM per worker. For any multi-user setup, use an external embedding API instead
Embedding model

The default SentenceTransformers model runs locally on CPU and is fine for a single user getting started. For anything beyond that, point at an external embeddings API: set RAG_EMBEDDING_ENGINE=openai with an OpenAI API key, or RAG_EMBEDDING_ENGINE=ollama with any Ollama embedding model (e.g., nomic-embed-text). This offloads the work and frees significant RAM.

Enhanced agentic RAG: enable kb_exec

Native function calling is the default, so for a noticeably better knowledge-base experience set ENABLE_KB_EXEC=True. It gives the model a filesystem-style interface over your knowledge (ls, tree, grep, cat, read-by-line) that capable models chain more reliably than the individual search tools, so they find the right passage more often. It has no effect for models set to Legacy. See Filesystem-style access.

More detail:

Models only know what was in their training data. That data has a cutoff date and never includes anything private to your world (today's news, a library released last month, the current price of something). Web Search closes the gap: it lets the model run live searches and read the results mid-answer, so replies cite current sources instead of guessing from stale memory.

It is a built-in tool, so there is nothing to install. The one decision is which search provider to use, and Open WebUI supports over twenty of them. They fall into two rough groups:

  • Self-hosted, no API key. Run your own search backend and keep every query in-house. SearXNG is the usual pick.
  • Commercial APIs. Tavily, Brave, Exa AI, Perplexity Search, Firecrawl and others trade an API key (and usually a bill) for higher-quality, AI-tuned results.

Enable it: go to Settings > Admin > Tools > Web Search, toggle Enable Web Search, then pick your provider and paste its key or config. In any chat, switch web search on for a message with the + button in the prompt field.

Native function calling does the rest

Native is the default tool-calling mode now, so once web search is enabled the model decides on its own when a question needs the live web and runs the search as a tool. You do not have to flip the toggle every time; it is there for when you want to force a fresh lookup.

More detail:

Open Terminal​

If "run Python" is too restrictive and you want the model to actually work on your machine (clone repos, install packages, run test suites, spin up a local preview of a website, iterate on a data report against a real CSV), that is what Open Terminal is for. It connects a real shell (sandboxed in a Docker container by default, or bare-metal if you want) as a tool the model can call the same way it calls any other tool. In-chat file browser, live web previews, and skill definitions are included.

Try this

This is the biggest "aha" feature once you get past basic chat. It turns Open WebUI from a chat UI into a place where the model actually builds things for you. If Native Mode is on and you have given the model a capable terminal, ask it to build you a small app or run an analysis on a folder of files and watch it go.

More detail:

info

Open WebUI Computer by the Open WebUI team is your entire computer in a browser tab: files, terminal, git, editor, and AI, accessible from any device. It connects to Open WebUI via its gateway API.

Open WebUI Computer​

Open Terminal hands the chat model a quick toolbox to run a task for you inside Open WebUI. Open WebUI Computer is a different thing entirely: a full-blown agentic cowork and coding app in its own right. It is a self-hosted workspace with a terminal, file browser, editor, git and a capable AI agent living in it, that you can reach from anywhere once you have set it up to be reachable.

It is a separate Open WebUI project, but a first-class, fully integratable one. Open WebUI Computer's OpenAI-compatible gateway exposes each workspace as a model, so you plug an Open WebUI Computer workspace straight into Open WebUI as a connection and drive the whole agentic coding loop (branching and all) from your normal chat UI. The same workspaces are reachable from Telegram, Discord, Slack and other apps too, so a project follows you onto whatever device you happen to be on.

Use both, they do different jobs

Open Terminal is the model's scratchpad for one-off tasks inside an Open WebUI chat. Open WebUI Computer is a standing coding workspace you own and operate from anywhere, and you can run both at once: Open Terminal for quick in-chat jobs, a connected Open WebUI Computer workspace when you want a real project environment with the agent set up in it.

More detail:

What to do next​

You do not need all of the above at once. A reasonable order for a new install:

  1. Pick a good default model, have a few conversations, get a feel for the UI.
  2. Set a Task Model and decide which background chores you actually want enabled. This is the single biggest "feels better" change you can make, and it directly addresses hidden per-chat costs.
  3. Enable the built-in tools you want (web search, image generation, code execution, memory) and install one or two community Tools that match your work.
  4. Install a context filter the first time you see "prompt is too long."
  5. Set up a Knowledge base when you want to ask questions across multiple documents.
  6. Point the model at Open Terminal and let it actually build things for you.
  7. Revisit the RAG infrastructure section if you go beyond a single user.

Everything else (enterprise SSO, multi-replica HA, Redis scaling, observability) is in Advanced Topics and Troubleshooting when and if you need it.

Troubleshooting​

When something goes wrong, start here:

Having problems with...Read this
Connection refused, 401 errors, CORS failures, WebSocket disconnectsConnection Errors
"Prompt is too long" or context window exceededContext Window / Prompt Too Long
RAG not returning relevant results, uploads failing, knowledge base issuesRAG Troubleshooting
Web search not working or returning poor resultsWeb Search Troubleshooting
Image generation errors or provider setupImage Generation Troubleshooting
Speech-to-text, text-to-speech, or audio playbackAudio Troubleshooting
SSO, OAuth, or LDAP login issuesSSO & OAuth Troubleshooting
High memory usage, slow responses, or worker crashesPerformance & RAM · Scaling Guide
Login loops, config drift, or database locks in multi-replica setupsScaling & HA Troubleshooting · Scaling Guide
Locked out of admin accountReset Admin Password
TLS certificate errors with custom/internal CAsCustom CA Store
Alembic migration errors or manual schema fixesDatabase Migration

Questions?​

This page is the condensed version. The full docs go much deeper. If you did not find what you needed:

  • Search the docs: use the search box at the top of any page. There is a lot more in here than this overview covers.
  • Ask on GitHub Discussions: best for open-ended questions, feature discussions, and "how would I do X?" threads. Searchable and visible to future users who hit the same thing.
  • Ask on Discord: the most active community. Try the #questions channel; there is also an experimental bot there with full docs and issue context that can answer most questions in a few seconds.
  • Ask on Reddit: good for broader discussion, deployment stories, and community showcases.
  • Report a bug: only after you have confirmed it is a bug (reproducible, latest version, template filled in). "It doesn't work" issues get closed; "here's the exact repro, here are the logs" issues get fixed.
This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.