Troubleshooting Guide

The install script needs curl. Install it first:

sudo apt update && sudo apt install -y curl
curl -fsSL https://openclaw.ai/install.sh | bash

OpenClaw requires Node.js 22.19 or higher. Ubuntu's default apt repositories ship an older version. If you see an error about the Node version, pull it from NodeSource instead:

# Remove the old version if present
sudo apt remove nodejs -y

# Install Node.js 24 from NodeSource
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash -
sudo apt install -y nodejs

# Verify
node --version   # should show v24.x.x
npm --version

Then re-run the OpenClaw install:

sudo npm install -g openclaw@latest

The install completed but the shell doesn't know where to find the command yet. Your PATH hasn't updated in the current session:

# Reload your shell config
source ~/.bashrc

# Or just open a new terminal session and try again
openclaw --version

If it still says command not found after reloading, find where npm puts global packages and add it to your PATH:

npm prefix -g               # shows the global prefix path
ls $(npm prefix -g)/bin    # openclaw should be in here

# Add to PATH if missing (replace /usr/local with your prefix)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Running npm install -g without sudo can fail on permission errors. Running with sudo can sometimes cause different permission problems. The cleanest fix:

# Use sudo with npm for global installs on Ubuntu
sudo npm install -g openclaw@latest

If sudo npm causes issues (sometimes it conflicts with nvm setups), fix npm's global prefix to a user-owned directory instead:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw@latest

If the onboarding wizard starts and then immediately closes or errors out, it's usually one of these:

openclaw doctor

Doctor parses your config, checks for schema violations, and verifies that any environment variables referenced with ${VAR_NAME} actually exist. If it reports an error, fix that first. The gateway won't start with a broken config.

A missing comma, mismatched brace, or stray character in openclaw.json will prevent the gateway from starting. The error message points to the approximate line number - that's where to look.

If your config references ${DISCORD_BOT_TOKEN} or similar and that variable isn't set, the gateway refuses to start with a clear error message.

echo $DISCORD_BOT_TOKEN      # should print your token
echo $TELEGRAM_BOT_TOKEN     # if using Telegram

If it prints nothing, the variable isn't set in the current session. Fix:

echo 'export DISCORD_BOT_TOKEN="your-token-here"' >> ~/.bashrc
source ~/.bashrc

For a production server, set it in the systemd service file instead so it survives reboots and works regardless of which user is logged in:

sudo systemctl edit openclaw

[Service]
Environment="DISCORD_BOT_TOKEN=your-token-here"
Environment="TELEGRAM_BOT_TOKEN=your-token-here"

sudo systemctl daemon-reload
openclaw gateway restart

If another process is already using port 18789, the gateway won't bind to it. Find what's using it:

sudo lsof -i :18789

If it's an old OpenClaw process that didn't shut down cleanly, kill it: sudo kill -9 <PID> then restart. If it's something else, change the gateway port in your config to something unused (e.g. 18790) and update your firewall rules to match.

This almost always means a runtime error on startup. Check the last 50 log lines:

openclaw logs --tail 50

Look for lines with ERROR or FATAL. Common causes at this stage: bad API key for the AI provider, invalid model string, or a channel token that was already revoked.

If OpenClaw was set up as a systemd service during onboarding, it should start automatically on boot. If it didn't:

# Check if service is enabled for auto-start
systemctl is-enabled openclaw

# Enable it if not
sudo systemctl enable openclaw

# Start it now
openclaw gateway restart

If the service doesn't exist yet (you skipped the daemon step during onboarding), re-run onboarding and accept the systemd install this time: openclaw onboard --install-daemon

This is the most common Discord problem after setup. The bot connects fine but goes completely silent. 90% of the time this is the Message Content Intent.

Pairing codes expire after a few minutes. If the code in the Discord message isn't working, it's probably stale. Send another message to the bot to trigger a fresh code, then approve immediately:

openclaw pairing approve discord PAIRING_CODE

If you keep getting pairing prompts even after approving, the approval isn't persisting - check that OpenClaw has write access to its workspace directory: ls -la ~/.openclaw/workspace/

The bot needs View Channels and Read Message History permissions in the specific channel. Check:

If OpenClaw can't reach Ollama, check whether Ollama is actually running:

# Check service status
systemctl status ollama

# Start it if stopped
sudo systemctl start ollama

# Enable on boot so this doesn't happen again
sudo systemctl enable ollama

# Verify the API is reachable
curl http://localhost:11434/api/tags

The curl command should return a JSON list of your installed models. If you get "connection refused", Ollama isn't running. If you get an empty list, it's running but you haven't pulled any models yet.

If Ollama is running but a specific model refuses to load, RAM is almost always the reason. Check how much you have free vs. how much the model needs:

# How much RAM is free right now?
free -h

# Which models are currently loaded in Ollama?
ollama ps

# How big is the model you're trying to use?
ollama list

If you're out of headroom, unload models that aren't being used - Ollama keeps recently used models in memory. Or switch to a smaller model. The Best Local AI Models 2026 guide has the full breakdown of what fits where.

CPU-only inference is inherently slower than GPU. This is normal - here's what "normal" looks like and what you can do about it:

Budget / older CPU (4 cores):    3-6 tokens/sec
Mid-range (8 cores, 16 threads): 8-15 tokens/sec
High-end (12+ cores):            15-25 tokens/sec
Apple Silicon M2/M3:             30-50+ tokens/sec

At 10 tokens/sec, a 200-word response takes about 30-40 seconds. That's normal for CPU inference - not broken, just the physics of running AI locally.

Things that actually help:

If OpenClaw is configured to use Ollama but the model name doesn't match exactly, it'll fail silently or throw a model-not-found error. Check:

ollama list

The name shown in ollama list is what goes in your OpenClaw config. The format in openclaw.json is ollama/modelname:

model: {
  primary: "ollama/qwen3:8b"    // matches "qwen3:8b" in ollama list
}

If you pulled the model with a specific tag like qwen3:8b-q8_0, use that exact tag. ollama/qwen3:8b and ollama/qwen3:8b-q8_0 are different entries.

# Cancel with Ctrl+C and retry
ollama pull qwen3:8b

# Check available disk space
df -h

Most failed downloads are either a network timeout or a full disk. Qwen3:8b is 5.2GB - make sure you have at least 8GB free (the model plus working space). If disk is the issue, remove models you're not using: ollama rm modelname.

If none of the above solved it, a few more places to look: