Connect OpenClaw to Open WebUI: Step-by-Step Guide

What is Open WebUI?

Open WebUI (formerly Ollama WebUI) is a self-hosted, open-source web interface for interacting with large language models. It provides a ChatGPT-like experience that runs entirely on your own infrastructure. You get a clean chat interface with conversation history, model switching, system prompts, file uploads, and multi-user support.

Open WebUI was originally designed to work with Ollama, but it now supports any OpenAI-compatible API endpoint. This makes it compatible with a wide range of backends, including LiteLLM proxies that can translate between different provider formats. It is written in Python (backend) and Svelte (frontend), runs in Docker, and is actively maintained with frequent releases.

Key features that make Open WebUI relevant for OpenClaw users:

Why Connect OpenClaw to Open WebUI

OpenClaw is CLI-first by design. You interact with agents through terminal commands like openclaw agent --agent orion --message "status report". This is fast and scriptable, but it is not ideal for every situation.

Open WebUI solves three specific pain points that OpenClaw CLI users run into:

First, team access. Not everyone on your team is comfortable in a terminal. Product managers, designers, and non-technical stakeholders need a way to interact with your agents without learning CLI commands. Open WebUI gives them a familiar chat interface in their browser.

Second, conversation continuity. OpenClaw sessions are stored in JSON files under ~/.openclaw/agents/[name]/sessions/. These work, but browsing and searching past conversations is not as ergonomic as a web interface with a sidebar showing your full chat history.

Third, mobile and remote access. If your OpenClaw agents run on a home server or VPS, Open WebUI lets you interact with them from any device with a browser. No SSH required.

The important distinction: you are not replacing OpenClaw with Open WebUI. OpenClaw continues to manage your agent identities (SOUL.md), team coordination (AGENTS.md), scheduled tasks (HEARTBEAT.md), and messaging integrations (Telegram, Slack, Discord). Open WebUI adds a visual chat layer on top of the same model backend that your OpenClaw agents already use.

Prerequisites

Before you start, make sure you have the following installed and running:

Step 1: Install Open WebUI with Docker

The fastest way to get Open WebUI running is with Docker. One command pulls the image and starts the container.

Option A: Connect to local Ollama

If you already have Ollama running on your machine (which most OpenClaw users do for local models), use this command:

# Pull and run Open WebUI connected to local Ollama
docker run -d \
  --name open-webui \
  --network host \
  -v open-webui:/app/backend/data \
  -e OLLAMA_BASE_URL=http://localhost:11434 \
  -p 3000:8080 \
  ghcr.io/open-webui/open-webui:main

# Verify it is running
docker ps | grep open-webui

# Open in browser
# http://localhost:3000

The --network host flag allows the container to access Ollama running on localhost. On macOS, replace localhost with host.docker.internal because Docker on macOS runs in a VM.

Option B: Standalone without Ollama

If your OpenClaw agents use Anthropic or OpenAI (not Ollama), you can run Open WebUI in standalone mode and connect it to those providers through an OpenAI-compatible proxy:

# Run Open WebUI in standalone mode (no Ollama)
docker run -d \
  --name open-webui \
  -v open-webui:/app/backend/data \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:4000/v1 \
  -e OPENAI_API_KEY=sk-your-key \
  -p 3000:8080 \
  ghcr.io/open-webui/open-webui:main

The OPENAI_API_BASE_URL points to wherever your OpenAI-compatible API is running. If you use LiteLLM as a proxy (covered in the next section), that would be http://host.docker.internal:4000/v1.

Step 2: Provider JSON Configuration

The key to making OpenClaw and Open WebUI work together is ensuring both tools point to the same model backend. Here is how to configure each provider scenario.

Scenario 1: Ollama as shared backend

This is the simplest setup. Both OpenClaw and Open WebUI connect to the same Ollama instance. No proxy needed.

{
  "models": {
    "local-llama": {
      "provider": "ollama",
      "model": "llama3.1:8b",
      "endpoint": "http://localhost:11434",
      "temperature": 0.7,
      "max_tokens": 4096
    }
  },
  "default_model": "local-llama"
}

Open WebUI automatically detects all models available in your Ollama instance. No additional configuration needed on the Open WebUI side. Just select the model from the dropdown.

Scenario 2: Anthropic via LiteLLM proxy

Open WebUI does not natively support the Anthropic API format. LiteLLM acts as a translation layer, exposing Anthropic models through an OpenAI-compatible endpoint.

# Install LiteLLM
pip install litellm

# Start the proxy with your Anthropic key
litellm --model anthropic/claude-sonnet-4-20250514 \
  --api_key sk-ant-your-key-here \
  --port 4000

# LiteLLM now serves Claude at http://localhost:4000/v1

model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: sk-ant-your-key-here

  - model_name: claude-haiku
    litellm_params:
      model: anthropic/claude-haiku-3-5-20241022
      api_key: sk-ant-your-key-here

  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-your-openai-key

# Start LiteLLM with the config file
litellm --config litellm_config.yaml --port 4000

Once LiteLLM is running, set Open WebUI's OPENAI_API_BASE_URL to http://localhost:4000/v1. All models defined in your LiteLLM config will appear in Open WebUI's model dropdown.

Scenario 3: Mixed providers (Ollama + Anthropic)

Most OpenClaw setups use multiple providers. You can connect Open WebUI to both Ollama and a LiteLLM proxy simultaneously.

{
  "models": {
    "local-llama": {
      "provider": "ollama",
      "model": "llama3.1:8b",
      "endpoint": "http://localhost:11434",
      "temperature": 0.7
    },
    "claude-sonnet": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "api_key": "sk-ant-...",
      "max_tokens": 4096
    }
  },
  "default_model": "local-llama"
}

version: "3.8"
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
      - OPENAI_API_BASE_URL=http://litellm:4000/v1
      - OPENAI_API_KEY=sk-litellm
    volumes:
      - open-webui:/app/backend/data
    depends_on:
      - litellm

  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports:
      - "4000:4000"
    volumes:
      - ./litellm_config.yaml:/app/config.yaml
    command: --config /app/config.yaml --port 4000

volumes:
  open-webui:

With this setup, Open WebUI shows both your Ollama models (Llama, Mistral, etc.) and your cloud models (Claude, GPT) in the same dropdown. Your OpenClaw agents continue using their configured providers independently.

Step 3: Replicate Your Agent Personality in Open WebUI

Open WebUI does not read SOUL.md files directly. But you can recreate your agent's identity by setting a system prompt in Open WebUI's model profile settings.

Creating a model profile

In Open WebUI, go to Settings, then Models, then click Create a Model. Give it a name that matches your OpenClaw agent (for example, "Orion - PM Agent"). Select the base model (the same one your OpenClaw agent uses), then paste your SOUL.md content into the System Prompt field.

# Orion - Project Manager Agent

## Identity
You are Orion, a senior project manager AI agent.
You coordinate tasks between team members, track deadlines,
and provide clear status reports.

## Rules
- Always respond in English
- Keep status updates concise and actionable
- Flag blockers immediately
- Use bullet points for task lists

## Tone
Professional but approachable. No jargon unless the audience
is technical. Prioritize clarity over formality.

This gives you a browser-based version of your OpenClaw agent. The personality and rules will match, but OpenClaw-specific features like scheduled heartbeats, team coordination, and messaging bot integrations will not be available through Open WebUI. Those continue to run through the OpenClaw CLI.

Troubleshooting Common Issues

Here are the most common problems people run into when connecting OpenClaw and Open WebUI, along with their fixes.

# 1. Check if Ollama is running
curl http://localhost:11434/api/tags

# 2. Check if Open WebUI can reach Ollama
docker exec open-webui curl http://host.docker.internal:11434/api/tags

# 3. Check Open WebUI logs for errors
docker logs open-webui --tail 50

# 4. Verify a model is available
ollama list

# 5. Test the model directly
ollama run llama3.1:8b "Hello, are you working?"

# 1. Test your API key directly
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: sk-ant-your-key" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":50,"messages":[{"role":"user","content":"Hi"}]}'

# 2. Test LiteLLM proxy directly
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet","messages":[{"role":"user","content":"Hi"}]}'

# 3. Check LiteLLM logs
litellm --config litellm_config.yaml --port 4000 --debug

# For Ollama: verify models are pulled
ollama list

# If no models appear, pull one
ollama pull llama3.1:8b

# For LiteLLM: verify the /models endpoint works
curl http://localhost:4000/v1/models

# Restart Open WebUI after fixing
docker restart open-webui

Alternative UIs for OpenClaw

Open WebUI is the most popular option, but it is not the only way to add a visual interface to your OpenClaw agents. Here are other options worth considering.

For most OpenClaw users, the best setup is Open WebUI for browser-based chat combined with a Telegram bot for mobile access. Open WebUI handles the desktop experience, and Telegram gives you agent access from your phone without any additional infrastructure.

If you do not want to manage another Docker container, the messaging integrations built into OpenClaw deploy packages (Telegram, Slack, Discord, WhatsApp) already provide a visual interface. Many users find that a Telegram bot is all they need for day-to-day agent interaction, especially since it works on both mobile and desktop.

Architecture Overview: How the Pieces Fit Together

Here is how OpenClaw and Open WebUI coexist in a typical setup:

                    +------------------+
                    |   Open WebUI     |  (browser chat, port 3000)
                    |   (web UI)       |
                    +--------+---------+
                             |
                    +--------v---------+
                    |   LiteLLM Proxy  |  (optional, port 4000)
                    |   (API gateway)  |
                    +--------+---------+
                             |
              +--------------+--------------+
              |              |              |
     +--------v---+  +------v-----+  +-----v------+
     |   Ollama   |  | Anthropic  |  |  OpenAI    |
     | (local LLM)|  | (Claude)   |  |  (GPT)     |
     +--------+---+  +------+-----+  +-----+------+
              |              |              |
     +--------v--------------v--------------v------+
     |                  OpenClaw                    |
     |  (SOUL.md, AGENTS.md, HEARTBEAT.md, bots)   |
     +----------------------------------------------+

OpenClaw and Open WebUI share the same model backends but operate independently. OpenClaw manages agent identity, coordination, and messaging integrations. Open WebUI provides a visual chat interface. Neither depends on the other. You can stop Open WebUI without affecting your running OpenClaw agents, and you can restart OpenClaw without impacting Open WebUI sessions.

Frequently Asked Questions