OpenClaw Installation Guide — All Platforms (Linux, macOS, Unraid)

⚠️ The Problem

Users encounter various installation issues when setting up OpenClaw, including:

Gateway won't start or is unreachable:

bash

Gateway: unreachable (connect failed: connect ECONNREFUSED 127.0.0.1:18789)

Ollama "address already in use" error:

bash

Error: listen tcp 127.0.0.1:11434: bind: address already in use

Model keeps forgetting context / "Hello, who am I?" every few messages
NPM ENOENT errors during installation:

bash

npm ERR! enoent ENOENT: no such file or directory

Small models producing garbage output (raw TTS instructions, broken formatting)
Dashboard showing "unauthorized: gateway token missing":

bash

disconnected (1008): unauthorized: gateway token missing (open a tokenized dashboard URL or paste token in Control UI settings)

systemd service name confusion:

bash

Failed to enable unit: Unit file clawdbot.service does not exist.

🔍 Why This Happens

These issues stem from different root causes:

ECONNREFUSED — The gateway daemon isn't running. OpenClaw requires the gateway to be started before you can interact with it.
Ollama "address in use" — This is actually normal! It means Ollama is already running as a background service. You don't need to start it again.
Context amnesia — The model's context window is too small, OR the model itself is too small (0.5b-3b models can't maintain coherent conversations). The Ollama docs recommend 64k context, but 128k may be the minimum that works reliably.
NPM ENOENT — Usually means you're in the wrong directory, node_modules is corrupted, or the file has a hidden extension like package.json.txt.
Garbage output from small models — Models under 7B parameters struggle with system prompts and complex instructions. The 0.5b and 3b models are essentially unusable for agent work.
Gateway token missing — The dashboard requires authentication. You need to open the tokenized URL from the CLI or configure the token in settings.
systemd naming — The service is named clawdbot-gateway.service, not clawdbot.service.

✅ The Fix

Fresh Installation

First, ensure you have the prerequisites installed:

bash

# Check Node.js version (need 22+)node --version# Install pnpm if you don't have itnpm install -g pnpm

Clone and build OpenClaw:

bash

git clone https://github.com/clawdbot/clawdbot.gitcd clawdbotpnpm installpnpm build

Run the onboarding wizard:

bash

pnpm clawdbot onboard

This walks you through model setup, workspace configuration, and channel connections (WhatsApp, Telegram, Discord, etc.).

Starting the Gateway

The gateway must be running for OpenClaw to work:

bash

# Start the gatewayopenclaw gateway start# Check statusopenclaw gateway status# Enable auto-start on boot (correct service name!)sudo systemctl enable clawdbot-gateway

Note: The service is clawdbot-gateway.service, NOT clawdbot.service.

Ollama Setup

If you see "address already in use" when running ollama serve, that's fine — Ollama is already running. Verify it's working:

bash

# Check running modelsollama ps# List installed modelsollama list# Test the APIcurl http://127.0.0.1:11434/api/tagscurl http://127.0.0.1:11434/v1/models

Important: Models don't load into RAM until something calls them. Test with:

bash

openclaw chat --model ollama/deepseek-r1:14b "hello"

Make sure you've pulled the model first:

bash

ollama pull deepseek-r1:14b

Fixing Context Amnesia

If your bot keeps forgetting who it is every 2-3 messages, the context window is too small or the model is too weak.

Minimum viable models for CPU:

Qwen2.5 7B
Llama3 8B

For reliable performance: 14B+ models recommended

Check your Ollama model's context settings. The default 64k may not be enough — try 128k if you have the VRAM:

bash

# Check VRAM usage while model is loadednvtop

Fixing NPM ENOENT Errors

bash

# Make sure you're in the project rootcd /path/to/clawdbotls package.json  # Should show the file# Clear and reinstallrm -rf node_modules package-lock.jsonpnpm install

On Windows, check if the file has a hidden extension:

powershell

ls -la | grep package# If it shows package.json.txt:ren "package.json.txt" package.json

Complete Uninstall & Fresh Start

bash

# Stop and remove the daemonopenclaw daemon stopopenclaw daemon uninstall# Delete all OpenClaw datarm -rf ~/.clawdbot# Optional: delete workspacerm -rf ~/clawd# Fresh installgit clone https://github.com/clawdbot/clawdbot.gitcd clawdbotpnpm installpnpm buildpnpm clawdbot onboard

Debugging Tips

Run these commands to diagnose issues:

bash

# Deep status checkopenclaw status --deep# Watch logs in real-timeopenclaw logs --follow# Check versionopenclaw --version

🔥 Your AI should run your business, not just answer questions.

We'll show you how.Free to join.

Join Vibe Combinator →

📋 Quick Commands

Command	Description
openclaw gateway start	Start the gateway daemon
openclaw gateway status	Check if gateway is running
sudo systemctl enable clawdbot-gateway	Enable auto-start on boot
ollama ps	List currently running Ollama models
ollama list	List all installed Ollama models
ollama pull <model>	Download a model
openclaw status --deep	Deep diagnostic check
openclaw logs --follow	Watch logs in real-time
curl http://127.0.0.1:11434/api/tags	Test Ollama API
rm -rf node_modules && pnpm install	Clean reinstall dependencies

OpenClaw Installation Guide — All Platforms (Linux, macOS, Unraid)

⚠️ The Problem

🔍 Why This Happens

✅ The Fix

Fresh Installation

Starting the Gateway

Ollama Setup

Fixing Context Amnesia

Fixing NPM ENOENT Errors

Complete Uninstall & Fresh Start

Debugging Tips

📋 Quick Commands

Related Issues

📚 You Might Also Like

Set Up OpenClaw for Beginners

30-Minute Setup Guide

OpenClaw Free Download: Install on Mac, Linux, Windows, Pi

Top 5 Ways to Install OpenClaw (2026 Guide)