How to Deploy OpenClaw with Ansible

82% of configuration errors originate from manual setup or oversight, according to DataStackHub's 2025 cloud misconfiguration analysis. For an AI agent gateway like OpenClaw, the failure modes are worse than a typical web app. A missed firewall rule exposes your agent's tool-calling surface to the internet. A Docker daemon without proper iptables chains lets containers bind to public ports. Forgetting to restrict the gateway to localhost means anyone with your IP can issue agent commands.

The openclaw-ansible playbook exists to eliminate these gaps. It ships a four-layer security model that most manual install guides skip entirely: UFW firewall restricting traffic to SSH and Tailscale only, VPN-gated gateway access, Docker container isolation via the DOCKER-USER iptables chain, and systemd service hardening with NoNewPrivileges and PrivateTmp.

The playbook is idempotent. Run it once for initial setup, run it again after changing a variable, and it converges to the desired state without side effects. That matters when you need to rotate SSH keys, update Tailscale auth tokens, or switch between release and development install modes.

Before running the playbook, verify your target server meets these requirements:

Operating system: Debian 11+ or Ubuntu 20.04+. The playbook uses apt-based package management and has been tested against these distributions. macOS support was removed in February 2026 due to security concerns with system-level permissions.

Access: Root or sudo privileges on the target machine. The playbook installs system packages, configures firewall rules, and creates a dedicated service user account.

Network: Active internet connection for downloading packages. The playbook pulls Tailscale, Docker CE, Node.js 22 LTS, and the OpenClaw runtime from their respective upstream repositories.

Ansible: Version 2.14 or newer. If you use the quick-start script, it handles Ansible installation automatically. For the manual path, install it beforehand with sudo apt install -y ansible git.

Optional credentials: A Tailscale pre-auth key lets the playbook join the VPN mesh without interactive login, and SSH public keys can be passed in for key-based access on the service account. Both are set as playbook variables.

No Docker experience is needed. The playbook handles Docker installation for agent sandboxing. The OpenClaw gateway runs as a systemd service on the host, not inside a container.

The playbook supports two installation paths depending on how much control you need.

Quick-Start (Single Command)

The fast path from bare server to running OpenClaw:

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

This script installs Ansible and Git if missing, clones the repository, installs required Ansible collections from requirements.yml, and runs the playbook with default settings. The entire process takes roughly 5 to 10 minutes on a fresh VPS depending on network speed.

Manual Installation

For teams that want to inspect and customize before executing:

sudo apt update && sudo apt install -y ansible git
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible
ansible-galaxy collection install -r requirements.yml
./run-playbook.sh

The manual path lets you review and customize variables before the first run. Pass overrides inline with the extra-vars flag, or create a YAML vars file and reference it. The playbook README documents every available variable including install mode, SSH keys, Tailscale auth tokens, and Node.js version.

Release vs. Development Mode

The default release mode installs the latest stable OpenClaw from npm. Development mode clones the source repository and builds from source, which is useful for testing pre-release features or contributing patches. Switch between modes by changing a single playbook variable.

Persistent storage for your OpenClaw agents

generous storage workspace with semantic search, file versioning, and ownership transfer. Connect your OpenClaw deployment to Fastio in one command, no credit card required.

Start 14-Day Trial

The playbook implements four distinct security layers. Understanding each layer helps you verify the deployment and adapt the configuration for your network policies.

Layer 1: UFW Firewall UFW is configured to deny all inbound traffic by default, then allow only two ports: SSH (port 22) for remote management and Tailscale (port 41641/UDP) for VPN mesh connectivity. Every other port is blocked, including common web ports like 80 and 443. The OpenClaw gateway never needs to be directly reachable from the public internet.

Layer 2: Tailscale VPN

The gateway binds to localhost only, which means it refuses connections from any network interface except the loopback adapter and the Tailscale tunnel. Remote access works exclusively through the Tailscale mesh. Your other devices on the same Tailscale network can reach the gateway; public internet traffic cannot.

Layer 3: Docker Isolation Docker CE is installed for running agent sandboxes, not for containerizing the gateway. The playbook configures the DOCKER-USER iptables chain to prevent containers from exposing ports to the public internet. Agent processes run inside Docker containers with restricted network access, keeping untrusted tool executions isolated from your host system.

Layer 4: Systemd Hardening

The OpenClaw systemd service unit applies several kernel-level restrictions: NoNewPrivileges prevents the process from gaining additional capabilities, PrivateTmp gives the service its own temporary directory isolated from other processes, and ProtectSystem limits filesystem write access. The gateway runs under a dedicated service user, not root.

Additional Protections

The playbook also installs Fail2ban for SSH brute-force protection (five failed attempts trigger a one-hour ban) and enables unattended-upgrades for automatic security patches.

After deployment, verify your external attack surface:

nmap -p- YOUR_SERVER_IP

Only port 22 should respond. If additional ports appear, check your cloud provider's security group rules, as those operate independently of UFW.

The playbook exposes several variables you can override without editing the role directly.

The key variables you can override include the system account name, home directory, install mode (release or development), SSH public keys, source repository URL and branch (for development mode), Tailscale pre-auth token, and Node.js version. The official playbook README documents the full variable list with defaults.

You can set variables three ways: command-line flags with the extra-vars option, a YAML vars file, or by editing the role defaults directly.

Safe Re-Runs

Every task in the playbook is idempotent. Running ./run-playbook.sh again after changing a variable updates only what changed. Package installation checks skip already-installed packages. Firewall rules are declarative. Tailscale reconnects only if the auth key changed. The systemd service restarts only when its unit file or the OpenClaw binary is updated.

This design lets you use the playbook for ongoing configuration management, not just initial setup. Rotate SSH keys by updating the SSH keys variable and re-running. Switch from release to development mode by changing the install mode variable. Add the playbook to a CI pipeline that runs on push to your infrastructure repo, and your OpenClaw server stays in sync with your declared state.

Ansible Collection Usage

For teams managing multiple servers, install openclaw-ansible as a reusable Ansible collection:

ansible-galaxy collection install git+https://github.com/openclaw/openclaw-ansible.git

Then reference it in your existing playbooks:

- name: Deploy OpenClaw
  hosts: my_servers
  become: true
  roles:
    - openclaw.installer.openclaw

This approach integrates OpenClaw deployment into your broader infrastructure-as-code workflow alongside other roles and collections.

After the playbook finishes, switch to the dedicated service user and run the onboarding wizard. The wizard walks through provider authentication, gateway configuration, and daemon installation in a single interactive flow. For more control, the official docs list each step separately so you can configure, authenticate providers, set up the gateway, and install the daemon individually.

Verify the service is running with standard systemd commands to check the service status and follow logs.

Connecting Messaging Channels

OpenClaw supports messaging providers including Telegram, Discord, Slack, and others. After onboarding, authenticate each channel through the built-in channel login flow. The official documentation covers supported providers and configuration details.

Persistent File Storage for Agent Output

Production OpenClaw deployments generate artifacts: research documents, code files, reports, and datasets. Local server storage works initially, but it creates problems as agent workloads grow. Files scattered across a VPS have no previews, no version history, no sharing controls, and no search.

Fastio provides workspaces where agents store, organize, and share files with built-in intelligence. The Business Trial includes 50 GB storage, included credits, and 5 workspaces with no credit card required. Agents access Fastio through the MCP server with 19 consolidated tools covering workspace management, file operations, AI queries, and sharing workflows.

Compared to alternatives: S3 gives you raw object storage without previews or search. Google Drive lacks agent-native APIs. Dropbox charges per seat regardless of whether the "user" is a bot. Fastio is built for agent workflows, with Intelligence Mode that auto-indexes uploaded files for semantic search and citation-backed chat, plus ownership transfer so agents can build workspaces and hand them to humans when the project is ready.

Install the Fastio ClawHub skill to connect your OpenClaw deployment:

npx clawhub@latest install fast-io

Once installed, agents can create workspaces, upload files, run semantic searches, and transfer completed projects to human collaborators, all from within their OpenClaw tool-calling surface. See the storage for OpenClaw guide for detailed setup steps and the Fastio pricing page for plan details.