OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Containers

Ansible

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

Prerequisites

Requirement Details
OS Debian 11+ or Ubuntu 20.04+
Access Root or sudo privileges
Network Internet connection for package installation
Ansible 2.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

bash
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 24 is recommended)
  5. OpenClaw, installed host-based, not containerized
  6. A systemd service with security hardening

Post-install setup

  • Switch to the openclaw user

    bash
    sudo -i -u openclaw

  • Run the onboarding wizard

    The post-install script guides you through configuring OpenClaw.

  • Connect messaging channels

    Log in to WhatsApp, Telegram, Discord, or Signal:

    bash
    openclaw channels login --channel <name>

  • Verify the installation

    bash
    sudo systemctl status openclawsudo journalctl -u openclaw -f

  • Connect to Tailscale

    Join your VPN mesh for secure remote access.

    • Quick commands

    bash
    # Check service statussudo systemctl status openclaw # View live logssudo journalctl -u openclaw -f # Restart gatewaysudo systemctl restart openclaw # Channel login (run as openclaw user)sudo -i -u openclawopenclaw 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:

    bash
    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

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

  • Clone the repository

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

  • Install Ansible collections

    bash
    ansible-galaxy collection install -r requirements.yml

  • Run the playbook

    bash
    ./run-playbook.sh

    Or run the playbook directly and then run the setup script manually:

    bash
    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):

    bash
    cd openclaw-ansible./run-playbook.sh

    This is idempotent and safe to run multiple times.

    Troubleshooting

    Firewall blocks my connection
    • Connect via Tailscale VPN first; the gateway is only reachable that way by design.
    • SSH (port 22) is always allowed.
    Service will not start
    bash
    # Check logssudo journalctl -u openclaw -n 100 # Verify permissionssudo ls -la /opt/openclaw # Test manual startsudo -i -u openclawcd ~/openclawopenclaw gateway run
    Docker sandbox issues
    bash
    # Verify Docker is runningsudo systemctl status docker # Check sandbox imagesudo docker images | grep openclaw-sandbox # Build the sandbox image if missing (requires a 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
    Channel login fails

    Make sure you are running as the openclaw user:

    bash
    sudo -i -u openclawopenclaw channels login --channel <name>

    Advanced configuration

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

    Was this useful?
    On this page

    On this page