OpenClawForArchLinux.md

This guide is designed for a Linux Systems Engineer workflow. We are going to build a hardened, performant environment for OpenClaw on your ThinkPad X1 Carbon. Given your i7-8650U and 16GB RAM, we have plenty of overhead, but we will optimize for efficiency.

SYSTEM ENVIRONMENT

• OS: Arch Linux x86_64 (latest rolling release)
• Host: 20KGS9HK00 ThinkPad X1 Carbon 6th
• Kernel: 6.19.6-arch1-1
• Shell: bash 5.3.9
• Resolution: 1920x1080
• Window Manager: DWM
• Display Server: X11
• CPU: Intel i7-8650U (8) @ 4.200GHz
• GPU: Intel Kaby Lake-R GT2 [UHD Graphics 620]
• Memory: 1219MiB / 15728MiB
• Packages: 971 (pacman) + yay

---

Phase 1: System Preparation & Dependencies

Arch Linux is the perfect playground for this, but we need the right toolchain. We will use yay for AUR packages and standard pacman for core binaries.

1. Update and Base Tooling

First, ensure your microcode and build headers are current.

sudo pacman -Syu --needed base-devel git cmake python python-pip

2. Node.js Strategy (LTS)

For a stable agent, Node.js LTS is non-negotiable. While Arch’s nodejs package is usually the latest (Current), we want iron (v20) or hydrogen (v18). I recommend using fnm (Fast Node Manager) for speed, or nodejs-lts-iron from the official repos.

Recommendation: Use the system LTS for the dedicated service user to avoid shell-init overhead in systemd.

sudo pacman -S nodejs-lts-iron npm

3. pnpm vs. npm

Verdict: Use pnpm. OpenClaw has many nested dependencies. pnpm uses a content-addressable store, which saves significant disk space and, more importantly, prevents the "heavy node_modules" performance drag on your SSD.

sudo npm install -g pnpm

---

Phase 2: Security-First Setup

Running an AI agent that has "Browser Control" and "Terminal Access" capabilities as your primary user is a massive security risk. We will isolate it.

1. Create a Dedicated User

sudo useradd -m -s /bin/bash openclaw
sudo passwd openclaw # Set a secure password

2. Directory Structure

We will follow the XDG standard for the user.

sudo mkdir -p /home/openclaw/ai/openclaw
sudo chown -R openclaw:openclaw /home/openclaw/ai

---

Phase 3: Installing OpenClaw from Source

Switch to the service user to perform the installation. This ensures all pnpm caches and config files remain within the restricted environment.

sudo -u openclaw -i
cd ~/ai/openclaw
git clone https://github.com/OpenClaw/OpenClaw.git .
pnpm install

Troubleshooting Arch-Specific Build Errors:

• Missing Python headers: If node-gyp fails, ensure python is in your path (Arch does this by default).
• C++17 Errors: Ensure gcc is version 13+ (Standard on Arch now).
• Memory Pressure: If the build hangs, your 16GB is enough, but check if zram is swapping too aggressively.

---

Phase 4: Environment Configuration

OpenClaw relies on a .env file for its brain and limbs.

1. Create the Environment File

cp .env.example .env
nano .env

2. Configuration Strategy

• Model Provider: For a local-first feel with high intelligence, use Anthropic (Claude 3.5 Sonnet) or OpenRouter.
• Local LLM: If you want 100% local, set the base URL to your Ollama instance ($http://localhost:11434/v1$).

Example .env Snippet:

# Provider Config
PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-xxx

# Agent Settings
AGENT_NAME="Claw-X1"
LOG_LEVEL=info

# Integrations (Optional)
TELEGRAM_BOT_TOKEN=...

---

Phase 5: The Onboarding Process

Run the initial setup to generate your identity keys and database schemas.

pnpm run setup

Onboarding Options Explained:

1. Identity Setup: Creates the cryptographic keys the agent uses to sign messages.
2. Memory Initialization: Sets up the local JSON/Vector store in ~/ai/openclaw/memory.
3. Skill Discovery: Scans the skills/ folder to see what the agent is allowed to do (e.g., read files, search web).

---

Phase 6: Persistence with Systemd

Since you are on Arch, we will use a systemd user service. This allows the agent to start when the user logs in (or at boot if lingering is enabled) without requiring root.

1. Create the Service File

As the openclaw user:

mkdir -p ~/.config/systemd/user/
nano ~/.config/systemd/user/openclaw.service

2. Service Definition

[Unit]
Description=OpenClaw Personal AI Agent
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/openclaw/ai/openclaw
ExecStart=/usr/bin/pnpm start
Restart=always
RestartSec=10
StandardOutput=append:/home/openclaw/ai/openclaw/logs/stdout.log
StandardError=append:/home/openclaw/ai/openclaw/logs/stderr.log

[Install]
WantedBy=default.target

3. Enable and Start

systemctl --user daemon-reload
systemctl --user enable --now openclaw

To keep this running without an active SSH/TTY session: sudo loginctl enable-linger openclaw

---

Phase 7: Browser Control Setup

OpenClaw uses Playwright to "see" the web. Arch requires specific dependencies for the bundled Chromium to run.

1. Install Dependencies

sudo pacman -S nspr nss nss-mdns alsa-lib atk at-spi2-core cups dbus expat fontconfig freetype2 gdk-pixbuf2 glib2 gtk3 libdrm libx11 libxcb libxcomposite libxdamage libxext libxfixes libxi libxrandr libxrender libxtst pango mesa

2. Install Playwright Binaries

As the openclaw user:

npx playwright install chromium

---

Phase 8: File Structure Explanation

Folder	Purpose
memory/	The "Long-term memory." Contains vector embeddings and JSON history. Backup this folder.
skills/	Executable scripts (JS/TS). This is how the agent interacts with your Arch system.
cron/	Scheduled tasks (e.g., "Check my email every hour").
heartbeats/	Vital signs. Used for monitoring the health of the agent process.
configs/	Modular configuration files for specific integrations (Telegram/Discord).

---

Phase 9: Performance & Troubleshooting

Optimization for your i7-8650U:

• CPU Pinning: If OpenClaw spikes during builds, you can limit the systemd service using CPUQuota=200% (limiting it to 2 of your 8 threads).
• Memory Control: Set NODE_OPTIONS="--max-old-space-size=2048" in your .env to prevent the agent from eating your 16GB RAM during complex tasks.

Common Arch Issues:

• Node Version Conflicts: If you see GLIBC_X.XX not found, you are likely using a Node binary built for a different distro. Stick to pacman or fnm.
• Permission Errors: Ensure the openclaw user has rx permissions on the parent directory /home/openclaw.

---

Phase 10: Advanced - Local LLM (Ollama)

If you want to run this fully offline:

1. Install Ollama: yay -S ollama-bin.
2. Serve it: systemctl enable --now ollama.
3. In .env, set BASE_URL=http://localhost:11434/v1 and MODEL=llama3.

---