Initial Commit

2026-09-15 15:24:03 -04:00
commit 4dc7086e7e
605 changed files with 101380 additions and 0 deletions
@@ -0,0 +1,82 @@
+# Registering it in Open WebUI
+
+Two steps, both by hand, and the second is the one people skip.
+
+## 1. The tool connection
+
+**Admin Panel → Settings → Integrations.**
+
+> Not *Settings → Tools* in your own profile. That adds the connection for **you only**, and
+> every other account sees an assistant with no tools and no explanation. It is the single
+> most common setup mistake here.
+
+| Field | Value |
+|---|---|
+| Type | OpenAPI |
+| URL | `http://owuitools-gw:8000` |
+| Auth | **Bearer**, and your `OWUITOOLS_AUTH_TOKEN` |
+| Name | anything |
+| Visibility | Public |
+
+`owuitools-gw` resolves because the gateway container joins `openwebui_default`. It is the
+only container in this project that does — everything else sits on an internal network with
+no route out except through squid. If your Open WebUI is elsewhere, publish the gateway's
+port and use the host address.
+
+Save. Open WebUI fetches the spec; you should see **22 tools**.
+
+### Re-save it after any schema change
+
+Open WebUI caches the spec from when the connection was saved. Adding a tool, switching one
+off in `configs/tools.toml`, or editing a docstring all need:
+
+```sh
+docker compose restart api
+```
+
+…and then **Save** on the connection again. Without that you keep the old list.
+
+## 2. The model
+
+**Workspace → Models → your model → Edit.**
+
+- **System prompt**: paste
+  [`../configs/assistant/system-prompt.md`](../configs/assistant/system-prompt.md).
+- **Tools**: enable the connection.
+- **Function Calling**: **Default**. Not Legacy — Legacy reformats the tool definitions in a
+  way that loses the request-body schema, which is where the enums and defaults live.
+- **Advanced Params**: `num_ctx` must match what Ollama actually loaded, or it reloads the
+  model mid-conversation. See [advanced-params.md](advanced-params.md).
+
+**The system prompt is doing most of the work.** The tool descriptions alone do not produce
+using tools instead of recalling, checking rather than asserting, or saying "I don't know".
+
+## 3. Forward the user headers
+
+On the Open WebUI container:
+
+```yaml
+ENABLE_FORWARD_USER_INFO_HEADERS: "True"
+```
+
+The tool server keys its per-user rate limits off `X-OpenWebUI-User-Id`, and the VM
+sub-agent's live view needs the chat id. Without it the limiter treats every request as the
+same anonymous caller and the live view silently does nothing.
+
+## Trimming the tool list
+
+Open WebUI has a **Function Name Filter List** on the connection, which hides tools from one
+model. It is the wrong lever for this: the spec is still fetched, the endpoint still
+answers, and the setting lives in Open WebUI's database where you cannot read it.
+
+Use [`../configs/tools.toml`](../configs/tools.toml) instead. It removes the tool, so you
+stop paying its schema tokens on every turn.
+
+## Checking it worked
+
+Ask something a tool should answer and recall should not:
+
+> what's the current version of ripgrep?
+
+You should see a `lookup_package` call. If the model answers from memory, check Function
+Calling is Default and the system prompt was actually pasted.