OpenClaw on Debian 12 Bookworm: Complete Setup Guide in 15 Minutes (2026)
Who This Guide Is For: Debian 12 Bookworm users — whether you run a VPS, dedicated server, or desktop — who want to install OpenClaw as a persistent 24/7 AI personal agent. This guide covers both server (headless) and desktop installations. Estimated setup time: 15 minutes. Difficulty level: Beginner-friendly.
Why Debian 12 Bookworm Is Perfect for OpenClaw
Debian 12 "Bookworm," released in June 2023, is one of the most stable and widely deployed Linux distributions in the world. It powers millions of VPS instances, dedicated servers, home labs, and developer workstations globally. Its reputation for rock-solid stability, long release cycles, and minimal bloat makes it an ideal host for OpenClaw — your personal AI agent that needs to run continuously without interruptions.
Unlike Ubuntu which ships with Snaps and additional background services, Debian 12 gives you a clean slate with only essential packages installed. This means less overhead for your AI agent, fewer system conflicts, and more predictable behavior. The systemd init system in Debian 12 also makes it straightforward to configure OpenClaw as an auto-starting background service that survives reboots, crashes, and even server migrations.
Debian 12 is also the upstream foundation for Ubuntu, Linux Mint, and many other popular distributions. If you know Ubuntu, you already know Debian — the commands are nearly identical. The main difference is that Debian uses apt without snap by default, and its package versions are slightly more conservative (older but tested extensively). For a 24/7 AI agent, stability beats cutting-edge every time.
Debian 12 vs Ubuntu 22.04 for OpenClaw: Which Is Better?
Both work excellently. Debian 12 has an edge on pure VPS/server deployments due to lower memory footprint (typically 150–200MB less RAM in use) and absence of Ubuntu's snap daemon. Ubuntu 22.04 has an edge on desktops where you want a graphical interface. This guide focuses on Debian 12 servers, but all commands also work on Ubuntu 22.04+ with no modifications.
Prerequisites: What You Need Before Starting
Before running the first command, make sure you have the following ready. OpenClaw itself is lightweight, but a few dependencies and accounts are required.
Debian 12 Bookworm System
Any Debian 12 instance: VPS (DigitalOcean, Hetzner, Linode, Vultr), dedicated server, Raspberry Pi 4/5, or desktop PC. Minimum specs: 512MB RAM (1GB recommended), 5GB free disk, internet access.
Root or Sudo Access
You need either root access or a user with sudo privileges. Most VPS providers give you root access by default. For desktops, your regular user account typically already has sudo access.
AI API Key (Free to Start)
OpenClaw supports Anthropic Claude, OpenAI GPT, Google Gemini, and local models. Get a free Claude API key at console.anthropic.com (includes $5 free credit). OpenAI keys work at platform.openai.com. Both take under 3 minutes to obtain.
Telegram Account (Recommended)
OpenClaw can communicate via Telegram, WhatsApp, Discord, Slack, Signal, or iMessage. Telegram is the easiest to set up on a Linux server since it doesn't require a desktop app. Just have your Telegram account ready on your phone.
Step 1: Update Debian 12 and Install Dependencies
Always start by updating your Debian 12 system. This ensures you have the latest security patches and that the package manager cache is current, which prevents download conflicts during Node.js installation.
# Update package lists and upgrade installed packages
sudo apt update && sudo apt upgrade -y
# Install essential build tools and curl
sudo apt install -y curl wget gnupg2 ca-certificates lsb-release git build-essential
# Verify curl is working
curl --version
The build-essential package includes gcc, make, and other tools that some npm packages need to compile native modules. Even though OpenClaw itself is pure JavaScript, some optional plugins and skills may require build tools, so it is best practice to install them upfront on Debian.
Note on Debian 12 Minimal Installations: If you installed Debian using the "minimal" or "netinstall" image (common with VPS providers), you may be missing curl and wget. The command above installs both. If you see errors about missing packages, run sudo apt install -y apt-transport-https first.
Step 2: Install Node.js 22 on Debian 12
Debian 12's default repositories include Node.js 18, but OpenClaw requires Node.js 22 LTS or newer. We use the official NodeSource repository to get the latest LTS version — this is the safest and most reliable method for Debian servers.
# Add NodeSource repository for Node.js 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# Install Node.js 22
sudo apt install -y nodejs
# Verify installation
node --version # Should show v22.x.x
npm --version # Should show 10.x.x or higher
The NodeSource setup script adds the NodeSource APT repository and its GPG signing key to your Debian 12 system. This means future apt upgrade commands will automatically keep Node.js updated to the latest 22.x release — a significant advantage over manual installations.
Do NOT use the Debian 12 default Node.js package: Running sudo apt install nodejs without adding NodeSource first will install Node.js 18.x from Debian's default repos, which is too old for OpenClaw. Always add the NodeSource repo first as shown above.
Step 3: Install OpenClaw on Debian 12
With Node.js 22 ready, installing OpenClaw takes just seconds. The official one-liner curl installer is the recommended approach for Debian servers — it handles all dependencies and PATH configuration automatically.
# Method 1: Official one-liner installer (recommended for Debian)
curl -fsSL https://openclaw.ai/install.sh | bash
# Method 2: npm global install (alternative if curl method fails)
npm install -g openclaw
# Verify installation
openclaw --version
On a Debian 12 VPS with a fast internet connection, the installation typically completes in under 30 seconds. The installer downloads OpenClaw's package from npm's registry, resolves all JavaScript dependencies, and sets up the global openclaw command. Once complete, you should see the OpenClaw version number printed to the terminal.
Hackable Install Option for Debian Power Users
If you prefer to inspect and modify OpenClaw's source code, use the hackable git-based installation. This clones the full repository and lets you modify any part of OpenClaw:
# Hackable installation from source
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
# Or manually:
git clone https://github.com/openclaw/openclaw.git ~/openclaw
cd ~/openclaw && npm install && npm run build
npm link # Makes 'openclaw' command available globally
Step 4: Run the Interactive Onboarding Wizard
OpenClaw's onboarding wizard runs in your terminal and guides you through initial configuration. This is fully text-based and works perfectly on Debian headless servers over SSH — no graphical display required.
openclaw onboard
The wizard walks you through five configuration steps, each clearly explained in the interface. Here is what to expect on Debian 12:
Select AI Model Provider
Choose between Claude (Anthropic), GPT-4o (OpenAI), Gemini (Google), or a local model via Ollama. For server deployments, Claude or GPT-4o are recommended for their superior instruction-following capability. You can switch models later at any time with openclaw config.
Enter Your API Key
Paste your Anthropic or OpenAI API key. The key is stored locally in your Debian home directory under ~/.openclaw/config.json. It is never transmitted to openclaw.ai servers — your API key goes directly from your Debian machine to the AI provider's API endpoint.
Name Your AI Agent
Give your agent a name — this becomes its persona and how it introduces itself in chats. Popular choices among Debian server users: "Nexus," "Daemon," "Igor," "Orion." The name also appears in system logs and PM2/systemd process names, so choose something recognizable.
Connect Telegram (Recommended for Servers)
On a headless Debian server, Telegram is by far the easiest integration. Open Telegram on your phone, message @BotFather, type /newbot, give it a name, and paste the bot token when prompted by OpenClaw. The whole process takes 3 minutes and requires no desktop app on the server.
Configure System Access Permissions
OpenClaw will ask what your agent is allowed to do on the Debian system — execute bash commands, read files, browse the web, write files. Start conservatively and add permissions as you explore. On a VPS, "read files, execute read-only commands, browse web" is a safe starting configuration.
Step 5: Create a systemd Service for 24/7 Operation
Unlike Windows where you use PM2 for auto-start, Debian 12 has the superior systemd init system built in. Creating a systemd service for OpenClaw gives you automatic startup on boot, crash recovery, centralized logging via journald, and easy start/stop/restart management — all without any additional tools.
First, find where OpenClaw was installed:
# Find openclaw binary location
which openclaw
# Usually: /usr/local/bin/openclaw or /usr/bin/openclaw
# Find Node.js location
which node
# Usually: /usr/bin/node or /usr/local/bin/node
Now create the systemd service file. Replace your_username with your actual Debian username:
# Create the systemd service file
sudo nano /etc/systemd/system/openclaw.service
Paste the following content into the file (adjust User and paths as needed):
[Unit]
Description=OpenClaw Personal AI Agent
After=network.target network-online.target
Wants=network-online.target
[Service]
Type=simple
User=your_username
WorkingDirectory=/home/your_username
ExecStart=/usr/local/bin/openclaw start
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw
Environment=HOME=/home/your_username
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.target
Save the file (Ctrl+X, Y, Enter in nano), then enable and start the service:
# Reload systemd to pick up the new service file
sudo systemctl daemon-reload
# Enable OpenClaw to start automatically on boot
sudo systemctl enable openclaw
# Start OpenClaw now
sudo systemctl start openclaw
# Check service status
sudo systemctl status openclaw
# View live logs
sudo journalctl -u openclaw -f
If the status shows Active: active (running) in green, OpenClaw is now running as a proper Debian system service. It will start automatically every time your server boots, restart itself within 10 seconds if it crashes, and write all logs to systemd's journal — searchable with journalctl.
Essential systemd Commands for OpenClaw Management
sudo systemctl start openclaw # Start
sudo systemctl stop openclaw # Stop
sudo systemctl restart openclaw # Restart
sudo systemctl status openclaw # Status
journalctl -u openclaw -n 50 # Last 50 lines
journalctl -u openclaw -f # Follow logs
journalctl -u openclaw --since today
systemctl is-enabled openclaw # Check if enabled
Step 6: Test Your Debian AI Agent via Telegram
With OpenClaw running as a systemd service, open Telegram on your phone or computer, navigate to the bot you created with BotFather, and send a test message to verify everything is working correctly.
You: Hello! Tell me about yourself and what you can do on this server.
Your agent should respond within 3–5 seconds with its name and server capabilities.
You: Run "uname -a" and tell me the Debian kernel version.
Tests bash command execution on your Debian 12 system.
You: Check available disk space on my server.
Tests system monitoring — your agent runs "df -h" and reports results.
You: Fetch the current Bitcoin price from the web.
Tests browser/web access capability through your Debian server's internet connection.
All four tests passing means your OpenClaw installation on Debian 12 is complete and functioning correctly. Your AI agent now has persistent memory — every conversation you have is stored and remembered. Over time, your agent builds a detailed understanding of your preferences, workflows, and goals without you having to re-explain anything.
Debian 12 Troubleshooting: Common Issues & Fixes
Issue: "openclaw: command not found" after npm install
Cause: npm's global bin directory is not in your PATH on Debian.
Fix: Run npm config get prefix. The output will be something like /usr/local. Add export PATH="$PATH:/usr/local/bin" to your ~/.bashrc, then run source ~/.bashrc.
Issue: systemd service fails with "ExecStart path is not absolute"
Fix: Use the full absolute path in the service file. Find the correct path with which openclaw and replace the ExecStart line with the full path, e.g., ExecStart=/usr/local/bin/openclaw start.
Issue: OpenClaw API calls time out or fail (Anthropic/OpenAI unreachable)
Cause: Your Debian VPS's ISP or datacenter may be routing traffic inefficiently to US-based AI API servers, or your IP may be geo-restricted.
Fix: Install VPN07 on your Debian server. With 1000Mbps dedicated bandwidth across 70+ countries, VPN07 ensures your Debian OpenClaw agent always reaches AI API endpoints reliably. This is especially important on budget VPS providers where routing quality varies significantly.
Issue: Permission denied when OpenClaw tries to read/write files
Fix: Check the User= line in your systemd service file matches the user who owns the files you want to access. The service runs as that user, so it has the same permissions as that user normally would.
Why Debian 12 + OpenClaw Servers Need VPN07
Running OpenClaw on a Debian 12 VPS is the ideal setup for a 24/7 AI agent — but there is one critical factor that can silently degrade your agent's performance: network routing quality between your VPS and the AI API servers it depends on.
Anthropic's Claude API and OpenAI's GPT API are hosted in data centers primarily in the United States and Western Europe. Budget VPS providers often have poor BGP routing to these destinations, resulting in high latency, packet loss, and occasional complete failures. A Debian VPS in Southeast Asia or Eastern Europe might take 8–15 seconds for each API call without proper routing optimization — making your AI agent feel frustratingly slow.
API Latency Comparison: Debian VPS With and Without VPN07
VPN07 solves this by providing dedicated 1000Mbps tunnels through optimized routing infrastructure in 70+ countries. Unlike consumer VPNs, VPN07's backbone has direct peering with major cloud providers, meaning your OpenClaw API requests take the shortest possible path to Anthropic and OpenAI servers. For Debian server deployments where OpenClaw handles hundreds of interactions per day, this performance difference is night and day.
VPN07 also provides a stable residential-clean IP address for your Debian server — preventing false positives in rate limiting that AI API providers sometimes apply to datacenter IP ranges. With 10 years of continuous operation and a 30-day money-back guarantee, VPN07 is the recommended network layer for any serious OpenClaw deployment on Debian Linux.
Power Your Debian OpenClaw with VPN07
1000Mbps dedicated bandwidth — built for 24/7 AI agent performance
VPN07 is the professional-grade VPN for developers and AI enthusiasts running OpenClaw on Linux servers. With 1000Mbps dedicated bandwidth across 70+ countries, 10 years of proven reliability, and direct peering to AI API infrastructure, VPN07 transforms your Debian OpenClaw server from occasionally slow to consistently lightning-fast. Just $1.5/month with a 30-day money-back guarantee — the best investment you can make for your AI agent setup.
Related Articles
OpenClaw on Ubuntu 24.04 LTS: Auto-Start Server Setup
Complete guide for running OpenClaw as a persistent service on Ubuntu 24.04 LTS with systemd and PM2 configuration.
Read More →OpenClaw on Google Cloud Free VM: Complete Install Guide
Run OpenClaw 24/7 on Google Cloud's always-free tier VM instance with zero monthly cost. Full setup walkthrough.
Read More →