OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Hosting

Hetzner

Execute um Gateway persistente do OpenClaw em um VPS da Hetzner usando Docker, com estado durável, binários incorporados e comportamento seguro de reinicialização.

Os preços da Hetzner mudam; escolha o menor VPS Debian/Ubuntu que atenda às necessidades e aumente sua capacidade se ocorrerem erros de falta de memória (OOM).

O Gateway pode ser acessado por meio de encaminhamento de porta SSH a partir do seu laptop ou pela exposição direta da porta, caso você mesmo gerencie o firewall e os tokens.

Lembrete sobre o modelo de segurança:

  • Agentes compartilhados pela empresa são adequados quando todos estão no mesmo limite de confiança e o ambiente de execução é usado exclusivamente para fins empresariais.
  • Mantenha uma separação rigorosa: VPS/ambiente de execução dedicados + contas dedicadas; não use perfis pessoais da Apple, do Google, do navegador ou do gerenciador de senhas nesse host.
  • Se os usuários forem adversários entre si, separe-os por Gateway/host/usuário do sistema operacional.

Consulte Segurança e Hospedagem em VPS.

Este guia pressupõe o uso do Ubuntu ou Debian na Hetzner. Em outro VPS Linux, adapte os pacotes conforme necessário. Para o fluxo genérico do Docker, consulte Docker.

O que você precisa

  • VPS da Hetzner com acesso root
  • Acesso SSH a partir do seu laptop
  • 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)
  • Cerca de 20 minutos

Caminho rápido

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

  • Provisionar o VPS

    Crie um VPS Ubuntu ou Debian na Hetzner e conecte-se como root:

    bash
    ssh root@YOUR_VPS_IP

    Trate o VPS como uma infraestrutura com estado, não como uma infraestrutura descartável.

  • Instalar o Docker (no VPS)

    bash
    apt-get updateapt-get install -y git curl ca-certificatescurl -fsSL https://get.docker.com | sh

    Verifique:

    bash
    docker --versiondocker compose version

  • Clonar o repositório do OpenClaw

    bash
    git clone https://github.com/openclaw/openclaw.gitcd openclaw

    Este guia cria uma imagem personalizada para que todos os binários incorporados a ela sobrevivam às reinicializações.

  • Criar diretórios persistentes no host

    Os contêineres Docker são efêmeros; todo estado de longa duração deve residir no host.

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

  • Configurar as variáveis de ambiente

    Crie .env na raiz do repositório:

    bash
    OPENCLAW_IMAGE=openclaw:latestOPENCLAW_GATEWAY_TOKEN=OPENCLAW_GATEWAY_BIND=lanOPENCLAW_GATEWAY_PORT=18789 OPENCLAW_CONFIG_DIR=/root/.openclawOPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace GOG_KEYRING_PASSWORD=XDG_CONFIG_HOME=/home/node/.openclaw

    Defina OPENCLAW_GATEWAY_TOKEN para gerenciar o token estável do Gateway por meio do .env; caso contrário, configure gateway.auth.token antes de depender de clientes entre reinicializações. Se nenhum dos dois estiver definido, o OpenClaw usará, nessa inicialização, um token válido somente durante o ambiente de execução. Gere uma senha para o chaveiro em GOG_KEYRING_PASSWORD:

    bash
    openssl rand -hex 32

    Não confirme este arquivo no repositório. Ele contém variáveis de ambiente do contêiner/ambiente de execução, como OPENCLAW_GATEWAY_TOKEN. A autenticação OAuth/por chave de API armazenada dos provedores reside no arquivo montado ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

  • Configuração do Docker Compose

    Crie ou atualize docker-compose.yml:

    yaml
    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"    command:      [        "node",        "dist/index.js",        "gateway",        "--bind",        "${OPENCLAW_GATEWAY_BIND}",        "--port",        "${OPENCLAW_GATEWAY_PORT}",        "--allow-unconfigured",      ]

    --allow-unconfigured serve apenas para facilitar a inicialização, não como substituto para uma configuração real do Gateway. Ainda é necessário configurar a autenticação (gateway.auth.token ou senha) e um modo de vinculação seguro para sua implantação.

  • Etapas compartilhadas do ambiente de execução da VM Docker

    Siga o guia compartilhado do ambiente de execução para o fluxo comum do host Docker:

  • Acesso específico da Hetzner

    Após as etapas compartilhadas de criação e inicialização, abra o túnel.

    Pré-requisito: certifique-se de que a configuração do sshd no VPS permita o encaminhamento TCP. Se você reforçou a segurança da configuração SSH, verifique /etc/ssh/sshd_config e defina:

    text
    AllowTcpForwarding local

    local permite encaminhamentos locais com ssh -L a partir do seu laptop e, ao mesmo tempo, bloqueia encaminhamentos remotos originados no servidor. Defini-lo como no faz o túnel falhar com: channel 3: open failed: administratively prohibited: open failed

    Após confirmar que o encaminhamento TCP está habilitado, reinicie o serviço SSH (systemctl restart ssh) e execute o túnel a partir do seu laptop:

    bash
    ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP

    Abra http://127.0.0.1:18789/ e cole o segredo compartilhado configurado. Este guia usa o token do Gateway por padrão; use sua senha configurada caso tenha mudado para autenticação por senha.

    • O mapa de persistência compartilhado está em Ambiente de execução da VM Docker.

    Infraestrutura como código (Terraform)

    Para equipes que preferem fluxos de trabalho de infraestrutura como código, uma configuração do Terraform mantida pela comunidade oferece:

    • Configuração modular do Terraform com gerenciamento remoto de estado
    • Provisionamento automatizado por meio do cloud-init
    • Scripts de implantação (inicialização, implantação, backup/restauração)
    • Reforço de segurança (firewall, UFW, acesso somente por SSH)
    • Configuração de túnel SSH para acesso ao Gateway

    Repositórios:

    Essa abordagem complementa a configuração do Docker apresentada acima com implantações reproduzíveis, infraestrutura controlada por versão e recuperação automatizada de desastres.

    Próximas etapas

    Conteúdo relacionado

    Was this useful?
    On this page

    On this page