> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ansible

Deploy OpenClaw to production servers with **[openclaw-ansible](https://github.com/openclaw/openclaw-ansible)**, an automated installer with a security-first architecture.

<Info>
  The [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) repo is the source of truth for Ansible deployment. This page is a quick overview.
</Info>

## 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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.19+ or 23.11+; Node 24 is recommended)
5. OpenClaw, installed host-based, not containerized
6. A systemd service with security hardening

<Note>
  The gateway runs directly on the host, not in Docker. Agent sandboxing is
  optional; this playbook installs Docker because it is the default sandbox
  backend. See [Sandboxing](/gateway/sandboxing) for other backends.
</Note>

## Post-install setup

<Steps>
  <Step title="Switch to the openclaw user">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo -i -u openclaw
    ```
  </Step>

  <Step title="Run the onboarding wizard">
    The post-install script guides you through configuring OpenClaw.
  </Step>

  <Step title="Connect messaging channels">
    Log in to WhatsApp, Telegram, Discord, or Signal:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw channels login --channel <name>
    ```
  </Step>

  <Step title="Verify the installation">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo systemctl status openclaw
    sudo journalctl -u openclaw -f
    ```
  </Step>

  <Step title="Connect to Tailscale">
    Join your VPN mesh for secure remote access.
  </Step>
</Steps>

### Quick commands

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Check service status
sudo systemctl status openclaw

# View live logs
sudo journalctl -u openclaw -f

# Restart gateway
sudo systemctl restart openclaw

# Channel login (run as openclaw user)
sudo -i -u openclaw
openclaw 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/tools/multi-agent-sandbox-tools) for sandbox configuration.

## Manual installation

<Steps>
  <Step title="Install prerequisites">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo apt update && sudo apt install -y ansible git
    ```
  </Step>

  <Step title="Clone the repository">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    git clone https://github.com/openclaw/openclaw-ansible.git
    cd openclaw-ansible
    ```
  </Step>

  <Step title="Install Ansible collections">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    ansible-galaxy collection install -r requirements.yml
    ```
  </Step>

  <Step title="Run the playbook">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    ./run-playbook.sh
    ```

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

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    ansible-playbook playbook.yml --ask-become-pass
    # Then run: /tmp/openclaw-setup.sh
    ```
  </Step>
</Steps>

## Updating

The Ansible installer sets up OpenClaw for manual updates; see [Updating](/install/updating) for the standard flow.

To re-run the playbook (for example, after configuration changes):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
cd openclaw-ansible
./run-playbook.sh
```

This is idempotent and safe to run multiple times.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Firewall blocks my connection">
    * Connect via Tailscale VPN first; the gateway is only reachable that way by design.
    * SSH (port 22) is always allowed.
  </Accordion>

  <Accordion title="Service will not start">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # Check logs
    sudo journalctl -u openclaw -n 100

    # Verify permissions
    sudo ls -la /opt/openclaw

    # Test manual start
    sudo -i -u openclaw
    cd ~/openclaw
    openclaw gateway run
    ```
  </Accordion>

  <Accordion title="Docker sandbox issues">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # Verify Docker is running
    sudo systemctl status docker

    # Check sandbox image
    sudo docker images | grep openclaw-sandbox

    # Build the sandbox image if missing (requires a source checkout)
    cd /opt/openclaw/openclaw
    sudo -u openclaw ./scripts/sandbox-setup.sh
    # For npm installs without a source checkout, see
    # https://docs.openclaw.ai/gateway/sandboxing#images-and-setup
    ```
  </Accordion>

  <Accordion title="Channel login fails">
    Make sure you are running as the `openclaw` user:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    sudo -i -u openclaw
    openclaw channels login --channel <name>
    ```
  </Accordion>
</AccordionGroup>

## Advanced configuration

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

* [Security Architecture](https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md)
* [Technical Details](https://github.com/openclaw/openclaw-ansible/blob/main/docs/architecture.md)
* [Troubleshooting Guide](https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md)

## Related

* [openclaw-ansible](https://github.com/openclaw/openclaw-ansible): full deployment guide
* [Docker](/install/docker): containerized gateway setup
* [Sandboxing](/gateway/sandboxing): agent sandbox configuration
* [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools): per-agent isolation