Hetzner

Provisione o VPS

Crie um VPS Ubuntu ou Debian na Hetzner.

Conecte-se como root:

ssh root@YOUR_VPS_IP

Este guia pressupõe que o VPS seja stateful. Não o trate como infraestrutura descartável.

Instale o 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

Clone o repositório do OpenClaw

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Este guia pressupõe que você criará uma imagem personalizada para garantir a persistência dos binários.

Crie diretórios persistentes no host

Contêineres Docker são efêmeros. Todo estado de longa duração deve ficar no host.

mkdir -p /root/.openclaw/workspace

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

Configure variáveis de ambiente

Crie .env na raiz do repositório.

OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789

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

GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw

Defina OPENCLAW_GATEWAY_TOKEN quando quiser gerenciar o token estável do gateway por meio de .env; caso contrário, configure gateway.auth.token antes de depender de clientes entre reinicializações. Se nenhuma das fontes existir, o OpenClaw usa um token apenas de runtime para essa inicialização. Gere uma senha de keyring e cole-a em GOG_KEYRING_PASSWORD:

openssl rand -hex 32

Não faça commit deste arquivo.

Este arquivo .env é para env de contêiner/runtime, como OPENCLAW_GATEWAY_TOKEN. A autenticação armazenada de OAuth/chave de API de provedor fica no ~/.openclaw/agents/<agentId>/agent/auth-profiles.json montado.

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

--allow-unconfigured serve apenas para conveniência de bootstrap, não substitui uma configuração adequada de gateway. Ainda assim, defina autenticação (gateway.auth.token ou senha) e use configurações de bind seguras para sua implantação.

Etapas de runtime compartilhado da VM Docker

Use o guia de runtime compartilhado para o fluxo comum de host Docker:

• Incorporar os binários necessários na imagem
• Criar e iniciar
• O que persiste onde
• Atualizações

Acesso específico da Hetzner

Após as etapas compartilhadas de build e inicialização, conclua a seguinte configuração para abrir o túnel:

Pré-requisito: Garanta que a configuração sshd do seu VPS permita encaminhamento TCP. Se você reforçou sua configuração SSH, verifique /etc/ssh/sshd_config e defina:

AllowTcpForwarding local

local permite encaminhamentos locais ssh -L a partir do seu laptop enquanto bloqueia encaminhamentos remotos do servidor. Defini-lo como no fará o túnel falhar com: channel 3: open failed: administratively prohibited: open failed

Depois de 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:

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

Abra:

http://127.0.0.1:18789/

Cole o segredo compartilhado configurado. Este guia usa o token do gateway por padrão; se você mudou para autenticação por senha, use essa senha em vez disso.