OpenClaw Ansible Installer

OpenClaw is managed as a systemd service. Systemd controls the lifecycle of Docker Compose, which in turn manages the OpenClaw container. This allows for automatic startup on boot, dependency management (ensuring Docker is running before OpenClaw starts), and integration with system logs.

# Service hierarchy:
# systemd → docker compose → openclaw container

OpenClaw employs a defense-in-depth security model designed to prevent external access to the application container. The architecture relies on three layers of protection:

1. UFW Firewall: Configured to allow only SSH and Tailscale traffic.
2. DOCKER-USER Chain (iptables): Since Docker bypasses standard UFW rules, a custom DOCKER-USER chain is configured in /etc/ufw/after.rules to block all external access to containers before Docker's internal routing takes over.
3. Localhost Binding: The OpenClaw container is bound strictly to 127.0.0.1:3000. This ensures that even if firewall rules are misconfigured, the service is not reachable from the external network.

Additionally, the application follows the principle of least privilege by running as a non-root user (openclaw) inside the container.

To avoid committing sensitive data like tailscale_authkey to version control, use environment variables or Ansible Vault.

Using Ansible Vault:

1. Create an encrypted file: ansible-vault create secrets.yml.
2. Add your sensitive variable: vault_tailscale_authkey: tskey-auth-xxxxx.
3. Run the playbook referencing the secrets file and providing the vault password.

# Create the vault
ansible-vault create secrets.yml

# Run the playbook with the vault
ansible-playbook playbook.yml --ask-become-pass \
  -e @secrets.yml --ask-vault-pass

After installation, switch to the openclaw user using the correct login shell command to ensure all environment variables (like DBUS_SESSION_BUS_ADDRESS) are loaded. Once switched, verify the version and run the onboarding command to install the daemon.

# Switch to the openclaw user
sudo su - openclaw

# Verify installation
openclaw --version

# Run onboarding to install the daemon
openclaw onboard --install-daemon

After installation, you must complete three main steps: connect to Tailscale, configure the OpenClaw settings, and log in to your chosen provider.

1. Connect to Tailscale

Use sudo tailscale up for interactive login, or provide an auth key for automation:

sudo tailscale up --authkey tskey-auth-xxxxx

2. Configure OpenClaw

Edit the configuration file at /home/openclaw/.openclaw/config.yml. Key settings include:

• provider: whatsapp, telegram, or signal
• phone: your phone number
• ai.provider: anthropic or openai
• ai.model: e.g., claude-3-5-sonnet-20241022

3. Login to Provider

Run the login command inside the Docker container. This will prompt for QR code or phone verification:

sudo docker exec -it openclaw openclaw login

To monitor the connection status, check the logs:

sudo docker logs -f openclaw

Use Ansible's check mode and diff to verify your configuration without making actual changes to the system.

• Use --check to see what changes would be applied.
• Use --diff to see the specific differences in files.
• Use --tags never -vv to inspect all variables currently in scope.

# Check what variables will be used and see differences
ansible-playbook playbook.yml --ask-become-pass \
  -e @vars.yml --check --diff

# View all variables in scope
ansible-playbook playbook.yml --ask-become-pass \
  -e @vars.yml -e "ansible_check_mode=true" \
  --tags never -vv

The OpenClaw web interface (port 3000) is bound to 127.0.0.1 for security. You cannot access it directly via the server's public IP. Use one of the following two methods:

Method 1: SSH Tunnel (Standard)

Create a local tunnel to map the remote port 3000 to your local machine.

Method 2: Tailscale (Recommended)

If Tailscale is enabled, you can access the interface directly using the server's Tailscale IP address.

# Method 1: SSH Tunnel
ssh -L 3000:localhost:3000 user@server
# Then browse to http://localhost:3000

# Method 2: Tailscale
# Browse to http://TAILSCALE_IP:3000

To install OpenClaw manually, ensure you have ansible and git installed, then clone the repository, install the required Ansible collections, and run the playbook.

Prerequisites:

sudo apt update
sudo apt install -y ansible git

Installation Steps:

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

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

# Run playbook
ansible-playbook playbook.yml --ask-become-pass

OpenClaw configures unattended-upgrades to apply security patches automatically. Note that automatic reboots are disabled, so you must manually check if a reboot is required after updates.

Use these commands to monitor the update service and logs.

# Check if the service is active
sudo systemctl status unattended-upgrades

# Run a dry run to test updates
sudo unattended-upgrade --dry-run

# View update logs
sudo cat /var/log/unattended-upgrades/unattended-upgrades.log

# Check if a reboot is required
cat /var/run/reboot-required 2>/dev/null || echo "No reboot required"

For a standalone or self-hosted production setup, use the one-command installer to fetch the latest stable version from npm and configure the system automatically.

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

The development installation uses a symlink at ~/.local/bin/openclaw pointing to your local source code. This means the openclaw command uses your local code immediately after a rebuild.

Rebuilding after changes

Whenever you modify source files, you must rebuild the project to apply changes:

# Using the development alias
openclaw-rebuild

# Or manually
pnpm build

Pulling updates

To sync your local repository with the remote and rebuild:

# Using the development alias
openclaw-pull

# Or manually
cd ~/code/openclaw
git pull
pnpm install
pnpm build

Testing changes

After rebuilding, verify your changes using the CLI:

openclaw status
openclaw gateway
openclaw logs

# Rebuild and test
openclaw-rebuild
openclaw doctor