Running OpenClaw with Ollama – KDnuggets

# Introduction

 
You have successfully set up Ollama, pulled a capable model, run a few queries in the terminal, and it worked. The responses were sharp. The latency was real. The whole thing ran on your own hardware with no API key and no cloud.

Then you closed the terminal and walked away. The AI was gone. That is the gap OpenClaw fills. It is a personal AI assistant that runs on your hardware and stays running, bridging your local Ollama models to the messaging apps you already use: WhatsApp, Telegram, Slack, Discord, iMessage.

OpenClaw was created by Peter Steinberger, a macOS developer known for Apple tooling, and released in late 2025 under the name Clawdbot. The project passed 60,000 GitHub stars within weeks. As of Ollama 0.17, the entire setup collapses to a single command.

This article covers the full path from zero to a running private research assistant on Telegram, including configuring the context length correctly, connecting the channel, enabling web search, and deploying it headlessly in Docker.

# What OpenClaw Is and How It Works

 
Before running any commands, it helps to understand what is actually happening under the hood, because the architecture explains several decisions you will make during setup.
Everything flows through a single daemon called the Gateway. It stays running in the background, holds your messaging connections open, and coordinates the AI agent. When you send a message from WhatsApp or Telegram, here is the actual sequence: your text arrives through the messaging platform’s protocol (WhatsApp uses Baileys, Telegram uses the Bot API), travels to the Gateway, which routes it to your model via Ollama’s local API, and delivers the response back through the same channel. You see a reply in the messaging app. Nothing else happens on your device visibly.

This three-layer design is what makes OpenClaw different from just running a chatbot in a terminal:

1. The messaging layer is the channel you send messages through: your phone, a desktop Telegram client, a Slack workspace. You do not need to be at the machine running Ollama. You just need to be connected to the messaging service.
2. The Gateway daemon is the coordination layer. It persists even when you are not actively using it, holds connections open, and manages multi-step agent tasks. This is what makes OpenClaw useful, rather than just interactive; tasks that take multiple tool calls can run in the background and deliver results when complete.
3. The model layer is Ollama. This can be a fully local model running on your GPU, or a cloud-backed model routed through Ollama’s cloud service. The Gateway does not care which; it talks to Ollama’s API either way.

One naming note worth covering upfront: OpenClaw was previously known as Moltbot and, before that, Clawdbot. It was renamed in early 2026. All old command aliases still work: ollama launch clawdbot still functions, so nothing breaks if you have those stored in scripts or documentation.

# System Requirements and Prerequisites

 
The 64k context window requirement shapes everything else in your hardware and model selection decisions, so understand this before choosing a model.

Ollama defaults to context lengths based on available VRAM: under 24 GB gets 4k context, 24–48 GB gets 32k, and 48 GB or more gets 256k. The default for most consumer hardware is 4k, which is not enough for an agent doing multi-step tasks. You will need to set context explicitly, which the next section covers.

Hardware requirements:

Software prerequisites:

• Ollama 0.17 or later is required; this is the version that introduced ollama launch. Check your version with ollama --version and download the latest from ollama.com/download if needed.
• Node.js 18 or later is required because OpenClaw installs via npm. Ollama detects and prompts for this automatically, but it is worth having it installed before you start. Download from nodejs.org if needed.
• An Ollama account is required for cloud models and for web search on local models. Create one at ollama.com and sign in with:

Model recommendations:

Cloud models have full context length automatically and include web search support without any additional configuration. For most users starting out, kimi-k2.5:cloud is the right pick; it is free to start, handles agentic tasks well, and requires no VRAM.

# One-Command Installation with ollama launch

 
With Ollama 0.17+, you do not manually install OpenClaw, configure a Gateway, or manage npm packages. Ollama handles the entire bootstrap sequence.

Open a terminal and run:

Or, to go directly to a specific model and skip the selector:

ollama launch openclaw --model kimi-k2.5:cloud

Ollama then handles five things automatically, in this order:

1. Install check: If OpenClaw is not already on your system, Ollama detects this and prompts you to install it via npm. Confirm, and it installs without you touching npm directly.
2. Security notice: Before anything else runs, OpenClaw displays a security warning: the agent has the ability to read files and execute actions on your machine when tools are enabled. This is not boilerplate. An agent with file access that receives a malicious instruction can cause real damage. Read it. Run OpenClaw in an isolated environment if you are not certain about what it can reach. The OpenClaw security documentation covers this in detail.
3. Model selector: A list of recommended models appears. Select one, or press Enter to use the model you specified with --model. The selector shows both cloud and local models with context window notes.
4. Onboarding: Ollama configures your provider, installs the Gateway daemon, sets the selected model as primary, and, if you chose a cloud model, enables OpenClaw’s bundled Ollama web search automatically.
5. Gateway starts: The Gateway launches in the background. The OpenClaw terminal user interface (TUI) opens, and you can start chatting immediately.

If you only want to change the configuration without starting the Gateway and TUI:

# Reconfigure without starting the agent
ollama launch openclaw --config

If the Gateway is already running when you do this, it restarts automatically to pick up the new settings. No manual restart needed.

# Configuring Context Length for Agent Workloads

 
This is the step most tutorials skip, and it is the most common reason OpenClaw underperforms on real tasks.

The official docs state the minimum is 64k tokens, but understand what “minimum” means here. An agent doing a multi-step research task (web search → read page → extract information → summarize → respond) accumulates context across every step. At 64k, you have enough for a few turns with tool calls. For longer conversations or tasks with many tool invocations, you want more headroom. Cloud models are set to their maximum context length automatically and do not need this configuration.

For local models, set context length before launching:

# Option 1: Environment variable (set it before starting Ollama)
OLLAMA_CONTEXT_LENGTH=64000 ollama serve

# For longer tasks on machines with enough VRAM, use more
OLLAMA_CONTEXT_LENGTH=131072 ollama serve

# Option 2: Through the Ollama app
# Open Ollama settings → Context Length → move the slider to 64000 or higher

Verify that the context was actually applied and that your model is not being offloaded to the CPU:

Look for output like this:

NAME                  ID              SIZE      PROCESSOR    CONTEXT    UNTIL
qwen3-coder:latest    a4f2cc91b3e1    28.1 GB   100% GPU     65536      5 minutes from now

Two things to check: PROCESSOR should show 100% GPU. If it shows a split like 40% GPU / 60% CPU, the model is being offloaded, and performance will be significantly degraded. CONTEXT should show 65536 or higher. If it shows 4096, your environment variable did not take effect. Make sure you started ollama serve in the same shell session where you set the variable.

If you cannot fit the full 64k in VRAM, use a cloud model instead of compromising on context. The agent needs the context more than it needs local inference.

# Connecting a Messaging Channel

 
Once the Gateway is running, you connect your messaging platform with:

openclaw configure --section channels

This opens an interactive selector listing WhatsApp, Telegram, Slack, Discord, and iMessage. The setup steps differ per platform. Telegram is the cleanest starting point for developers. It requires no phone number linking and uses a proper bot token rather than emulating a personal account.

// Setting Up Telegram

Step 1: Create a bot with BotFather
Open Telegram and search for @BotFather. Send /newbot, choose a name (this is the display name), then choose a username (must end in bot, e.g. my_openclaw_bot). BotFather returns a token that looks like:

1234567890:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Copy this token. You will not be shown it again. If you lose it, you can generate a new one with /token.

Step 2: Paste the token into OpenClaw
In the openclaw configure --section channels menu, select Telegram, then paste the bot token when prompted.

Step 3: Select “Finished” to save
After configuring, select Finished in the configurator. This is required. Exiting without selecting Finished discards your configuration.

Step 4: Find your bot on Telegram and start a conversation
Search for your bot’s username in Telegram. Send /start. The Gateway handles the first connection and the bot begins responding.

For WhatsApp, the process uses the Baileys protocol, which means you scan a QR code in the OpenClaw TUI to link your WhatsApp account. This works, but it links your actual WhatsApp account rather than creating a separate bot account. Be aware of that before proceeding.

For Slack and Discord, you will need to create an app in each platform’s developer portal and supply the bot token and channel IDs. The OpenClaw configurator walks through the required fields for each.

# The Real-World Project: Private Research Assistant on Telegram

 
Here is the full project this article has been building toward. A private Telegram bot that:

• Answers questions using your local or cloud model
• Searches the web for live information using Ollama’s built-in web search
• Fetches and summarizes documents and URLs you send it
• Handles multi-step research tasks with no data leaving your machine (when using a local model)

Once your Telegram channel is connected and the Gateway is running, this is already functional without any additional code. OpenClaw handles the agent loop natively. The configuration choices you make are what shape the experience.

// Enabling Web Search

If you launched with a cloud model, Ollama installs the web search plugin automatically. You can verify it is active by asking your bot a question that requires current information: “What did Anthropic announce this week?” A properly configured bot with web search will search and return a cited answer. Without web search, it will answer from training data or say it does not know.

For local models, web search requires ollama signin first, then:

openclaw configure --section web

This enables the bundled Ollama web_search provider, which routes searches through Ollama’s web search API using your account credentials.

// What a Multi-Step Task Looks Like in the TUI

Send this to your Telegram bot:

Find the three most-cited papers on transformer attention published in 2025 and give me a one-sentence summary of each.

In the OpenClaw TUI on your machine, you will see the agent’s tool call log as it works. Something like:

[tool] web_search: "most cited transformer attention papers 2025"
[tool] web_fetch: https://arxiv.org/...
[tool] web_fetch: https://paperswithcode.com/...
[reasoning] Identified three papers: ...
[response] Sending to Telegram...

The task completes in Telegram as a formatted message with the three papers, their citation counts, and summaries, typically in 20–40 seconds depending on your model and connection speed.

That is the core of what makes this setup genuinely useful: multi-step agent tasks that would require a browser, multiple searches, and manual synthesis can be delegated from your phone with a single message and return a synthesized answer while you do something else.

// The Python Script Approach: Calling the Web Search API Directly

If you want to build on top of this setup programmatically, for example, scheduling daily research summaries or piping results into a database, you can call Ollama’s web search API directly from Python using the same credentials OpenClaw uses:

# research_agent.py
# A minimal research agent using Ollama's web search + chat API.
# Prerequisites:
#   pip install ollama
#   ollama signin (run once in your terminal)
#   ollama pull qwen3.5:cloud  (or any tool-capable model)
#
# How to run:
#   python research_agent.py "What are the latest developments in local LLMs?"

import sys
from ollama import chat, web_search, web_fetch

# ── Tool registry ─────────────────────────────────────────────────────────────
# Map tool names to actual callables so we can dispatch tool calls from the model.
AVAILABLE_TOOLS = {
    "web_search": web_search,
    "web_fetch":  web_fetch,
}

def run_research_agent(query: str, model: str = "qwen3.5:cloud") -> str:
    """
    A multi-turn research agent that uses web search and page fetching
    to answer questions with up-to-date information.

    Args:
        query: The research question to answer
        model: Ollama model to use. Cloud models recommended for 64k+ context.

    Returns:
        The agent's final synthesized answer as a string.
    """
    messages = [
        {
            "role": "system",
            "content": (
                "You are a research assistant. When answering questions that require "
                "current information, use the web_search tool to find relevant results, "
                "then use web_fetch to read the most promising pages before responding. "
                "Always cite your sources in the final answer."
            ),
        },
        {
            "role": "user",
            "content": query,
        },
    ]

    print(f"Query: {query}\nModel: {model}\n{'─' * 60}")

    # ── Agentic loop ──────────────────────────────────────────────────────────
    # The loop continues as long as the model is making tool calls.
    # When the model stops calling tools and writes a final response, we break.

    while True:
        response = chat(
            model=model,
            messages=messages,
            tools=[web_search, web_fetch],  # Pass the actual callables -- Ollama extracts the schema
            think=True,                      # Enable chain-of-thought before tool decisions
        )

        # Show reasoning trace if present (think=True)
        if response.message.thinking:
            print(f"[thinking] {response.message.thinking[:200]}...")

        # Append the model's response to message history
        messages.append(response.message)

        # If the model made tool calls, execute each one and inject results
        if response.message.tool_calls:
            for tool_call in response.message.tool_calls:
                tool_name = tool_call.function.name
                tool_fn   = AVAILABLE_TOOLS.get(tool_name)

                if not tool_fn:
                    # Tool not found -- tell the model so it can adjust
                    print(f"[tool] {tool_name}: NOT FOUND")
                    messages.append({
                        "role":      "tool",
                        "content":   f"Tool '{tool_name}' is not available.",
                        "tool_name": tool_name,
                    })
                    continue

                args   = tool_call.function.arguments
                print(f"[tool] {tool_name}({args})")

                result = tool_fn(**args)
                result_str = str(result)
                print(f"[result] {result_str[:150]}...")

                # Truncate tool results to stay within context budget.
                # At 64k context, ~8000 chars per result is a safe ceiling
                # for multi-step tasks with several tool calls.
                messages.append({
                    "role":      "tool",
                    "content":   result_str[:8000],
                    "tool_name": tool_name,
                })
        else:
            # No more tool calls -- the model has a final answer
            final_answer = response.message.content
            print(f"\n{'─' * 60}\nAnswer:\n{final_answer}")
            return final_answer


# ── Entry point ───────────────────────────────────────────────────────────────

if __name__ == "__main__":
    query = sys.argv[1] if len(sys.argv) > 1 else "What are the latest developments in local LLMs?"
    run_research_agent(query)

Prerequisites:

pip install ollama
ollama signin
ollama pull qwen3.5:cloud

How to run:

python research_agent.py "What are the three most-cited papers on transformer attention published in 2025?"

Expected output:

Query: What are the three most-cited papers on transformer attention published in 2025?
Model: qwen3.5:cloud
────────────────────────────────────────────────────────────
[thinking] The user wants specific papers from 2025. I need to search for recent publications...
[tool] web_search({'query': 'most cited transformer attention papers 2025', 'max_results': 5})
[result] results=[WebSearchResult(content="..."), ...]...
[tool] web_fetch({'url': 'https://paperswithcode.com/...'})
[result] title="Papers With Code - Transformer Attention..."...

────────────────────────────────────────────────────────────
Answer:
Here are three highly-cited transformer attention papers from 2025:

1. **[Paper Title]** -- [Summary]. Cited 847 times as of June 2026.
   Source: arxiv.org/...

2. **[Paper Title]** -- [Summary]. Cited 623 times.
   Source: paperswithcode.com/...

3. **[Paper Title]** -- [Summary]. Cited 511 times.
   Source: semanticscholar.org/...

The tool call truncation at 8,000 characters per result is the most important practical detail in this script. Without it, a long web page fetched in a single tool call can consume 20k–40k tokens of your context budget in one step, leaving insufficient room for subsequent tool calls and the final synthesis. Truncate aggressively and rely on the model’s ability to work with the most relevant portion.

# Non-Interactive and Headless Deployment

 
For production use, a machine that runs the agent 24/7, or a deployment in Docker, the interactive TUI is in the way. The --yes flag removes it entirely:

ollama launch openclaw --model kimi-k2.5:cloud --yes

The --yes flag auto-pulls the model, skips all interactive selectors, and starts the Gateway immediately. It requires --model to be specified explicitly. The flag has no way to guess a model without the selector.

Dockerfile for a headless OpenClaw server:

# Dockerfile
# Runs Ollama + OpenClaw as a headless agent service.
# Build: docker build -t openclaw-agent .
# Run:   docker run -d --gpus all --env-file .env openclaw-agent
#
# Prerequisites for the build machine:
#   - Docker with nvidia-container-toolkit (for GPU passthrough)
#   - A .env file with OLLAMA_API_KEY and channel credentials

FROM ubuntu:22.04

# ── System dependencies ────────────────────────────────────────────────────────
# Ubuntu 22.04's default apt repo ships Node.js 12.x, which does not meet
# OpenClaw's Node.js 18+ requirement, so Node.js 18 is installed via NodeSource.
RUN apt-get update && apt-get install -y curl \
    && curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*

# ── Install Ollama ─────────────────────────────────────────────────────────────
RUN curl -fsSL https://ollama.com/install.sh | sh

# ── Install OpenClaw via npm ───────────────────────────────────────────────────
# Install globally so the `openclaw` binary is in PATH
RUN npm install -g openclaw

# ── Set context length for agent workloads ─────────────────────────────────────
# 64000 is the minimum. Increase if your GPU has VRAM headroom.
ENV OLLAMA_CONTEXT_LENGTH=64000

# ── Startup script ─────────────────────────────────────────────────────────────
# 1. Start the Ollama server in the background
# 2. Wait for it to be ready
# 3. Launch OpenClaw headlessly with the specified cloud model
COPY start.sh /start.sh
RUN chmod +x /start.sh

EXPOSE 11434

CMD ["/start.sh"]

# start.sh -- runs alongside the Dockerfile above

#!/bin/bash
set -e

# Start the Ollama server in the background
ollama serve &
OLLAMA_PID=$!

# Wait until Ollama's API is responding (up to 30 seconds)
echo "Waiting for Ollama to start..."
for i in $(seq 1 30); do
    if curl -s http://localhost:11434/api/tags > /dev/null 2>&1; then
        echo "Ollama ready."
        break
    fi
    sleep 1
done

# Launch OpenClaw headlessly -- --yes skips all interactive prompts
# OLLAMA_MODEL should be set in your .env file or docker run -e flag
ollama launch openclaw \
    --model "${OLLAMA_MODEL:-kimi-k2.5:cloud}" \
    --yes

# Keep the container alive and follow OpenClaw's logs
wait $OLLAMA_PID

Build and run:

# Create a .env file with your credentials
cat > .env << EOF
OLLAMA_MODEL=kimi-k2.5:cloud
OLLAMA_API_KEY=your_ollama_api_key
EOF

# Build the image
docker build -t openclaw-agent .

# Run with GPU passthrough (requires nvidia-container-toolkit)
docker run -d \
    --gpus all \
    --env-file .env \
    --name openclaw \
    openclaw-agent

# Follow logs
docker logs -f openclaw

For local models without GPU passthrough, remove --gpus all and ensure OLLAMA_MODEL points to a cloud model. The GPU flag is only needed when running local models that require VRAM.

Stopping and restarting the Gateway:

# Stop the Gateway cleanly (use this instead of killing the process)
openclaw gateway stop

# The Gateway restarts automatically when you run ollama launch again
ollama launch openclaw --model kimi-k2.5:cloud --yes

# Stopping the Gateway and Common Troubleshooting

 
Stop the Gateway cleanly when you need to:

Using Ctrl+C in the TUI works for the interactive session but may leave the Gateway daemon running. Use gateway stop to ensure it terminates.

Common issues:

• If messages are not being processed, check that the Gateway is actually running:

# Check if the openclaw gateway process is alive
pgrep -la openclaw

• If the agent gives outdated answers despite web search being configured, verify your Ollama account is signed in:

• If you see context length exceeded errors in the TUI log, your context window is too small for the task. Increase OLLAMA_CONTEXT_LENGTH and restart ollama serve before relaunching OpenClaw.
• If the model is being partially offloaded to CPU (visible in ollama ps as a split percentage), either reduce context length, switch to a smaller model, or move to a cloud model. CPU offloading works but will make multi-step tasks noticeably slow.

# Conclusion

 
OpenClaw and Ollama together close the gap between “AI that works in a terminal” and “AI that works wherever you are.” The Gateway runs in the background. Your messaging app becomes the interface. A single command sets up the entire stack.

The practical value shows up quickly: multi-step research tasks you would normally spend 20 minutes doing manually complete in the background while you are doing something else, delivered as a formatted message to your phone. File tasks, calendar management, and inbox processing are all expanding rapidly, and OpenClaw’s skill library is growing alongside them, as the community builds integrations on top of the Gateway architecture.

For users who care about where their data goes, the local model path is simple: a capable model, 25 GB of VRAM, and one context-length configuration deliver a fully private agent with no cloud dependency at all. For users who want the easiest possible start, a cloud model is one command away.

Either path ends at the same place: an AI assistant that answers your messages, does your research, and runs on infrastructure you control.

// Resources

Shittu Olumide is a software engineer and technical writer passionate about leveraging cutting-edge technologies to craft compelling narratives, with a keen eye for detail and a knack for simplifying complex concepts. You can also find Shittu on Twitter.