On this page
📋 Prerequisites
- OS: Ubuntu 22.04+, Debian 12+, or Fedora 39+ (x86_64 or ARM64)
- RAM: 1 GB minimum, 2 GB recommended
- Node.js: 22.12.0+ (includes critical security fixes)
- AI API key: Anthropic, OpenAI, OpenRouter, or Google
# Check your distro
cat /etc/os-release | head -3
# Check if Node.js is installed
node --version # Need 22.12.0+
📦 Install Node.js 22+
Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version
Fedora
sudo dnf module install nodejs:22
node --version
Alternative: nvm (any distro)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node --version
🦞 Install OpenClaw
# Option 1: One-liner (recommended)
curl -fsSL https://openclaw.ai/install.sh | bash
# Option 2: npm global install
sudo npm install -g openclaw
# Option 3: From source
git clone https://github.com/openclaw/openclaw.git ~/.openclaw-src
cd ~/.openclaw-src && pnpm install && pnpm ui:build && pnpm build
pnpm link -g
openclaw onboard --install-daemon
# Verify
openclaw --version
🧙 Run the onboarding wizard
openclaw onboard --install-daemon
The wizard guides you through:
- Choosing an AI provider and entering your API key
- Selecting a model
- Setting up your first channel (Telegram recommended)
- Configuring workspace files
- Installing the daemon for auto-start
💡 The
--install-daemon flag automatically creates a systemd service so OpenClaw starts on boot and restarts on crashes. If you skip it, see the next section for manual setup.⚙️ Daemon setup (manual)
If you didn't use --install-daemon, create the systemd service manually:
sudo tee /etc/systemd/system/openclaw.service <<'EOF'
[Unit]
Description=OpenClaw Gateway
After=network-online.target
[Service]
Type=simple
User=$USER
ExecStart=/usr/bin/openclaw gateway
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
✅ Verify everything works
# Is the gateway running?
openclaw gateway status
# Health check
openclaw doctor
# Test AI model connectivity
openclaw test model
# Open WebChat
openclaw dashboard
# → http://localhost:18789
Send a test message in WebChat. If you get a response, you're good.
📂 Key files & paths
| What | Path |
|---|---|
| Config | ~/.openclaw/openclaw.json |
| Workspace | ~/.openclaw/workspace/ |
| Credentials | ~/.openclaw/credentials/ |
| Cron jobs | ~/.openclaw/cron/ |
| Daily logs | ~/.openclaw/workspace/memory/ |
| Gateway logs | journalctl -u openclaw |
| Daemon | /etc/systemd/system/openclaw.service |
🔧 Troubleshooting
| Problem | Fix |
|---|---|
| “openclaw: command not found” | Check PATH: which openclaw. If npm global, add $(npm prefix -g)/bin to PATH. |
| Node.js too old | Need 22.12.0+. Run node --version. Upgrade via nvm or NodeSource. |
| Port 18789 in use | lsof -i :18789 — kill the other process or change gateway port in config. |
| Daemon won't start | journalctl -u openclaw -e — check for errors. Most common: wrong User in service file. |
| sharp module errors | sudo npm install -g sharp — common on ARM. May need build tools: sudo apt install build-essential |
| Permission denied on ~/.openclaw | chmod 700 ~/.openclaw && chmod 600 ~/.openclaw/openclaw.json |
🚀 What's next
- First 24 Hours — configure SOUL.md, USER.md, connect your first channel
- Security Guide — lock down DM policies, sandboxing, permissions
- VPS Deploy — if you're setting up on a remote server
- Channels Overview — connect Telegram, WhatsApp, Discord