The OpenClaw 30-minute setup guide.

IntroBefore we start

OpenClaw is useful, but setup can be fussy. This guide is for people who do not want a lecture about Linux. You are going to copy, paste, check a few things, and stop when the screen says it worked.

You have two good beginner paths:

This version uses OpenCode for local agent work. It does not use Ollama because Ollama can be heavier than we want on a Raspberry Pi.

KitWhat you need

The easiest setup looks like:

• ✓Raspberry Pi 5 with 8GB RAM
• ✓Official power supply
• ✓Case with cooling
• ✓SSD storage if possible
• ✓Raspberry Pi OS 64-bit
• ✓Ethernet or reliable Wi-Fi
• ✓A laptop/desktop to SSH into the Pi

If you only have a Pi 4 with 8GB RAM, you can experiment, but expect more waiting.

Step 1Prepare the Pi

Translation: we’re just going to update the Pi and give it a little extra memory to breathe. You don’t have to understand every line — just paste it in.

Open a terminal on the Pi, or SSH in from your laptop.

Update the system

sudo apt update
sudo apt upgrade -y
sudo reboot

After it reboots, reconnect. Then install basic tools:

sudo apt install -y git curl build-essential cmake pkg-config

Add some breathing room (swap)

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Check memory to make sure swap is on:

free -h

Step 2Install OpenCode

OpenCode is a friendly AI helper you run in the terminal. Think of it as your assistant who lives in the Pi.

curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

Then check it installed:

opencode --help

Step 3Pick a model provider

A model provider is just “who the AI actually is.” We’re starting with a cloud one because it’s easier to tell what’s working.

Fast beginner plan:

• Use OpenCode with a cloud model first.

• Add local Raspberry Pi models second.

Why? Because if both OpenClaw and the local model are broken at the same time, it’s harder to know what failed. One thing at a time.

Use whatever provider you already have. OpenCode supports many, and it can also use local models through a custom provider (we’ll set that up in a minute).

Step 4Install a lightweight local model server

This sets up the part that actually runs a tiny AI model on your Pi. We use llama.cpp because it’s lighter than Ollama and the Pi will thank you.

Download and build llama.cpp

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build --config Release -j 4

Make a folder for your models

mkdir -p ~/models

Start the local server

cd ~/llama.cpp
./build/bin/llama-server \
  -m ~/models/YOUR_MODEL_FILE.gguf \
  --host 127.0.0.1 \
  --port 8080 \
  -c 2048

Leave that terminal open. In a second terminal window, test it:

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-pi",
    "messages": [
      {"role": "user", "content": "Say hello in one short sentence."}
    ]
  }'

Step 5Point OpenCode at the local server

We’re telling OpenCode: “hey, your AI lives at this address on this Pi.” That’s it.

mkdir -p ~/.config/opencode
nano ~/.config/opencode/opencode.json

Paste this in and save (in nano, that’s Ctrl+O, Enter, then Ctrl+X):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "local-pi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Local Raspberry Pi",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "local-pi": {
          "name": "Local Pi Model"
        }
      }
    }
  },
  "model": "local-pi/local-pi"
}

Start OpenCode:

opencode

Ask something small:

write a 3-line checklist for testing a Raspberry Pi service

Step 6Install OpenClaw

Now we install OpenClaw itself — the control room that uses all of this.

If you are installing OpenClaw on the same Pi, keep expectations modest.

curl -fsSL https://openclaw.ai/install.sh | bash

Then run the doctor to check everything is okay:

openclaw doctor

If everything is green, open the OpenClaw web page using the address shown by the installer.

Step 7Connect a real AI provider first

Before connecting your shiny new Pi model, let’s make sure OpenClaw itself works. Using a cloud model is like plugging in a known-working lamp to check the outlet.

For your first OpenClaw test, use one cloud provider first:

• OpenAI

• Gemini

• Claude

• Another provider OpenClaw supports

After OpenClaw works, add the local Pi endpoint as an experiment if your version of OpenClaw supports a custom OpenAI-compatible provider:

Base URL: http://127.0.0.1:8080/v1
API key:  anything-local
Model:    local-pi

If OpenClaw is on a different machine than the Pi, replace 127.0.0.1 with the Pi’s local network IP, and bind llama-server to your LAN:

--host 0.0.0.0

Step 8Connect Telegram

Last bit: give OpenClaw a way to talk to you. Telegram is the easiest.

In Telegram:

1. Search for @BotFather.
2. Send /newbot.
3. Copy the token it gives you.

In OpenClaw:

1. Go to Channels.
2. Add Telegram.
3. Paste the token.
4. Send your bot a test message.

Fix itIf something breaks

This is normal. Here are the usual ones:

ShortEasiest setup, if you just want it to work

• Run OpenClaw on a VPS.

• Run OpenCode on your laptop or Pi.

• Run tiny local models only for experiments.

• Use cloud models for serious OpenClaw tasks.

• Move one piece at a time.

That is not failure. That is how you keep the machine from becoming soup.