Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Um ponto de partida mínimo para executar o OpenClaw no Kubernetes — não é uma implantação pronta para produção. Ele cobre os recursos principais e deve ser adaptado ao seu ambiente.

​
Por que não Helm?

O OpenClaw é um único contêiner com alguns arquivos de configuração. A personalização interessante está no conteúdo do agente (arquivos markdown, skills, substituições de configuração), não em templates de infraestrutura. O Kustomize gerencia sobreposições sem a sobrecarga de um chart Helm. Se a sua implantação ficar mais complexa, um chart Helm pode ser colocado sobre estes manifests.

​
O que você precisa

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

​
Início 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
Recupere o segredo compartilhado configurado para a Control UI. Este script de implantação cria autenticação por token por padrão: 
kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d
Para depuração local, ./scripts/k8s/deploy.sh --show-token imprime o token após a implantação.

​
Testes locais com Kind

Se você não tiver um cluster, crie um localmente com Kind: 
./scripts/k8s/create-kind.sh           # auto-detects docker or podman
./scripts/k8s/create-kind.sh --delete  # tear down
Depois implante normalmente com ./scripts/k8s/deploy.sh.

​
Passo a passo

​
1) Implantar

Opção A — chave de API no ambiente (uma etapa): 
# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh
O script cria um Kubernetes Secret com a chave de API e um token de Gateway gerado automaticamente, depois implanta. Se o Secret já existir, ele preserva o token de Gateway atual e quaisquer chaves de provedor que não estejam sendo alteradas. Opção B — criar o segredo 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 impresso em stdout para testes locais.

​
2) Acessar o Gateway

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

​
O que é implantado

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

​
Personalização

​
Instruções do agente

Edite o AGENTS.md em scripts/k8s/manifests/configmap.yaml e implante novamente: 
./scripts/k8s/deploy.sh

​
Configuração do Gateway

Edite openclaw.json em scripts/k8s/manifests/configmap.yaml. Consulte Configuração do Gateway para a referência completa.

​
Adicionar provedores

Execute novamente com chaves adicionais exportadas: 
export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh
As chaves de provedor existentes permanecem no Secret, a menos que você as sobrescreva. Ou aplique um patch diretamente ao Secret: 
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:latest # or pin to a specific version from https://github.com/openclaw/openclaw/releases

​
Expor além de port-forward

Os manifests padrão vinculam o Gateway ao loopback dentro do pod. Isso funciona com kubectl port-forward, mas não funciona com um Service do Kubernetes ou caminho de Ingress que precise alcançar o IP do pod. Se você quiser expor o Gateway por meio de um Ingress ou balanceador de carga:
  • Altere o bind do Gateway em scripts/k8s/manifests/configmap.yaml de loopback para um bind que não seja loopback e corresponda ao seu modelo de implantação
  • Mantenha a autenticação do Gateway ativada e use um ponto de entrada apropriado com terminação TLS
  • Configure a Control UI para acesso remoto usando o modelo de segurança web compatível (por exemplo, HTTPS/Tailscale Serve e origens permitidas explícitas quando necessário)

​
Reimplantar

./scripts/k8s/deploy.sh
Isso aplica todos os manifests e reinicia o pod para captar quaisquer alterações de configuração ou segredo.

​
Remoção

./scripts/k8s/deploy.sh --delete
Isso exclui o namespace e todos os recursos nele, incluindo o PVC.

​
Observações de arquitetura

  • O Gateway se vincula ao loopback dentro do pod por padrão, então a configuração incluída é para kubectl port-forward
  • Nenhum recurso com escopo de cluster — tudo fica em um único namespace
  • Segurança: readOnlyRootFilesystem, capacidades drop: ALL, usuário não root (UID 1000)
  • A configuração padrão mantém a Control UI no caminho de acesso local mais seguro: bind de loopback mais kubectl port-forward para http://127.0.0.1:18789
  • Se você for além do acesso por localhost, use o modelo remoto compatível: HTTPS/Tailscale mais o bind de Gateway apropriado e as configurações de origem da Control UI
  • Segredos são gerados em um diretório temporário e aplicados diretamente ao cluster — nenhum material secreto é escrito no checkout do repo

​
Estrutura de arquivos

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

​
Relacionado