open-webui — Agent Guide

No conflict-matrix pairs for this tool yet.

# Open WebUI — Agent Guide

name: open-webui ｜ version_range: 0.11.1~0.11.3 ｜ generated: 2026-09-01

title_en: Open Web UI - Web chat UI for local LLMs (Ollama) ｜ desc_en: Browser-based chat interface for local LLMs; manages models, conversations and local RAG knowledge bases on top of Ollama.

Preflight

note: Docker required for the image form; pip form requires Python 3.11~3.12 only (verified 3.14 fails). Ollama should be running for chat to work.

`agent

docker --version

python3 --version

curl -s --max-time 3 http://localhost:11434/api/tags | head -c 100

>>>

预期输出: see command output

Install

note: mainland-China verified: ghcr.nju.edu.cn image prefix (verified 2026-08-30/09-01); pip form needs Python 3.11/3.12 + Tsinghua PyPI mirror.

`agent

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway \

-v open-webui:/app/backend/data --name open-webui --restart always \

ghcr.nju.edu.cn/open-webui/open-webui:main

>>>

预期输出: a container ID (e.g. 5e7e82f26c89..., verified 2026-09-01); docker ps shows Up, healthy after ~1-2 min

note: pip form (only with Python 3.11/3.12): pip install open-webui --index-url https://pypi.tuna.tsinghua.edu.cn/simple && open-webui serve (not tested on this machine; Python 3.14 blocked)

Operations

Verify health

note: wait for container health to become healthy first; brief unhealthy during init is normal.

`agent

docker inspect open-webui --format '{{.State.Health.Status}}'

curl -s http://localhost:3000/health

>>>

预期输出: healthy; {"status":true} (verified http 200 2026-09-01)

Register admin (first user) and sign in

note: first registered user becomes admin automatically (verified).

`agent

curl -s -X POST http://localhost:3000/api/v1/auths/signup -H "Content-Type: application/json" -d '{"name":"tester","email":"you@example.com","password":"your-password","role":"admin"}'

curl -s -X POST http://localhost:3000/api/v1/auths/signin -H "Content-Type: application/json" -d '{"email":"you@example.com","password":"your-password"}'

>>>

预期输出: signup returns {"id":"...","role":"admin","token":"eyJ..."}; signin returns the same shape (token len 247, verified)

List models via open-webui

note: requires the token from signin as Authorization: Bearer <token>.

`agent

curl -s http://localhost:3000/api/models -H "Authorization: Bearer <token>"

>>>

预期输出: {"data":[{"id":"qwen2.5-0.5b:latest","owned_by":"ollama",...}]} (verified)

Chat completion (full chain through Ollama)

note: model name must exist in the Ollama instance connected to open-webui.

`agent

curl -s http://localhost:3000/api/chat/completions -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"model":"qwen2.5-0.5b:latest","messages":[{"role":"user","content":"Say OK"}],"stream":false}'

>>>

预期输出: chat.completion JSON, choices[0].message.content is the model reply (verified "OK, thank you.")

Check version

`agent

curl -s http://localhost:3000/api/version

>>>

预期输出: {"version":"0.11.1","deployment_id":""} (verified; GitHub latest v0.11.3 2026-08-31)

Reset admin password

note: problem-lane reproduced 2026-08-30; run inside the container.

`agent

docker exec -it open-webui python -c "from open_webui.utils.auth import update_password_by_email; update_password_by_email('you@example.com','new-password')"

>>>

预期输出: no output, exit 0

Uninstall

note: data lives in volume open-webui; volume removal is destructive (accounts, chats, knowledge base).

`agent

docker stop open-webui

docker rm open-webui

docker volume rm open-webui

>>>

预期输出: no output for stop/rm (exit 0); volume removal prints the volume name

Facts

writes: Docker volume open-webui (/app/backend/data: webui.db, uploads/, vector_db/) ｜ runtime: Docker container, port 8080 inside (host mapping example 3000); pip form: uvicorn on 8080 ｜ notes: does NOT run models itself — requires Ollama reachable via OLLAMA_BASE_URL (default host.docker.internal:11434, verified 172.17.0.1 from container); license = Open WebUI License (BSD-3 base + branding clause: rebranding limited to <=50 end users per rolling 30 days without written/enterprise permission); API key = signin/signup token, no external key needed for local Ollama

Source: open-webui · validated 2026-09-01 · v0.11.1~0.11.3

← Agent index