OpenClawDocs
On this page

On this page

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

Hosting

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 24.16+ or 26.1+; Node 26 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 gateway (run as openclaw user)openclaw gateway restart # Channel login (run as openclaw user)sudo -i -u openclawopenclaw channels login --channel <name>

    openclaw gateway restart records managed restart intent. For a system-scope service, follow the exact sudo systemctl restart <unit> command it prints.

    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?