108 lines
5.4 KiB
Markdown
108 lines
5.4 KiB
Markdown
# Operating it
|
|
|
|
## Logs
|
|
|
|
**Every component writes its own file into [`../logs/`](../logs/README.md)** — one place to
|
|
look rather than working out which compose invocation you wanted:
|
|
|
|
```sh
|
|
tail -f logs/api.log # tool calls and errors
|
|
tail -f logs/egress.access.log # every outbound request, with allow/deny
|
|
tail -f logs/searxng.log # which search engines are refusing
|
|
```
|
|
|
|
Nothing is hidden from Docker by this — it all still goes to stdout, so
|
|
`docker compose logs -f api` works exactly as before.
|
|
|
|
`logs/egress.access.log` is the audit trail of everything the assistant fetched and on whose
|
|
behalf. `TCP_DENIED/403` lines are the guard working, not a fault.
|
|
|
|
The VM daemon is the exception: it is a systemd service rather than part of this stack, so
|
|
it logs to the journal — `sudo journalctl -u owuivmd -f`.
|
|
|
|
For a VM session, the logs to read are the session transcripts — see
|
|
[vm-agent/troubleshooting.md](vm-agent/troubleshooting.md).
|
|
|
|
## Rate limits
|
|
|
|
`dns_lookup`, `inspect_tls`, `http_headers` and `lookup_ip_or_asn` each cost one unit of a
|
|
per-user hourly budget: `OWUITOOLS_PROBE_RATE_PER_HOUR`, default 30, keyed on the
|
|
`X-OpenWebUI-User-Id` header Open WebUI forwards. Set it to `0` to disable the limiter.
|
|
|
|
squid is what makes these tools *safe*; the budget only keeps them polite. Bounding how much
|
|
scanning one account can drive is the point, not preventing abuse — the private-range block
|
|
does that.
|
|
|
|
## Caching is load-bearing
|
|
|
|
It is not an optimisation. Stack Exchange allows 300 calls/day/IP without a key and GitHub
|
|
60/hour, and those budgets are shared by **every user of the assistant at once**. Without the
|
|
cache, one enthusiastic conversation exhausts the day for everyone.
|
|
|
|
Clear it after changing a tool that shapes its output:
|
|
|
|
```sh
|
|
docker exec owuitools-valkey valkey-cli --scan --pattern 'owuitools:*' | \
|
|
xargs -r docker exec -i owuitools-valkey valkey-cli del
|
|
```
|
|
|
|
If valkey is down the tools still work — the cache fails open, with a warning in the log.
|
|
|
|
## Restarting things
|
|
|
|
```sh
|
|
docker compose restart api # after editing configs/tools.toml
|
|
docker compose restart vmagent # after editing anything in configs/agent/
|
|
docker compose up -d --build # after changing code
|
|
```
|
|
|
|
**Restarting `netguard` or `vmguard` strands the containers that share their network
|
|
namespace.** `api` and `searxng` live in netguard's; `vmagent` lives in vmguard's. Docker
|
|
does not re-attach them, so they keep running, keep passing their own healthchecks — which
|
|
are loopback calls — and have no route to anything at all.
|
|
|
|
```sh
|
|
docker compose up -d --force-recreate netguard api searxng
|
|
docker compose up -d --force-recreate vmguard vmagent
|
|
```
|
|
|
|
## After changing the tool list
|
|
|
|
`docker compose restart api`, **then re-save the connection in Open WebUI.** It caches the
|
|
spec from when the connection was saved, so without the second step you keep the old list.
|
|
|
|
## Known constraints
|
|
|
|
Two of these are about one machine's egress IP and may simply not be true for yours — they
|
|
are recorded because the reasoning behind a configuration choice is worth more than the
|
|
choice.
|
|
|
|
- **arXiv's API rate-limits some datacentre IPs** to a hard 429, verified through three
|
|
separate paths, so it is the address rather than the request. `search_papers` uses
|
|
OpenAlex, which indexes arXiv anyway and allows 100k requests/day keyless.
|
|
- **Some search engines serve datacentre IPs a CAPTCHA.** The engine list in
|
|
`configs/services/searxng.settings.yml` reflects what was observed from one address; if
|
|
results are thin, that list is the first thing to change. General searches deliberately
|
|
fan out across several engines so no single one is a point of failure.
|
|
- **No keyless datasheet API exists.** Octopart, Nexar, DigiKey and Mouser all require
|
|
credentials. `find_datasheet` tries manufacturer URL patterns first, then a PDF-scoped
|
|
search.
|
|
- **PyMuPDF is deliberately not used**, despite being faster. It is AGPL-3.0, and section
|
|
13's network clause is a live concern for a tool server other people reach over a network.
|
|
`pypdf` (BSD) and `pdfminer.six` (MIT) cover it.
|
|
- **Scanned datasheets** — older parts, mostly — have no text layer and cannot be read
|
|
without OCR. `fetch_page` says so rather than returning garbage.
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Cause |
|
|
|---|---|
|
|
| "Connection failed" when adding the server | Added under **personal** Settings → Integrations rather than **Admin Panel** → Settings → Integrations. A personal tool server is fetched by your browser, which cannot resolve `owuitools-gw`. |
|
|
| The model never calls tools | System prompt not pasted, connection not enabled on the model, or Function Calling set to Legacy instead of Default. |
|
|
| Tools vanish after a rebuild | The spec is cached — re-save the connection. |
|
|
| The model answers from memory | `num_ctx` still at Ollama's 4096 default, silently truncating the tool definitions out of the prompt. |
|
|
| `FAILED: ... refused by the egress proxy` | Working as intended: a private address was requested. Check `docker compose logs egress`. |
|
|
| Thin search results | Rate-limited or blocked engines — `docker compose logs searxng`. `web_search` also reports them to the model. |
|
|
| `wikipedia_lookup` returns 403 | `OWUITOOLS_CONTACT` is unset. See [setup/contact.md](setup/contact.md). |
|
|
| Everything is "Up" and nothing is reachable | A namespace owner was recreated without its dependents — see above. |
|