diff --git a/docs/features/extensibility/plugin/functions/action.mdx b/docs/features/extensibility/plugin/functions/action.mdx index 9d52dfc411..b87a952631 100644 --- a/docs/features/extensibility/plugin/functions/action.mdx +++ b/docs/features/extensibility/plugin/functions/action.mdx @@ -3,12 +3,14 @@ sidebar_position: 2 title: "Action Function" --- -Action functions allow you to write custom buttons that appear in the message toolbar for end users to interact with. This feature enables more interactive messaging, allowing users to grant permission before a task is performed, generate visualizations of structured data, download an audio snippet of chats, and many other use cases. +# 🎬 Action Function: Custom Interactive Buttons :::danger ⚠️ Critical Security Warning **Action Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/). ::: +Action functions allow you to write custom buttons that appear in the message toolbar for end users to interact with. This feature enables more interactive messaging, allowing users to grant permission before a task is performed, generate visualizations of structured data, download an audio snippet of chats, and many other use cases. + :::warning Use Async Functions for Future Compatibility Action functions should always be defined as `async`. The backend is progressively moving toward fully async execution, and synchronous functions may block execution or cause issues in future releases. ::: diff --git a/docs/features/extensibility/plugin/functions/filter.mdx b/docs/features/extensibility/plugin/functions/filter.mdx index 4a4d3f3367..f7fe100ce6 100644 --- a/docs/features/extensibility/plugin/functions/filter.mdx +++ b/docs/features/extensibility/plugin/functions/filter.mdx @@ -3,12 +3,12 @@ sidebar_position: 3 title: "Filter Function" --- +# πŸͺ„ Filter Function: Modify Inputs and Outputs + :::danger ⚠️ Critical Security Warning **Filter Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/). ::: -# πŸͺ„ Filter Function: Modify Inputs and Outputs - Welcome to the comprehensive guide on Filter Functions in Open WebUI! Filters are a flexible and powerful **plugin system** for modifying data *before it's sent to the Large Language Model (LLM)* (input) or *after it’s returned from the LLM* (output). Whether you’re transforming inputs for better context or cleaning up outputs for improved readability, **Filter Functions** let you do it all. This guide will break down **what Filters are**, how they work, their structure, and everything you need to know to build powerful and user-friendly filters of your own. Let’s dig in, and don’t worryβ€”I’ll use metaphors, examples, and tips to make everything crystal clear! 🌟 diff --git a/docs/features/extensibility/plugin/functions/index.mdx b/docs/features/extensibility/plugin/functions/index.mdx index 97c9a24f55..244817ce2e 100644 --- a/docs/features/extensibility/plugin/functions/index.mdx +++ b/docs/features/extensibility/plugin/functions/index.mdx @@ -1,137 +1,223 @@ --- -sidebar_position: 1 +sidebar_position: 2 title: "Functions" --- -## πŸš€ What Are Functions? - -Functions are like **plugins** for Open WebUI. They help you **extend its capabilities**β€”whether it’s adding support for new AI model providers like Anthropic or Vertex AI, tweaking how messages are processed, or introducing custom buttons to the interface for better usability. - -Unlike external tools that may require complex integrations, **Functions are built-in and run within the Open WebUI environment.** That means they are fast, modular, and don’t rely on external dependencies. - -Think of Functions as **modular building blocks** that let you enhance how the WebUI works, tailored exactly to what you need. They’re lightweight, highly customizable, and written in **pure Python**, so you have the freedom to create anythingβ€”from new AI-powered workflows to integrations with anything you use, like Google Search or Home Assistant. +# 🧩 Functions :::danger ⚠️ Critical Security Warning **Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/). ::: ---- +Functions are **modular Python plugins** that extend the capabilities of Open WebUI itself. While [Tools](/features/extensibility/plugin/tools/) give LLMs the ability to call external APIs during inference, Functions change how the platform behaves at a deeper level. They can add entirely new "models" powered by any Python logic, intercept and transform every message flowing through the system, or place interactive buttons directly in the chat UI. -## πŸ—οΈ Types of Functions +The possibilities are broad: connect a proprietary AI provider, build a smart home controller that responds to natural language, create a database query interface, add real-time translation to every conversation, enforce compliance policies, generate charts from data, or trigger external workflows with a button click. If you can write it in Python, you can turn it into a Function. -There are **three types of Functions** in Open WebUI, each with a specific purpose. Let’s break them down and explain exactly what they do: +Functions are stored in the database as Python source code, dynamically loaded at runtime, and executed server-side. Administrators create and manage them; regular users interact with the results. --- -### 1. [**Pipe Function** – Create Custom "Agents/Models"](./pipe.mdx) +## Function Types -A **Pipe Function** is how you create **custom agents/models** or integrations, which then appear in the interface as if they were standalone models. +Open WebUI supports three types of Functions. The type is **auto-detected** from the class name in your Python code, so you never need to configure it manually. -**What does it do?** -- Pipes let you define complex workflows. For instance, you could create a Pipe that sends data to **Model A** and **Model B**, processes their outputs, and combines the results into one finalized answer. -- Pipes don’t even have to use AI! They can be setups for **search APIs**, **weather data**, or even systems like **Home Assistant**. Basically, anything you’d like to interact with can become part of Open WebUI. +| Type | Class Name | What It Does | How Users See It | +|:-----|:-----------|:-------------|:-----------------| +| **Pipe** | `class Pipe` | Adds a custom model or agent | Appears as a selectable model in the chat sidebar | +| **Filter** | `class Filter` | Intercepts data flowing to/from models | Runs transparently as middleware on existing models | +| **Action** | `class Action` | Adds interactive buttons to messages | Appears as a clickable button on chat messages | -**Use case example:** -Imagine you want to query Google Search directly from Open WebUI. You can create a Pipe Function that: -1. Takes your message as the search query. -2. Sends the query to Google Search’s API. -3. Processes the response and returns it to you inside the WebUI like a normal "model" response. +### Pipe Functions -When enabled, **Pipe Functions show up as their own selectable model**. Use Pipes whenever you need custom functionality that works like a model in the interface. +A Pipe registers itself as a new "model" in Open WebUI. When a user selects it and sends a message, the `pipe()` method handles the entire request with no LLM backend required. This makes Pipes incredibly versatile: -For a detailed guide, see [**Pipe Functions**](./pipe.mdx). +- **Model providers**: Integrate APIs that don't follow the OpenAI protocol (Anthropic native, Google Vertex, custom inference servers). +- **Agents & workflows**: Build multi-step agents that call tools, search the web, and reason across multiple turns. +- **Non-LLM interfaces**: Create a smart home controller, a database query tool, a search engine, a calculator, or a code executor. Anything that takes user input and returns a response. +- **Proxies & routers**: Route requests through your own logic, add caching, load balancing, or cost tracking. ---- +A single Pipe can also expose **multiple models** (called a "manifold") by defining a `pipes()` method that returns a list of model identifiers. + +β†’ **[Pipe Function Guide](./pipe)** + +### Filter Functions + +A Filter sits between the user and the model, intercepting data at three stages: + +- **`inlet()`**: Modifies the request **before** it reaches the model (add context, sanitize input, detect language, enforce rate limits, estimate token costs). +- **`stream()`**: Intercepts **streamed chunks** from the model in real time (censor content, replace terms, track token usage). +- **`outlet()`**: Processes the completed response **after** it's generated (log to observability platforms, format citations, append disclaimers, cache responses). -### 2. [**Filter Function** – Modify Inputs and Outputs](./filter.mdx) +Filters enable powerful cross-cutting concerns like real-time translation, content moderation, prompt injection detection, A/B testing, compliance logging, and PII redaction, all without modifying the underlying model. -A **Filter Function** is like a tool for tweaking data before it gets sent to the AI **or** after it comes back. +Filters can be applied globally (to all models) or attached to specific models. Toggleable filters let users enable/disable them per-chat. -**What does it do?** -Filters act as "hooks" in the workflow and have two main parts: -- **Inlet**: Adjust the input that is sent to the model. For example, adding additional instructions, keywords, or formatting tweaks. -- **Outlet**: Modify the output that you receive from the model. For instance, cleaning up the response, adjusting tone, or formatting data into a specific style. +β†’ **[Filter Function Guide](./filter)** -**Use case example:** -Suppose you’re working on a project that needs precise formatting. You can use a Filter to ensure: -1. Your input is always transformed into the required format. -2. The output from the model is cleaned up before being displayed. +### Action Functions -Filters are **linked to specific models** or can be enabled for all models **globally**, depending on your needs. +An Action adds a custom button to the chat message toolbar. When a user clicks it, the `action()` method runs with full access to the event system for real-time UI feedback, user prompts, and confirmations. -Check out the full guide for more examples and instructions: [**Filter Functions**](./filter.mdx). +Actions can do anything Python can do: summarize or translate a message, copy formatted output, pin important messages, export conversations to external systems, trigger a CI/CD pipeline, send a Slack notification, generate a PDF report, run a code snippet, or kick off an external workflow. + +β†’ **[Action Function Guide](./action)** --- -### 3. [**Action Function** – Add Custom Buttons](./action.mdx) +## How Functions Work -An **Action Function** is used to add **custom buttons** to the chat interface. +### Type Detection -**What does it do?** -Actions allow you to define **interactive shortcuts** that trigger specific functionality directly from the chat. These buttons appear underneath individual chat messages, giving you convenient, one-click access to the actions you define. +When you save a Function, Open WebUI scans the Python source code for a top-level class named `Pipe`, `Filter`, or `Action`. The first match determines the function type. You never need to manually set the type because it's inferred from the code. -**Use case example:** -Let’s say you often need to summarize long messages or generate specific outputs like translations. You can create an Action Function to: -1. Add a β€œSummarize” button under every incoming message. -2. When clicked, it triggers your custom function to process that message and return the summary. +``` +# This is detected as a Pipe function: +class Pipe: + def pipe(self, body: dict) -> str: + return "Hello from my custom model!" -Buttons provide a **clean and user-friendly way** to interact with extended functionality you define. +# This is detected as a Filter function: +class Filter: + def inlet(self, body: dict) -> dict: + return body +``` -Learn how to set them up in the [**Action Functions Guide**](./action.mdx). +### Module Loading & Caching ---- +The Python source code is loaded via `exec()` into a temporary module namespace. Once loaded, the module is cached in memory (`request.app.state.FUNCTIONS`) and only reloaded when the source code changes. Import statements in your code are automatically rewritten to resolve within the Open WebUI package namespace. -## πŸ› οΈ How to Use Functions +### Frontmatter -Here's how to put Functions to work in Open WebUI: +A triple-quoted docstring at the top of the file is parsed as YAML frontmatter for metadata: -### 1. **Install Functions** -You can install Functions via the Open WebUI interface or by importing them manually. You can find community-created functions on the [Open WebUI Community Site](https://openwebui.com/search). +```python +""" +title: My Custom Function +author: your_name +author_url: https://github.com/your_name +version: 1.0.0 +icon_url: https://example.com/icon.svg +required_open_webui_version: 0.4.0 +requirements: requests, beautifulsoup4 +""" +``` -⚠️ **Be cautious.** Only install Functions from trusted sources. Running unknown code poses security risks. +| Field | Purpose | +|:------|:--------| +| `title` | Display name in the admin UI | +| `author` / `author_url` | Attribution metadata | +| `version` | Version identifier | +| `icon_url` | Icon displayed next to the function name (use a URL, not base64) | +| `required_open_webui_version` | Minimum compatible Open WebUI version | +| `requirements` | Comma-separated list of pip packages to auto-install | + +:::tip Automatic Dependency Installation +When `requirements` is specified in the frontmatter, Open WebUI automatically installs the listed packages via `pip` the first time the function loads. This is controlled by the `PIP_INSTALL_FRONTMATTER_REQUIREMENTS` environment variable (enabled by default). +::: --- -### 2. **Enable Functions** -Functions must be explicitly enabled after installation: -- When you enable a **Pipe Function**, it becomes available as its own **model** in the interface. -- For **Filter** and **Action Functions**, enabling them isn’t enoughβ€”you also need to assign them to specific models or enable them globally for all models. +## Installing Functions ---- +### From the Community Library + +1. Browse the [Community Function Library](https://openwebui.com/search). +2. Click **Get** on the function you want. +3. Enter your Open WebUI instance URL (e.g., `http://localhost:3000`). +4. Click **Import to Open WebUI**. You'll be redirected to the Function Editor. +5. Review the code, then click **Save**. + +:::warning +Always review the source code before importing. Community functions are user-contributed and **run directly on your server**. +::: -### 3. **Assign Filters or Actions to Models** -- Navigate to `Workspace => Models` and assign your Filter or Action to the relevant model there. -- Alternatively, enable Functions for **all models globally** by going to `Workspace => Functions`, selecting the "..." menu, and toggling the **Global** switch. +### From a URL + +1. Go to **Admin Panel β†’ Functions**. +2. Click **Import from URL** and paste a link to the Python file. + - GitHub URLs are automatically converted to raw file URLs. +3. Review and save. + +### Create Manually + +1. Go to **Admin Panel β†’ Functions**. +2. Click **Create**. +3. Enter an ID (alphanumeric and underscores only), name, and description. +4. Write your Python code in the editor. +5. Click **Save**. The function type is auto-detected from your code. --- -### Quick Summary -- **Pipes** appear as standalone models you can interact with. -- **Filters** modify inputs/outputs for smoother AI interactions. -- **Actions** add clickable buttons to individual chat messages. +## Managing Functions + +### Admin Controls + +Functions are managed from **Admin Panel β†’ Functions**. Each function has the following controls: + +| Control | Description | +|:--------|:-----------| +| **Active toggle** | Enables or disables the function. Disabled functions are not loaded or executed. | +| **Global toggle** | When enabled, the function applies to **all models** automatically. Available for Filters and Actions. | +| **Valves** (βš™οΈ gear icon) | Opens the admin-configurable settings for this function. | +| **Export / Delete** | Export the function as a file or remove it. | + +### Assigning Functions to Specific Models + +Instead of making a Filter or Action global, you can attach it to specific models: -Once you’ve followed the setup process, Functions will seamlessly enhance your workflows. +1. Go to **Workspace β†’ Models**. +2. Edit the target model. +3. In the **Filters** or **Actions** section, select the functions you want to attach. + +This allows different models to use different filters. For example, you might apply a content-moderation filter only on public-facing models. + +### Toggleable Filters + +Filters can be made user-toggleable by setting `self.toggle = True` in `__init__`. When toggleable, users see an on/off switch in the chat input area and can enable or disable the filter per-conversation. Filters without `self.toggle` are always-on when active. --- -## βœ… Why Use Functions? +## Valves & UserValves + +Functions support a two-tier configuration system built on [Pydantic](https://docs.pydantic.dev/): -Functions are designed for anyone who wants to **unlock new possibilities** with Open WebUI: +| Level | Class Name | Who Configures | Where | +|:------|:-----------|:---------------|:------| +| **Admin** | `Valves` | Administrators only | Admin Panel β†’ Functions β†’ βš™οΈ | +| **User** | `UserValves` | Any user | Chat interface, per-function | -- **Extend**: Add new models or integrate with non-AI tools like APIs, databases, or smart devices. -- **Optimize**: Tweak inputs and outputs to fit your use case perfectly. -- **Simplify**: Add buttons or shortcuts to make the interface intuitive and efficient. +**Valves** are ideal for API keys, model endpoints, and global behavior settings. **UserValves** let individual users customize behavior (e.g., their preferred language, output format, or personal API key). -Whether you’re customizing workflows for specific projects, integrating external data, or just making Open WebUI easier to use, Functions are the key to taking control of your instance. +Both are defined as nested Pydantic `BaseModel` classes inside your `Pipe`, `Filter`, or `Action` class. The admin-configured values are stored in the database and loaded automatically at runtime. + +β†’ **[Valves Development Guide](/features/extensibility/plugin/development/valves)** --- -### πŸ“ Final Notes: -1. Always install Functions from **trusted sources only**. -2. Make sure you understand the difference between Pipe, Filter, and Action Functions to use them effectively. -3. Explore the official guides: - - [Pipe Functions Guide](./pipe.mdx) - - [Filter Functions Guide](./filter.mdx) - - [Action Functions Guide](./action.mdx) +## Functions vs Tools: When to Use Which + +| Use Case | Use a... | Why | +|:---------|:---------|:----| +| Give the LLM access to live data (weather, stocks, APIs) | **Tool** | Tools are called by the model during inference | +| Add a model provider with a non-OpenAI API | **Pipe Function** | Pipes register as models in the sidebar | +| Build a non-LLM interface (search, databases, smart home) | **Pipe Function** | Pipes handle the entire request without needing an LLM | +| Build a multi-step agent with custom logic | **Pipe Function** | Pipes control the full request/response cycle | +| Translate, moderate, or redact content in real time | **Filter Function** | Filters intercept every message transparently | +| Log requests to an observability platform | **Filter Function** | Inlet/outlet filters see all traffic | +| Rate-limit or enforce usage policies | **Filter Function** | Inlet filters can reject requests before the model | +| Add a button to export, summarize, or share messages | **Action Function** | Actions appear on the message toolbar | +| Trigger an external workflow from the chat UI | **Action Function** | Actions run arbitrary Python on click | + +--- -By leveraging Functions, you’ll bring entirely new capabilities to your Open WebUI setup. Start experimenting today! πŸš€ +## Development Resources + +| Guide | Description | +|:------|:-----------| +| [Pipe Function Guide](./pipe) | Build custom models, agents, and non-LLM interfaces | +| [Filter Function Guide](./filter) | Intercept, translate, moderate, and log messages | +| [Action Function Guide](./action) | Add buttons for export, workflows, and interactive tasks | +| [Valves](/features/extensibility/plugin/development/valves) | Configure functions with admin and user settings | +| [Events](/features/extensibility/plugin/development/events) | Send real-time updates to the UI | +| [Reserved Arguments](/features/extensibility/plugin/development/reserved-args) | `__user__`, `__event_emitter__`, `__metadata__`, and more | +| [Rich UI](/features/extensibility/plugin/development/rich-ui) | Embed interactive HTML/JS content in responses | diff --git a/docs/features/extensibility/plugin/functions/pipe.mdx b/docs/features/extensibility/plugin/functions/pipe.mdx index 6315fe15e1..ee0bff4d7c 100644 --- a/docs/features/extensibility/plugin/functions/pipe.mdx +++ b/docs/features/extensibility/plugin/functions/pipe.mdx @@ -3,11 +3,12 @@ sidebar_position: 4 title: "Pipe Function" --- +# 🚰 Pipe Function: Create Custom "Agents/Models" + :::danger ⚠️ Critical Security Warning **Pipe Functions execute arbitrary Python code on your server.** Function creation is restricted to administrators only. Only install from trusted sources and review code before importing. A malicious Function could access your file system, exfiltrate data, or compromise your entire system. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/). ::: -# 🚰 Pipe Function: Create Custom "Agents/Models" Welcome to this guide on creating **Pipes** in Open WebUI! Think of Pipes as a way to **adding** a new model to Open WebUI. In this document, we'll break down what a Pipe is, how it works, and how you can create your own to add custom logic and processing to your Open WebUI models. We'll use clear metaphors and go through every detail to ensure you have a comprehensive understanding. :::warning Use Async Functions for Future Compatibility diff --git a/docs/features/extensibility/plugin/index.mdx b/docs/features/extensibility/plugin/index.mdx index d1bd7aac5e..45fb2972ab 100644 --- a/docs/features/extensibility/plugin/index.mdx +++ b/docs/features/extensibility/plugin/index.mdx @@ -5,20 +5,6 @@ title: "Tools & Functions (Plugins)" # πŸ› οΈ Tools & Functions -Imagine you've just stumbled upon Open WebUI, or maybe you're already using it, but you're a bit lost with all the talk about "Tools", "Functions", and "Pipelines". Everything sounds like some mysterious tech jargon, right? No worries! Let's break it down piece by piece, super clearly, step by step. By the end of this, you'll have a solid understanding of what these terms mean, how they work, and why know it's not as complicated as it seems. - -## TL;DR - -- **Tools** extend the abilities of LLMs, allowing them to collect real-world, real-time data like weather, stock prices, etc. -- **Functions** extend the capabilities of the Open WebUI itself, enabling you to add new AI model support (like Anthropic or Vertex AI) or improve usability (like creating custom buttons or filters). -- **Pipelines** are more for advanced users who want to transform Open WebUI features into API-compatible workflowsβ€”mainly for offloading heavy processing. - -Getting started with Tools and Functions is easy because everything’s already built into the core system! You just **click a button** and **import these features directly from the community**, so there’s no coding or deep technical work required. - -## What are "Tools" and "Functions"? - ---- - :::danger ⚠️ Critical Security Warning **Tools, Functions, Pipes, Filters, and Pipelines execute arbitrary Python code on your server.** This is by designβ€”it's what makes them powerful. However, this also means: @@ -37,7 +23,15 @@ Getting started with Tools and Functions is easy because everything’s already ::: ---- +## TL;DR + +- **Tools** extend the abilities of LLMs, allowing them to collect real-world, real-time data like weather, stock prices, etc. +- **Functions** extend the capabilities of the Open WebUI itself, enabling you to add new AI model support (like Anthropic or Vertex AI) or improve usability (like creating custom buttons or filters). +- **Pipelines** are more for advanced users who want to transform Open WebUI features into API-compatible workflowsβ€”mainly for offloading heavy processing. + +Getting started with Tools and Functions is easy because everything’s already built into the core system! You just **click a button** and **import these features directly from the community**, so there’s no coding or deep technical work required. + +## What are "Tools" and "Functions"? Let's start by thinking of **Open WebUI** as a "base" software that can do many tasks related to using Large Language Models (LLMs). But sometimes, you need extra features or abilities that don't come *out of the box*β€”this is where **tools** and **functions** come into play. diff --git a/docs/features/extensibility/plugin/tools/development.mdx b/docs/features/extensibility/plugin/tools/development.mdx index 6b924589f5..3913e019e3 100644 --- a/docs/features/extensibility/plugin/tools/development.mdx +++ b/docs/features/extensibility/plugin/tools/development.mdx @@ -3,6 +3,8 @@ sidebar_position: 2 title: "Development" --- +# πŸ”§ Tool Development + :::danger ⚠️ Critical Security Warning **Workspace Tools execute arbitrary Python code on your server.** Only install from trusted sources, review code before importing, and restrict Workspace access to trusted administrators only. Granting a user the ability to create or import Tools is equivalent to giving them shell access to the server. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/). ::: diff --git a/docs/features/extensibility/plugin/tools/index.mdx b/docs/features/extensibility/plugin/tools/index.mdx index 38edef7ef1..43327c1581 100644 --- a/docs/features/extensibility/plugin/tools/index.mdx +++ b/docs/features/extensibility/plugin/tools/index.mdx @@ -5,12 +5,12 @@ title: "Tools" # What are Tools? -βš™οΈ Tools are the various ways you can extend an LLM's capabilities beyond simple text generation. When enabled, they allow your chatbot to do amazing things β€” like search the web, scrape data, generate images, talk back using AI voices, and more. - :::danger ⚠️ Critical Security Warning **Workspace Tools and Functions execute arbitrary Python code on your server.** Only install from trusted sources, review code before importing, and restrict Workspace access to trusted administrators only. Granting a user the ability to create or import Tools is equivalent to giving them shell access to the server. For full details, see the [Plugin Security Warning](/features/extensibility/plugin/). ::: +βš™οΈ Tools are the various ways you can extend an LLM's capabilities beyond simple text generation. When enabled, they allow your chatbot to do amazing things β€” like search the web, scrape data, generate images, talk back using AI voices, and more. + Because there are several ways to integrate "Tools" in Open WebUI, it's important to understand which type you are using. --- diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 748f5cfad4..d41b9f8d1f 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -30,6 +30,21 @@ Everything you need for a working setup. Choose Docker for the fastest path, Pyt --- +## πŸ€– Connect an Agent + +**Go beyond simple model providers. Connect an autonomous AI agent.** + +AI agents like Hermes Agent and OpenClaw bring their own tools (terminal, file ops, web search, memory) and use Open WebUI as a rich chat frontend. The agent decides when to use tools, executes them, and streams results back to you. + +| | | +| :--- | :--- | +| 🧠 **Hermes Agent** | Nous Research's agent with terminal, file ops, web search, and skills | +| 🐾 **OpenClaw** | Self-hosted agent framework with shell access, web browsing, and channel bots | + +[**Connect an agent β†’**](/getting-started/quick-start/connect-an-agent) + +--- + ## Sharing Open WebUI **Bring AI to your entire organization with a single deployment.** diff --git a/docs/getting-started/quick-start/connect-a-provider/index.md b/docs/getting-started/quick-start/connect-a-provider/index.md new file mode 100644 index 0000000000..6b95953de5 --- /dev/null +++ b/docs/getting-started/quick-start/connect-a-provider/index.md @@ -0,0 +1,74 @@ +--- +sidebar_position: 0 +title: "Connect a Provider" +--- + +# πŸ”Œ Connect a Provider + +**Connect Open WebUI to any model provider and start chatting in minutes.** + +Open WebUI supports multiple connection protocols, including **Ollama**, **OpenAI-compatible APIs**, and **Open Responses**. Any cloud API or local server that speaks one of these protocols works out of the box. Just add a URL and API key, and your models appear in the dropdown. + +--- + +## How It Works + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ β”‚ HTTP β”‚ β”‚ Inferenceβ”‚ β”‚ +β”‚ Open WebUI │────────▢│ Provider API │────────▢ β”‚ Model β”‚ +β”‚ (frontend) │◀────────│ (cloud/local) │◀──────── β”‚ (LLM/VLM) β”‚ +β”‚ β”‚ Stream β”‚ β”‚ Tokens β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +1. **You type a message** in Open WebUI +2. Open WebUI sends it to your provider's API endpoint +3. The provider runs inference on the selected model +4. Tokens **stream back** to Open WebUI in real time +5. You see the response in the chat interface + +:::tip +Adding a provider is as simple as entering a URL and API key in **Admin Settings β†’ Connections**. Open WebUI auto-detects available models from most providers. +::: + +--- + +## Cloud Providers + +Hosted APIs that require an account and API key. No hardware needed. + +| Provider | Models | Guide | +|----------|--------|-------| +| **Ollama** | Llama, Mistral, Gemma, Phi, and thousands more (local) | [Starting with Ollama β†’](./starting-with-ollama) | +| **OpenAI** | GPT-4o, GPT-4.1, o3, o4-mini | [Starting with OpenAI β†’](./starting-with-openai) | +| **Anthropic** | Claude Opus, Sonnet, Haiku | [Starting with Anthropic β†’](./starting-with-anthropic) | +| **OpenAI-Compatible** | Google Gemini, DeepSeek, Mistral, Groq, OpenRouter, Amazon Bedrock, Azure, and more | [OpenAI-Compatible Providers β†’](./starting-with-openai-compatible) | + +--- + +## Local Servers + +Run models on your own hardware. No API keys, no cloud dependency. + +| Server | Description | Guide | +|--------|-------------|-------| +| **llama.cpp** | Efficient GGUF model inference with OpenAI-compatible API | [Starting with llama.cpp β†’](./starting-with-llama-cpp) | +| **vLLM** | High-throughput inference engine for production workloads | [Starting with vLLM β†’](./starting-with-vllm) | + +More local servers (LM Studio, LocalAI, Docker Model Runner, Lemonade) are covered in the [OpenAI-Compatible Providers](./starting-with-openai-compatible#local-servers) guide. + +--- + +## Other Connection Methods + +| Feature | Description | Guide | +|---------|-------------|-------| +| **Open Responses** | Connect providers using the Open Responses specification | [Starting with Open Responses β†’](./starting-with-open-responses) | +| **Functions** | Extend Open WebUI with custom pipe functions for any backend | [Starting with Functions β†’](./starting-with-functions) | + +--- + +## Looking for Agents? + +If you want to connect an autonomous AI agent (with terminal access, file operations, web search, and more) instead of a plain model provider, see [**Connect an Agent**](/getting-started/quick-start/connect-an-agent). diff --git a/docs/getting-started/quick-start/connect-a-provider/starting-with-functions.mdx b/docs/getting-started/quick-start/connect-a-provider/starting-with-functions.mdx index 1281633f6b..cee3ad6b38 100644 --- a/docs/getting-started/quick-start/connect-a-provider/starting-with-functions.mdx +++ b/docs/getting-started/quick-start/connect-a-provider/starting-with-functions.mdx @@ -5,107 +5,87 @@ title: "Functions" ## Overview -Did you know Open WebUI can connect to almost **anything**β€”not just OpenAI-compatible APIs? +**Pipe Functions** are Python plugins that appear as selectable models in your chat sidebar. Behind the scenes, they can do anything Python can do: integrate a proprietary AI provider, control your smart home with natural language, query a database, run a search engine, build a multi-step agent, generate charts, automate workflows, or serve as a calculator. No LLM is even required. If you can write the logic in Python, it becomes a "model" users can chat with. -Thanks to **Pipe Functions**, you can bring in services that don’t support the OpenAI API (like **Anthropic**, Home Assistant, Google Search, or *any* Python codebase). No restrictions on LLMs or AI models: if you can automate it in Python, you can turn it into a plugin for Open WebUI! +This guide walks you through importing and enabling your first Pipe Function, using the [Anthropic Pipe](https://openwebui.com/f/justinrahb/anthropic) as an example. -This guide walks you through setting up your first Pipe Function, using the [Anthropic Pipe](https://openwebui.com/f/justinrahb/anthropic) plugin as an example. - -## What are Pipe Functions? - -Pipe Functions are β€œbring-your-own-model (or tool)” plugins: +:::info Already have an OpenAI-compatible provider? +If your provider supports the **OpenAI Chat Completions API protocol** (OpenAI, Google Gemini, Mistral, Groq, DeepSeek, and many more), you don't need a Function. Just [add a connection](/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible). Anthropic also has native support via their OpenAI-compatible endpoint; see the [Anthropic guide](/getting-started/quick-start/connect-a-provider/starting-with-anthropic). Functions are for everything else: proprietary APIs, custom agents, or entirely novel interfaces. +::: -- **Act like models**: They show up as selectable models in your Open WebUI sidebar. -- **Flexible**: Integrate with *any* backend, API, or workflowβ€”no OpenAI compatibility required. -- **No LLM required**: You can build plugins for search, home automation, weather, databases, or whatever you like. -- **Pure Python**: All logic is Python code that runs *directly inside* your WebUI (so be cautious with what you enable!). +--- -## Step 1: Find a Pipe Function to Try +## Step 1: Find a Function -Functions are powerful tools, and the community has created thousands of them! You can browse, search, and import them directly from our community hub. +1. Go to the [Community Function Library](https://openwebui.com/search). +2. Browse or search for the function you need. There are thousands of community-contributed functions for AI providers, search tools, home automation, productivity utilities, content filters, and more. +3. Click **Get** on the function you want to import. -:::info Community Account Required -To search and import functions directly from **[Open WebUI Community](https://openwebui.com/search)**, you must be logged in with a registered community account. +:::note Community Account Required +Importing directly from the community library requires a registered account at [openwebui.com](https://openwebui.com). ::: -1. Go to **[Open WebUI Community Search](https://openwebui.com/search)**. -2. Explore the library! You can find functions for: - * **New Providers**: Anthropic, Google Gemini, Groq. - * **Tools**: Web Search, Calculator, Home Assistant control. - * **Utilities**: Auto-tagging, content filtering, and more. -3. **Pro Tip**: Even if you don't find exactly what you need, you can use existing functions as **templates** to build your own! - -For this guide, let's try integrating **Anthropic** (Claude models): - -1. Locate the [Anthropic Pipe](https://openwebui.com/f/justinrahb/anthropic) function. -2. Click **Get**. - -![Anthropic Pipe Function Page](/images/getting-started/pipe-anthropic-function.png) +--- -## Step 2: Import the Function to Open WebUI +## Step 2: Import to Open WebUI A modal will appear: -1. Enter your Open WebUI URL (e.g., `http://localhost:3000`) in the prompt. +1. Enter your Open WebUI instance URL (e.g., `http://localhost:3000`). 2. Click **Import to Open WebUI**. +You'll be redirected to the **Function Editor** within your running instance. + ![Import Modal Screenshot](/images/getting-started/pipe-import-modal.png) -You’ll be redirected **directly to the Functions Editor** within your running instance of Open WebUI. +--- ## Step 3: Review & Save -- You’ll see all of the Pipe Function’s Python code and configuration. -- **Important:** Functions run arbitrary Python! Review the code for safety, and only install from sources you trust. -- If you’re happy with the code, click **Save** to add it to your instance. +Review the Python source code in the editor. Functions execute arbitrary code on your server, so only install from sources you trust. + +Click **Save** to add the function to your instance. ![Function Editor Screenshot](/images/getting-started/pipe-function-editor.png) -## Step 4: Enable the Function +--- -Your new Pipe Function is now available, but **must be enabled**: +## Step 4: Enable the Function -1. Switch the toggler to enable the function. +New functions are disabled by default. Toggle the switch to enable it. ![Enable Function Screenshot](/images/getting-started/pipe-enable.png) -## Step 5: Enter any Required API Keys via Valves - -Some functions need credentials (like Anthropic’s API key): - -1. Click on the Gear icon next to the switch to open the **Valves** configuration. -2. Input your required API key(s) for the Pipe Function. +--- - ![Valves/API Key Screenshot](/images/getting-started/pipe-valves.png) +## Step 5: Configure Valves -## Step 6: Start Using Your New Plugin! +Many functions require configuration, such as API keys or endpoint URLs: -- The new function now appears as a selectable β€œmodel” in the chat interface. -- Select `Anthropic` (or whatever you installed), and start chatting! +1. Click the βš™οΈ **gear icon** next to the toggle switch. +2. Enter the required values (e.g., your Anthropic API key). +3. Save. -![Select Pipe Function as Model Screenshot](/images/getting-started/pipe-select-model.png) +![Valves Configuration Screenshot](/images/getting-started/pipe-valves.png) -## πŸŽ‰ That’s Itβ€”You’re Plugged Into Anything! - -- Pipe Functions open Open WebUI to *any* API, model, or automationβ€”not just OpenAI-compatible endpoints. -- Think beyond LLMs: Integrate tools, APIs, local scripts, or your entire smart home. +--- -## ⚠️ Security Notes +## Step 6: Start Chatting -- **Always** review function code before enabling. -- Only use plugins from trusted sources. -- You have the power to enhance (or break!) your WebUIβ€”use responsibly. +The function now appears as a selectable model in the chat sidebar. Select it and start chatting. -### Next Steps & Learn More +![Select Pipe Function as Model Screenshot](/images/getting-started/pipe-select-model.png) -Ready to build your own? Check out our detailed development guides: +--- -* **[Functions Overview](/features/extensibility/plugin/functions/)**: Learn the basics of the Functions system. -* **[Pipes Guide](/features/extensibility/plugin/functions/pipe)**: Create custom model providers and logic pipelines. -* **[Filters Guide](/features/extensibility/plugin/functions/filter)**: Intercept and modify messages (Input/Output guards). -* **[Actions Guide](/features/extensibility/plugin/functions/action)**: Add buttons/actions to messages. -* **[Tools Guide](/features/extensibility/plugin/tools/)**: Build tools for LLMs to use (RAG, APIs). +:::danger ⚠️ Security Reminder +Functions run arbitrary Python on your server. Always review code before enabling, and only import from trusted sources. For details, see the [Plugin Security Warning](/features/extensibility/plugin/). +::: -* **[Community Registry](https://openwebui.com/search)**: Browse hundreds of community-made functions. +## Learn More -πŸš€ With Pipe Functions, your Open WebUI is limited *only by your imagination*! \ No newline at end of file +- **[Functions Overview](/features/extensibility/plugin/functions/)**: Architecture, types, and the full range of possibilities. +- **[Pipe Function Guide](/features/extensibility/plugin/functions/pipe)**: Build custom models, agents, and non-LLM interfaces. +- **[Filter Function Guide](/features/extensibility/plugin/functions/filter)**: Intercept, translate, moderate, and log messages. +- **[Action Function Guide](/features/extensibility/plugin/functions/action)**: Add interactive buttons for export, workflows, and more. +- **[Community Library](https://openwebui.com/search)**: Browse thousands of community functions. \ No newline at end of file diff --git a/docs/getting-started/quick-start/connect-an-agent/_category_.json b/docs/getting-started/quick-start/connect-an-agent/_category_.json new file mode 100644 index 0000000000..bc5cd3d2cf --- /dev/null +++ b/docs/getting-started/quick-start/connect-an-agent/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Connect an Agent", + "position": 15, + "collapsible": true, + "collapsed": true +} diff --git a/docs/getting-started/quick-start/connect-an-agent/hermes-agent.mdx b/docs/getting-started/quick-start/connect-an-agent/hermes-agent.mdx new file mode 100644 index 0000000000..3345c395b3 --- /dev/null +++ b/docs/getting-started/quick-start/connect-an-agent/hermes-agent.mdx @@ -0,0 +1,180 @@ +--- +sidebar_position: 1 +title: "Hermes Agent" +--- + +# Hermes Agent + +**Use Open WebUI as the chat frontend for Nous Research's autonomous AI agent.** + +[Hermes Agent](https://github.com/NousResearch/hermes-agent) by **Nous Research** is an autonomous AI agent with built-in tools: terminal access, file operations, web search, memory, and extensible skills. It exposes an **OpenAI-compatible API server**, so connecting it to Open WebUI takes just a few minutes. + +When you send a message through Open WebUI, Hermes Agent receives it, decides which tools to use (if any), executes them, and streams the final response back. You'll see inline progress indicators in real time (e.g., `πŸ’» ls -la`, `πŸ” searching...`). + +:::info What You'll Need +- **Hermes Agent** installed on your machine ([quickstart guide](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)) +- **Open WebUI** running (via Docker, pip, or desktop app) +- **~10 minutes** to complete this setup +::: + +--- + +## Step 1: Install Hermes Agent + +If you haven't installed Hermes Agent yet, follow the [official quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart). Once installed, verify it's working: + +```bash +hermes --version +``` + +--- + +## Step 2: Enable the API Server + +Add the following to your Hermes Agent environment file: + +```bash title="~/.hermes/.env" +API_SERVER_ENABLED=true +API_SERVER_KEY=your-secret-key +``` + +Replace `your-secret-key` with any strong, random string. This becomes the API key you'll enter in Open WebUI. + +:::tip Optional Configuration +You can also customize the port and host: + +| Variable | Default | Description | +|---|---|---| +| `API_SERVER_PORT` | `8642` | Port the API server listens on | +| `API_SERVER_HOST` | `127.0.0.1` | Bind address (localhost only by default) | +::: + +--- + +## Step 3: Start the Gateway + +```bash +hermes gateway +``` + +You should see output confirming the API server is running: + +``` +[API Server] API server listening on http://127.0.0.1:8642 +``` + +:::warning Keep this running +The gateway must stay running for Open WebUI to communicate with your agent. Consider running it in a terminal multiplexer (`tmux`, `screen`) or as a system service for persistent deployments. +::: + +--- + +## Step 4: Add the Connection in Open WebUI + +1. Open Open WebUI in your browser. +2. Go to βš™οΈ **Admin Settings** β†’ **Connections** β†’ **OpenAI**. +3. Click βž• **Add Connection**. +4. Enter the following: + +| Setting | Value | +|---|---| +| **URL** | `http://localhost:8642/v1` | +| **API Key** | The `API_SERVER_KEY` you set in Step 2 | + +5. Click the βœ… checkmark to verify, then **Save**. + +:::tip Running Open WebUI in Docker? +Replace `localhost` with `host.docker.internal`: + +``` +http://host.docker.internal:8642/v1 +``` +::: + +--- + +## Step 5: Start Chatting! + +The `hermes-agent` model should now appear in the model dropdown. Select it and start chatting. Your agent has full access to its toolset (terminal, file ops, web search, memory, skills) right through Open WebUI's interface. + +Streaming is enabled by default. You'll see brief inline indicators as tools execute before the agent's final response appears. + +--- + +## Docker Compose Setup + +For a more permanent deployment, run Open WebUI pre-configured to connect to Hermes Agent: + +```yaml title="docker-compose.yml" +services: + open-webui: + image: ghcr.io/open-webui/open-webui:main + ports: + - "3000:8080" + volumes: + - open-webui:/app/backend/data + environment: + - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 + - OPENAI_API_KEY=your-secret-key + extra_hosts: + - "host.docker.internal:host-gateway" + restart: always + +volumes: + open-webui: +``` + +```bash +docker compose up -d +``` + +Then open [http://localhost:3000](http://localhost:3000) and create your admin account. + +:::note +Environment variables only take effect on Open WebUI's **first launch**. After that, connection settings are stored in its internal database. To change them later, use the Admin UI or delete the Docker volume and start fresh. +::: + +--- + +## Troubleshooting + +### No models appear in the dropdown + +- Verify the URL includes `/v1`: `http://localhost:8642/v1` (not just `:8642`) +- Check the gateway is running: `curl http://localhost:8642/health` β†’ `{"status": "ok"}` +- Check model listing: `curl http://localhost:8642/v1/models` β†’ should list `hermes-agent` + +### Connection test passes but no models load + +Almost always the missing `/v1` suffix. Open WebUI's connection test checks basic connectivity, not model discovery. + +### "Invalid API key" errors + +Make sure the **API Key** in Open WebUI matches the `API_SERVER_KEY` in `~/.hermes/.env` exactly. + +### Response takes a long time + +Hermes Agent may be executing multiple tool calls before responding. This is normal for complex queries, as the agent is actually doing work on your behalf. + +### Linux Docker (no Docker Desktop) + +`host.docker.internal` doesn't resolve by default on Linux without Docker Desktop: + +```bash +# Option 1: Add host mapping +docker run --add-host=host.docker.internal:host-gateway ... + +# Option 2: Use host networking +docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ... + +# Option 3: Use Docker bridge IP +docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ... +``` + +--- + +## Learn More + +- [Hermes Agent Documentation](https://hermes-agent.nousresearch.com/docs/) - Full docs, skills, and integrations +- [Nous Research Discord](https://discord.gg/NousResearch) - Community support +- [GitHub](https://github.com/NousResearch/hermes-agent) - Source code and issues diff --git a/docs/getting-started/quick-start/connect-an-agent/index.md b/docs/getting-started/quick-start/connect-an-agent/index.md new file mode 100644 index 0000000000..4050761409 --- /dev/null +++ b/docs/getting-started/quick-start/connect-an-agent/index.md @@ -0,0 +1,61 @@ +--- +sidebar_position: 0 +title: "Connect an Agent" +--- + +# πŸ€– Connect an Agent + +**Use Open WebUI as the chat frontend for autonomous AI agents.** + +AI agents go beyond simple model providers. They can execute terminal commands, read and write files, search the web, manage memory, and chain complex workflows. Because many agent frameworks expose an **OpenAI-compatible API**, Open WebUI can serve as a polished, full-featured chat interface for them with minimal setup. + +--- + +## How Is This Different from a Provider? + +When you [connect a provider](/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible), you're connecting to a **model**. It receives your message and returns a response. That's it. + +When you connect an **agent**, you're connecting to an autonomous system that can: + +- πŸ–₯️ **Run terminal commands** on your machine +- πŸ“ **Read and write files** in your workspace +- πŸ” **Search the web** for real-time information +- 🧠 **Maintain memory** across conversations +- 🧩 **Use skills and plugins** to extend its capabilities +- πŸ”— **Chain multiple tool calls** to solve complex tasks + +The agent decides when and how to use these tools based on your message, and Open WebUI displays the results in a familiar chat interface. + +--- + +## Available Agents + +| Agent | Description | Guide | +|-------|-------------|-------| +| **Hermes Agent** | Autonomous agent by Nous Research with terminal, file ops, web search, memory, and extensible skills | [Set up Hermes Agent β†’](./hermes-agent) | +| **OpenClaw** | Open-source self-hosted agent framework with shell access, file operations, web browsing, and messaging channel integrations | [Set up OpenClaw β†’](./openclaw) | + +--- + +## How It Works + +Regardless of which agent you connect, the architecture is the same: + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ β”‚ HTTP β”‚ β”‚ Tools β”‚ β”‚ +β”‚ Open WebUI │────────▢│ Agent Gateway │────────▢│ Terminal, β”‚ +β”‚ (frontend) │◀────────│ (API server) │◀────────│ Files, Web β”‚ +β”‚ β”‚ Stream β”‚ β”‚ Resultsβ”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +1. **You type a message** in Open WebUI +2. Open WebUI sends it to the agent's API server (just like it would to OpenAI) +3. The agent **decides which tools to use**, executes them, and reasons about the results +4. The final response **streams back** to Open WebUI with optional progress indicators +5. You see the response in the familiar chat interface, with full conversation history, user accounts, and all Open WebUI features + +:::tip +Because agents speak the standard OpenAI Chat Completions protocol, adding one is as simple as adding the URL and API key in **Admin Settings β†’ Connections β†’ OpenAI**. No plugins, no pipes, no middleware required. +::: diff --git a/docs/getting-started/quick-start/connect-an-agent/openclaw.mdx b/docs/getting-started/quick-start/connect-an-agent/openclaw.mdx new file mode 100644 index 0000000000..f6fe9f6a93 --- /dev/null +++ b/docs/getting-started/quick-start/connect-an-agent/openclaw.mdx @@ -0,0 +1,226 @@ +--- +sidebar_position: 2 +title: "OpenClaw" +--- + +# OpenClaw + +**Connect the OpenClaw autonomous agent framework to Open WebUI.** + +[OpenClaw](https://openclaw.ai) is an open-source, self-hosted autonomous AI agent framework. It gives your AI "hands": the ability to execute shell commands, read and write files, browse the web, and connect to messaging platforms like Telegram, Slack, and WhatsApp. + +OpenClaw provides an **OpenAI-compatible API endpoint**, making Open WebUI a natural choice for a polished chat frontend. There are two distinct ways to integrate: + +| Method | Best For | +|---|---| +| [**API Connection**](#method-1-api-connection) | Using Open WebUI as the full chat frontend for your OpenClaw agents | +| [**Channels Plugin**](#method-2-channels-plugin) | Having an OpenClaw bot participate alongside humans in Open WebUI Channels | + +:::info What You'll Need +- **OpenClaw** installed on your machine ([getting started](https://openclaw.ai)) +- **Node.js 22+** (24 recommended) +- **An API key** from a supported LLM provider (Anthropic, OpenAI, etc.) +- **Open WebUI** running (via Docker, pip, or desktop app) +- **~15 minutes** to complete this setup +::: + +--- + +## Method 1: API Connection + +Use Open WebUI as the primary chat interface for your OpenClaw agent. This is the simplest and most common approach. + +### Step 1: Install OpenClaw + +If you haven't installed OpenClaw yet: + +```bash +# macOS / Linux +curl -fsSL https://openclaw.ai/install.sh | bash + +# Windows (PowerShell) +iwr -useb https://openclaw.ai/install.ps1 | iex +``` + +Or install via npm: + +```bash +npm install -g openclaw@latest +``` + +Then run the onboarding wizard to configure your LLM provider and name your agent: + +```bash +openclaw onboard +``` + +### Step 2: Enable the OpenAI-Compatible API + +By default, the OpenAI-compatible endpoint is **disabled** for security. Enable it in your OpenClaw configuration file: + +```json title="~/.openclaw/openclaw.json (partial)" +{ + "gateway": { + "http": { + "endpoints": { + "chatCompletions": { + "enabled": true + } + } + } + } +} +``` + +If the gateway is already running, restart it for changes to take effect. + +### Step 3: Start the Gateway + +```bash +openclaw gateway +``` + +The gateway starts on port **18789** by default. Verify it's running: + +```bash +openclaw gateway status +``` + +### Step 4: Add the Connection in Open WebUI + +1. Open Open WebUI in your browser. +2. Go to βš™οΈ **Admin Settings** β†’ **Connections** β†’ **OpenAI**. +3. Click βž• **Add Connection**. +4. Enter the following: + +| Setting | Value | +|---|---| +| **URL** | `http://localhost:18789/v1` | +| **API Key** | Your OpenClaw Gateway bearer token | + +5. Click the βœ… checkmark to verify, then **Save**. + +:::tip Running Open WebUI in Docker? +Replace `localhost` with `host.docker.internal`: + +``` +http://host.docker.internal:18789/v1 +``` +::: + +### Step 5: Start Chatting! + +Your OpenClaw agent should now appear in the model dropdown. Select it and start chatting. The agent has full access to all its configured tools through Open WebUI's interface. + +:::tip Targeting Specific Agents +OpenClaw uses the model field to route to different agents: + +| Model ID | Routes To | +|---|---| +| `openclaw/default` | Your configured default agent | +| `openclaw/` | A specific named agent | + +If you have multiple agents configured, they'll each appear as separate "models" in the dropdown. +::: + +--- + +## Method 2: Channels Plugin + +:::warning Community Plugin + +The Channels plugin is a **community-contributed integration** and is not maintained by the Open WebUI or OpenClaw teams. Use at your own discretion and refer to the [plugin repository](https://github.com/skyzi000/openclaw-open-webui-channels) for support. + +::: + +Want your OpenClaw agent to participate in **Open WebUI Channels** as a bot user, reading messages, replying, and interacting alongside human users? Use the community Channels plugin. + +### Step 1: Create a Bot Account in Open WebUI + +1. Log into Open WebUI as an **Administrator**. +2. Go to **Admin Panel** β†’ **Users**. +3. Create a new user account for the bot (e.g., `openclaw-bot@yourdomain.com`). +4. Add this bot user to the channels you want it to monitor. + +:::note +Make sure **Channels** are enabled in your Open WebUI instance (**Admin Settings** β†’ **General**). +::: + +### Step 2: Install the Plugin + +In a secure chat session with your OpenClaw agent (via its built-in dashboard or terminal), say: + +> *"I want to use the Open WebUI Channels plugin: `https://github.com/skyzi000/openclaw-open-webui-channels`"* + +OpenClaw will automatically download and install the plugin. + +### Step 3: Configure the Connection + +Tell your OpenClaw agent: + +> *"I want to connect to Open WebUI Channels."* + +It will prompt you for the following: + +| Setting | What to Enter | +|---|---| +| **Base URL** | Your Open WebUI URL (e.g., `http://localhost:3000`) | +| **Email** | The bot account email from Step 1 | +| **Password** | The bot account password | +| **Channel IDs** | *(Optional)* Specific channel IDs to monitor, or leave blank for all | + +:::warning Security +Always configure credentials in a **private** chat environment. The plugin stores them in `~/.openclaw/openclaw.json` under the `channels.open-webui` section. +::: + +### Step 4: Verify + +Open a connected channel in Open WebUI and mention the bot by username (e.g., `@openclaw-bot`). If it responds, you're all set! + +--- + +## OpenClaw's Built-In Dashboard + +OpenClaw also includes its own **zero-installation** web dashboard for managing agents, viewing logs, and monitoring system resources: + +```bash +openclaw dashboard +``` + +This opens at `http://localhost:18789` by default. It's a great companion to Open WebUI. Use the dashboard for agent management and Open WebUI for conversations. + +--- + +## Troubleshooting + +### Connection refused + +- Ensure the gateway is running: `openclaw gateway status` +- Verify the port (default is `18789`, not `8000` or `11434`) +- Confirm you appended `/v1` to the URL + +### Verification fails but models don't load + +The URL must be exactly `http://localhost:18789/v1`. The `/v1` suffix is required for model discovery. + +### Docker networking issues + +If Open WebUI runs in Docker, `localhost` points to the container itself. Use `host.docker.internal` instead. On Linux without Docker Desktop: + +```bash +docker run --add-host=host.docker.internal:host-gateway ... +``` + +### Channels bot not responding + +- Verify the bot user has been added to the target channel +- Check that Channels are enabled in **Admin Settings** β†’ **General** +- Ensure the bot credentials are correct in the OpenClaw plugin config (`~/.openclaw/openclaw.json`) + +--- + +## Learn More + +- [OpenClaw Documentation](https://openclaw.ai) - Full docs, skills, and agent configuration +- [Channels Plugin (Community)](https://github.com/skyzi000/openclaw-open-webui-channels) - Plugin source and issues +- [Open WebUI Channels](/features/channels) - Learn more about the Channels feature diff --git a/docs/getting-started/quick-start/index.mdx b/docs/getting-started/quick-start/index.mdx index 080fd8b39c..612399ba33 100644 --- a/docs/getting-started/quick-start/index.mdx +++ b/docs/getting-started/quick-start/index.mdx @@ -167,7 +167,7 @@ The desktop app is a **work in progress** and is not yet stable. For production ::: -### Connect a model provider +### Connect a Model Provider Open WebUI needs at least one model provider to start chatting. Choose yours: @@ -180,7 +180,18 @@ Open WebUI needs at least one model provider to start chatting. Choose yours: | **llama.cpp** | [Starting with llama.cpp β†’](/getting-started/quick-start/connect-a-provider/starting-with-llama-cpp) | | **vLLM** | [Starting with vLLM β†’](/getting-started/quick-start/connect-a-provider/starting-with-vllm) | -### Explore features +### Connect an Agent + +Want more than a model? AI agents can execute terminal commands, read and write files, search the web, maintain memory, and chain complex workflows β€” all through Open WebUI's familiar chat interface. + +| Agent | Description | Guide | +|-------|-------------|-------| +| **Hermes Agent** | Autonomous agent by Nous Research with terminal, file ops, web search, memory, and extensible skills | [Set up Hermes Agent β†’](/getting-started/quick-start/connect-an-agent/hermes-agent) | +| **OpenClaw** | Open-source self-hosted agent with shell access, file operations, web browsing, and messaging integrations | [Set up OpenClaw β†’](/getting-started/quick-start/connect-an-agent/openclaw) | + +Learn more about how agents differ from providers in the [**Connect an Agent overview β†’**](/getting-started/quick-start/connect-an-agent) + +### Explore Features Once connected, explore what Open WebUI can do: [Features Overview β†’](/features) diff --git a/docs/intro.mdx b/docs/intro.mdx index ad03233daa..8609a27213 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -55,6 +55,15 @@ DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve Then open [http://localhost:8080](http://localhost:8080). + + + +Download the desktop app from [**github.com/open-webui/desktop**](https://github.com/open-webui/desktop). It runs Open WebUI natively on your system without Docker or manual setup. + +:::warning Experimental +The desktop app is a **work in progress** and is not yet stable. For production use, install via **Docker** or **Python**. +::: + @@ -63,7 +72,8 @@ Then open [http://localhost:8080](http://localhost:8080). ## Getting Started - [**Quick Start**](/getting-started/quick-start) β€” Docker, Python, Kubernetes install options -- [**Connect a Provider**](/getting-started/quick-start/connect-a-provider/starting-with-ollama) β€” Ollama, OpenAI, Anthropic, vLLM, and more +- [**Connect a Provider**](/getting-started/quick-start/connect-a-provider) β€” Ollama, OpenAI, Anthropic, vLLM, and more +- [**Connect an Agent**](/getting-started/quick-start/connect-an-agent) β€” Hermes Agent, OpenClaw, and other autonomous AI agents - [**Updating**](/getting-started/updating) β€” Keep your instance current - [**Development Branch**](/getting-started/quick-start) β€” Help test the latest changes before stable release - [**Advanced Topics**](/getting-started/advanced-topics) β€” Scaling, logging, and advanced configuration diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index c097d636ff..13ef9fb1fe 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -47,7 +47,7 @@ Connect Open WebUI to LLM providers, monitoring platforms, developer tools, and | [iTerm2](/tutorials/integrations/dev-tools/iterm2) | Query models from your macOS terminal | πŸ‘€ Developer Β· ⏱️ 10 min | | [Firefox Sidebar](/tutorials/integrations/dev-tools/firefox-sidebar) | Pin Open WebUI in Firefox's AI sidebar | πŸ‘€ User Β· ⏱️ 5 min | | [Browser Search Engine](/tutorials/integrations/dev-tools/browser-search-engine) | Add Open WebUI as a browser search engine | πŸ‘€ User Β· ⏱️ 5 min | -| [Notion (MCP)](/tutorials/integrations/mcp-notion) | Connect Notion via Model Context Protocol | πŸ‘€ User Β· ⏱️ 20 min | +| [Notion (MCP)](/tutorials/integrations/mcp-notion) | Connect Notion via Model Context Protocol | πŸ‘€ User Β· ⏱️ 5 min | | [OneDrive & SharePoint](/tutorials/integrations/onedrive-sharepoint) | Pull Microsoft 365 documents into Open WebUI | πŸ‘€ Admin Β· ⏱️ 30 min | | [LibreTranslate](/tutorials/integrations/libre-translate) | Add self-hosted translation capabilities | πŸ‘€ Admin Β· ⏱️ 15 min | diff --git a/docs/tutorials/integrations/index.md b/docs/tutorials/integrations/index.md index c088273d00..1bdb953274 100644 --- a/docs/tutorials/integrations/index.md +++ b/docs/tutorials/integrations/index.md @@ -46,6 +46,6 @@ These community-contributed guides cover specific integration scenarios with ste | Tutorial | What you'll achieve | Details | |----------|-------------------|---------| -| [Notion (MCP)](./mcp-notion) | Connect Notion as a knowledge source via Model Context Protocol | πŸ‘€ User Β· ⏱️ 20 min | +| [Notion (MCP)](./mcp-notion) | Connect Notion via Model Context Protocol | πŸ‘€ User Β· ⏱️ 5 min | | [OneDrive & SharePoint](./onedrive-sharepoint) | Pull Microsoft 365 documents into Open WebUI | πŸ‘€ Admin Β· ⏱️ 30 min | | [LibreTranslate](./libre-translate) | Add self-hosted translation capabilities | πŸ‘€ Admin Β· ⏱️ 15 min | diff --git a/docs/tutorials/integrations/mcp-notion.mdx b/docs/tutorials/integrations/mcp-notion.mdx index 4d8ed7083c..2545e657a9 100644 --- a/docs/tutorials/integrations/mcp-notion.mdx +++ b/docs/tutorials/integrations/mcp-notion.mdx @@ -2,49 +2,45 @@ title: Notion (MCP) sidebar_label: Notion MCP Integration sidebar_position: 50 -description: Connect Open WebUI to your Notion workspace using the Model Context Protocol (MCP) to search, read, and create pages with automatic Markdown conversion. Supports native Streamable HTTP or self-hosted setups via MCPO. -keywords: [notion, mcp, model context protocol, integration, productivity, tools, markdown, npx, docker, mcpo, local cli, streamable http, oauth] +description: Connect Open WebUI to your Notion workspace using Notion's hosted MCP endpoint. Search, read, create, and manage pages and databases with automatic Markdown conversion. +keywords: [notion, mcp, model context protocol, integration, productivity, tools, streamable http, oauth] --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - :::warning Community Contribution This tutorial is a community contribution and is not supported by the Open WebUI team. It serves as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the [contributing tutorial](/tutorials/contributing-tutorial/). ::: -This guide enables Open WebUI to interact with your Notion workspaceβ€”searching pages, reading content, creating docs, and managing databasesβ€”using the **Model Context Protocol (MCP)**. +Notion hosts a remote MCP server at `https://mcp.notion.com/mcp` that Open WebUI connects to natively via **Streamable HTTP**. Authentication is handled through Notion's OAuth flow β€” no API tokens, no proxies, no extra containers. -:::info Why this Integration? -This integration utilizes the official Notion MCP server, which specializes in **automatic Markdown conversion**. When the AI reads a Notion page, it receives clean, structured Markdown rather than raw JSON blocks, significantly improving the model's ability to understand and summarize your notes. -::: +## Setup +:::danger Prerequisite: WEBUI_SECRET_KEY +You **MUST** set the `WEBUI_SECRET_KEY` environment variable to a persistent value. Without it, your OAuth session breaks every time the container restarts, forcing re-authentication. See the [MCP feature docs](/features/extensibility/mcp) for details. +::: -## Method 1: Streamable HTTP (Recommended) +### 1. Add the tool -This method connects directly to Notion's hosted MCP endpoint (`https://mcp.notion.com/mcp`). It utilizes standard OAuth and is **natively supported** by Open WebUI without extra containers. +Go to **Admin Panel β†’ Settings β†’ External Tools** and click **+** to add a new connection. Fill in the following: -:::info Preferred Method -**Streamable HTTP** is preferred for its simplicity and enhanced security. It handles authentication via Notion's official OAuth flow, meaning you do not need to manually manage secrets or integration tokens. -::: +| Field | Value | +|-------|-------| +| **Type** | MCP Streamable HTTP | +| **URL** | `https://mcp.notion.com/mcp` | +| **Auth** | OAuth 2.1 | +| **ID** | `ntn` | +| **Name** | `Notion` | -:::danger Critical for OAuth Persistence -You **MUST** set the `WEBUI_SECRET_KEY` environment variable in your Docker setup to a persistent value. -If you do not, your Notion OAuth session will become invalid every time you restart the container, forcing you to re-authenticate repeatedly. -::: +Click **Register Client**, then **Save**. Use `OAuth 2.1 (Static)` if you have pre-created OAuth client credentials. -### 1. Configure Tool -You can automatically prefill the connection settings by importing the JSON configuration below. +
+Alternative: Import JSON -1. Navigate to **Admin Panel > Settings > External Tools**. -2. Click the **+** (Plus) button to add a new tool. -3. Click **Import** (top right of the modal). -4. Paste the following JSON snippet: +You can also click **Import** in the modal and paste this configuration: -```json title="Notion Remote MCP Configuration" +```json [ { "type": "mcp", @@ -57,371 +53,58 @@ You can automatically prefill the connection settings by importing the JSON conf "info": { "id": "ntn", "name": "Notion", - "description": "A note-taking and collaboration platform that allows users to create, organize, and share notes, databases, and other content." - } - } -] -``` - -`auth_type` can also be set to `oauth_2.1_static` if you are using pre-created OAuth client credentials instead of dynamic client registration. - -5. **Register:** Click the **Register Client** button (next to the Auth dropdown). -6. Click **Save**. - -![Open WebUI Tool Config: Shows the External Tools modal with the JSON imported and Register Client button highlighted.](/images/mcp-notion/notion-setup-step5.png) - -### 2. Authenticate & Grant Access -Once the tool is added, you must authenticate to link your specific workspace. - -1. Open any chat window. -2. Click the **+** (Plus) button in the chat input bar. -3. Navigate to **Integrations > Tools**. -4. Toggle the **Notion** switch to **ON**. - -![Chat Interface Toggle: Shows the chat input bar with the '+' menu open, 'Integrations' selected, and the 'Notion' tool toggled ON.](/images/mcp-notion/notion-setup-step6.png) - -5. **Authorize:** You will be redirected to a "Connect with Notion MCP" screen. - * Ensure the correct **Workspace** is selected in the dropdown. - * Click **Continue**. - -:::note Security: Frequent Re-authentication -For security reasons, Notion's OAuth session may expire after a period of inactivity or if you restart your Open WebUI instance. If this happens, you will see a `Failed to connect to MCP server 'ntn'` error. - -This is **intended behavior** by Notion to keep your workspace secure. To refresh your session, revisit the steps above to complete the "Connect with Notion MCP" authorization flow again. -::: - -![Notion OAuth Screen: Shows the 'Connect with Notion MCP' authorization page with the workspace dropdown selected.](/images/mcp-notion/notion-setup-step7.png) - ---- - -## Method 2: Self-Hosted via MCPO (Advanced) - -This method is for advanced users who prefer to run the MCP server locally within their own infrastructure using **MCPO**. Unlike Streamable HTTP, this method requires you to manually manage your own credentials. - -Direct local execution (stdio) of MCP servers is not natively supported in Open WebUI. To run the Notion MCP server locally (using Docker or Node.js) within your infrastructure, you must use **MCPO** to bridge the connection. - -:::info Prerequisites -To use this method, you must first create an internal integration to obtain a **Secret Key**. Please complete the **[Creating an Internal Integration](#creating-an-internal-integration)** section below before proceeding with the configuration steps here. -::: - -### 1. Configure MCPO -Follow the installation instructions in the [MCPO Repository](https://github.com/open-webui/mcpo) to get it running. Configure your MCPO instance to run the Notion server using one of the runtimes below by adding the JSON block to your `mcpo-config.json` file. - -**Note:** Replace `secret_YOUR_KEY_HERE` with the secret obtained from the [Creating an Internal Integration](#creating-an-internal-integration) section. - - - - This configuration uses the official Node.js package. - - ```json title="mcpo-config.json" - { - "mcpServers": { - "notion": { - "command": "npx", - "args": [ - "-y", - "@notionhq/notion-mcp-server" - ], - "env": { - "NOTION_TOKEN": "secret_YOUR_KEY_HERE" - } - } - } - } - ``` - - - This configuration uses the official Docker image. - - ```json title="mcpo-config.json" - { - "mcpServers": { - "notion": { - "command": "docker", - "args": [ - "run", - "--rm", - "-i", - "-e", - "NOTION_TOKEN", - "mcp/notion" - ], - "env": { - "NOTION_TOKEN": "secret_YOUR_KEY_HERE" - } - } - } - } - ``` - - - -### 2. Connect Open WebUI -Once MCPO is running and configured with Notion: - -1. Navigate to **Admin Panel > Settings > External Tools**. -2. Click the **+** (Plus) button. -3. Click **Import** (top right of the modal). -4. Paste the following JSON snippet (update the URL with your MCPO address): - -```json title="MCPO Connection JSON" -[ - { - "type": "openapi", - "url": "http://:/notion", - "spec_type": "url", - "spec": "", - "path": "openapi.json", - "auth_type": "none", - "info": { - "id": "notion-local", - "name": "Notion (Local)", - "description": "Local Notion integration via MCPO" + "description": "Search, read, create, and manage Notion pages and databases." } } ] ``` -5. Click **Save**. - ---- - -## Creating an Internal Integration - -Required for **Method 2**, creating an internal integration within Notion ensures you have the necessary credentials and permission scopes readily available. - -### 1. Create Integration -1. Navigate to **[Notion My Integrations](https://www.notion.so/my-integrations)**. -2. Click the **+ New integration** button. -3. Fill in the required fields: - * **Integration Name:** Give it a recognizable name (e.g., "Open WebUI MCP"). - * **Associated workspace:** Select the specific workspace you want to connect. - * **Type:** Select **Internal**. - * **Logo:** Uploading a logo is optional but helps identify the integration. -4. Click **Save**. - -:::info Important: Integration Type -You **must** select **Internal** for the integration type. Public integrations require a different OAuth flow that is not covered in this guide. -::: - -![Notion Integration Setup Form: Shows the 'New Integration' screen with Name filled, Workspace selected, and 'Type' set to Internal.](/images/mcp-notion/notion-setup-step1.png) - -### 2. Configure Capabilities & Copy Secret -Once saved, you will be directed to the configuration page. -1. **Copy Secret:** Locate the **Internal Integration Secret** field. Click **Show** and copy this key. You will need it for MCPO configuration. -2. **Review Capabilities:** Ensure the following checkboxes are selected under the "Capabilities" section: - * βœ… **Read content** - * βœ… **Update content** - * βœ… **Insert content** - * *(Optional)* Read user information including email addresses. -3. Click **Save changes** if you modified any capabilities. - -:::warning Security: Risk to Workspace Data -While the Notion MCP server limits the scope of the API (e.g., databases cannot be deleted), exposing your workspace to LLMs carries a **non-zero risk**. -**Security-conscious users** can create a safer, **Read-Only** integration by unchecking **Update content** and **Insert content**. The AI will be able to search and answer questions based on your notes but will be physically unable to modify or create pages. -::: - -:::danger Secret Safety -Your **Internal Integration Secret** allows access to your Notion data. Treat it like a password. Do not share it or commit it to public repositories. -::: - -![Notion Capabilities Config: Shows the Internal Integration Secret revealed and the three content capability checkboxes selected.](/images/mcp-notion/notion-setup-step2.png) - -### 3. Grant Page Access (Manual) - -:::danger Critical Step: Permissions -By default, your new internal integration has **zero access** to your workspace. It cannot see *any* pages until you explicitly invite it. If you skip this step, the AI will return "Object not found" errors. -::: - -You can grant access centrally or on a per-page basis. - -#### Method A: Centralized Access (Recommended) -Still in the Notion Integration dashboard: -1. Click the **Access** tab (next to Configuration). -2. Click the **Edit access** button. -3. A modal will appear allowing you to select specific pages or "Select all" top-level pages. -4. Check the pages you want the AI to read/edit and click **Save**. - -![Notion Access Tab: Shows the 'Manage page access' modal where specific pages like 'To Do List' are being selected for the integration.](/images/mcp-notion/notion-setup-step3.png) - -#### Method B: Page-Level Access -1. Go to a specific Notion Page or Database you want the AI to access. -2. Click the **...** (three dots) menu in the top right corner of the page. -3. Select **Connections** (in the "Add connections" section). -4. Search for your integration name (e.g., "Open WebUI MCP") and click **Connect**. -5. *You must repeat this for every root page or database you want the AI to be able to search or edit.* - -![Notion Page Connection: Shows a Notion page with the '...' menu open, the 'Connect' submenu active, and the integration being selected.](/images/mcp-notion/notion-setup-step4.png) - ---- - -## Configuration: Always On (Optional) - -By default, users must toggle the tool **ON** in the chat menu. You can configure a specific model to have Notion access enabled by default for every conversation. - -1. Go to **Workspace > Models**. -2. Click the **pencil icon** to edit a model. -3. Scroll down to the **Tools** section. -4. Check the box for **Notion**. -5. Click **Save & Update**. - -## Building a Specialized Notion Agent (Optional) - -For the most reliable experience, we recommend creating a dedicated "Notion Assistant" model. This allows you to provide a specialized **System Prompt**, a helpful **Knowledge Base**, and quick-start **Prompt Suggestions** that teaches the model how to navigate Notion's structure. - -### Step 1: Create a Knowledge Base for the Agent -First, create a knowledge base with the official Notion MCP documentation. This will help the model understand its own capabilities. - -1. **Navigate to Knowledge:** Go to **Workspace > Knowledge**. -2. **Create New Knowledge Base:** Click the **+ New Knowledge** button. -3. **Fill in Details:** - * **Name:** `Notion MCP Docs` - * **Description:** `Official documentation for Notion's MCP tools to improve agent accuracy.` -4. Click **Create Knowledge**. - -![Create Knowledge Base Form: Shows the form with 'Notion MCP Docs' as the name and a relevant description.](/images/mcp-notion/notion-setup-step8.png) - -5. **Upload Content:** - * Save the content from the [Notion MCP Documentation](https://developers.notion.com/docs/mcp-supported-tools) as a PDF or `.txt` file. - * Inside your new knowledge base, click the **+ Add Content** button and upload the file you saved. - -:::tip Recommended: Optimize with Jina Reader -For optimal RAG performance, we recommend converting web documentation into clean Markdown. You can use **[Jina Reader](https://github.com/jina-ai/reader)** (or the hosted `https://r.jina.ai/` API) to strip clutter and format the page specifically for LLMs. - -Simply visit `https://r.jina.ai/https://developers.notion.com/docs/mcp-supported-tools`, copy the output, and save it as a `.md` file to upload. -::: - -![Knowledge Base Content View: Shows the 'Notion MCP Docs' knowledge base with the documentation file successfully uploaded.](/images/mcp-notion/notion-setup-step9.png) - -### Step 2: Create the Custom Model -Now, create the dedicated agent and attach the knowledge base you just made. - -1. Go to **Workspace > Models > Create a Model**. -2. **Name:** `Notion Assistant` -3. **Description:** `An intelligent agent that manages your Notion workspace using MCP tools to search, read, and create content.` -4. **Base Model:** Select your preferred local LLM (e.g., Llama 3.1). -5. **Tools:** Enable **Notion**. -6. **System Prompt:** Paste the following optimized prompt: - -
-Click to view Optimized System Prompt - -```markdown -You are the Notion Workspace Manager, an intelligent agent connected directly to the user's Notion workspace via the Model Context Protocol (MCP). Your goal is to help the user organize, retrieve, and generate content within their personal knowledge base. - -### CRITICAL OPERATIONAL RULES: - -1. **SEARCH IS MANDATORY:** - - You cannot interact with a page or database without its unique ID or URL. - - If the user refers to a page by name (e.g., "Add this to my Todo list"), you MUST first run `notion-search` to find the correct page and retrieve its ID or URL. - - NEVER guess a Page ID. - - If a search returns multiple results (e.g., two pages named "Meeting Notes"), ask the user to clarify which one to use before proceeding. - -2. **READ BEFORE ANSWERING:** - - If the user asks a question about their data (e.g., "What is the status of Project Alpha?"), do not answer from your internal training data. - - First `notion_search` for the relevant page, then `notion-read-page` to get the content, and finally answer based *strictly* on the tool output. - - Note: Page content is returned to you as Markdown. Preserve this structure in your response. - -3. **CREATION PROTOCOLS:** - - When asked to create a page (`notion-create-page`), you must identify a Parent Page ID. - - If the user does not specify a location, search for a logical parent page (like "Dashboard", "Projects", or "Notes") or ask the user where to put it. - -4. **CONTENT FORMATTING:** - - When appending content (`notion-append-block`) or creating pages, use clean Markdown. - - Structure complex information with headers, bullet points, and checkboxes to utilize Notion's block structure effectively. - -### ERROR HANDLING: -- If a tool returns "Object not found" or an empty search result, inform the user: "I cannot see that page. Please ensure you have connected it to the Open WebUI integration via the '...' menu > Connections in Notion." - -### BEHAVIORAL PERSONA: -- Be concise and action-oriented. -- Confirm actions after completion (e.g., "βœ… I have added that task to your 'Tasks' database."). -- If you are analyzing a large amount of text from a Notion page, provide a structured summary unless asked for specific details. -```
-7. **Attach Knowledge Base:** - * In the **Knowledge** section, click **Select Knowledge**. - * In the modal that appears, find and select the **Notion MCP Docs** knowledge base you created in Step 1. - -:::warning Performance Tuning -While the knowledge base helps the model understand Notion's capabilities, injecting large amounts of documentation can sometimes interfere with tool calling on smaller models (overloading the context). - -If you notice the model failing to call tools correctly or hallucinating parameters, **detach the knowledge base** and rely solely on the System Prompt provided above. -::: - -8. **Add Prompt Suggestions:** - -Under the **Prompts** section, click the **+** button to add a few helpful starting prompts. - -| # | Title | Subtitle | Prompt | -|---|----------------------|--------------------------|-----------------------------------------------------------------------------------------------------------| -| 1 | Search my workspace | for a specific page | Search Notion for my **'Project Roadmap'** page. | -| 2 | Summarize a page | after finding it first | First, search for the **'Onboarding Guide'** page, then read its content and give me a summary. | -| 3 | Add a new task | to my main to‑do list | Find my **'To‑Do List'** page and add a new task: **β€œFollow up with the design team.”** | +![External Tools modal with the Notion MCP configuration imported.](/images/mcp-notion/notion-setup-step5.png) -![Model Prompts Config: Shows the 'Default Prompt Suggestions' section with examples filled in.](/images/mcp-notion/notion-setup-step10.png) +### 2. Authorize -9. Finally, **Save & Update** the model. +In any chat, open **+ β†’ Integrations β†’ Tools** and toggle **Notion** on. You'll be redirected to Notion's OAuth flow β€” select your workspace and grant access. -![Model Creation Screen: Shows the model settings with Name 'Notion Assistant', description, and the Notion System Prompt filled out.](/images/mcp-notion/notion-setup-step11.png) +![Chat input bar with Notion tool toggled on.](/images/mcp-notion/notion-setup-step6.png) -## Supported Tools +![Notion OAuth authorization screen.](/images/mcp-notion/notion-setup-step7.png) -:::tip Workflow Best Practice -LLMs cannot "browse" Notion like a human. For most actions, the model first needs to know the **Page ID or URL**. Always ask the model to **search** for a page first before asking it to read or modify it. +:::warning OAuth 2.1 tools cannot be pre-enabled +Do **not** set this as a default tool on a model. OAuth 2.1 requires an interactive browser redirect that cannot happen mid-request. Users must enable it manually per-chat via the **+** button. See [MCP docs](/features/extensibility/mcp) for details. ::: -This integration supports a wide range of tools for searching, reading, creating, and updating Notion pages and databases. +:::note Re-authentication +Notion's OAuth session may expire after inactivity or container restarts. If you see `Failed to connect to MCP server 'ntn'`, re-toggle the tool in any chat to trigger the authorization flow again. +::: -For a complete list of available tools, their descriptions, and specific usage examples, please refer to the **[official Notion MCP documentation](https://developers.notion.com/docs/mcp-supported-tools)**. -## Rate Limits -Standard [API request limits](https://developers.notion.com/reference/request-limits) apply to your use of Notion MCP, totaled across all tool calls. +## Rate limits -- **General Limit:** Average of **180 requests per minute** (3 requests per second). -- **Search-Specific Limit:** **30 requests per minute**. +Standard [Notion API limits](https://developers.notion.com/reference/request-limits) apply: -:::warning Rate Limits -If you encounter rate limit errors, prompt your model to reduce the number of parallel searches or operations. For example, instead of "Search for A, B, and C," try asking for them sequentially. -::: +- **General:** 180 requests per minute +- **Search:** 30 requests per minute ## Troubleshooting -### Connection Errors - -#### `Failed to connect to MCP server 'ntn'` +### `Failed to connect to MCP server 'ntn'` -![MCP Connection Error: Shows a red error message in the chat 'Failed to connect to MCP server 'ntn'.](/images/mcp-notion/notion-setup-step12.png) +Your OAuth session has expired. Re-toggle the Notion tool in any chat (**+** β†’ **Integrations β†’ Tools**) to re-authorize. -* **Cause:** This usually indicates that your OAuth session with Notion has expired or the token needs a refresh. This often occurs after restarting Open WebUI or after a period of inactivity. -* **Fix:** - 1. Open any chat. - 2. Click the **+** (Plus) button > **Integrations > Tools**. - 3. Toggle the **Notion** switch **ON**. - 4. This will trigger the redirect to Notion's authorization page to complete the "Connect with Notion MCP" authorization flow again. - 5. Once authorized successfully, the connection will work across all chats again, including for models with the tool enabled by default. +![Failed to connect to MCP server error in chat.](/images/mcp-notion/notion-setup-step12.png) -#### `OAuth callback failed: mismatching_state` -![OAuth Error Toast: Shows the red error notification 'OAuth callback failed: mismatching_state: CSRF Warning! State not equal in request and response'.](/images/mcp-notion/notion-setup-step13.png) +### `OAuth callback failed: mismatching_state` -* **Cause:** You are likely accessing Open WebUI via `localhost` (e.g., `http://localhost:3000`), but your instance is configured with a public domain via the `WEBUI_URL` environment variable (e.g., `https://chat.mydomain.com`). The OAuth session state created on `localhost` is lost when the callback redirects to your public domain. -* **Fix:** Access your Open WebUI instance using the **exact URL** defined in `WEBUI_URL` (your public domain) and perform the setup again. **Do not use `localhost` for OAuth setups if a domain is configured.** +You're accessing Open WebUI via `localhost`, but `WEBUI_URL` is set to a public domain. Access your instance using the **exact URL** from `WEBUI_URL` and authorize again. -### Usage Errors +![OAuth callback mismatching_state error.](/images/mcp-notion/notion-setup-step13.png) -#### `Object not found` -* **Cause:** The Integration Token is valid, but the specific page has not been shared with the integration. -* **Fix:** In Notion, go to your Integration settings > **Access** tab and ensure the page is checked, or visit the page directly and check the **Connections** menu to ensure your integration is listed and selected. +### `Object not found` -#### `Tool execution failed` (Local Method) -* **Cause:** Open WebUI is unable to execute the local command (npx/docker) because it is missing from the container, or the configuration is incorrect. -* **Fix:** Native local execution is not supported. Ensure you are using **MCPO** (Method 2) to bridge these commands, rather than entering them directly into Open WebUI's config, or switch to **Method 1 (Streamable HTTP)** in the Configuration section above. This runs on Notion's servers and requires no local dependencies. +The page hasn't been shared with the integration. During the OAuth flow, Notion asks which pages to grant access to β€” make sure the relevant pages are selected. You can update access anytime from your [Notion integrations settings](https://www.notion.so/profile/integrations). -#### `missing_property` when creating a page -* **Cause:** The model is trying to create a page without specifying a **Parent ID**. Notion requires every page to exist inside another page or database. -* **Fix:** Instruct the model in your prompt: *"Search for my 'Notes' page first, get its ID, and create the new page inside there."* +### `missing_property` when creating a page -#### `RateLimitedError` (429) -* **Cause:** You have exceeded Notion's API limits (approx. 3 requests/second). -* **Fix:** Ask the model to perform actions sequentially rather than all at once (e.g., "Search for X, then wait, then search for Y"). +Notion requires a parent page or database. Tell the model: *"Search for my 'Notes' page first, then create the new page inside it."* diff --git a/static/images/mcp-notion/notion-setup-step1.png b/static/images/mcp-notion/notion-setup-step1.png deleted file mode 100644 index cbf038f985..0000000000 Binary files a/static/images/mcp-notion/notion-setup-step1.png and /dev/null differ diff --git a/static/images/mcp-notion/notion-setup-step10.png b/static/images/mcp-notion/notion-setup-step10.png deleted file mode 100644 index ff5a359f89..0000000000 Binary files a/static/images/mcp-notion/notion-setup-step10.png and /dev/null differ diff --git a/static/images/mcp-notion/notion-setup-step11.png b/static/images/mcp-notion/notion-setup-step11.png deleted file mode 100644 index f3744ea6cc..0000000000 Binary files a/static/images/mcp-notion/notion-setup-step11.png and /dev/null differ diff --git a/static/images/mcp-notion/notion-setup-step2.png b/static/images/mcp-notion/notion-setup-step2.png deleted file mode 100644 index e28f65821a..0000000000 Binary files a/static/images/mcp-notion/notion-setup-step2.png and /dev/null differ diff --git a/static/images/mcp-notion/notion-setup-step3.png b/static/images/mcp-notion/notion-setup-step3.png deleted file mode 100644 index a893fd9eea..0000000000 Binary files a/static/images/mcp-notion/notion-setup-step3.png and /dev/null differ diff --git a/static/images/mcp-notion/notion-setup-step4.png b/static/images/mcp-notion/notion-setup-step4.png deleted file mode 100644 index 6d1189e2f5..0000000000 Binary files a/static/images/mcp-notion/notion-setup-step4.png and /dev/null differ diff --git a/static/images/mcp-notion/notion-setup-step8.png b/static/images/mcp-notion/notion-setup-step8.png deleted file mode 100644 index f06179c600..0000000000 Binary files a/static/images/mcp-notion/notion-setup-step8.png and /dev/null differ diff --git a/static/images/mcp-notion/notion-setup-step9.png b/static/images/mcp-notion/notion-setup-step9.png deleted file mode 100644 index 4c7e0ee4d3..0000000000 Binary files a/static/images/mcp-notion/notion-setup-step9.png and /dev/null differ