Hetzner

Effettua il provisioning della VPS

Crea una VPS Ubuntu o Debian in Hetzner.

Connettiti come root:

ssh root@YOUR_VPS_IP

Questa guida presuppone che la VPS sia stateful. Non trattarla come infrastruttura usa e getta.

Installa Docker (sulla VPS)

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

Verifica:

docker --version
docker compose version

Clona il repository OpenClaw

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

Questa guida presuppone che tu crei un'immagine personalizzata per garantire la persistenza dei binari.

Crea directory host persistenti

I container Docker sono effimeri. Tutto lo stato a lungo termine deve risiedere sull'host.

mkdir -p /root/.openclaw/workspace

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

Configura le variabili d'ambiente

Crea .env nella radice del repository.

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

Imposta OPENCLAW_GATEWAY_TOKEN quando vuoi gestire il token stabile del gateway tramite .env; altrimenti configura gateway.auth.token prima di fare affidamento sui client tra i riavvii. Se nessuna delle due fonti esiste, OpenClaw usa un token solo runtime per quell'avvio. Genera una password per il keyring e incollala in GOG_KEYRING_PASSWORD:

openssl rand -hex 32

Non committare questo file.

Questo file .env è per l'env del container/runtime, come OPENCLAW_GATEWAY_TOKEN. L'autenticazione OAuth/API-key dei provider archiviata risiede nel file montato ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.

Configurazione Docker Compose

Crea o aggiorna 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 solo per comodità di bootstrap, non sostituisce una configurazione corretta del gateway. Imposta comunque l'autenticazione (gateway.auth.token o password) e usa impostazioni di bind sicure per il tuo deployment.

Passaggi runtime condivisi della VM Docker

Usa la guida runtime condivisa per il flusso comune dell'host Docker:

• Integra i binari richiesti nell'immagine
• Crea e avvia
• Cosa persiste dove
• Aggiornamenti

Accesso specifico per Hetzner

Dopo i passaggi condivisi di build e avvio, completa la seguente configurazione per aprire il tunnel:

Prerequisito: assicurati che la configurazione sshd della VPS consenta l'inoltro TCP. Se hai irrigidito la configurazione SSH, controlla /etc/ssh/sshd_config e imposta:

AllowTcpForwarding local

local consente inoltri locali ssh -L dal tuo laptop bloccando gli inoltri remoti dal server. Impostarlo su no farà fallire il tunnel con: channel 3: open failed: administratively prohibited: open failed

Dopo aver confermato che l'inoltro TCP è abilitato, riavvia il servizio SSH (systemctl restart ssh) ed esegui il tunnel dal tuo laptop:

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

Apri:

http://127.0.0.1:18789/

Incolla il segreto condiviso configurato. Questa guida usa il token del gateway per impostazione predefinita; se sei passato all'autenticazione con password, usa invece quella password.