Getting Started with OpenClaw on Ubuntu

I've spent the last three weeks breaking OpenClaw in every way possible so you don't have to. Here's the path from a fresh Ubuntu install to a running agent — tested, verified, and ready to replicate.

Prerequisites

Before we start, you'll need:

• Ubuntu 24.04 LTS (tested; 22.04 works with one extra step)
• Node.js 20+ (`node --version` to check)
• Git configured with SSH access to GitHub
• A sense of humor for when things break

Step 1: Install Node.js 24

Ubuntu's default Node.js is usually two major versions behind. Don't use it.

# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

# Install Node.js
sudo apt-get install -y nodejs

# Verify
node --version  # Should print v24.x.x
npm --version   # Should print 10.x.x

**What breaks here:** If you see "Command 'node' not found" after install, NodeSource may have failed silently. Check `/etc/apt/sources.list.d/` for `nodesource.list` and manually add it if missing.

Step 2: Clone and Install OpenClaw

# Clone the repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies
npm install

# Build the project
npm run build

**What breaks here:** `npm install` will fail if you don't have `build-essential` installed. OpenClaw compiles native modules for file watching and process management.

# Fix: install build tools first
sudo apt-get update
sudo apt-get install -y build-essential python3 make g++

Step 3: Configure Your First Agent

OpenClaw uses a JSON configuration file to define agents, models, and capabilities.

{
  "agents": [
    {
      "name": "my-agent",
      "model": "ollama/llama3.2",
      "capabilities": ["filesystem", "shell", "web-search"],
      "workspace": "./workspace"
    }
  ]
}

Save this as `openclaw.json` in your project root, then run:

npx openclaw run my-agent

**What breaks here:** The `ollama/llama3.2` model won't work unless Ollama is installed and running locally.

Step 4: Install Ollama (Local LLM Backend)

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

# Pull a model
ollama pull llama3.2

# Verify it's running
ollama list

**What breaks here:** Ollama binds to `localhost:11434` by default. If you see "Connection refused," check that the service is active:

systemctl status ollama
sudo systemctl start ollama  # if inactive

Step 5: Test Your Agent

With Ollama running and OpenClaw configured, test the integration:

npx openclaw run my-agent --prompt "Hello, are you working?"

You should see a response from the model. If you get a timeout, check:

1. Ollama is running (`systemctl status ollama`)

2. The model is downloaded (`ollama list`)

3. Your `openclaw.json` points to the correct model name

Common Pitfalls

**Permission denied on `/usr/local/lib/node_modules/`**

Solution: Use `npx` instead of global install, or fix npm permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

**"Module not found: fs/promises"**

Solution: Your Node.js is too old. Upgrade to v20+ using the NodeSource method above.

**Agent hangs after first message**

Solution: Increase the timeout in `openclaw.json`:

{
  "agents": [{
    "name": "my-agent",
    "model": "ollama/llama3.2",
    "timeout": 60000
  }]
}

What's Next

Now that OpenClaw is running, you can:

• Add web search capabilities (requires API key)
• Configure multiple agents with different models
• Set up cron jobs for automated tasks
• Connect to Google Workspace APIs

The next post will cover connecting OpenClaw agents to Google Workspace for automated productivity workflows — stay tuned.

Verification Checklist

Before moving on, confirm:

• [ ] Node.js v24+ installed and working
• [ ] OpenClaw builds without errors
• [ ] Ollama installed and `ollama list` shows your model
• [ ] `npx openclaw run my-agent` produces a response
• [ ] You can modify the prompt and get different outputs

If any step fails, the error message is usually in the terminal output above the failure point. Scroll up.

---

*Got questions? Hit reply. I break things so you don't have to.*