Skip to main content
Deploy OpenClaw to production servers with openclaw-ansible, an automated installer with a security-first architecture.
The openclaw-ansible repo is the source of truth for Ansible deployment. This page is a quick overview.

​
Prerequisites

RequirementDetails
OSDebian 11+ or Ubuntu 20.04+
AccessRoot or sudo privileges
NetworkInternet connection for package installation
Ansible2.14+ (installed automatically by the quick-start script)

​
What you get

  • Firewall-first security: UFW + Docker isolation (only SSH + Tailscale reachable)
  • Tailscale VPN for remote access without exposing services publicly
  • Docker for isolated sandbox containers with localhost-only bindings
  • Systemd integration with hardening, auto-starting on boot
  • One-command setup

​
Quick start

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

​
What gets installed

  1. Tailscale (mesh VPN for secure remote access)
  2. UFW firewall (SSH + Tailscale ports only)
  3. Docker CE + Compose V2 (default agent sandbox backend)
  4. Node.js and pnpm (OpenClaw requires Node 22.19+ or 23.11+; Node 24 is recommended)
  5. OpenClaw, installed host-based, not containerized
  6. A systemd service with security hardening
The gateway runs directly on the host, not in Docker. Agent sandboxing is optional; this playbook installs Docker because it is the default sandbox backend. See Sandboxing for other backends.

​
Post-install setup

1

Switch to the openclaw user

sudo -i -u openclaw
2

Run the onboarding wizard

The post-install script guides you through configuring OpenClaw.
3

Connect messaging channels

Log in to WhatsApp, Telegram, Discord, or Signal:
openclaw channels login --channel <name>
4

Verify the installation

sudo systemctl status openclaw
sudo journalctl -u openclaw -f
5

Connect to Tailscale

Join your VPN mesh for secure remote access.

​
Quick commands

# Check service status
sudo systemctl status openclaw

# View live logs
sudo journalctl -u openclaw -f

# Restart gateway
sudo systemctl restart openclaw

# Channel login (run as openclaw user)
sudo -i -u openclaw
openclaw channels login --channel <name>

​
Security architecture

Four-layer defense model:
  1. Firewall (UFW): only SSH (22) and Tailscale (41641/udp) exposed publicly
  2. VPN (Tailscale): gateway reachable only via the VPN mesh
  3. Docker isolation: DOCKER-USER iptables chain prevents external port exposure
  4. Systemd hardening: NoNewPrivileges, PrivateTmp, unprivileged user
Verify your external attack surface: 
nmap -p- YOUR_SERVER_IP
Only port 22 (SSH) should be open. Gateway and Docker stay locked down. Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway. See Multi-Agent Sandbox and Tools for sandbox configuration.

​
Manual installation

1

Install prerequisites

sudo apt update && sudo apt install -y ansible git
2

Clone the repository

git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible
3

Install Ansible collections

ansible-galaxy collection install -r requirements.yml
4

Run the playbook

./run-playbook.sh
Or run the playbook directly and then run the setup script manually:
ansible-playbook playbook.yml --ask-become-pass
# Then run: /tmp/openclaw-setup.sh

​
Updating

The Ansible installer sets up OpenClaw for manual updates; see Updating for the standard flow. To re-run the playbook (for example, after configuration changes): 
cd openclaw-ansible
./run-playbook.sh
This is idempotent and safe to run multiple times.

​
Troubleshooting

  • Connect via Tailscale VPN first; the gateway is only reachable that way by design.
  • SSH (port 22) is always allowed.
# Check logs
sudo journalctl -u openclaw -n 100

# Verify permissions
sudo ls -la /opt/openclaw

# Test manual start
sudo -i -u openclaw
cd ~/openclaw
openclaw gateway run

# Verify Docker is running
sudo systemctl status docker

# Check sandbox image
sudo docker images | grep openclaw-sandbox

# Build the sandbox image if missing (requires a source checkout)
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh
# For npm installs without a source checkout, see
# https://docs.openclaw.ai/gateway/sandboxing#images-and-setup
Make sure you are running as the openclaw user:
sudo -i -u openclaw
openclaw channels login --channel <name>

​
Advanced configuration

For detailed security architecture and troubleshooting, see the openclaw-ansible repo: