OpenClaw no Kubernetes

Um ponto de partida minimo para executar o OpenClaw no Kubernetes — nao e uma implantacao pronta para producao. Cobre os recursos essenciais e deve ser adaptado ao seu ambiente.

Por que nao Helm?

O OpenClaw e um unico container com alguns arquivos de configuracao. A personalizacao interessante esta no conteudo dos agentes (arquivos markdown, skills, sobrescritas de config), nao em templating de infraestrutura. O Kustomize lida com overlays sem a sobrecarga de um chart Helm. Se sua implantacao ficar mais complexa, um chart Helm pode ser adicionado sobre esses manifests.

O que voce precisa

  • Um cluster Kubernetes funcionando (AKS, EKS, GKE, k3s, kind, OpenShift, etc.)
  • kubectl conectado ao seu cluster
  • Uma chave API para pelo menos um provedor de modelos

Inicio rapido

# Substitua pelo seu provedor: ANTHROPIC, GEMINI, OPENAI ou OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

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

Recupere o token do gateway e cole na interface de controle:

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

Para debug local, ./scripts/k8s/deploy.sh --show-token exibe o token apos o deploy.

Teste local com Kind

Se voce nao tem um cluster, crie um localmente com Kind:

./scripts/k8s/create-kind.sh           # detecta automaticamente docker ou podman
./scripts/k8s/create-kind.sh --delete  # destruir

Depois faca deploy normalmente com ./scripts/k8s/deploy.sh.

Passo a passo

1) Deploy

Opcao A — Chave API no ambiente (uma etapa):

# Substitua pelo seu provedor: ANTHROPIC, GEMINI, OPENAI ou OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

O script cria um Secret Kubernetes com a chave API e um token de gateway gerado automaticamente, depois faz deploy. Se o Secret ja existir, ele preserva o token de gateway atual e quaisquer chaves de provedor nao alteradas.

Opcao B — criar o secret separadamente:

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

Use --show-token com qualquer comando se quiser que o token seja exibido no stdout para teste local.

2) Acessar o gateway

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

O que e implantado

Namespace: openclaw (configuravel via OPENCLAW_NAMESPACE)
├── Deployment/openclaw        # Pod unico, init container + gateway
├── Service/openclaw           # ClusterIP na porta 18789
├── PersistentVolumeClaim      # 10Gi para estado e config do agente
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # Token do gateway + chaves API

Personalizacao

Instrucoes do agente

Edite o AGENTS.md em scripts/k8s/manifests/configmap.yaml e faca redeploy:

./scripts/k8s/deploy.sh

Configuracao do gateway

Edite openclaw.json em scripts/k8s/manifests/configmap.yaml. Consulte Configuracao do gateway para a referencia completa.

Adicionar provedores

Re-execute com chaves adicionais exportadas:

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

Chaves de provedores existentes permanecem no Secret a menos que voce as sobrescreva.

Ou aplique patch no Secret diretamente:

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

Imagem personalizada

Edite o campo image em scripts/k8s/manifests/deployment.yaml:

image: ghcr.io/openclaw/openclaw:2026.3.1

Expor alem do port-forward

Os manifests padrao ligam o gateway ao loopback dentro do pod. Isso funciona com kubectl port-forward, mas nao funciona com um Service Kubernetes ou caminho Ingress que precisa alcancar o IP do pod.

Se voce quer expor o gateway via Ingress ou load balancer:

  • Mude o binding do gateway em scripts/k8s/manifests/configmap.yaml de loopback para um binding nao-loopback que corresponda ao seu modelo de implantacao
  • Mantenha a autenticacao do gateway habilitada e use um entrypoint TLS-terminated adequado
  • Configure a interface de controle para acesso remoto usando o modelo de seguranca web suportado (por exemplo HTTPS/Tailscale Serve e origens permitidas explicitas quando necessario)

Re-deploy

./scripts/k8s/deploy.sh

Aplica todos os manifests e reinicia o pod para captar mudancas de config ou secrets.

Remocao

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

Remove o namespace e todos os recursos dentro dele, incluindo o PVC.

Notas de arquitetura

  • O gateway escuta em loopback dentro do pod por padrao, entao a configuracao incluida e para kubectl port-forward
  • Sem recursos com escopo de cluster — tudo vive em um unico namespace
  • Seguranca: readOnlyRootFilesystem, drop: ALL capabilities, usuario nao-root (UID 1000)
  • A config padrao mantem a interface de controle no caminho de acesso local mais seguro: binding loopback mais kubectl port-forward para http://127.0.0.1:18789
  • Se voce for alem do acesso localhost, use o modelo remoto suportado: HTTPS/Tailscale mais o binding de gateway e configuracoes de origem da interface de controle apropriados
  • Secrets sao gerados em um diretorio temporario e aplicados diretamente ao cluster — nenhum material secreto e escrito no checkout do repositorio

Estrutura de arquivos

scripts/k8s/
├── deploy.sh                   # Cria namespace + secret, faz deploy via kustomize
├── create-kind.sh              # Cluster Kind local (detecta automaticamente docker/podman)
└── manifests/
    ├── kustomization.yaml      # Base Kustomize
    ├── configmap.yaml          # openclaw.json + AGENTS.md
    ├── deployment.yaml         # Spec do pod com hardening de seguranca
    ├── pvc.yaml                # Armazenamento persistente 10Gi
    └── service.yaml            # ClusterIP na 18789
arrow_back
Anterior
VPS
Próximo
Fly
arrow_forward