### Manual OpenClaw Installation and Setup

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Provides step-by-step instructions for manual installation, including prerequisite package installation, cloning the repository, installing Ansible collections, and running the main playbook.

```bash
sudo apt update
sudo apt install -y ansible git
```

```bash
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
```

--------------------------------

### Manual Development Setup

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/development-mode.md

Step-by-step manual installation process including dependency installation, repository cloning, and playbook execution.

```bash
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
ansible-playbook playbook.yml --ask-become-pass -e openclaw_install_mode=development
```

--------------------------------

### OpenClaw Installation Modes

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

Illustrates the commands and configurations for installing OpenClaw in both Release Mode (stable, recommended for production) and Development Mode (from source, recommended for development).

```bash
# Release Mode
pnpm install -g openclaw@latest

# Development Mode
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm build
```

```bash
# Enable Development Mode via command line
ansible-playbook playbook.yml -e openclaw_install_mode=development
```

--------------------------------

### Install Openclaw (Release Mode)

Source: https://github.com/openclaw/openclaw-ansible/blob/main/RELEASE_NOTES_v2.0.0.md

Installs the latest stable version of Openclaw globally using a script. This is the default and recommended installation method for most users.

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

--------------------------------

### OpenClaw Automation: Unattended Install

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Example of how to perform an unattended installation of OpenClaw using Ansible by providing the Tailscale authentication key as an extra variable.

```bash
# Set Tailscale auth key in playbook vars
ansible-playbook playbook.yml \
  --ask-become-pass \
  -e "tailscale_authkey=tskey-auth-xxxxx"
```

--------------------------------

### Configure OpenClaw Post-Installation

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

Commands to initialize the OpenClaw daemon, configure providers, and verify the installation status after the playbook completes.

```bash
sudo su - openclaw
openclaw onboard --install-daemon
openclaw configure
openclaw providers login
openclaw gateway
openclaw daemon install
openclaw daemon start
```

--------------------------------

### Install OpenClaw via Shell Script

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Uses the provided install.sh script to automate the installation of Ansible and the OpenClaw collection. This is the quickest method for setting up a new server.

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

--------------------------------

### Install Openclaw (Development Mode)

Source: https://github.com/openclaw/openclaw-ansible/blob/main/RELEASE_NOTES_v2.0.0.md

Sets up Openclaw in development mode by cloning the repository, building from source, and creating a symlink to the binary. This mode is intended for developers contributing to Openclaw.

```bash
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible
./run-playbook.sh -e openclaw_install_mode=development
```

--------------------------------

### Install Ansible Collection via Galaxy

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Demonstrates how to install the OpenClaw collection using ansible-galaxy, either directly from Git or via a requirements.yml file.

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

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

--------------------------------

### OpenClaw Automation: CI/CD Integration Example

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

A sample GitHub Actions workflow snippet demonstrating how to deploy OpenClaw in a CI/CD pipeline, passing secrets like the Tailscale key to the Ansible playbook.

```yaml
# Example GitHub Actions
- name: Deploy OpenClaw
  run: |
    ansible-playbook playbook.yml \
      -e "tailscale_authkey=${{ secrets.TAILSCALE_KEY }}" \
      --become
```

--------------------------------

### Install OpenClaw as Ansible Collection

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

Instructions for integrating the OpenClaw installer into existing Ansible projects via requirements.yml or command line.

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

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

--------------------------------

### Deploy in Development Mode

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

This command sets the installation mode to development and specifies a custom Git repository and branch. This is useful for testing local changes or specific feature branches.

```bash
ansible-playbook playbook.yml --ask-become-pass -e openclaw_install_mode=development -e openclaw_repo_url=https://github.com/YOUR_USERNAME/openclaw.git -e openclaw_repo_branch=feature-branch
```

--------------------------------

### Customize Ansible Installation

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/development-mode.md

Examples of overriding default Ansible variables to use custom forks, branches, or installation directories.

```yaml
ansible-playbook playbook.yml --ask-become-pass \
  -e openclaw_install_mode=development \
  -e openclaw_repo_url=https://github.com/YOUR_USERNAME/openclaw.git \
  -e openclaw_repo_branch=your-feature-branch
```

--------------------------------

### OpenClaw Service Management with Systemd

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Essential systemd commands for managing the OpenClaw service, including starting, stopping, restarting, checking status, and enabling/disabling auto-start on boot.

```bash
# Start/stop/restart
sudo systemctl start openclaw
sudo systemctl stop openclaw
sudo systemctl restart openclaw

# View status
sudo systemctl status openclaw

# Enable/disable auto-start
sudo systemctl enable openclaw
sudo systemctl disable openclaw
```

--------------------------------

### Enable Tailscale Auto-Connect

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

This command provides the required Tailscale authentication key to the playbook to enable automatic connection to the Tailscale network during installation.

```bash
ansible-playbook playbook.yml --ask-become-pass -e tailscale_authkey=tskey-auth-xxxxxxxxxxxxx
```

--------------------------------

### Execute Local Playbook with run-playbook.sh

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Runs the deployment playbook from a local repository clone. Supports custom installation modes, repository URLs, and configuration variables like SSH keys and Tailscale auth keys.

```bash
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible
./run-playbook.sh
./run-playbook.sh -e openclaw_install_mode=development
./run-playbook.sh -e openclaw_install_mode=development -e openclaw_repo_url=https://github.com/YOUR_USERNAME/openclaw.git -e openclaw_repo_branch=feature-branch
./run-playbook.sh -e "openclaw_ssh_keys=['ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... user@host']" -e tailscale_authkey=tskey-auth-xxxxxxxxxxxxx
```

--------------------------------

### Deploy OpenClaw using Ansible Playbook

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

Demonstrates two primary methods for running the OpenClaw deployment playbook: one for installations via ansible-galaxy and another for running directly from a cloned git repository.

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

```bash
ansible-playbook playbooks/deploy.yml -i inventory.yml
```

--------------------------------

### Ansible: Configure Tailscale Authentication

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Provides the Tailscale authentication key for automatic network connection. If not provided, manual setup is required.

```yaml
tailscale_authkey: "tskey-auth-k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6"
```

--------------------------------

### Verifying OpenClaw Installation Mode

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Command to check the active installation mode for OpenClaw during an Ansible playbook run. This helps confirm that the correct configuration is being applied.

```bash
ansible-playbook playbook.yml --ask-become-pass \
  -e @vars.yml --check | grep "install_mode"
```

--------------------------------

### Resolve Ansible Execution Errors

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md

Commands to install collections, handle sudo passwords, and ensure Docker is running.

```bash
ansible-galaxy collection install -r requirements.yml
ansible-playbook playbook.yml --ask-become-pass
sudo systemctl start docker
```

--------------------------------

### Configure Environment Variables and Settings for Migration

Source: https://github.com/openclaw/openclaw-ansible/blob/main/RELEASE_NOTES_v2.0.0.md

Provides commands to update shell configurations and system settings for migrating existing Openclaw installations. This includes setting environment variables like XDG_RUNTIME_DIR and PNPM_HOME, enabling systemd lingering, and configuring Homebrew.

```bash
# Add environment variables
echo 'export XDG_RUNTIME_DIR=/run/user/$(id -u)' >> ~/.bashrc
echo 'export PNPM_HOME="$HOME/.local/share/pnpm"' >> ~/.bashrc

# Enable lingering
sudo loginctl enable-linger openclaw

# Add Homebrew (Linux)
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc

# Reload
source ~/.bashrc

# Reinstall openclaw
pnpm install -g openclaw@latest
```

--------------------------------

### Copy and Edit Ansible Inventory

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

This snippet shows how to copy a sample inventory file and then edit it to define your cluster setup, including server IP addresses and optional variable configurations.

```bash
cp inventory-sample.yml inventory.yml
```

```yaml
openclaw_servers:
  children:
    server:
      hosts:
        192.16.35.11:
        192.16.35.12:
```

--------------------------------

### Ansible: Set Node.js Version

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Specifies the major version of Node.js to be installed. This is a prerequisite for running OpenClaw.

```yaml
nodejs_version: "20.x"
```

--------------------------------

### Ansible: Configure Development Mode Repository

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Variables for development mode installation, specifying the Git repository URL and branch to clone. Used when `openclaw_install_mode` is set to 'development'.

```yaml
openclaw_repo_url: "https://github.com/YOUR_USERNAME/openclaw.git"
openclaw_repo_branch: "feature-branch"
openclaw_code_dir: "/home/openclaw/projects"
openclaw_repo_dir: "/home/openclaw/projects/openclaw"
```

--------------------------------

### Ansible Verification Playbook

Source: https://github.com/openclaw/openclaw-ansible/blob/main/tests/README.md

The verify.yml playbook contains assertions to check the system's state after the Ansible playbook has been applied. It verifies configurations such as user existence, package installations, and directory creation.

```yaml
--- 
- name: Verify system state
  hosts: all
  tasks:
    - name: Assert user exists
      ansible.builtin.assert:
        that:
          - "user_exists('testuser')"

    - name: Assert packages are installed
      ansible.builtin.package_facts:
        manager: auto

    - name: Check for expected packages
      ansible.builtin.assert:
        that:
          - "'nginx' in ansible_facts.packages"
          - "'vim' in ansible_facts.packages"

    - name: Assert directory structure
      ansible.builtin.stat:
        path: "/home/testuser/.openclaw"
      register: openclaw_dir

    - name: Check .openclaw directory permissions
      ansible.builtin.assert:
        that:
          - "openclaw_dir.stat.mode == '0755'"

```

--------------------------------

### Bind Docker Containers to Localhost

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md

Example YAML configuration for Docker Compose to bind container ports exclusively to the localhost interface, preventing external access.

```yaml
ports:
  - "127.0.0.1:3000:3000"
```

--------------------------------

### Dockerfile for Ubuntu 24.04 Test Environment

Source: https://github.com/openclaw/openclaw-ansible/blob/main/tests/README.md

This Dockerfile defines the environment for testing Ansible playbooks. It uses Ubuntu 24.04 as the base image and installs Ansible, ensuring a consistent testing environment.

```dockerfile
FROM ubuntu:24.04

RUN apt-get update && apt-get install -y --no-install-recommends \
    ansible \
    ca-certificates \
    curl \
    git \
    vim \
    && rm -rf /var/lib/apt/lists/*

COPY entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh

ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

```

--------------------------------

### Development Environment Configuration

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/development-mode.md

Commands to set up the local directory structure, build the project, and create symlinks for the development binary.

```bash
mkdir -p ~/code
cd ~/code
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
ln -sf ~/code/openclaw/bin/openclaw.js ~/.local/bin/openclaw
chmod +x ~/code/openclaw/bin/openclaw.js
```

--------------------------------

### Ansible: Set OpenClaw Installation Mode

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Determines whether OpenClaw is installed from the latest release via npm or built from source in development mode. Affects installation process and dependencies.

```yaml
openclaw_install_mode: "development"
```

--------------------------------

### Configure OpenClaw using a Variables File

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

Demonstrates creating a separate YAML file (`vars.yml`) to define configuration variables and then using the `-e @vars.yml` flag to apply these settings during playbook execution.

```bash
# Create vars.yml
cat > vars.yml << EOF
openclaw_install_mode: development
openclaw_ssh_keys:
  - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx user@host"
  - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... user@host"
openclaw_repo_url: "https://github.com/YOUR_USERNAME/openclaw.git"
openclaw_repo_branch: "feature-branch"
tailscale_authkey: "tskey-auth-xxxxxxxxxxxxx"
EOF

# Use it
ansible-playbook playbook.yml --ask-become-pass -e @vars.yml
```

--------------------------------

### Manage OpenClaw via CLI

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Commands for running the onboarding wizard, configuring messaging providers, and managing the OpenClaw daemon service.

```bash
sudo su - openclaw
openclaw onboard --install-daemon
openclaw configure
openclaw providers login
openclaw gateway
openclaw daemon install
openclaw daemon start
openclaw status
openclaw logs
openclaw doctor
```

--------------------------------

### Deploy OpenClaw via Ansible

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Demonstrates how to trigger the OpenClaw deployment playbook using Ansible and how to execute the playbook from the command line with specific inventory and privilege escalation.

```yaml
- name: Deploy OpenClaw via imported playbook
  ansible.builtin.import_playbook: openclaw.installer.deploy
```

```bash
ansible-playbook your-playbook.yml -i inventory.yml --ask-become-pass
```

--------------------------------

### Debug Container Startup Failures

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md

Commands to inspect logs, rebuild images, and fix file permissions.

```bash
sudo journalctl -u openclaw -n 50
sudo docker logs openclaw
sudo docker compose -f /opt/openclaw/docker-compose.yml ps
cd /opt/openclaw
sudo docker compose build --no-cache
sudo systemctl restart openclaw
sudo chown -R openclaw:openclaw /home/openclaw/.openclaw
```

--------------------------------

### OpenClaw Configuration and Login

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Instructions for configuring OpenClaw by editing its configuration file and logging into the provider service using Docker commands. Includes checking logs for connection status.

```bash
# Edit config
sudo nano /home/openclaw/.openclaw/config.yml

# Key settings to configure:
# - provider: whatsapp/telegram/signal
# - phone: your number
# - ai.provider: anthropic/openai
# - ai.model: claude-3-5-sonnet-20241022
```

```bash
# Login (will prompt for QR code or phone verification)
sudo docker exec -it openclaw openclaw login

# Check connection
sudo docker logs -f openclaw
```

--------------------------------

### Initialize Tailscale Connectivity

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Commands to bring up the Tailscale interface on the server and identify the assigned IP address for accessing the OpenClaw web interface.

```bash
sudo tailscale up
tailscale ip -4
```

--------------------------------

### Restricting SSH Key Access

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Example of an SSH authorized_keys entry that restricts access based on the source IP address. This enhances security by limiting where the key can be used from.

```text
from="192.168.1.0/24" ssh-ed25519 AAAAC3... admin@trusted-network
```

--------------------------------

### Verify Security Configuration

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md

A collection of commands to verify the firewall status, container isolation, and service health after deployment.

```bash
sudo ufw status verbose
sudo fail2ban-client status
sudo tailscale status
sudo iptables -L DOCKER-USER -n -v
nmap -p- YOUR_SERVER_IP
sudo docker run -d -p 80:80 --name test-nginx nginx
curl http://YOUR_SERVER_IP:80
curl http://localhost:80
sudo docker rm -f test-nginx
sudo systemctl status unattended-upgrades
```

--------------------------------

### Verify Security Configuration

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

System commands to verify firewall status, service protection, network isolation, and security updates.

```bash
sudo ufw status verbose
sudo fail2ban-client status sshd
sudo iptables -L DOCKER-USER -n -v
sudo tailscale status
sudo systemctl status unattended-upgrades
```

--------------------------------

### Firewall Management with UFW and iptables

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Commands for managing the Uncomplicated Firewall (UFW) and inspecting Docker's user-defined iptables rules. Includes viewing status, adding custom rules, and reloading the firewall.

```bash
# View UFW status
sudo ufw status verbose

# Add custom rule
sudo ufw allow 8080/tcp comment 'Custom service'
sudo ufw reload

# View Docker isolation
sudo iptables -L DOCKER-USER -n -v
```

--------------------------------

### Environment-Specific Ansible Variable Files

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

YAML files defining variables for different OpenClaw deployment environments. These files specify installation modes, repository URLs, branches, SSH keys, and other environment-specific settings.

```yaml
# vars.yml
openclaw_ssh_keys:
  - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx user@desktop"
  - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHyyyyyyyy user@laptop"
```

```yaml
# vars-dev.yml
openclaw_install_mode: development
openclaw_repo_url: "https://github.com/myorg/openclaw.git"
openclaw_repo_branch: "develop"
openclaw_ssh_keys:
  - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx dev@workstation"
```

```yaml
# vars-prod.yml
openclaw_install_mode: release
tailscale_authkey: "tskey-auth-k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6"
openclaw_ssh_keys:
  - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx admin@mgmt-server"
nodejs_version: "22.x"
```

```yaml
# vars-custom.yml
openclaw_user: mybot
openclaw_home: /opt/mybot
openclaw_config_dir: /etc/mybot
openclaw_code_dir: /opt/mybot/repositories
```

```yaml
# vars-testing.yml
openclaw_install_mode: development
openclaw_repo_branch: "experimental-feature"
openclaw_ssh_keys:
  - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx tester@qa"
```

```yaml
# environments/dev.yml
openclaw_install_mode: development
openclaw_repo_url: "https://github.com/openclaw/openclaw.git"
openclaw_repo_branch: "main"
openclaw_ssh_keys:
  - "{{ lookup('file', '~/.ssh/id_ed25519.pub') }}"
```

```yaml
# environments/staging.yml
openclaw_install_mode: release
tailscale_authkey: "{{ lookup('env', 'TAILSCALE_AUTHKEY_STAGING') }}"
openclaw_ssh_keys:
  - "{{ lookup('file', '~/.ssh/id_ed25519.pub') }}"
```

```yaml
# environments/prod.yml
openclaw_install_mode: release
tailscale_authkey: "{{ lookup('env', 'TAILSCALE_AUTHKEY_PROD') }}"
openclaw_ssh_keys:
  - "ssh-ed25519 AAAAC3... ops@prod-mgmt"
  - "ssh-ed25519 AAAAC3... admin@backup-server"
nodejs_version: "22.x"
```

--------------------------------

### Ansible Playbook Execution with Variable Files

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Demonstrates how to execute an Ansible playbook using a variable file. The playbook is run with the `--ask-become-pass` option for privilege escalation and `-e @<vars_file>.yml` to load environment-specific variables.

```bash
ansible-playbook playbook.yml --ask-become-pass -e @vars.yml
```

```bash
ansible-playbook playbook.yml --ask-become-pass -e @vars-dev.yml
```

```bash
ansible-playbook playbook.yml --ask-become-pass -e @vars-prod.yml
```

```bash
ansible-playbook playbook.yml --ask-become-pass -e @vars-custom.yml
```

```bash
ansible-playbook playbook.yml --ask-become-pass -e @vars-testing.yml
```

--------------------------------

### Test Execution Script

Source: https://github.com/openclaw/openclaw-ansible/blob/main/tests/README.md

The entrypoint.sh script orchestrates the CI test process within the Docker container. It runs the Ansible playbook for convergence, then executes verification checks, and finally runs the playbook again to test idempotency.

```bash
#!/bin/bash

set -euo pipefail

ANSIBLE_PLAYBOOK="site.yml"
VERIFY_PLAYBOOK="verify.yml"

# Default to running all tests if no distro specified
DISTRO=${1:-ubuntu2404}

echo "Running Ansible playbook for convergence..."
ansible-playbook -e "ci_test=true" ${ANSIBLE_PLAYBOOK}

echo "Running verification tests..."
ansible-playbook ${VERIFY_PLAYBOOK}

echo "Running Ansible playbook for idempotency check..."
if ansible-playbook -e "ci_test=true" ${ANSIBLE_PLAYBOOK} | grep -q "changed=0"; then
  echo "Idempotency test passed: 0 changes detected."
else
  echo "Idempotency test failed: Changes detected."
  exit 1
fi

echo "All tests passed."
exit 0

```

--------------------------------

### Configure Ansible Pipelining

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md

Settings to resolve permission issues when running Ansible playbooks with become_user.

```ini
[defaults]
pipelining = True

[defaults]
allow_world_readable_tmpfiles = True
```

--------------------------------

### OpenClaw Security Verification

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Commands for verifying the security posture of the OpenClaw installation, including checking open ports with `ss`, performing external port scans with `nmap`, and testing container isolation with Docker.

```bash
# Check open ports (should show only SSH + Tailscale)
sudo ss -tlnp

# External port scan (only port 22 should be open)
nmap -p- YOUR_SERVER_IP

# Test container isolation
sudo docker run -d -p 80:80 --name test-nginx nginx
curl http://YOUR_SERVER_IP:80  # Should fail
curl http://localhost:80        # Should work
sudo docker rm -f test-nginx
```

--------------------------------

### Execute OpenClaw Ansible Playbook with Custom Modes

Source: https://github.com/openclaw/openclaw-ansible/blob/main/UPGRADE_NOTES.md

Demonstrates how to run the Ansible playbook in either default release mode or development mode. Development mode allows for custom repository URLs and branches to be specified via extra variables.

```bash
# Release mode (default)
./run-playbook.sh

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

# With custom repo
ansible-playbook playbook.yml --ask-become-pass \
  -e openclaw_install_mode=development \
  -e openclaw_repo_url=https://github.com/YOUR_USERNAME/openclaw.git \
  -e openclaw_repo_branch=feature-branch
```

--------------------------------

### OpenClaw Development Workflow

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Commands and aliases for building OpenClaw from source, managing development environments, and iterating on code changes.

```bash
./run-playbook.sh -e openclaw_install_mode=development
sudo su - openclaw
openclaw-dev
openclaw-rebuild
openclaw-pull
```

--------------------------------

### Tailscale Connection and Status

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Commands for connecting to Tailscale, including interactive login and using an authentication key for automation. Also shows how to check the Tailscale connection status.

```bash
# Interactive login
sudo tailscale up

# Or with auth key for automation
sudo tailscale up --authkey tskey-auth-xxxxx

# Check status
sudo tailscale status
```

--------------------------------

### Troubleshooting Tailscale Connection Issues

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Command to verify if a Tailscale authentication key is valid and if the Tailscale service can connect. The `--verbose` flag provides additional debugging information.

```bash
sudo tailscale up --authkey=YOUR_KEY --verbose
```

--------------------------------

### Configure OpenClaw via Ansible Variables

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Reference for default configuration variables and how to override them via the command line during playbook execution.

```yaml
ci_test: false
tailscale_enabled: false
tailscale_authkey: ""
nodejs_version: "22.x"
openclaw_port: 3000
openclaw_config_dir: "{{ openclaw_home }}/.openclaw"
openclaw_user: openclaw
openclaw_home: /home/openclaw
openclaw_install_mode: "release"
```

```bash
ansible-playbook playbook.yml --ask-become-pass \
  -e openclaw_user=mybot \
  -e openclaw_home=/opt/mybot \
  -e openclaw_install_mode=development \
  -e "openclaw_ssh_keys=['ssh-ed25519 AAAAC3... user@host']" \
  -e tailscale_authkey=tskey-auth-xxxxx \
  -e nodejs_version=22.x
```

--------------------------------

### Run OpenClaw Ansible Playbook

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

Commands to clone the repository and execute the Ansible playbook for either release or development environments.

```bash
# Development mode
./run-playbook.sh -e openclaw_install_mode=development

# Manual installation
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
```

--------------------------------

### Managing Tailscale Auth Keys with Ansible

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Shows how to securely provide a Tailscale authentication key to an Ansible playbook. It demonstrates using an environment variable, which is a recommended practice for sensitive data.

```bash
# Use environment variable
export TAILSCALE_AUTHKEY=$(vault read -field=key secret/tailscale)
ansible-playbook playbook.yml --ask-become-pass \
  -e tailscale_authkey="$TAILSCALE_AUTHKEY"
```

--------------------------------

### Recover from Firewall Lockout

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md

Steps to disable UFW, verify SSH rules, and re-enable the firewall.

```bash
sudo ufw disable
sudo ufw status numbered
sudo ufw allow 22/tcp
sudo ufw enable
```

--------------------------------

### OpenClaw Advanced Configuration: Volume Mounts

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Details on how to configure additional volume mounts in `docker-compose.yml` to persist data or integrate custom directories with the OpenClaw container.

```yaml
volumes:
  - /home/openclaw/.openclaw:/home/openclaw/.openclaw
  - /path/to/custom:/custom
```

--------------------------------

### Resolve Docker Networking and Firewall Issues

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md

Commands to inspect iptables and restart core services to restore connectivity.

```bash
sudo iptables -L DOCKER-USER -n -v
sudo systemctl restart docker
sudo ufw reload
sudo systemctl restart openclaw
```

--------------------------------

### Creating and Using Ansible Vault for Secrets

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Provides instructions for creating an encrypted Ansible Vault file to store sensitive data and how to use it with `ansible-playbook`. This ensures secrets are not exposed in plain text.

```bash
ansible-vault create secrets.yml
# Add: vault_tailscale_authkey: tskey-auth-xxxxx

ansible-playbook playbook.yml --ask-become-pass \
  -e @secrets.yml --ask-vault-pass
```

--------------------------------

### Ansible: Set Variables via Command Line

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Demonstrates how to pass Ansible variables directly on the command line using the -e flag. This method is useful for quick overrides or single-variable changes.

```bash
ansible-playbook playbook.yml --ask-become-pass \
  -e openclaw_install_mode=development \
  -e "openclaw_ssh_keys=['ssh-ed25519 AAAAC3... user@host']"
```

--------------------------------

### OpenClaw Advanced Configuration: Environment Variables

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

How to set environment variables for OpenClaw by adding them to the `docker-compose.yml` file, useful for API keys and debugging.

```yaml
environment:
  - NODE_ENV=production
  - ANTHROPIC_API_KEY=sk-ant-xxx
  - DEBUG=openclaw:*
```

--------------------------------

### OpenClaw Uninstall Procedure

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Comprehensive steps to uninstall OpenClaw, including stopping services, removing Docker containers and data, cleaning up systemd files, and optionally removing packages and the OpenClaw user.

```bash
# Stop services
sudo systemctl stop openclaw
sudo systemctl disable openclaw
sudo tailscale down

# Remove containers and data
sudo docker compose -f /opt/openclaw/docker-compose.yml down
sudo rm -rf /opt/openclaw
sudo rm -rf /home/openclaw/.openclaw
sudo rm /etc/systemd/system/openclaw.service
sudo systemctl daemon-reload

# Remove packages (optional)
sudo apt remove --purge tailscale docker-ce docker-ce-cli containerd.io docker-compose-plugin nodejs

# Remove user (optional)
sudo userdel -r openclaw

# Reset firewall (optional)
sudo ufw disable
sudo ufw --force reset
```

--------------------------------

### Troubleshooting SSH Key Permissions

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Commands to diagnose issues with SSH keys not working. This involves checking file ownership and permissions for the `.ssh` directory and the `authorized_keys` file on the target host.

```bash
sudo ls -la /home/openclaw/.ssh/
sudo cat /home/openclaw/.ssh/authorized_keys
```

--------------------------------

### Ansible: Set Variables via YAML File

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Shows how to define Ansible variables in a separate YAML file (e.g., vars.yml) and apply them using the -e @vars.yml flag. This is recommended for managing multiple configurations.

```yaml
# vars.yml
openclaw_install_mode: development
openclaw_ssh_keys:
  - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx user@host"
  - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... admin@laptop"
openclaw_repo_url: "https://github.com/YOUR_USERNAME/openclaw.git"
openclaw_repo_branch: "main"
tailscale_authkey: "tskey-auth-xxxxxxxxxxxxx"
nodejs_version: "22.x"
```

```bash
ansible-playbook playbook.yml --ask-become-pass -e @vars.yml
```

--------------------------------

### Integrate OpenClaw Deployment into Existing Playbook

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

Shows how to incorporate the OpenClaw deployment as a role or by importing a playbook within an existing Ansible playbook structure.

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

```yaml
- name: Deploy OpenClaw
  ansible.builtin.import_playbook: openclaw.installer.deploy
```

```yaml
- name: Deploy OpenClaw
  ansible.builtin.import_playbook: playbooks/deploy.yml
```

--------------------------------

### Configure Development Aliases

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/development-mode.md

Shell aliases to streamline the development workflow, including rebuilding, pulling updates, and navigating the source directory.

```bash
alias openclaw-rebuild='cd ~/code/openclaw && pnpm build'
alias openclaw-dev='cd ~/code/openclaw'
alias openclaw-pull='cd ~/code/openclaw && git pull && pnpm install && pnpm build'
export OPENCLAW_DEV_DIR="$HOME/code/openclaw"
```

--------------------------------

### Deploy to Remote Servers via Inventory

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Configures an inventory file to deploy OpenClaw across multiple remote servers. Uses the collection's deploy playbook for multi-host management.

```yaml
all:
  children:
    openclaw_servers:
      hosts:
        192.168.1.100:
        my-claw-server:
          ansible_host: 192.168.1.101
          ansible_user: admin
          openclaw_install_mode: release
  vars:
    openclaw_ssh_keys:
      - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... admin@mgmt"
    tailscale_authkey: "tskey-auth-xxxxxxxxxxxxx"
```

--------------------------------

### Ansible: Define OpenClaw User and Home Directory

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Configuration for the system user that will run OpenClaw and its home directory. These variables control user creation and file paths.

```yaml
openclaw_user: "myuser"
openclaw_home: "/home/myuser"
```

--------------------------------

### OpenClaw Container Management with Docker

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Docker commands for managing the OpenClaw container, including viewing logs, accessing the container shell, restarting the container, and checking the status of Docker Compose services.

```bash
# View logs
sudo docker logs openclaw
sudo docker logs -f openclaw  # follow

# Shell access
sudo docker exec -it openclaw bash

# Restart container
sudo docker restart openclaw

# Check status
sudo docker compose -f /opt/openclaw/docker-compose.yml ps
```

--------------------------------

### Run Playbook Directly with Ansible

Source: https://context7.com/openclaw/openclaw-ansible/llms.txt

Executes the playbook using the ansible-playbook command. This allows for fine-grained control, dry runs, and external variable file integration.

```bash
ansible-playbook playbook.yml --ask-become-pass
ansible-playbook playbook.yml --ask-become-pass --check --diff
ansible-playbook playbook.yml --ask-become-pass -e @vars.yml
```

--------------------------------

### Diagnose Container Network Connectivity

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md

Commands to verify container internet access and check UFW outbound rules.

```bash
sudo docker exec openclaw ping -c 3 8.8.8.8
sudo ufw status verbose | grep OUT
```

--------------------------------

### Security Audit and Dry Run with Ansible

Source: https://github.com/openclaw/openclaw-ansible/blob/main/README.md

Provides commands to clone the Ansible repository, review playbooks, and perform a dry run (`--check --diff`) to verify changes before applying them to the system.

```bash
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible
# Review playbook.yml and roles/
ansible-playbook playbook.yml --check --diff  # Dry run
ansible-playbook playbook.yml --ask-become-pass
```

--------------------------------

### Accessing OpenClaw via SSH Tunnel

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Demonstrates how to access the OpenClaw web interface, which is bound to localhost, by creating an SSH tunnel. This allows remote access to the local port.

```bash
ssh -L 3000:localhost:3000 user@server
# Then browse to: http://localhost:3000
```

--------------------------------

### OpenClaw Advanced Configuration: Custom Port

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/installation.md

Instructions for changing the default port OpenClaw listens on by modifying the `docker-compose.yml` file and restarting the service.

```yaml
ports:
  - "127.0.0.1:3001:3000"  # Change 3001 to desired port
```

```bash
sudo systemctl restart openclaw
```

--------------------------------

### Manage Port Conflicts

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md

Identify processes using specific ports and update docker-compose configuration.

```bash
sudo ss -tlnp | grep 3000
sudo nano /opt/openclaw/docker-compose.yml
sudo systemctl restart openclaw
```

--------------------------------

### Configure Fail2ban for SSH Protection

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/security.md

Commands to manage and verify the Fail2ban service, which protects the system against SSH brute-force attacks by banning IPs after repeated failed attempts.

```bash
sudo fail2ban-client status sshd
sudo fail2ban-client set sshd unbanip IP_ADDRESS
```

--------------------------------

### Ansible: Configure OpenClaw Service Settings

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/configuration.md

Sets the port for the OpenClaw gateway and the directory for its configuration files. The port is currently informational.

```yaml
openclaw_port: 8080
openclaw_config_dir: "/etc/openclaw"
```

--------------------------------

### Verify Docker Network Isolation

Source: https://github.com/openclaw/openclaw-ansible/blob/main/docs/troubleshooting.md

Test that external access to container ports is correctly blocked by the firewall.

```bash
sudo docker run -d -p 80:80 --name test-nginx nginx
curl http://YOUR_SERVER_IP:80
curl http://localhost:80
sudo docker rm -f test-nginx
```