swarm-master/ansible/docs/configuration.md

Configuration Guide

This guide explains all available configuration options for the OpenClaw Ansible installer.

Configuration File

All default variables are defined in: roles/openclaw/defaults/main.yml

How to Configure

Method 1: Command Line Variables

Pass variables directly via -e flag:

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

Method 2: Variables File

Create a vars.yml file:

# 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"

Then use it:

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

Method 3: Edit Defaults

Directly edit roles/openclaw/defaults/main.yml before running the playbook.

Note: This is not recommended for version control, use variables files instead.

Available Variables

User Configuration

openclaw_user

• Type: String
• Default: openclaw
• Description: System user name for running OpenClaw
• Example:

  -e openclaw_user=myuser
  

openclaw_home

• Type: String
• Default: /home/openclaw
• Description: Home directory for the openclaw user
• Example:

  -e openclaw_home=/home/myuser
  

openclaw_ssh_keys

• Type: List of strings
• Default: [] (empty)
• Description: SSH public keys for accessing the openclaw user account
• Example:

  openclaw_ssh_keys:
    - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGxxxxxxxx user@host"
    - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB... admin@laptop"
  

  -e "openclaw_ssh_keys=['ssh-ed25519 AAAAC3... user@host']"
  

Installation Mode

openclaw_install_mode

• Type: String (release or development)
• Default: release
• Description: Installation mode
  • release: Install via npm (pnpm install -g openclaw@latest)
  • development: Clone repo, build from source, symlink binary
• Example:

  -e openclaw_install_mode=development
  

Development Mode Settings

These variables only apply when openclaw_install_mode: development

openclaw_repo_url

• Type: String (Git URL)
• Default: https://github.com/openclaw/openclaw.git
• Description: Git repository URL to clone
• Example:

  -e openclaw_repo_url=https://github.com/YOUR_USERNAME/openclaw.git
  

openclaw_repo_branch

• Type: String
• Default: main
• Description: Git branch to checkout
• Example:

  -e openclaw_repo_branch=feature-branch
  

openclaw_code_dir

• Type: String (Path)
• Default: {{ openclaw_home }}/code
• Description: Directory where code repositories are stored
• Example:

  -e openclaw_code_dir=/home/openclaw/projects
  

openclaw_repo_dir

• Type: String (Path)
• Default: {{ openclaw_code_dir }}/openclaw
• Description: Full path to openclaw repository
• Example:

  -e openclaw_repo_dir=/home/openclaw/projects/openclaw
  

OpenClaw Settings

openclaw_port

• Type: Integer
• Default: 3000
• Description: Port for OpenClaw gateway (currently informational)
• Example:

  -e openclaw_port=8080
  

openclaw_config_dir

• Type: String (Path)
• Default: {{ openclaw_home }}/.openclaw
• Description: OpenClaw configuration directory
• Example:

  -e openclaw_config_dir=/etc/openclaw
  

Node.js Configuration

nodejs_version

• Type: String
• Default: 22.x
• Description: Node.js major version to install
• Example:

  -e nodejs_version=20.x
  

Tailscale Configuration

tailscale_authkey

• Type: String
• Default: "" (empty - manual setup required)
• Description: Tailscale authentication key for automatic connection
• Example:

  -e tailscale_authkey=tskey-auth-k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6
  

• Get Key: https://login.tailscale.com/admin/settings/keys

OS-Specific Settings

These are automatically set based on the detected OS:

homebrew_prefix

• Type: String (Path)
• Default: /opt/homebrew (macOS) or /home/linuxbrew/.linuxbrew (Linux)
• Description: Homebrew installation prefix
• Read-only: Set automatically based on OS

package_manager

• Type: String
• Default: brew (macOS) or apt (Linux)
• Description: System package manager
• Read-only: Set automatically based on OS

Configuration Examples

Basic Setup with SSH Keys

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

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

Development Setup

# 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"

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

Production Setup with Tailscale

# 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"

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

Custom User and Directories

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

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

Testing Different Branches

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

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

Environment-Specific Configurations

Development Environment

# 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') }}"

Staging Environment

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

Production Environment

# 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"

Security Best Practices

SSH Keys

1. Use dedicated keys: Create separate SSH keys for OpenClaw access

   ssh-keygen -t ed25519 -f ~/.ssh/openclaw_ed25519 -C "openclaw-access"
   

2. Limit key permissions: Use SSH key options to restrict access

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

3. Rotate keys regularly: Update SSH keys periodically

   ansible-playbook playbook.yml --ask-become-pass \
     -e "openclaw_ssh_keys=['$(cat ~/.ssh/new_key.pub)']"
   

Tailscale Auth Keys

1. Use ephemeral keys for temporary access
2. Set expiration times for auth keys
3. Use reusable keys only for automation
4. Store in secrets manager: Don't commit to git

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

Sensitive Variables

Never commit sensitive data to git:

# ❌ BAD - Don't do this
tailscale_authkey: "tskey-auth-actual-key-here"

# ✅ GOOD - Use environment variables or vault
tailscale_authkey: "{{ lookup('env', 'TAILSCALE_AUTHKEY') }}"

# ✅ GOOD - Use Ansible Vault
tailscale_authkey: "{{ vault_tailscale_authkey }}"

Create encrypted vault:

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

Validation

After configuration, verify settings:

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

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

Troubleshooting

SSH Keys Not Working

Check file ownership and permissions:

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

Tailscale Not Connecting

Verify auth key is valid:

sudo tailscale up --authkey=YOUR_KEY --verbose

Installation Mode Issues

Check which mode is active:

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

See Also

• Main README
• Development Mode Guide
• Upgrade Notes
• Defaults File