OpenClaw Ansible Installer

Automated, hardened installation of OpenClaw with Docker and Tailscale VPN support for Debian/Ubuntu Linux.

⚠️ macOS Support: Deprecated & Disabled

Effective 2026-02-06, support for bare-metal macOS installations has been removed from this playbook.

Why?

The underlying project currently requires system-level permissions and configurations that introduce significant security risks when executed on a primary host OS. To protect user data and system integrity, we have disabled bare-metal execution.

What does this mean?

• The playbook will now explicitly fail if run on a
  Darwin
  (macOS) system.
• We strongly discourage manual workarounds to bypass this check.
• Future Support: We are evaluating a virtualization-first strategy (using Vagrant or Docker) to provide a sandboxed environment for this project in the future.

Features

• 🔒 Firewall-first: UFW firewall + Docker isolation
• 🛡️ Fail2ban: SSH brute-force protection out of the box
• 🔄 Auto-updates: Automatic security patches via unattended-upgrades
• 🔐 Tailscale VPN: Secure remote access without exposing services
• 🐳 Docker: Docker CE with security hardening
• 🚀 One-command install: Complete setup in minutes
• 🔧 Auto-configuration: DBus, systemd, environment setup
• 📦 pnpm installation: Uses
  pnpm install -g openclaw@latest

Quick Start

Release Mode (Recommended)

Install the latest stable version from npm:

Development Mode

Install from source for development or testing:

What Gets Installed

• Tailscale (mesh VPN)
• UFW firewall (SSH + Tailscale ports only)
• Docker CE + Compose V2 (for sandboxes)
• Node.js 22.x + pnpm
• OpenClaw on host (not containerized)
• Systemd service (auto-start)

Post-Install

After installation completes, switch to the openclaw user:

Then run the quick-start onboarding wizard:

This will:

• Guide you through the setup wizard
• Configure your messaging provider (WhatsApp/Telegram/Signal)
• Install and start the daemon service

Alternative Manual Setup

Installation Modes

Release Mode (Default)

• Installs via
  pnpm install -g openclaw@latest
• Gets latest stable version from npm registry
• Automatic updates via
  pnpm install -g openclaw@latest
• Recommended for production

Development Mode

• Clones from
  https://github.com/openclaw/openclaw.git
• Builds from source with
  pnpm build
• Symlinks binary to
  ~/.local/bin/openclaw
• Adds helpful aliases:
  • openclaw-rebuild
    - Rebuild after code changes
  • openclaw-dev
    - Navigate to repo directory
  • openclaw-pull
    - Pull, install deps, and rebuild
• Recommended for development and testing

Enable with:

Security

• Public ports: SSH (22), Tailscale (41641/udp) only
• Fail2ban: SSH brute-force protection (5 attempts → 1 hour ban)
• Automatic updates: Security patches via unattended-upgrades
• Docker isolation: Containers can't expose ports externally (DOCKER-USER chain)
• Non-root: OpenClaw runs as unprivileged user
• Scoped sudo: Limited to service management (not full root)
• Systemd hardening: NoNewPrivileges, PrivateTmp, ProtectSystem

Verify:

should show only port 22 open.

Security Note

For high-security environments, audit before running:

Documentation

• Configuration Guide - All configuration options
• Development Mode - Build from source
• Security Architecture - Security details
• Technical Details - Architecture overview
• Troubleshooting - Common issues
• Agent Guidelines - AI agent instructions

Requirements

• Debian 11+ or Ubuntu 20.04+
• Root/sudo access
• Internet connection

What Gets Installed

• Tailscale (mesh VPN)
• UFW firewall (SSH + Tailscale ports only)
• Docker CE + Compose V2 (for sandboxes)
• Node.js 22.x + pnpm
• OpenClaw on host (not containerized)
• Systemd service (auto-start)

Manual Installation

Release Mode (Default)

Development Mode

Build from source for development:

This will:

• Clone openclaw repo to
  ~/code/openclaw
• Run
  pnpm install
  and
  pnpm build
• Symlink binary to
  ~/.local/bin/openclaw
• Add development aliases to
  .bashrc

Configuration Options

All configuration variables can be found in

.

You can override them in three ways:

1. Via Command Line

2. Via Variables File

3. Edit Defaults Directly

Edit

before running the playbook.

Available Variables

See

for the complete list.

Common Configuration Examples

SSH Keys for Remote Access

Development Mode with Custom Repository

Tailscale Auto-Connect

License

MIT - see LICENSE

Support

• OpenClaw: https://github.com/openclaw/openclaw
• This installer: https://github.com/openclaw/openclaw-ansible/issues