Ansible

Deploy OpenClaw to production servers with openclaw-ansible -- an automated installer with security-first architecture.

Prerequisites

What you get

• Firewall-first security -- UFW + Docker isolation (only SSH + Tailscale accessible)
• Tailscale VPN -- secure remote access without exposing services publicly
• Docker -- isolated sandbox containers, localhost-only bindings
• Defense in depth -- 4-layer security architecture
• Systemd integration -- auto-start on boot with hardening
• One-command setup -- complete deployment in minutes

Quick start

One-command install:

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

What gets installed

The Ansible playbook installs and configures:

1. Tailscale -- mesh VPN for secure remote access
2. UFW firewall -- SSH + Tailscale ports only
3. Docker CE + Compose V2 -- for the default agent sandbox backend
4. Node.js 24 + pnpm -- runtime dependencies (Node 22 LTS, currently 22.19+, remains supported)
5. OpenClaw -- host-based, not containerized
6. Systemd service -- auto-start with security hardening

Post-Install Setup

sudo -i -u openclaw

openclaw channels login

sudo systemctl status openclawsudo journalctl -u openclaw -f

Quick commands

# Check service statussudo systemctl status openclaw # View live logssudo journalctl -u openclaw -f # Restart gatewaysudo systemctl restart openclaw # Provider login (run as openclaw user)sudo -i -u openclawopenclaw channels login

Security architecture

The deployment uses a 4-layer defense model:

1. Firewall (UFW) -- only SSH (22) + Tailscale (41641/udp) exposed publicly
2. VPN (Tailscale) -- gateway accessible only via VPN mesh
3. Docker isolation -- DOCKER-USER iptables chain prevents external port exposure
4. Systemd hardening -- NoNewPrivileges, PrivateTmp, unprivileged user

To verify your external attack surface:

nmap -p- YOUR_SERVER_IP

Only port 22 (SSH) should be open. All other services (gateway, Docker) are locked down.

Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway itself. See Multi-Agent Sandbox and Tools for sandbox configuration.

Manual installation

If you prefer manual control over the automation:

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

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

ansible-galaxy collection install -r requirements.yml

./run-playbook.sh

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 update flow.

To re-run the Ansible playbook (for example, for configuration changes):

cd openclaw-ansible./run-playbook.sh

This is idempotent and safe to run multiple times.

Troubleshooting

# Check logssudo journalctl -u openclaw -n 100 # Verify permissionssudo ls -la /opt/openclaw # Test manual startsudo -i -u openclawcd ~/openclawopenclaw gateway run

# Verify Docker is runningsudo systemctl status docker # Check sandbox imagesudo docker images | grep openclaw-sandbox # Build sandbox image if missing (requires source checkout)cd /opt/openclaw/openclawsudo -u openclaw ./scripts/sandbox-setup.sh# For npm installs without a source checkout, see# https://docs.openclaw.ai/gateway/sandboxing#images-and-setup

sudo -i -u openclawopenclaw channels login

Advanced configuration

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

• 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