Instalacao via Ansible

A forma recomendada de implantar o OpenClaw em servidores de producao e via openclaw-ansible — um instalador automatizado com arquitetura focada em seguranca.

Inicio Rapido

Instalacao em um comando:

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

📦 Guia completo: github.com/openclaw/openclaw-ansible

O repositorio openclaw-ansible e a referencia para implantacao via Ansible. Esta pagina e apenas uma visao geral.

O que voce recebe

  • 🔒 Seguranca por firewall: UFW + isolamento Docker (apenas SSH + Tailscale acessiveis)
  • 🔐 Tailscale VPN: Acesso remoto seguro sem expor servicos publicamente
  • 🐳 Docker: Containers sandbox isolados, bindings apenas em localhost
  • 🛡️ Defesa em profundidade: Arquitetura de seguranca em 4 camadas
  • 🚀 Configuracao em um comando: Implantacao completa em minutos
  • 🔧 Integracao com systemd: Inicio automatico com hardening

Requisitos

  • SO: Debian 11+ ou Ubuntu 20.04+
  • Acesso: Privilegios root ou sudo
  • Rede: Conexao com a internet para instalacao de pacotes
  • Ansible: 2.14+ (instalado automaticamente pelo script de inicio rapido)

O que e instalado

O playbook Ansible instala e configura:

  1. Tailscale (VPN mesh para acesso remoto seguro)
  2. Firewall UFW (apenas portas SSH + Tailscale)
  3. Docker CE + Compose V2 (para sandboxes de agentes)
  4. Node.js 24 + pnpm (dependencias de runtime; Node 22 LTS, atualmente 22.16+, continua suportado para compatibilidade)
  5. OpenClaw (no host, nao containerizado)
  6. Servico systemd (inicio automatico com hardening de seguranca)

Observacao: o gateway roda diretamente no host (nao no Docker), mas os sandboxes de agentes usam Docker para isolamento. Consulte Sandboxing para detalhes.

Configuracao pos-instalacao

Apos a instalacao, mude para o usuario openclaw:

sudo -i -u openclaw

O script pos-instalacao vai guia-lo por:

  1. Assistente de onboarding: Configurar as opcoes do OpenClaw
  2. Login no provedor: Conectar WhatsApp/Telegram/Discord/Signal
  3. Teste do gateway: Verificar a instalacao
  4. Configuracao do Tailscale: Conectar ao seu mesh VPN

Comandos uteis

# Verificar status do servico
sudo systemctl status openclaw

# Ver logs em tempo real
sudo journalctl -u openclaw -f

# Reiniciar o gateway
sudo systemctl restart openclaw

# Login no provedor (executar como usuario openclaw)
sudo -i -u openclaw
openclaw channels login

Arquitetura de seguranca

Defesa em 4 camadas

  1. Firewall (UFW): Apenas SSH (22) + Tailscale (41641/udp) expostos publicamente
  2. VPN (Tailscale): Gateway acessivel apenas via mesh VPN
  3. Isolamento Docker: Chain iptables DOCKER-USER impede exposicao externa de portas
  4. Hardening systemd: NoNewPrivileges, PrivateTmp, usuario sem privilegios

Verificacao

Teste a superficie de ataque externa:

nmap -p- YOUR_SERVER_IP

Voce deve ver apenas a porta 22 (SSH) aberta. Todos os outros servicos (gateway, Docker) estao bloqueados.

Disponibilidade do Docker

O Docker e instalado para sandboxes de agentes (execucao isolada de ferramentas), nao para rodar o gateway em si. O gateway escuta apenas em localhost e e acessivel via VPN Tailscale.

Consulte Multi-Agent Sandbox & Tools para configuracao de sandbox.

Instalacao manual

Se voce prefere controle manual sobre a automacao:

# 1. Instalar pre-requisitos
sudo apt update && sudo apt install -y ansible git

# 2. Clonar repositorio
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible

# 3. Instalar colecoes Ansible
ansible-galaxy collection install -r requirements.yml

# 4. Executar playbook
./run-playbook.sh

# Ou executar diretamente (depois execute manualmente /tmp/openclaw-setup.sh)
# ansible-playbook playbook.yml --ask-become-pass

Atualizando o OpenClaw

O instalador Ansible configura o OpenClaw para atualizacoes manuais. Consulte Atualizacao para o fluxo padrao.

Para re-executar o playbook Ansible (por exemplo, para mudancas de configuracao):

cd openclaw-ansible
./run-playbook.sh

Observacao: a operacao e idempotente e segura para executar varias vezes.

Solucao de problemas

Firewall bloqueia minha conexao

Se voce ficou trancado do lado de fora:

  • Certifique-se de que consegue acessar via VPN Tailscale primeiro
  • Acesso SSH (porta 22) e sempre permitido
  • O gateway e acessivel apenas via Tailscale, por design

Servico nao inicia

# Verificar logs
sudo journalctl -u openclaw -n 100

# Verificar permissoes
sudo ls -la /opt/openclaw

# Testar inicio manual
sudo -i -u openclaw
cd ~/openclaw
pnpm start

Problemas com sandbox Docker

# Verificar se o Docker esta rodando
sudo systemctl status docker

# Verificar imagem sandbox
sudo docker images | grep openclaw-sandbox

# Construir imagem sandbox se ausente
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh

Login no provedor falha

Certifique-se de que esta executando como o usuario openclaw:

sudo -i -u openclaw
openclaw channels login

Configuracao avancada

Para arquitetura de seguranca detalhada e solucao de problemas:

Relacionados

arrow_back
Anterior
Nix
Próximo
Bun
arrow_forward