Set Up ZeroClaw Bot Locally with Ollama (Complete 2026 Guide)

Running your own AI assistant locally means zero cloud bills, zero data leaving your machine, and full control over which model handles your queries. ZeroClaw makes that setup surprisingly straightforward. It acts as a lightweight gateway layer that connects a chat interface — such as Telegram — to a locally running Ollama instance, letting you chat with models like Llama 3.2 or Qwen 2.5 as if you were using any commercial bot.

This guide walks through every step using the official zeroclaw-labs repository as it stood in April 2026. The process was validated on Ubuntu, and the same steps apply to macOS. Windows users should expect extra friction around paths and environment variables, but the core flow is identical.

Getting the prerequisites right saves you from half the troubleshooting issues that appear in community threads.

Hardware Minimums

• A solid CPU (GPU is optional but speeds things up considerably)
• At least 8 GB of RAM if you plan to test models larger than 7B parameters
• Raspberry Pi setups need 4 GB or more RAM to remain stable

Recommended operating systems: Ubuntu 22.04 or 24.04 delivers the cleanest experience. macOS runs without issues. Windows works but config files and paths require extra attention.

Ollama carries the inference load. ZeroClaw adds almost nothing on top of it, so size your hardware around the model, not the gateway.

---

How to Install Ollama and Pull Your First Model

Install Ollama using the official one-line script:

curl -fsSL https://ollama.com/install.sh | sh

Start the server in a dedicated terminal window:

ollama serve

In a second terminal, pull a starting model. Keep it small on the first run:

ollama pull llama3.2
# or qwen2.5:7b if you want faster initial replies

Run a quick sanity check to confirm inference is working:

ollama run llama3.2 "Tell me a short joke"

Keep the ollama serve process alive throughout the rest of this guide. ZeroClaw defaults to connecting at http://localhost:11434, so the server must be running before you launch the gateway.

---

Installing ZeroClaw on Your Machine

Visit the repository at https://github.com/zeroclaw-labs/zeroclaw before proceeding.

One-Line Bootstrap Command

Most users start here:

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

The install script frequently launches the onboard wizard automatically, so watch the terminal output. If it does not, you will run it manually in the next section.

Building from Source with Cargo (Optional)

If you want the absolute newest code or want to patch something yourself, build from source:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo build --release

The compiled binary lands at target/release/zeroclaw. Either add that directory to your PATH or reference the full path when running commands.

Running the Onboard Wizard

After installation, run:

zeroclaw onboard

This command creates your workspace, sets the gateway port (default 8080), and prompts for provider details.

Handling the Dummy API Key Requirement

ZeroClaw insists on a value in the API key field during initial onboarding, even for local providers. Type a placeholder such as sk-dummy123. Once the provider switches to Ollama, that dummy entry is ignored entirely.

First Test Chat in the CLI

After onboarding completes, confirm the basic connection works:

zeroclaw chat "What is the capital of France?"

A successful response from Ollama at this stage confirms the core connection is healthy before you wire up any messaging channel.

---

Configuring ZeroClaw to Use Ollama as Provider

The main configuration file lives at ~/.zeroclaw/config.toml or inside the workspace folder created during onboarding.

Editing config.toml

Here is the full working block:

default_provider = "ollama"

[providers.ollama]
base_url = "http://localhost:11434"
default_model = "llama3.2"   # Must match `ollama list` exactly
temperature = 0.7

[provider_extra_body]
think = false

A simpler version that some users prefer:

[provider]
name = "ollama"
default_model = "qwen2.5:7b"

Save the file and restart the gateway after any change.

Common Model Tag Mistakes

Model names must match the exact tag shown by ollama list, including any suffix like :7b. Even a single typo causes silent failures or unexpected fallbacks to a default model. When using a remote Ollama instance, update base_url to the correct IP and port. Firewall rules and incorrect addresses account for the majority of connection problems reported in community forums.

---

Connecting ZeroClaw to Telegram

Telegram provides the fastest path to a real chat interface running locally without building a custom frontend.

Creating a Telegram Bot Token

Open Telegram, search for @BotFather, and send /newbot. Pick a name and a username that ends in "bot". BotFather replies with a token in the format 123456:ABC-DEF..... Copy it.

Binding the Channel and Testing Messages

Run the channel-only onboarding flow:

zeroclaw onboard --channels-only

Select Telegram and paste your token. Add your own Telegram username or numeric user ID so the bot responds only to you.

Launch the gateway:

zeroclaw gateway

Send any message to your bot on Telegram. Replies arrive from your local Ollama model with no cloud hop in between.

For permanent operation, run the gateway inside tmux, screen, or a systemd service so the process survives terminal closure.

Early 2026 releases carried several rough edges. The fixes below appear most frequently in community reports.

Tool Calling Handshakes That Fail

Confirm Ollama is running in its own terminal and that base_url matches exactly. Scan the ZeroClaw logs for connection errors. Certain models handle tool calling more reliably than others — if one model consistently refuses tool calls, swap to a different one before digging further.

Long First-Response Times on CPU

Large models can need 10 to 20 minutes for the very first inference when running on CPU alone. Use 3B to 8B parameter models for everyday work, or attach a GPU. Ollama detects available hardware automatically and offloads layers accordingly.

Context Window Errors in Scheduled Tasks

Automated jobs can exceed context limits when prompts accumulate over long sessions. Shorten prompts, adjust pacing settings in the config file, or disable skill auto-updates for fully offline operation:

[skills]
auto_update = false

---

Performance Expectations and Hardware Tips

ZeroClaw barely registers in system monitors. The Ollama model you choose dictates the real limits.

• The binary hovers near 3.4 MB; idle RAM stays under 20 MB.
• First responses feel sluggish on CPU with bigger models but improve noticeably after the initial context loads into memory.
• Move to smaller quantized models when replies feel too slow.
• GPU support drops latency sharply because Ollama offloads matrix operations to VRAM.
• On laptops or Raspberry Pi devices, 7B class models typically deliver the best speed-to-quality balance for general-purpose chat.