Despliega OpenClaw en Kubernetes: Guía rápida

A veces, desplegar una herramienta sencilla en Kubernetes se siente como intentar armar un mueble gigante cuando solo necesitas una silla. Si estás cansado de configurar Helm charts interminables para un solo contenedor, esta guía es para ti.

Este es un punto de partida mínimo para ejecutar OpenClaw en Kubernetes; no es un despliegue listo para producción. Cubre los recursos principales y está pensado para que lo adaptes a tu entorno.

¿Por qué no Helm?

OpenClaw es un solo contenedor con algunos archivos de configuración. La personalización interesante está en el contenido del agente (archivos markdown, skills, sobrescritura de configuraciones), no en la creación de plantillas de infraestructura. Kustomize maneja los overlays sin la carga de un Helm chart. Si tu despliegue se vuelve más complejo, puedes añadir un Helm chart encima de estos manifiestos.

Qué necesitas

• Un cluster de Kubernetes funcionando (AKS, EKS, GKE, k3s, kind, OpenShift, etc.)
• kubectl conectado a tu cluster
• Una API key para al menos un proveedor de modelos

Inicio rápido

# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

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

Recupera el token del gateway y pégalo en la Control UI:

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

Para debugging local, ./scripts/k8s/deploy.sh --show-token imprime el token después del despliegue.

Pruebas locales con Kind

Si no tienes un cluster, crea uno localmente con Kind:

./scripts/k8s/create-kind.sh           # auto-detects docker or podman
./scripts/k8s/create-kind.sh --delete  # tear down

Luego despliega como de costumbre con ./scripts/k8s/deploy.sh.

Paso a paso

1) Desplegar

Opción A — API key en el entorno (un solo paso):

# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

El script crea un Kubernetes Secret con la API key y un token de gateway generado automáticamente, luego realiza el despliegue. Si el Secret ya existe, conserva el token del gateway actual y cualquier key de proveedor que no estés cambiando.

Opción B — crear el secret por separado:

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

Usa --show-token con cualquier comando si quieres que el token se imprima en la salida estándar para pruebas locales.

2) Acceder al gateway

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

Qué se despliega

Namespace: openclaw (configurable via OPENCLAW_NAMESPACE)
├── Deployment/openclaw        # Single pod, init container + gateway
├── Service/openclaw           # ClusterIP on port 18789
├── PersistentVolumeClaim      # 10Gi for agent state and config
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # Gateway token + API keys

Personalización

Instrucciones del agente

Edita el archivo AGENTS.md en scripts/k8s/manifests/configmap.yaml y vuelve a desplegar:

./scripts/k8s/deploy.sh

Configuración del Gateway

Edita openclaw.json en scripts/k8s/manifests/configmap.yaml. Consulta la configuración del Gateway para ver la referencia completa.

Añadir proveedores

Vuelve a ejecutar con keys adicionales exportadas:

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

Las keys de proveedores existentes se mantienen en el Secret a menos que las sobrescribas.

O puedes parchear el Secret directamente:

kubectl patch secret openclaw-secrets -n openclaw \
  -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
kubectl rollout restart deployment/openclaw -n openclaw

Namespace personalizado

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

Imagen personalizada

Edita el campo image en scripts/k8s/manifests/deployment.yaml:

image: ghcr.io/openclaw/openclaw:2026.3.1

Exponer más allá del port-forward

Los manifiestos por defecto vinculan el gateway al loopback dentro del pod. Esto funciona con kubectl port-forward, pero no funcionará con un Service de Kubernetes o una ruta de Ingress que necesite alcanzar la IP del pod.

Si quieres exponer el gateway a través de un Ingress o un balanceador de carga:

• Cambia el bind del gateway en scripts/k8s/manifests/configmap.yaml de loopback a un bind que no sea loopback y que coincida con tu modelo de despliegue.
• Mantén la autenticación del gateway activada y usa un punto de entrada con TLS terminado correctamente.
• Configura la Control UI para acceso remoto usando el modelo de seguridad web soportado (por ejemplo, HTTPS/Tailscale Serve y orígenes permitidos explícitos cuando sea necesario).

Re-desplegar

./scripts/k8s/deploy.sh

Esto aplica todos los manifiestos y reinicia el pod para recoger cualquier cambio en la configuración o en los secrets.

Eliminar

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

Esto elimina el namespace y todos los recursos dentro de él, incluyendo el PVC.

Notas de arquitectura

• El gateway se vincula al loopback dentro del pod por defecto, por lo que la configuración incluida es para kubectl port-forward.
• Sin recursos con alcance de cluster: todo vive dentro de un único namespace.
• Seguridad: readOnlyRootFilesystem, capacidades drop: ALL, usuario no-root (UID 1000).
• La configuración por defecto mantiene la Control UI en la ruta de acceso local más segura: bind de loopback más kubectl port-forward a http://127.0.0.1:18789.
• Si pasas del acceso por localhost, usa el modelo remoto soportado: HTTPS/Tailscale más el bind del gateway adecuado y los ajustes de origen de la Control UI.
• Los Secrets se generan en un directorio temporal y se aplican directamente al cluster; no se escribe material sensible en el checkout del repositorio.

Estructura de archivos

scripts/k8s/
├── deploy.sh                   # Creates namespace + secret, deploys via kustomize
├── create-kind.sh              # Local Kind cluster (auto-detects docker/podman)
└── manifests/
    ├── kustomization.yaml      # Kustomize base
    ├── configmap.yaml          # openclaw.json + AGENTS.md
    ├── deployment.yaml         # Pod spec with security hardening
    ├── pvc.yaml                # 10Gi persistent storage
    └── service.yaml            # ClusterIP on 18789

AI Setup Assistant

Siguientes pasos

• Configuración del Gateway
• Gestión de Agentes
• Seguridad en producción