openclaw-ansible hardens a Debian host before OpenClaw touches it

A playbook that fails rather than installs on macOS

The most unusual thing about this repository is the part it refuses to do. Effective 2026-02-06, support for bare metal macOS installations has been removed from the playbook, and the reason given is specific. The underlying project currently requires system level permissions and configurations that introduce significant security risks when executed on a primary host OS, so bare metal execution has been disabled to protect user data and system integrity. The consequence for the operator is concrete. The playbook will now explicitly fail if run on a Darwin system, and the documentation strongly discourages manual workarounds to bypass that check. The future direction is also stated, with a virtualization first strategy using Vagrant or Docker being evaluated to provide a sandboxed environment. That is a reasonable way to handle a request that cannot be satisfied safely, and it is worth noting when you are reading the project that the restriction is a security decision rather than a missing feature.

What the hardening actually covers

The feature list is short and each item maps to a real exposure. The approach is firewall first, with UFW and Docker isolation, and the firewall is opened only for SSH and the Tailscale ports. Fail2ban gives SSH brute force protection out of the box, and automatic security patches come through unattended-upgrades. Tailscale provides secure remote access without exposing services to the public internet, which is the design choice that makes the rest of the posture workable. Docker CE is installed with security hardening, and Docker is used for sandboxes rather than for OpenClaw itself. Automatic configuration covers DBus, systemd and the environment, and the OpenClaw install uses pnpm install -g openclaw@latest. The documentation lists what lands on the host: Tailscale as a mesh VPN, the UFW firewall limited to SSH and Tailscale ports, Docker CE with Compose V2 for sandboxes, Node.js 22.x with pnpm, OpenClaw on the host rather than containerised, and the systemd user service prerequisites, with onboarding installing the Gateway service. A firewall-first design with one reachable path over a VPN is a defensible default for a bot that talks to messaging providers on your behalf.

One command for the common case, a playbook for the rest

There are two entry points, and the difference between them is the difference between convenience and control. Release mode is the recommended path, and it is a single command that fetches the installer script and pipes it to a shell:

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

Development mode clones the repository and runs the playbook against it:

# Clone the installer
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible

# Install in development mode
./run-playbook.sh -e openclaw_install_mode=development

For a manual installation, the dependencies go on first, then the repository, then the Ansible collections, then the playbook:

# Install dependencies
sudo apt update && sudo apt install -y ansible git

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

# Install Ansible collections
ansible-galaxy collection install -r requirements.yml

# Run installation
./run-playbook.sh

The playbook can also be run directly with ansible-playbook, which is the form you want when you need to see what a task does before it does it:

ansible-playbook playbook.yml --ask-become-pass -e openclaw_install_mode=development

The two install modes differ in what they fetch and how they update. Release mode installs via pnpm install -g openclaw@latest, takes the latest stable version from the npm registry, and updates automatically the same way, and it is marked as recommended for production. Development mode clones from the openclaw repository, builds from source with pnpm build, symlinks the binary into ~/.local/bin/openclaw, and adds development aliases to .bashrc, including openclaw-rebuild to rebuild after code changes.

Post-install verification is part of the design

The playbook does not stop at installing software, and the part after installation is what makes the hardening claim checkable. After installation you switch to the openclaw user and run the onboarding wizard:

sudo su - openclaw

openclaw onboard --install-daemon

That wizard walks through the setup, configures the messaging provider, which is listed as WhatsApp, Telegram or Signal, and installs and starts the daemon service. The documentation then directs you to run the post install security verification, and the checks are named, which is the point. They confirm that the firewall and SSH protection are active, that Docker published ports remain externally blocked, and that OpenClaw only listens on localhost. That last check is the one that matters most for a bot that holds credentials for a messaging account, and verifying it is cheap compared with finding out later. There is also a manual path for people who do not want the wizard, with commands for configure, providers login, gateway, daemon install, daemon start, status and logs.

Using it as an Ansible collection rather than a script

The repository doubles as an Ansible collection, which is how you would use it in an existing infrastructure codebase. The collection is named openclaw.installer and can be installed with ansible-galaxy:

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

Or you can add it to the requirements.yml file of your Ansible project:

collections:
  - name: https://github.com/openclaw/openclaw-ansible.git
    type: git
    version: main

The version can be a branch, a version tag such as v2.0.0, or a specific commit hash, and pinning to a tag or a hash rather than main is the sensible choice for a collection you deploy to many hosts. Usage follows the usual collection conventions. You copy the sample inventory to inventory.yml and edit it to match your setup:

cp inventory-sample.yml inventory.yml

The inventory shape is a group with a child group and host entries, and the vars section can be edited to match your environment. The deployment then depends on how you installed the collection. With ansible-galaxy, you run the deploy playbook against your inventory:

ansible-playbook openclaw.installer.deploy -i inventory.yml

Or you reference the role from a playbook of your own:

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

And from inside a cloned repository, the equivalent is ansible-playbook playbooks/deploy.yml with your inventory, or importing the playbook from your own project. The repository layout supports all of this, with a roles/ directory, meta/ for collection metadata, galaxy.yml, playbooks/, tests/, a .ansible-lint configuration and a .yamllint configuration, so the project is set up for both consumption as a collection and development as a repository.

Editorial conclusion

Adopt openclaw-ansible if you deploy OpenClaw to Debian or Ubuntu hosts and want the firewall, SSH protection, VPN and container isolation configured the same way every time, reviewed as code. Do not adopt it on macOS, where the playbook deliberately fails, or if you need a Windows or non-Debian target. Before you run it, read the security verification document and check the UFW rules and Docker isolation against your own requirements, and if you use it as a collection, pin the version rather than tracking the main branch.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. openclaw/openclaw-ansible on GitHub
4. README