Saltar para o conteúdo principal

​
OpenClaw na Hetzner (Docker, Guia de Produção em VPS)

​
Objetivo

Executar um OpenClaw Gateway persistente em um VPS da Hetzner usando Docker, com estado durável, binários incorporados e comportamento seguro de reinício. Se você quer “OpenClaw 24/7 por ~US$5”, esta é a configuração confiável mais simples. Os preços da Hetzner mudam; escolha o menor VPS Debian/Ubuntu e aumente se encontrar OOMs.

​
O que estamos fazendo (em termos simples)?

  • Alugar um pequeno servidor Linux (VPS da Hetzner)
  • Instalar Docker (runtime de aplicativo isolado)
  • Iniciar o OpenClaw Gateway no Docker
  • Persistir ~/.openclaw + ~/.openclaw/workspace no host (sobrevive a reinícios/reconstruções)
  • Acessar a UI de Controle a partir do seu laptop via um túnel SSH
O Gateway pode ser acessado via:
  • Encaminhamento de porta SSH a partir do seu laptop
  • Exposição direta de porta se você gerenciar firewall e tokens por conta própria
Este guia assume Ubuntu ou Debian na Hetzner.
Se você estiver em outro VPS Linux, mapeie os pacotes de acordo. Para o fluxo genérico de Docker, veja Docker.

​
Caminho rápido (operadores experientes)

  1. Provisionar VPS da Hetzner
  2. Instalar Docker
  3. Clonar o repositório OpenClaw
  4. Criar diretórios persistentes no host
  5. Configurar .env e docker-compose.yml
  6. Incorporar os binários necessários na imagem
  7. docker compose up -d
  8. Verificar persistência e acesso ao Gateway

​
O que você precisa

  • VPS da Hetzner com acesso root
  • Acesso SSH a partir do seu laptop
  • Conforto básico com SSH + copiar/colar
  • ~20 minutos
  • Docker e Docker Compose
  • Credenciais de autenticação do modelo
  • Credenciais opcionais de provedores
    • QR do WhatsApp
    • Token de bot do Telegram
    • OAuth do Gmail

​
1. Provisionar o VPS

Crie um VPS Ubuntu ou Debian na Hetzner. Conecte-se como root: 
ssh root@YOUR_VPS_IP
Este guia assume que o VPS é stateful. Não o trate como infraestrutura descartável.

​
2. Instalar Docker (no VPS)

apt-get update
apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sh
Verifique: 
docker --version
docker compose version

​
3. Clonar o repositório OpenClaw

git clone https://github.com/openclaw/openclaw.git
cd openclaw
Este guia assume que você irá criar uma imagem personalizada para garantir a persistência dos binários.

​
4. Criar diretórios persistentes no host

Contêineres Docker são efêmeros. Todo estado de longa duração deve viver no host. 
mkdir -p /root/.openclaw/workspace

# Set ownership to the container user (uid 1000):
chown -R 1000:1000 /root/.openclaw

​
5. Configurar variáveis de ambiente

Crie .env na raiz do repositório. 
OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=change-me-now
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace

GOG_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.openclaw
Gere segredos fortes: 
openssl rand -hex 32
Não faça commit deste arquivo.

​
6. Configuração do Docker Compose

Crie ou atualize docker-compose.yml. 
services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - OPENCLAW_GATEWAY_BIND=${OPENCLAW_GATEWAY_BIND}
      - OPENCLAW_GATEWAY_PORT=${OPENCLAW_GATEWAY_PORT}
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
      - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"

      # Optional: only if you run iOS/Android nodes against this VPS and need Canvas host.
      # If you expose this publicly, read /gateway/security and firewall accordingly.
      # - "18793:18793"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND}",
        "--port",
        "${OPENCLAW_GATEWAY_PORT}",
        "--allow-unconfigured",
      ]
--allow-unconfigured é apenas para conveniência de bootstrap; não substitui uma configuração adequada do gateway. Ainda configure a autenticação (gateway.auth.token ou senha) e use configurações de bind seguras para sua implantação.

​
7. Incorporar os binários necessários na imagem (crítico)

Instalar binários dentro de um contêiner em execução é uma armadilha. Qualquer coisa instalada em tempo de execução será perdida no reinício. Todos os binários externos exigidos por Skills devem ser instalados no momento da construção da imagem. Os exemplos abaixo mostram apenas três binários comuns:
  • gog para acesso ao Gmail
  • goplaces para Google Places
  • wacli para WhatsApp
Estes são exemplos, não uma lista completa. Você pode instalar quantos binários forem necessários usando o mesmo padrão. Se você adicionar novas Skills posteriormente que dependam de binários adicionais, você deve:
  1. Atualizar o Dockerfile
  2. Reconstruir a imagem
  3. Reiniciar os contêineres
Exemplo de Dockerfile 
FROM node:22-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# Example binary 1: Gmail CLI
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog

# Example binary 2: Google Places CLI
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces

# Example binary 3: WhatsApp CLI
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

# Add more binaries below using the same pattern

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

​
8. Construir e iniciar

docker compose build
docker compose up -d openclaw-gateway
Verifique os binários: 
docker compose exec openclaw-gateway which gog
docker compose exec openclaw-gateway which goplaces
docker compose exec openclaw-gateway which wacli
Saída esperada: 
/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli

​
9. Verificar o Gateway

docker compose logs -f openclaw-gateway
Sucesso: 
[gateway] listening on ws://0.0.0.0:18789
A partir do seu laptop: 
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
Abra: http://127.0.0.1:18789/ Cole o token do seu gateway.

​
O que persiste onde (fonte da verdade)

O OpenClaw roda em Docker, mas o Docker não é a fonte da verdade. Todo estado de longa duração deve sobreviver a reinícios, reconstruções e reboots.
ComponenteLocalizaçãoMecanismo de persistênciaNotas
Configuração do Gateway/home/node/.openclaw/Montagem de volume do hostInclui openclaw.json, tokens
Perfis de autenticação do modelo/home/node/.openclaw/Montagem de volume do hostTokens OAuth, chaves de API
Configurações de Skills/home/node/.openclaw/skills/Montagem de volume do hostEstado no nível da Skill
Workspace do agente/home/node/.openclaw/workspace/Montagem de volume do hostCódigo e artefatos do agente
Sessão do WhatsApp/home/node/.openclaw/Montagem de volume do hostPreserva o login por QR
Keyring do Gmail/home/node/.openclaw/Volume do host + senhaRequer GOG_KEYRING_PASSWORD
Binários externos/usr/local/bin/Imagem DockerDeve ser assado no tempo de construção
Runtime do NodeSistema de arquivos do contêinerImagem DockerReconstruído a cada build da imagem
Pacotes do SOSistema de arquivos do contêinerImagem DockerNão instale em tempo de execução
Contêiner DockerEfêmeroReiniciávelSeguro para destruir

​
Infraestrutura como Código (Terraform)

Para equipes que preferem fluxos de trabalho de infraestrutura como código, uma configuração Terraform mantida pela comunidade oferece:
  • Configuração modular do Terraform com gerenciamento de estado remoto
  • Provisionamento automatizado via cloud-init
  • Scripts de implantação (bootstrap, deploy, backup/restore)
  • Endurecimento de segurança (firewall, UFW, acesso somente via SSH)
  • Configuração de túnel SSH para acesso ao gateway
Repositórios: Essa abordagem complementa a configuração Docker acima com implantações reproduzíveis, infraestrutura versionada e recuperação automatizada de desastres.
Observação: Mantido pela comunidade. Para problemas ou contribuições, consulte os links dos repositórios acima.