Guia de Instalação — OpenClaw VPS Stack

Software no seu computador (local)

• Node.js 22+ — nodejs.org
• Git
• Tailscale — tailscale.com/download

Contas necessárias

Serviço	Link	Para quê
Hetzner Cloud	console.hetzner.cloud	VPS (servidor)
Tailscale	tailscale.com	VPN mesh segura
Supabase	supabase.com	Database
OpenRouter	openrouter.ai	LLM routing (opcional)
Anthropic	console.anthropic.com	Claude API (opcional)
OpenAI	platform.openai.com	GPT API (opcional)
AssemblyAI	assemblyai.com	Transcrição de áudio (opcional)
ClickUp	clickup.com	Project management (opcional)

API Keys para preparar

Obtenha antes de iniciar a instalação:

1. Acessar Hetzner Console
2. Criar servidor com:
   • Localização: Helsinki (ou mais próximo)
   • Imagem: Ubuntu 24.04
   • Tipo: CX21 ou superior (2 vCPU, 4GB RAM)
   • SSH Key: adicionar sua chave pública
3. Anotar o IP do servidor criado

Conectar e preparar o sistema

# Conectar via SSH
ssh root@SEU_IP_DO_SERVIDOR

# Atualizar sistema
apt update && apt upgrade -y

# Instalar Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs

# Instalar ferramentas essenciais
apt install -y git build-essential screen jq curl ffmpeg

Na VPS

# Instalar Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# Autenticar (abre link no browser)
tailscale up --hostname=openclaw

# Verificar
tailscale status

No seu computador (macOS/Windows/Linux)

Baixe e instale o Tailscale de tailscale.com/download. Autentique com a mesma conta usada na VPS.

# Verificar conectividade
tailscale ping openclaw

Conecte na VPS via SSH e instale o OpenClaw:

# Conectar na VPS (use IP Tailscale ou IP público)
ssh root@IP_DA_VPS

# Instalar OpenClaw globalmente
npm install -g openclaw@latest

# Verificar instalação
openclaw --version

openclaw onboard --install-daemon

O wizard vai pedir várias configurações. Aqui está o que cada campo significa:

Anthropic Setup Token

No seu computador local (não na VPS), abra um terminal e rode:

claude setup-token

Copie o token gerado (formato sk-ant-oat01-...) e cole na VPS.

WhatsApp

Quando perguntar sobre o telefone, selecione se é pessoal ou dedicado ao bot.

Gateway Service

Selecione "Restart" se já estiver instalado, ou instale normalmente.

Hatch

Quando perguntar "How do you want to hatch your bot?", pode pular por enquanto (vamos configurar manualmente).

Se você gerou configs localmente com o setup.sh, precisa enviá-las para a VPS.

Método recomendado: Deploy via SSH

Se scp/rsync travarem, use redirecionamento via SSH (funciona sempre):

# 1. Criar estrutura na VPS
ssh root@IP_VPS 'mkdir -p /opt/aiosbot/vps/{config,mcps,skills,workspace}'

# 2. Enviar arquivo por arquivo
ssh root@IP_VPS 'cat > /opt/aiosbot/.env' < .env
ssh root@IP_VPS 'cat > /opt/aiosbot/vps/install.sh' < vps/install.sh
ssh root@IP_VPS 'chmod +x /opt/aiosbot/vps/install.sh'

# Repetir para cada arquivo necessário

# Na VPS
cd /opt/aiosbot
chmod +x vps/install.sh
./vps/install.sh

O script instala:

• Dependências do sistema (curl, git, build-essential, jq, screen)
• Node.js 22 (se não tiver)
• Cria usuário aiosbot
• Copia configs e skills
• Configura Tailscale (se não tiver)

Configurar o Gateway

# Configuração interativa
openclaw configure

Selecione Gateway e configure:

Campo	Valor Recomendado
Gateway port	18789 (padrão)
Gateway bind mode	Loopback (pra começar, depois mude pra Tailnet)
Gateway auth	Password
Gateway password	Uma senha forte

Iniciar o Gateway

# Iniciar em modo verboso (primeiro teste)
openclaw gateway --force --verbose

Deve mostrar:

• [gateway] listening on ws://127.0.0.1:18789
• [whatsapp] Listening for personal WhatsApp inbound messages.

Conectar WhatsApp

Abra outro terminal SSH na VPS e rode:

openclaw channels login --verbose

Vai aparecer um QR code. Escaneie com o WhatsApp (Dispositivos Conectados → Conectar Dispositivo).

Configurar Política de DMs

Por padrão, o OpenClaw bloqueia mensagens de números não autorizados.

# Opção 1: Aceitar de qualquer número (mais fácil pra testar)
openclaw config set channels.whatsapp.dmPolicy open

# Opção 2: Allowlist (mais seguro - só números específicos)
openclaw config set channels.whatsapp.dmPolicy allowlist
# Adicionar números permitidos no config

Criar túnel SSH

No seu computador local, abra um terminal e rode:

ssh -N -L 18789:127.0.0.1:18789 root@IP_DA_VPS

Deixe esse terminal aberto (não vai mostrar nada, é normal).

Acessar no browser

Abra no browser:

http://127.0.0.1:18789/

O dashboard mostra:

• Chat — conversar diretamente com o agente
• Overview — visão geral do sistema
• Channels — canais conectados (WhatsApp, Telegram, etc.)
• Sessions — sessões de conversa
• Skills — habilidades do agente
• Config — editar configurações
• Logs — logs em tempo real

Trocar o modelo padrão

# Definir modelo principal
openclaw config set agents.defaults.model.primary openai/gpt-4.1-mini

# Outros exemplos:
# openclaw config set agents.defaults.model.primary anthropic/claude-sonnet-4
# openclaw config set agents.defaults.model.primary google/gemini-2.0-flash-001
# openclaw config set agents.defaults.model.primary deepseek/deepseek-chat

Configurar API Keys

# Configuração interativa (recomendado)
openclaw configure
# Selecione "Model" e siga o wizard

Modelos disponíveis por provedor

Provedor	Modelos Populares	Custo
OpenAI	gpt-4.1-mini, gpt-4o, gpt-4o-mini	$$
Anthropic	claude-sonnet-4, claude-haiku-4	$$
Google	gemini-2.0-flash, gemini-pro	$
DeepSeek	deepseek-chat, deepseek-v3	$
OpenRouter	Qualquer modelo via proxy	Varia

Instalar serviço systemd

# Instalar o gateway como serviço
openclaw gateway install

# Se já estiver instalado:
openclaw gateway install --force

Gerenciar o serviço

# Iniciar
openclaw gateway start

# Parar
openclaw gateway stop

# Ver status
openclaw health

# Ver logs
openclaw logs --follow

Agora o gateway:

• Roda em background (sem terminal aberto)
• Reinicia automaticamente se crashar
• Inicia automaticamente no boot do servidor

Gateway não responde

openclaw health
openclaw gateway --force --verbose
# Ver logs detalhados
openclaw logs --follow

"pairing required" ao conectar TUI/Dashboard

• Use túnel SSH (ssh -N -L 18789:127.0.0.1:18789 root@VPS) e acesse via http://127.0.0.1:18789/
• Conexões localhost são auto-aprovadas
• Se persistir, faça openclaw reset → selecione "Config + credentials + sessions" → rode openclaw onboard de novo

"gateway password missing"

# Definir variável de ambiente
OPENCLAW_GATEWAY_PASSWORD="SUA_SENHA" openclaw tui

# Ou configurar permanentemente
openclaw config set gateway.auth.password '"SUA_SENHA"'

"Blocked unauthorized sender"

# Abrir pra todos (teste)
openclaw config set channels.whatsapp.dmPolicy open

# Reiniciar gateway após mudar config
openclaw gateway --force

"No API key found for provider"

# Configurar API keys
openclaw configure
# Selecione "Model" e configure o provedor

API rate limit

• Espere 30 segundos e tente de novo
• Troque para um modelo mais barato/rápido
• Verifique limites no dashboard do provedor

Bug macOS: sed "extra characters"

No macOS, sed -i precisa de argumento extra. Troque:

# De (não funciona no macOS):
sed -i "s|algo|outro|g" arquivo

# Para (funciona no macOS):
sed -i '' "s|algo|outro|g" arquivo

Bug macOS: scp/rsync/tar travam

Extended attributes do macOS quebram transferências. Limpe antes:

xattr -cr ~/caminho/do/projeto/

Se ainda travar, use o método SSH com cat:

ssh root@VPS 'cat > /destino/arquivo' < arquivo_local

Comandos úteis

Comando	O que faz
openclaw doctor	Diagnóstico completo do sistema
openclaw health	Status rápido do gateway
openclaw status	Status dos canais e sessões
openclaw channels list	Listar canais conectados
openclaw models list	Listar modelos disponíveis
openclaw skills list	Listar skills instaladas
openclaw logs --follow	Logs em tempo real
openclaw configure	Wizard de configuração
openclaw reset	Reset de configuração
openclaw dashboard	Gerar URL tokenizada do dashboard