Install OpenClaw with Ansible: Secure, Automated Deployment

Deploy OpenClaw onto production machines using openclaw-ansible, an installer built around a security-first design.

Info

The openclaw-ansible repository serves as the authoritative reference for Ansible-based deployments. This page only provides a brief summary.

Prerequisites

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.22.3+, 24.15+, or 25.9+; Node 26 is recommended)
5. OpenClaw, installed host-based, not containerized
6. A systemd service with security hardening

Note

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

Switch to the openclaw user

sudo -i -u openclaw

Run the onboarding wizard

The post-install script walks you through OpenClaw's configuration.

Connect messaging channels

Authenticate with WhatsApp, Telegram, Discord, or Signal:

openclaw channels login --channel <name>

Verify the installation

sudo systemctl status openclaw
sudo journalctl -u openclaw -f

Connect to Tailscale

Connect to your VPN mesh to enable secure remote access.

Quick commands

# Check service status
sudo systemctl status openclaw

# View live logs
sudo journalctl -u openclaw -f

# Restart gateway (run as openclaw user)
openclaw gateway restart

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

openclaw gateway restart signals a planned restart. When the service is system-scoped, run exactly the sudo systemctl restart <unit> command it outputs.

Security architecture

Security is layered across four tiers:

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

Check what an attacker can see from outside:

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

Install prerequisites

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

Clone the repository

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

Install Ansible collections

ansible-galaxy collection install -r requirements.yml

Run the playbook

./run-playbook.sh

Alternatively, execute the playbook yourself and then launch the setup script by hand:

ansible-playbook playbook.yml --ask-become-pass
# Then run: /tmp/openclaw-setup.sh

Updating

The Ansible installer configures OpenClaw for manual updates; the standard procedure is described in Updating.

To run the playbook again (for instance, after tweaking the configuration):

cd openclaw-ansible
./run-playbook.sh

Repeated runs are safe since the playbook is idempotent.

Troubleshooting

Firewall blocks my connection

• Always connect through Tailscale VPN first; by design, the gateway is reachable only that way.
• SSH (port 22) is permitted at all times.

Service will not start

# 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

Docker sandbox issues

# 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

Channel login fails

Verify that you are operating under the openclaw user:

sudo -i -u openclaw
openclaw channels login --channel <name>

Advanced configuration

For an in-depth look at the security model and how to resolve issues, consult the openclaw-ansible repository:

• Security Architecture
• Technical Details
• Troubleshooting Guide

Related

• openclaw-ansible: full deployment guide
• Docker: containerized gateway setup
• Sandboxing: agent sandbox configuration
• Multi-Agent Sandbox and Tools: per-agent isolation