# How to Set Up OpenClaw on Ubuntu 24.04 with Local AI: A Real-World Guide

**SEO Title:** How to Set Up OpenClaw on Ubuntu 24.04 with Local AI (Ollama + AMD GPU): A Real-World Guide

**SEO Description:** A complete, honest walkthrough of installing and configuring OpenClaw on Ubuntu 24.04 with Ollama, local LLMs, AMD GPU ROCm setup, memory search, and API integrations — including every error we hit and how we solved them.

**Tags:** OpenClaw, Ubuntu 24.04, Ollama, local AI, AMD GPU, ROCm, llama, self-hosted AI, Linux AI setup, qwen2.5, memory search, embeddings, home lab AI, privacy-first AI

---

## The Goal

Run OpenClaw completely locally on Ubuntu 24.04 — no data leaving the machine, no cloud dependency, using a local LLM via Ollama for chat responses and local embeddings for memory search.

**Hardware:** iMac (2017), Intel i5-7400, 31GB RAM, AMD Radeon RX 560 (Polaris/gfx803)
**OS:** Ubuntu 24.04.4 LTS (Noble), kernel 6.17.0-14-generic (HWE)

This is a real, unfiltered account of two weeks of work — every error hit, every fix found. If you're trying to run OpenClaw locally on Linux, this is the guide we wish existed.

---

## Step 1: Start with openclaw doctor

After install, always run the health check first:

```bash
openclaw doctor --fix
```

Common issues it will surface:

- Orphan transcript files (doctor fixes these automatically)
- Memory search provider not configured
- Missing API keys
- Telegram channel errors (if you haven't set up a bot)

The `--fix` flag handles simple issues automatically. Anything remaining needs manual intervention.

---

## Step 2: Fix Memory Search — Local Embeddings

The doctor will likely complain about memory search having no embedding provider configured. It will list OpenAI, Google, Voyage, and Mistral as options. But if you want to stay fully local, ignore all of those.

### Setting up local embeddings

First check what's already working:

```bash
openclaw memory status --deep
```

If it shows `Provider: none` and `Embeddings: unavailable`, configure it:

```bash
openclaw config set agents.defaults.memorySearch.provider local
```

**Important:** Don't try to set `localModel` or `localEndpoint` via config — those keys don't exist in the schema and will throw validation errors. OpenClaw picks its own built-in local embedding model automatically (embeddinggemma-300m-qat) when you set provider to `local`.

Then create the missing memory directory:

```bash
mkdir -p ~/.openclaw/workspace/memory
```

Run `openclaw memory status --deep` again. You should now see:

```
Provider: local
Embeddings: ready
Vector: ready
FTS: ready
```

That's all you need. Memory search is working.

### What NOT to do

The doctor output suggests running `openclaw agents add <id>` or copying `auth-profiles.json`. Ignore this for local embeddings — it's not needed and will send you down the wrong path.

---

## Step 3: Configure Your LLM (Ollama)

OpenClaw needs a model to generate responses. For local-only use, Ollama is the way to go.

### Install Ollama

Follow the official Ollama install for Linux. Once installed, pull a model:

```bash
ollama pull llama3.2:3b
```

**Important:** `llama3.2:3b` is a generation model, not an embedding model. Don't try to use it for memory search embeddings — it won't work.

### Point OpenClaw at Ollama

```bash
openclaw config set agents.defaults.model "ollama/qwen2.5:0.5b"
openclaw gateway restart
```

Note the format: `ollama/model-name` with a forward slash. Using a colon (e.g. `ollama:model`) will cause an error like:

```
Unknown model: anthropic/ollama:qwen2.5:0.5b
```

OpenClaw was prepending "anthropic/" to the model string because of the colon format.

### Choosing the right model for your hardware

Not all models are equal on CPU-only hardware. On an i5-7400:

- `llama3.2:3b` — ~53 seconds per response on CPU. Too slow for practical use.
- `qwen2.5:0.5b` — ~10 seconds per response on CPU. Usable.

Always match model size to your hardware. On older CPUs without GPU acceleration, smaller is better.

### Tuning Ollama for performance

Set thread count and reduce context window:

```bash
sudo systemctl edit ollama
```

Add:

```
[Service]
Environment="OLLAMA_NUM_THREADS=4"
Environment="OLLAMA_CONTEXT_LENGTH=512"
```

Then restart:

```bash
sudo systemctl restart ollama
```

This brought response time from 53 seconds down to ~10 seconds on a 0.5b model.

---

## Step 4: AMD GPU Acceleration (RX 560 / gfx803) — The Hard Road

This section documents what we tried and why it didn't work, so you can avoid the same rabbit holes.

### The problem

Ollama running 100% on CPU is slow. The system has an AMD Radeon RX 560, which should be able to accelerate inference. AMD uses ROCm for GPU compute on Linux.

```bash
ollama ps
# NAME           PROCESSOR    
# qwen2.5:0.5b   100% CPU     ← problem
```

### Attempt 1: ROCm 7.x (latest)

```bash
# Find the right .deb for Ubuntu 24.04 (noble)
curl -s https://repo.radeon.com/amdgpu-install/latest/ubuntu/noble/ | grep -o 'amdgpu-install[^"]*\.deb'
wget https://repo.radeon.com/amdgpu-install/latest/ubuntu/noble/amdgpu-install_7.2.70200-1_all.deb
sudo apt install ./amdgpu-install_7.2.70200-1_all.deb
sudo amdgpu-install --usecase=rocm
```

**Result:** Installs fine, but `rocminfo` fails with `HSA_STATUS_ERROR`. The RX 560 (gfx803/Polaris) was dropped from ROCm support in newer versions.

### Attempt 2: Force gfx version

```bash
HSA_OVERRIDE_GFX_VERSION=8.0.3 rocminfo
```

**Result:** Same error. The override doesn't help when support is fully removed.

### Attempt 3: OpenCL via Mesa

```bash
sudo apt install mesa-opencl-icd clinfo
clinfo | grep "Device Name"
```

OpenCL detected the GPU successfully via Mesa/radeonsi. However, Ollama on Linux requires ROCm for AMD GPU acceleration — OpenCL alone is not enough.

### Attempt 4: ROCm 6.2 (last version with noble support and possible gfx803 support)

```bash
wget https://repo.radeon.com/amdgpu-install/6.2/ubuntu/noble/amdgpu-install_6.2.60200-1_all.deb
sudo apt install ./amdgpu-install_6.2.60200-1_all.deb
sudo amdgpu-install --usecase=rocm
```

**Result:** The amdgpu-dkms kernel module fails to build against kernel 6.17:

```
error: conflicting types for '__dma_fence_is_later'
error: implicit declaration of function 'vm_insert_pfn'
```

ROCm 6.2's driver code is incompatible with kernel 6.17 API changes.

### Attempt 5: Downgrade kernel to 6.8

```bash
sudo apt install linux-image-6.8.0-51-generic linux-headers-6.8.0-51-generic
```

**Result:** The amdgpu-dkms module also fails to build for 6.8 (different errors). The 6.8 kernel itself boots but freezes — likely because the broken amdgpu-dkms left the system in a bad state.

### The root cause

Ubuntu 24.04's HWE (Hardware Enablement) kernel automatically tracks bleeding-edge kernels. We ended up on 6.17, which is too new for ROCm 6.x drivers. ROCm 7.x dropped gfx803 support. There's no version of ROCm that simultaneously supports Ubuntu 24.04 (noble), kernel 6.17, and gfx803.

### Cleanup after failed ROCm install

```bash
sudo amdgpu-install --uninstall
sudo apt remove --purge amdgpu-install
sudo dpkg --remove --force-remove-reinstreq amdgpu-dkms
sudo dpkg --purge amdgpu-dkms
sudo apt autoremove
```

Verify clean:

```bash
dpkg -l | grep amdgpu-dkms
# Should return nothing
```

### Checking your display renderer

After the ROCm cleanup, you may find your display is running in software mode:

```bash
sudo apt install mesa-utils
glxinfo | grep "OpenGL renderer"
```

If you see `llvmpipe`, your GPU is not being used for display. Fix:

```bash
sudo apt install xserver-xorg-video-amdgpu mesa-vulkan-drivers
sudo reboot
```

### Bottom line on AMD GPU + ROCm

If you have an RX 560 or similar older AMD card (gfx803), GPU acceleration via ROCm is not currently achievable on Ubuntu 24.04 with the HWE kernel. Your options are:

- Accept CPU-only inference and use small models (qwen2.5:0.5b works)
- Use a cloud API (OpenAI, Gemini) for speed while keeping local embeddings
- Upgrade to a newer AMD GPU (gfx1000 series or later) with current ROCm support

---

## Step 5: User/Group Permissions for ROCm (for reference)

Even if ROCm doesn't work on your card, here's the correct permissions setup for future reference or for users with supported hardware:

```bash
sudo usermod -aG render,video $USER
sudo reboot
```

Verify after reboot:

```bash
id
# Should show render and video in groups
```

`sudo su - username` and logout/login without full reboot may not apply group changes — a full reboot is required.

---

## Step 6: Disable Telegram (Stop the Log Spam)

If you're not using Telegram, your logs will be flooded with 404 errors as OpenClaw repeatedly tries to connect:

```
telegram deleteWebhook failed: Call to 'deleteWebhook' failed! (404: Not Found)
```

Fix:

```bash
openclaw config set channels.telegram.enabled false
openclaw gateway restart
```

---

## Step 7: Adding a Remote API (Optional Fallback)

If local inference is too slow for your use case, you can add a remote API while keeping local embeddings for memory search. This gives you fast responses without sending your memory/context data to the cloud.

### OpenAI / GPT

```bash
openclaw configure
# Follow prompts to add API key
```

Check available models:

```bash
openclaw models list
```

Set your preferred model:

```bash
openclaw config set agents.defaults.model "openai/gpt-5-mini"
openclaw gateway restart
```

Model string format matters — use the exact string from `openclaw models list`.

### Google Gemini

To add a Gemini key:

```bash
openclaw configure
```

Note: `openclaw config set auth.google.apiKey "key"` will throw `Unrecognized key: "google"` — the interactive `configure` command is required for Google auth.

Getting a Gemini API key requires Google AI Studio (aistudio.google.com/apikey). If it redirects, try a different browser or incognito mode. US users should have access but browser/account issues can block it.

**Security reminder:** Never paste API keys into chat interfaces or terminals while screen sharing. If you accidentally expose a key, revoke it immediately from the provider's dashboard.

---

## Lessons Learned

**On OpenClaw config:** Not all config keys are accepted via `openclaw config set`. Some auth and provider settings require the interactive `openclaw configure` command. When you get a `Config validation failed: Unrecognized key` error, try the interactive path instead.

**On model naming:** The format for Ollama models is `ollama/model-name` (forward slash). Colons in the model name confuse the parser.

**On ROCm and Ubuntu:** The HWE kernel tracks aggressively new kernel versions. ROCm driver DKMS modules often lag behind by several kernel versions. If GPU acceleration matters to you, consider pinning your kernel version or using a non-HWE install.

**On model selection:** For CPU-only inference, model size matters enormously. A 0.5b model at 10 seconds per response is far more usable than a 3b model at 53 seconds, even if the quality is lower.

**On memory search:** OpenClaw's local embedding provider works out of the box — no external API needed, no Ollama embedding model needed. It uses a bundled model (embeddinggemma-300m-qat). Just set provider to `local` and create the workspace directory.

---

## Quick Reference: Key Commands

```bash
# Health check
openclaw doctor --fix

# Memory status
openclaw memory status --deep

# Set local embedding provider
openclaw config set agents.defaults.memorySearch.provider local
mkdir -p ~/.openclaw/workspace/memory

# Set Ollama as LLM
openclaw config set agents.defaults.model "ollama/qwen2.5:0.5b"

# Tune Ollama performance
sudo systemctl edit ollama
# Add: Environment="OLLAMA_NUM_THREADS=4"
# Add: Environment="OLLAMA_CONTEXT_LENGTH=512"

# Disable Telegram
openclaw config set channels.telegram.enabled false

# Restart gateway
openclaw gateway restart

# View live logs
openclaw logs --follow

# List available models
openclaw models list

# Interactive configuration (for API keys)
openclaw configure
```

---

## Hardware Compatibility Notes

| Component | Status | Notes |
|-----------|--------|-------|
| AMD RX 560 (gfx803) + ROCm 7.x | ❌ Not supported | gfx803 dropped |
| AMD RX 560 + ROCm 6.2 + kernel 6.17 | ❌ DKMS build fails | Kernel API incompatible |
| AMD RX 560 + OpenCL (Mesa) | ✅ Detects GPU | But Ollama can't use OpenCL |
| Ollama CPU-only, qwen2.5:0.5b | ✅ Works | ~10s response on i5-7400 |
| Local embeddings (embeddinggemma) | ✅ Works | No GPU needed |
| OpenAI/GPT-5-mini via API | ✅ Works | Fast, but cloud |

---

*This guide will be updated as OpenClaw, ROCm, and Ubuntu HWE kernels continue to evolve. If you've found a working path for gfx803 + ROCm on Ubuntu 24.04 noble, please share it.*