OpenClaw su Kubernetes

Un punto di partenza minimale per eseguire OpenClaw su Kubernetes — non un deployment pronto per la produzione. Copre le risorse principali ed e pensato per essere adattato al tuo ambiente.

Perche non Helm?

OpenClaw e un singolo container con alcuni file di configurazione. La personalizzazione interessante sta nel contenuto dell’agente (file markdown, skill, override di configurazione), non nel templating dell’infrastruttura. Kustomize gestisce gli overlay senza l’overhead di un chart Helm. Se il tuo deployment diventa piu complesso, un chart Helm puo essere stratificato sopra questi manifest.

Cosa ti serve

  • Un cluster Kubernetes funzionante (AKS, EKS, GKE, k3s, kind, OpenShift, ecc.)
  • kubectl connesso al tuo cluster
  • Una chiave API per almeno un provider di modelli

Avvio rapido

# Sostituisci con il tuo provider: ANTHROPIC, GEMINI, OPENAI, o OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789

Recupera il token del gateway e incollalo nella Control UI:

kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d

Per il debug locale, ./scripts/k8s/deploy.sh --show-token stampa il token dopo il deploy.

Test locale con Kind

Se non hai un cluster, creane uno localmente con Kind:

./scripts/k8s/create-kind.sh           # rileva automaticamente docker o podman
./scripts/k8s/create-kind.sh --delete  # smonta

Poi distribuisci come al solito con ./scripts/k8s/deploy.sh.

Passo per passo

1) Distribuisci

Opzione A — Chiave API nell’ambiente (un passo):

# Sostituisci con il tuo provider: ANTHROPIC, GEMINI, OPENAI, o OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

Lo script crea un Secret Kubernetes con la chiave API e un token gateway auto-generato, poi distribuisce. Se il Secret esiste gia, conserva il token gateway attuale e le chiavi provider non modificate.

Opzione B — crea il secret separatamente:

export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

Usa --show-token con entrambi i comandi se vuoi che il token venga stampato su stdout per test locali.

2) Accedi al gateway

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789

Cosa viene distribuito

Namespace: openclaw (configurabile via OPENCLAW_NAMESPACE)
├── Deployment/openclaw        # Pod singolo, init container + gateway
├── Service/openclaw           # ClusterIP sulla porta 18789
├── PersistentVolumeClaim      # 10Gi per stato agente e configurazione
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # Token gateway + chiavi API

Personalizzazione

Istruzioni dell’agente

Modifica AGENTS.md in scripts/k8s/manifests/configmap.yaml e ridistribuisci:

./scripts/k8s/deploy.sh

Configurazione del gateway

Modifica openclaw.json in scripts/k8s/manifests/configmap.yaml. Vedi Configurazione del gateway per il riferimento completo.

Aggiungi provider

Riesegui con chiavi aggiuntive esportate:

export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

Le chiavi provider esistenti restano nel Secret a meno che non le sovrascrivi.

Namespace personalizzato

OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh

Immagine personalizzata

Modifica il campo image in scripts/k8s/manifests/deployment.yaml:

image: ghcr.io/openclaw/openclaw:2026.3.1

Esponi oltre port-forward

I manifest predefiniti collegano il gateway al loopback all’interno del pod. Questo funziona con kubectl port-forward, ma non funziona con un Service Kubernetes o un percorso Ingress che deve raggiungere l’IP del pod.

Se vuoi esporre il gateway attraverso un Ingress o load balancer:

  • Cambia il bind del gateway in scripts/k8s/manifests/configmap.yaml da loopback a un bind non-loopback che corrisponda al tuo modello di deployment
  • Mantieni l’autenticazione del gateway abilitata e usa un entrypoint terminato TLS appropriato

Ridistribuisci

./scripts/k8s/deploy.sh

Questo applica tutti i manifest e riavvia il pod per acquisire qualsiasi modifica alla configurazione o ai secret.

Smontaggio

./scripts/k8s/deploy.sh --delete

Questo cancella il namespace e tutte le risorse al suo interno, incluso il PVC.

Note sull’architettura

  • Il gateway si collega al loopback all’interno del pod di default, quindi la configurazione inclusa e per kubectl port-forward
  • Nessuna risorsa a livello di cluster — tutto vive in un singolo namespace
  • Sicurezza: readOnlyRootFilesystem, drop: ALL capabilities, utente non-root (UID 1000)
  • I secret sono generati in una directory temporanea e applicati direttamente al cluster — nessun materiale segreto viene scritto nel checkout del repo

Struttura dei file

scripts/k8s/
├── deploy.sh                   # Crea namespace + secret, distribuisce via kustomize
├── create-kind.sh              # Cluster Kind locale (rileva automaticamente docker/podman)
└── manifests/
    ├── kustomization.yaml      # Base Kustomize
    ├── configmap.yaml          # openclaw.json + AGENTS.md
    ├── deployment.yaml         # Spec pod con hardening di sicurezza
    ├── pvc.yaml                # 10Gi di storage persistente
    └── service.yaml            # ClusterIP sulla 18789
arrow_back
Precedente
VPS
Successivo
Fly
arrow_forward