How to Connect OpenClaw with Ollama: The Complete Guide
Learn how to Connect OpenClaw with Ollama locally to run a powerful private AI chatbot with faster performance, and data privacy on your own hardware.
AI tools are no longer something you rent from a big tech company. They are moving onto personal hardware fast, and pairing OpenClaw with Ollama is one of the most compelling reasons why. Whether you are a developer who wants full control, someone who handles sensitive information, or just a person who does not want to pay a monthly fee for a chatbot, this setup delivers.
Picture sending a message on WhatsApp or Telegram and getting a sharp, intelligent reply in seconds. No data leaves your house. No bill arrives at the end of the month. Best of all, Your own computer does all the thinking. That is exactly what happens when you wire OpenClaw and Ollama together to run a private AI chatbot locally.
Previously called Clawdbot or Moltbot? You are in the right place. OpenClaw was renamed in early 2026. All old command aliases still work, so nothing breaks if you have them stored in scripts.
This guide covers every step, from installing both tools to sending your first local AI message, with a verified pipeline test before you link a single messaging account. Before jumping into commands, though, it helps to understand what each piece actually does.
What Is OpenClaw and Why Does It Matter?
Think of OpenClaw as the front door to your AI. It is an open-source personal AI agent that sits on your computer and acts as a bridge between the messaging apps on your phone and whatever AI model you want to power it with. When you send a message on Telegram, it travels to OpenClaw, From there, the AI processes it and the reply lands back on your phone, without touching any external server.
What separates OpenClaw from a basic chatbot is its support for tool calling. Instead of simply generating text, the assistant can take real actions on your behalf: searching the web, reading files on your system, executing code, and automating tasks that would otherwise require manual input. That capability is what makes it a genuine personal AI agent rather than just a conversational interface.
Supported messaging platforms: WhatsApp, Telegram, Slack, Discord, iMessage
OpenClaw manages the messaging side of the equation, but it needs an AI model to reason with. That is the specific gap Ollama fills.
Want to go deeper on what OpenClaw is? Read our full guide on OpenClaw (aka MoltBot): The Complete Guide to Your Personal AI Assistant →
What Is Ollama and What Does It Bring to the Table?
Where OpenClaw manages connections and routes messages, Ollama handles the actual intelligence. Specifically, It is a free, open-source application designed to make running large language models on your own hardware as straightforward as possible, no external API account needed, no subscription, and no data sent to a remote server.
Think of it as a package manager built specifically for AI models, similar in concept to how npm manages JavaScript libraries. Once installed, You choose a model from Ollama’s library, it downloads and registers it on your machine, and from that point the model runs entirely on your local hardware.
Ollama handles GPU detection and memory allocation automatically. Once running, it exposes a local API endpoint at http://localhost:11434. From that point, OpenClaw connects to that endpoint and uses it as its reasoning layer, routing every conversation through the model on your hardware.
How OpenClaw and Ollama Work Together
To understand this better, here is what happens each time you send a message:
- You send a message through Telegram, WhatsApp, or any connected platform
- OpenClaw’s gateway process receives it on your local machine
- The gateway forwards it to Ollama’s local API at http://localhost:11434
- Ollama passes the message into the AI model loaded on your hardware
- The model generates a response and returns it to OpenClaw
- OpenClaw delivers that response back to your messaging app
Importantly, entire process runs on your machine. No cloud infrastructure, no third-party processing, no per-message billing. The only scenario where internet access enters the picture is if you enable the optional web search plugin, which allows the model to retrieve current information when needed.
OpenClaw communicates with Ollama through the native API at
http://localhost:11434, not the OpenAI-compatible /v1 endpoint.
The native API provides reliable support for tool calling. which is essential for OpenClaw’s agent capabilities. Using /v1 instead will silently break tool calling without producing any obvious error message, a particularly frustrating issue to diagnose. The configuration section covers this in full IN STEP 5
Prerequisites: What You Need Before You Start
Before installing anything, take a few minutes to verify your environment. In fact, The majority of setup problems trace directly back to skipping this step.
System requirements
- Operating system: macOS, Linux, or Windows
- RAM: At least 8 GB. For models above 14B parameters, 16 GB or more is strongly recommended
- Disk space: Model files range from 4 GB to 20+ GB. Verify you have adequate free space before pulling any model
- GPU (optional but recommended): Ollama automatically uses NVIDIA CUDA or Apple Metal. Without a GPU, models run on CPU and are significantly slower
- Node.js 18 or higher: OpenClaw is installed via npm. Verify your version: node –version
The context window requirement
OpenClaw requires the AI model to support a context window of at least 64,000 tokens. In simple terms, the context window determines how much conversation history the model can retain and reference at any given time. If you configure a model with a smaller window, multi-turn conversations and the agent’s memory will not operate correctly. Every model recommended below meets this threshold.
It is important to note that AI model files are quite large. Depending on the model you choose, the download can range from around 4 GB up to 20 GB or more. Confirm that you have sufficient free space on your drive before you begin pulling any models.
OpenClaw Ollama Setup: Full Configuration Steps
Step 1: Choose the Right Model for Your Hardware
This decision is best made before you download anything. After all, model files are large (4 GB to 20+ GB) and choosing the wrong one for your hardware wastes significant time and disk space. The table below maps hardware configurations to recommended models.
| Model | Best for | VRAM needed |
| gpt-oss:20b | Recommended starting point. Tool-capable, large context | ~12 GB |
| qwen2.5-coder:32b | Coding tasks and technical questions | ~20 GB |
| deepseek-r1:32b | Complex reasoning. Auto-detected as a reasoning model | ~20 GB |
| llama3.3 | Solid general-purpose model for everyday use | ~8 GB |
| glm-4.7-flash | Reasoning and code on local hardware | ~25 GB |
For high-end hardware (16+ GB VRAM): gpt-oss:20b and qwen2.5-coder:32b are both strong choices In addition, they deliver results comparable to leading cloud-based models. For demanding analytical work, deepseek-r1:32b performs very well, OpenClaw automatically identifies it as a reasoning model and adjusts its output handling.
Similarly, For mid-range hardware (8–16 GB VRAM): llama3.3 or gpt-oss:20b with 4-bit quantization (the q4_K_M variant) offer a solid balance of quality and speed when GPU acceleration is active.
For CPU-only or low-memory machines: instead, Use smaller quantized models. Responses will be slower, but they function correctly. Set a shorter context window (8,000–16,000 tokens) to avoid running out of memory during long sessions. Pull a quantized variant explicitly:
ollama pull qwen2.5:7b-q4_K_M
or
ollama pull llama3.2:3b
Step 2: Install Ollama and Pull Your Model
Visit ollama.com and download the installer for your operating system. For Linux users, the installation script is the simplest approach:
curl -fsSL https://ollama.com/install.sh | sh
Once installed, start the server and verify the API is accessible:
# Start Ollama
ollama serve
# In a new terminal, verify the API responds
curl http://localhost:11434/api/tags
If the API returns a JSON response, even an empty list, Ollama is healthy and ready to proceed. If the request times out, Ollama is not running. Start it with ollama serve and test again before moving on.
Now pull your chosen model. Use ollama pull to download without launching an interactive session:
# Pull the recommended starting model
ollama pull gpt-oss:20b
# Or for coding-focused work
ollama pull qwen2.5-coder:32b
# Or for low-RAM machines (quantized)
ollama pull qwen2.5:7b-q4_K_M
After the download completes, confirm the model is registered:
ollama list
Step 3: Keep the Model Loaded in Memory
By default, Ollama unloads inactive models from memory after several minutes . Because of this, the first message after a period of inactivity can experience a delay of 30 seconds or more while the model reloads. Set this before proceeding to avoid the issue entirely:
# For the current terminal session
export OLLAMA_KEEP_ALIVE=24h
ollama serve
# On Linux, to persist across reboots, add to your service file or shell profile:
echo 'export OLLAMA_KEEP_ALIVE=24h' >> ~/.bashrc
source ~/.bashrc
On Linux, also enable Ollama as a system service so it restarts automatically after every reboot:
sudo systemctl enable ollama
sudo systemctl start ollama
Step 4: Install OpenClaw
OpenClaw can be installed in two ways. For most users, the automated approach through Ollama is the simplest path to a working setup.
Method A: Through the Ollama Launcher (Recommended)
Ollama includes a built-in launcher for OpenClaw that handles installation, initial configuration, and gateway startup in one continuous flow:
ollama launch openclaw
If OpenClaw is not already installed, Ollama detects this and prompts you to install it via npm before proceeding. Once installed, the interactive onboarding wizard takes over, it guides you through selecting a model, reviewing the security notice around tool access permissions, and installs the gateway as a background service. After the wizard completes, OpenClaw is fully operational.
Method B: Manual Installation
If you prefer to install OpenClaw independently before launching it, use the official installation script for your platform:
#macOS and Linux
curl -fsSL https://openclaw.ai/install.sh | bash
powershell -- Windows
iwr -useb https://openclaw.ai/install.ps1 | iex
After a manual installation, run ollama launch openclaw to complete the configuration process and start the gateway service.
Step 5: Configure the Ollama Connection
This is the most critical section in the guide. How you configure the Ollama connection directly determines whether tool calling functions correctly, and tool calling is what makes OpenClaw an agent rather than a simple text interface.
Step 5.1: Back up your config before editing
Before touching any configuration file, make a backup. A corrupted config.json will break the entire setup with no automatic recovery:
# macOS / Linux
cp ~/.openclaw/config.json ~/.openclaw/config.json.bak
# Windows
copy C:\Users\YOUR_USERNAME\.openclaw\config.json C:\Users\YOUR_USERNAME\.openclaw\config.json.bak
Step 5.2: Set the Ollama API key
OpenClaw’s provider system requires an API key for every model provider it connects to, including local providers that do not actually use authentication. For Ollama, any non-empty string is sufficient, the value itself is never validated, since Ollama running locally does not enforce authentication.
You can set this either as an environment variable before launching, or permanently through the OpenClaw CLI. Both approaches produce the same result:
# Set it for the current terminal session
export OLLAMA_API_KEY="ollama-local"
# Or configure it permanently through the CLI
openclaw config set models.providers.ollama.apiKey "ollama-local"
Step 5.3: Let auto-discovery find your models (recommended)
Once OLLAMA_API_KEY is set, OpenClaw automatically queries the Ollama API and discovers all installed models that declare tool-calling support. Any model you add in the future will also appear automatically, without additional configuration steps.
After setting the API key, verify what has been discovered:
openclaw models list
If a model you know is installed does not appear in the list, it is likely because that model does not report tool calling support to the Ollama API. In that case, you can add it manually in the configuration file to bypass that check.
Step 5.4: Manual provider configuration (advanced)
Manual configuration is needed when you want Ollama on a different machine on your network, on a non-standard port, or when you need precise control over context window sizes. When you define the Ollama provider block manually, auto-discovery is disabled and you must list your models explicitly.
OpenClaw communicates with Ollama through the native API at
http://localhost:11434, not the OpenAI-compatible /v1 endpoint.
The native API (http://localhost:11434) reliably supports tool calling. The OpenAI-compatible path (http://localhost:11434/v1) does not, it will silently produce raw JSON output in responses and disable agent features with no clear error message. Always use the native endpoint when connecting OpenClaw to Ollam
{
"models": {
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434",
"apiKey": "ollama-local",
"api": "ollama",
"models": [
{
"id": "gpt-oss:20b",
"name": "gpt-oss:20b",
"reasoning": false,
"input": ["text"],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 131072,
"maxTokens": 8192
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "ollama/gpt-oss:20b",
"fallbacks": ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"]
},
"workspace": "/Users/YOUR_USERNAME/.openclaw/workspace",
"maxConcurrent": 4,
"subagents": {
"maxConcurrent": 8
}
}
},
"tools": {
"web": {
"search": {
"enabled": false
},
"fetch": {
"enabled": true
}
}
}
}
Save this to the appropriate location for your operating system:
- macOS / Linux: ~/.openclaw/config.json
- Windows: C:\Users\YOUR_USERNAME\.openclaw\config.json
You can also open it directly for editing with:
openclaw config edit
Replace/Users/YOUR_USERNAME/ with your actual home directory path.
- On Linux this is typically /home/your-username/.
- On Windows it follows the format C:\Users\your-username\.
Step 5.5: Set the primary model and fallbacks
Once the provider connection is established, you need to specify which model OpenClaw should use by default. You can also define fallback models, which OpenClaw will switch to automatically if the primary model is unavailable or fails to respond, particularly useful when experimenting with multiple models or running in environments where response times vary:
{
"agents": {
"defaults": {
"model": {
"primary": "ollama/gpt-oss:20b",
"fallbacks": ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"]
}
}
}
}
Step 6: Start the Gateway
The gateway is the background process that manages everything once OpenClaw is configured, it maintains connections to your messaging platforms, routes messages between your apps and Ollama, handles tool call execution, and keeps the entire system running continuously.
If you complete the setup through ollama launch openclaw, the gateway is already active. For a manual setup, use the following commands. The logs option is particularly useful when verifying that messages are flowing correctly end to end:
openclaw gateway start # Start the background gateway service
openclaw gateway logs # View real-time activity and message routing
openclaw gateway stop # Stop the gateway when needed
One useful behaviour to be aware of: if you modify your configuration or switch models while the gateway is running, it detects the change and restarts itself automatically. You do not need to stop and restart it manually after every configuration update.
It is important to keep Ollama running at all times. The OpenClaw gateway depends on Ollama being continuously available, if Ollama stops for any reason, AI responses will fail immediately. On Linux and macOS, setting up Ollama as a system service ensures it restarts automatically after every reboot:
sudo systemctl enable ollama
sudo systemctl start ollama
Step 7: Verify the Full Pipeline Before Connecting Any Messaging App
Before linking Telegram or WhatsApp, confirm that the entire stack, Ollama, OpenClaw, and your chosen model, is working end to end. Running a quick test here saves significant debugging time later.
# Send a test message directly through the CLI
openclaw chat "Hello, are you working?"
# Run the full system health check
openclaw doctor
openclaw doctor performs a comprehensive check of the entire system and identifies most common issues in seconds. Only proceed to channel setup once you receive a coherent reply from the chat command and a clean result from the doctor.
Step 8: Connect Telegram, WhatsApp, and Other Messaging Apps
With the gateway running, OpenClaw is ready to receive messages, it simply needs to know which platforms to listen on. The channel configuration wizard handles this through a guided setup process. Run the following command and follow the on-screen prompts, as this only needs to be completed once per platform:
openclaw configure --section channels
Setting Up Telegram
Telegram is the recommended starting point because it uses a bot API that does not require you to link your personal phone number. The process is straightforward and typically takes only a few minutes:
- Open Telegram and search for the official @BotFather account
- Send the command /newbot and follow the prompts to assign a name and username to your bot
- BotFather will respond with an API token, a long alphanumeric string. Copy it carefully and completely.
- When the OpenClaw configuration wizard asks for a Telegram token, paste it in
- Restart the gateway, open a conversation with your new bot, and send a test message. You should receive a response from your local Ollama model within a few seconds.
Setting Up WhatsApp
For users who prefer WhatsApp, the pairing process works similarly to how WhatsApp Web operates In that case, follow these steps:
- Select WhatsApp when prompted in the channel configuration wizard
- A QR code will appear in your terminal window
- On your phone, navigate to WhatsApp → Settings → Linked Devices → Link a Device
- Point your phone camera at the QR code displayed on screen
- Once the scan is successful, your WhatsApp account is linked. Send a message to verify the connection is working correctly.
Security consideration: With tool calling enabled, OpenClaw can read and send messages on your behalf and execute commands on your system. This represents a significant level of access. Review the OpenClaw security documentation before connecting accounts that contain sensitive financial or personal information.
Step 9: Enable Web Search (Optional)
By default, a local model can only respond based on its training data, which has a fixed knowledge cutoff date. The web search plugin gives OpenClaw the ability to retrieve current information from the internet on demand, recent events, live prices, and other time-sensitive topics, without changing how you interact with the assistant.
If you launched OpenClaw through ollama launch openclaw, the web search plugin was installed automatically. If you set things up manually, install it now
# Install the web search plugin
openclaw plugins install @ollama/openclaw-web-search
# Local models also require an Ollama sign-in to use web search
ollama signin
Once active, only the search query leaves your machine. Your conversation history remains local, and responses are still generated on your hardware.
Step 10: Keep Both Tools Up to Date
Running outdated versions is one of the most common causes of unexplained issues, particularly as new models introduce changes to how tool calling is declared.
# Update Ollama
curl -fsSL https://ollama.com/install.sh | sh
# Update OpenClaw
npm update -g openclaw
# After updating, verify everything still connects cleanly
openclaw doctor
Check for Ollama and OpenClaw release notes before updating in a production environment, as major versions occasionally include breaking configuration changes.
Running OpenClaw Headless: Docker, Servers, and Automated Setups
For server deployments, Docker containers, or automated pipelines, the interactive onboarding wizard is not suitable. In these scenarios, the headless mode flag bypasses all prompts and runs the entire setup without requiring any user input:
ollama launch openclaw --model kimi-k2.5:cloud --yes
The yes flag automatically accepts all prompts and proceeds without requiring any input. The model flag is required in headless mode, the command will not proceed without a model specified. This approach is well-suited for Docker configurations and startup scripts where you need the gateway to initialize reliably without manual intervention.
Troubleshooting Common OpenClaw and Ollama Problems
Even with a clean setup, configuration issues can arise. The majority of problems with this integration trace back to a small number of root causes, each of which has a clear and straightforward resolution.
OpenClaw Cannot Connect to Ollama
This issue almost always indicates that Ollama is not currently running. Start the server and then verify the API is accessible:
ollama serve
Then verify that the API is accessible:
curl http://localhost:11434/api/tags
A successful JSON response confirms the connection is working. If the request hangs without responding, another process may be occupying port 11434. You can check this on macOS and Linux with lsof -i :11434.
No Models Appear in OpenClaw
OpenClaw’s auto-discovery only surfaces models that explicitly report tool calling support to the Ollama API. Some older or smaller models do not advertise this capability and are therefore excluded from the discovered list. There are two ways to address this:
# Option 1: Pull a model that reliably declares tool support
ollama pull gpt-oss:20b
Alternatively, add the model manually in your configuration file, manual entries bypass the tool support check entirely and will appear in OpenClaw regardless of what the model reports.
Models Are Responding With Raw JSON Instead of Normal Text
This symptom is almost always caused by a mismatch between the api field and the baseUrl in your configuration. When using the configuration from this guide, both settings must be consistent with each other:
json
"baseUrl": "http://localhost:11434/v1",includes /v1
"api": "openai-completions" correct matching mode
Using api: “ollama” alongside a URL that includes /v1, or using api: “openai-completions” without /v1 in the URL, will produce raw JSON output in responses. Ensure the two settings are consistent and the issue will resolve.
Responses Are Very Slow
There are two common causes for slow responses. The first is that the model was unloaded from memory during an inactive period and needs to reload before responding. Resolve this by keeping the model loaded:
OLLAMA_KEEP_ALIVE=24h ollama serve
The second cause is that Ollama is running inference on the CPU rather than the GPU. Review Ollama’s startup logs to confirm whether GPU detection succeeded at launch. If the GPU was not detected, verify that the appropriate drivers are installed and up to date for your hardware.
Messages Are Not Arriving on Telegram or WhatsApp
If messages are being sent but no reply is arriving, begin by reviewing the gateway logs for any error messages:
openclaw gateway logs
The most common causes are an expired or incorrectly copied Telegram bot token, a WhatsApp session that has timed out and requires re-pairing, or a gateway crash caused by an invalid configuration entry. Re-running the channel configuration wizard will re-establish the connection:
openclaw configure --section channels
Diagnostic Commands
When you are not sure where to start, running these commands in order helps narrow down where a problem is originating:
openclaw doctor # Comprehensive system health check -- always start here
openclaw gateway logs # Real-time log output from the gateway
openclaw models list # All models currently registered with OpenClaw
ollama list # All models installed on your machine
ollama ps # Models currently loaded in memory
Best Practices to Optimize OpenClaw Local Setup with Ollama
- Start with Telegram before adding other channels: It is the simplest platform to configure and the most straightforward to verify end to end. Confirm the full pipeline is working correctly before moving to WhatsApp, Slack, or other platforms.
- Set OLLAMA_KEEP_ALIVE=24h from the start: This single environment variable eliminates the model reload delay and ensures consistent response times regardless of how long the system has been idle.
- Define fallback models in your configuration: A fallback model ensures OpenClaw continues operating if the primary model is unavailable. This takes very little time to configure and significantly improves overall reliability.
- Restrict the agent workspace to a dedicated directory: Keeping the workspace path contained limits what the agent can access on your filesystem, which is the most practical mitigation for the tool-calling security surface.
- Keep context windows appropriately sized: A context window of 16,000 to 32,000 tokens is sufficient for the vast majority of real-world conversations. Only increase this if you regularly conduct sessions that require retaining very long conversation histories.
- Monitor RAM and VRAM usage during extended sessions; Running large language models is resource-intensive. If you are also running other GPU-dependent applications, memory pressure can become a factor.
- Back up your config before any edits: A single corrupted JSON field can take the entire setup offline. The backup habit takes one command and saves significant debugging time.
- Use openclaw doctoras your first diagnostic step: whenever something stops working. It identifies most common issues in seconds, which is considerably more efficient than manually reviewing logs.
Need a Production-Ready Deployment?
Setting up OpenClaw for personal use is manageable by following this guide. Deploying it within a real business environment, with appropriate security controls, performance optimization, and infrastructure that scales reliably, requires a significantly higher level of planning and technical work.
Smart Webtech manages the complete deployment from initial setup through long-term maintenance.
What we deliver:
- Full production deployment with infrastructure designed for reliability
- Security hardening: sandboxing, access control policies, permission management, and audit logging
- Performance optimization: GPU configuration, model selection, and context window calibration for your specific hardware
- Multi-channel integration: WhatsApp, Telegram, Slack, Discord, and enterprise platforms configured, tested, and monitored
- Scaling and ongoing support: multi-device rollouts, scheduled updates, monitoring, and continued technical support
Contact Smart Webtech, we help reduce manual effort and save your team meaningful time, because initial setup is just the beginning.
