DEV Community

Cover image for Installing OpenClaw on Linux - 0$ Personal Agentic AI Assistant - Part 4
AK DevCraft
AK DevCraft Subscriber

Posted on

Installing OpenClaw on Linux - 0$ Personal Agentic AI Assistant - Part 4

#openclaw #ai #llm #gemini

Introduction

Part 4 of the Zero Dollar AI Assistant series- Installing OpenClaw on Linux — Avoiding Every Trap. Part 1 covers the architecture. Part 2 covers Oracle Cloud setup. Part 3 covers Ollama and model selection.

OpenClaw's documentation assumes a Mac. The install script works on Linux, but several things that work automatically on Mac require manual intervention on a Linux server. This article documents every one of them, the right user to install as, the systemd service traps, the config file quirks, and the silent background token drain that will surprise you on day one.

Install as the Right User

This sounds trivial. It isn't.

The OpenClaw installer sets up a systemd user service, a service that runs under a specific user account, not as root. If you install as root, the systemd user service won't work correctly, the gateway won't auto-start on boot, and you'll spend time debugging problems that don't exist on a proper install.

Always install as a non-root user. On Oracle Cloud, that user is ubuntu.

Verify before installing:

whoami
# Must show: ubuntu
Enter fullscreen mode Exit fullscreen mode

If you're currently root, exit and SSH back in directly as ubuntu:

exit  # if su'd to root
ssh -i ~/.ssh/id_rsa ubuntu@YOUR_PUBLIC_IP
Enter fullscreen mode Exit fullscreen mode

Switching via su - ubuntu from a root session isn't sufficient; the systemd user session won't be properly initialized, and you'll get "systemd user services unavailable" errors during setup.

Installation 

# use tmux — install may take several minutes
tmux new -s openclaw
curl -fsSL https://openclaw.ai/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

The installer will launch the onboarding wizard automatically on completion.

The Onboarding Wizard

Work through each step. Key selections for this stack:

  • AI Provider: Ollama

  • Ollama host: http://localhost:11434

  • Model: Select ollama/llama3.2:3b from the browse list — look for the entry showing (ctx 128K)

  • Search provider: Skip for now — or select a provider if you have a key. Tavily has a free tier at tavily.com.

  • Secret provider: No, secrets stored in openclaw.json directly is fine for a personal server

  • Skills: Skip all for now. Add after verifying the core setup works. One gotcha: the GitHub skill tries to install via Homebrew, which doesn't exist on Linux; skip it here and install the GitHub CLI via apt afterward.

  • Hooks: Skip

  • Hatch: Select "Hatch in terminal". This verifies that the gateway starts correctly before you exit the wizard

⚠️ On first hatch, OpenClaw reads BOOTSTRAP.md from the workspace and prompts you to have a setup conversation with the agent to define its identity and personality. This is intentional — but with a local 3B model, it's very slow. Skip it by creating the files manually (covered below).

Skip the Bootstrap Conversation

The bootstrap flow is designed for interactive use; it has a conversation with you to set the agent's name, personality, and preferences. With a local 3B model, this takes 10-15 minutes of slow back-and-forth.

Create the required files manually instead:

# Create SOUL.md - agent personality and preferences
cat > ~/.openclaw/workspace/SOUL.md << 'EOF'
# Soul

## Identity
- Name: Claw
- Vibe: Casual, helpful, direct
- Emoji: 🦞

## User
- Preferred responses: Concise, no fluff
- Direct answers preferred

## Preferences
- Keep responses brief
- No unnecessary preamble
EOF

# Create IDENTITY.md
cat > ~/.openclaw/workspace/IDENTITY.md << 'EOF'
# Identity
- Name: Claw
- Nature: AI assistant
- Vibe: Casual and helpful
- Emoji: 🦞
EOF

# Create USER.md
cat > ~/.openclaw/workspace/USER.md << 'EOF'
# User
- Name: Your name here
- Preferred address: Your name
EOF

# Delete the bootstrap file to clear the pending state
rm ~/.openclaw/workspace/BOOTSTRAP.md
Enter fullscreen mode Exit fullscreen mode

Customise the files with your actual name and preferences. Once BOOTSTRAP.md is deleted, the gateway proceeds normally.

Post-Install Configuration

We don’t have to configure all the settings during onboarding; we can pick and configure as we go. That way, we don’t have to worry about having all the information that is needed, like api key or bot token, during onboarding.

1. Create a Telegram Bot and Configure the Channel

Create your bot via BotFather:

  1. Open Telegram → search @botfather
  2. Send /newbot
  3. Choose a display name (e.g., My AI Assistant)
  4. Choose a username — must end in bot (e.g., myassistant_bot)
  5. BotFather replies with your token: 12346789:AAFxxx... — save this

Add the channel to OpenClaw via the wizard:

openclaw channels add
Enter fullscreen mode Exit fullscreen mode

The wizard walks you through selecting Telegram, entering your bot token, and setting access policies. A few things to watch for during setup:

  • When asked about a secret provider — select No
  • When asked about DM access policy — select pairing (only your approved accounts can talk to the agent)
  • When asked to bind accounts to agents — select Yes

⚠️ The wizard may ask to install the Telegram plugin from npm — this may fail. Telegram is a bundled plugin. If you see this error, run openclaw plugins enable telegram first, then retry openclaw channels add.

2. Add Gemini Fallback

Add the Gemini API key you obtained in Part 3 to the systemd service:

sed -i '/Environment=OPENCLAW_SERVICE_KIND=gateway/a Environment=GEMINI_API_KEY=your_gemini_key_here' \
  ~/.config/systemd/user/openclaw-gateway.service
Enter fullscreen mode Exit fullscreen mode

Configure Ollama as primary with Gemini as fallback:

openclaw config set agents.defaults.model.primary "ollama/llama3.2:3b"
openclaw config set agents.defaults.model.fallbacks '["gemini/gemini-2.5-flash-lite"]' --json

# Add available model list
openclaw config set agents.defaults.models '{"ollama/llama3.2:1b": {}, "google/gemini-2.5-flash-lite": {}}' --json
Enter fullscreen mode Exit fullscreen mode

3. Enable Ollama Auto-Discovery

This tells OpenClaw to automatically detect all locally running Ollama models:

echo 'export OLLAMA_API_KEY=ollama-local' >> ~/.bashrc
source ~/.bashrc

sed -i '/Environment=OPENCLAW_SERVICE_KIND=gateway/a Environment=OLLAMA_API_KEY=ollama-local' \
  ~/.config/systemd/user/openclaw-gateway.service
Enter fullscreen mode Exit fullscreen mode

4. Disable mDNS

Oracle Cloud doesn't support mDNS/Bonjour, leaving it enabled causes repeated crash-restart cycles:

openclaw gateway stop
openclaw config set discovery.mdns.mode off
openclaw config set discovery.wideArea.enabled false
Enter fullscreen mode Exit fullscreen mode

5. Apply Low-Power Optimizations

These reduce startup time and memory overhead:

mkdir -p /var/tmp/openclaw-compile-cache
echo 'export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' >> ~/.bashrc
echo 'export OPENCLAW_NO_RESPAWN=1' >> ~/.bashrc

sed -i '/Environment=OLLAMA_API_KEY/a Environment=NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' \
  ~/.config/systemd/user/openclaw-gateway.service
sed -i '/Environment=NODE_COMPILE_CACHE/a Environment=OPENCLAW_NO_RESPAWN=1' \
  ~/.config/systemd/user/openclaw-gateway.service

source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

6. Add Gateway Token to CLI

The CLI needs the gateway token to authenticate against the running service:

# Get your token
python3 -c "import json; import os;d=json.load(open(os.path.expanduser('~/.openclaw/openclaw.json'))); print(d['gateway']['auth']['token'])"

# Add to bashrc
echo 'export OPENCLAW_TOKEN=your_token_here' >> ~/.bashrc
source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

7. Reload and Restart 

systemctl --user daemon-reload
openclaw gateway start
Enter fullscreen mode Exit fullscreen mode

The Silent Token Drain

This is the most important thing in this article.

OpenClaw has a background process that runs every 30 minutes — sweepStaleRunContexts which cleans up expired agent sessions. On a fresh install with default settings, this sweep triggers a Claude API call each time it runs via the startupContext feature, which loads daily memory on every session reset.

The result: if you're using the Anthropic API (not Ollama), you'll see API calls every 30 minutes even when nobody is using the assistant. Left overnight, this consumed $2-3 in API credits silently.

Disable startup context to prevent this:

openclaw gateway stop
openclaw config set agents.defaults.contextInjection.startupContext.enabled false
openclaw gateway start
Enter fullscreen mode Exit fullscreen mode

ℹ️ If you're using Ollama as your primary model with Gemini as a fallback (as set up in this series), this is less of a concern — the sweep uses your local model at zero cost. But if you ever switch to an Anthropic API key as primary, disable this first.

Verifying the Installation

  • 1. Check gateway status: 
openclaw gateway status
Enter fullscreen mode Exit fullscreen mode

A healthy output shows:

Connectivity probe: ok
Capability: read-only
Runtime: running
Enter fullscreen mode Exit fullscreen mode
  • 2. Check if the Ollama model has been discovered: 
openclaw models list
Enter fullscreen mode Exit fullscreen mode

Should show ollama/llama3.2:3b as configured.

  • 3. Check logs in real time: 
openclaw logs --follow

# You can update logging level as below
openclaw config set logging.level "info"
Enter fullscreen mode Exit fullscreen mode

Common Issues

  • systemd user services unavailable
    You installed as root or switched via su. Exit completely and SSH back in directly as the ubuntu user. A proper login session is required for systemd user services.

  • Gateway starts, but Telegram is not connecting
    The bot token isn't in the config, or the IPv6 issue is causing timeouts. Verify:

grep -i telegram ~/.openclaw/openclaw.json
curl -4 https://api.telegram.org/botYOUR_TOKEN/getMe
Enter fullscreen mode Exit fullscreen mode

  • CIAO PROBING CANCELLED crash
    mDNS is not disabled. Follow step 4 in the post-install configuration above.

  • Config changes disappear after gateway restart
    The gateway rewrites openclaw.json on startup. Always stop the gateway before editing the config:

openclaw gateway stop
# make edits
openclaw gateway start
Enter fullscreen mode Exit fullscreen mode

  • Model times out in agent mode but works in ollama run
    OpenClaw's agent mode adds tool context, memory, and session history to every request — significantly heavier than a bare model call. Switch to llama3.2:3b if using a larger model, or add Gemini as a fallback to catch timeouts.

  • HTTP 401 on CLI commands
    The OPENCLAW_TOKEN environment variable isn't set. Add it to ~/.bashrc (see step 6 above).

What's Next

Gateway running, Telegram configured, Ollama as primary, Gemini as fallback — all the pieces are in place.

Part 5 and the final part cover pairing your Telegram account, testing the end-to-end flow, and making the whole setup production-ready for daily use.

This article is the fourth in a five-part series:

  1. $0 Personal Agentic AI Assistant - Architecture
  2. Setting Up Free Cloud Server — VCN, ARM instances, static IPs, the gotchas
  3. Running Ollama on ARM — model selection, disk management, CPU inference, reality
  4. Installing OpenClaw on Linux — avoiding every trap ← you are here
  5. The Complete Setup — Telegram, end-to-end testing

Stay tuned, all links will be updated as articles are published.

If you have reached this point, I have made a satisfactory effort to keep you reading. Please be kind enough to leave any comments or share any corrections.

My Other Blogs:

Top comments (0)