콘텐츠로 이동
이 페이지는 더 이상 업데이트되지 않습니다. 최신 내용은 OpenClaw 공식 문서에서 확인하세요 →

OpenClaw Kubernetes 배포 가이드: 5분 만에 시작하기

새로운 도구를 Kubernetes에 배포하려고 할 때, 복잡한 설정 파일과 끝도 없는 Helm 차트 때문에 시작도 하기 전에 지치는 경우가 많죠. OpenClaw는 이런 복잡함을 덜어내고 핵심 기능에 집중할 수 있도록 아주 가볍게 설계되었습니다.

이 가이드는 Kubernetes에서 OpenClaw를 실행하기 위한 최소한의 시작점을 제공해요. 운영 환경에 바로 적용하기보다는, 각자의 환경에 맞춰 수정해서 사용하는 것을 추천합니다.

OpenClaw는 몇 개의 설정 파일만 있으면 되는 단일 컨테이너 구조예요. 인프라 템플릿을 만드는 것보다 에이전트의 내용(markdown 파일, 기술, 설정 오버라이드)을 커스텀하는 것이 훨씬 중요하죠. Kustomize를 사용하면 Helm 차트 같은 복잡한 오버헤드 없이도 레이어를 겹쳐서 설정을 관리할 수 있습니다. 만약 배포 구조가 더 복잡해진다면, 그때 이 매니페스트 위에 Helm 차트를 얹어서 사용해도 늦지 않아요.

  • 실행 중인 Kubernetes 클러스터 (AKS, EKS, GKE, k3s, kind, OpenShift 등)
  • 클러스터에 연결된 kubectl
  • 최소 하나 이상의 모델 프로바이더 API key
Terminal window
# 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

Gateway 토큰을 가져와서 Control UI에 붙여넣으세요:

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

로컬에서 디버깅할 때는 ./scripts/k8s/deploy.sh --show-token 명령어를 사용하면 배포 후에 토큰을 바로 확인할 수 있습니다.

클러스터가 없다면 Kind를 사용해 로컬에 하나 만들어보세요:

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

그다음 평소처럼 ./scripts/k8s/deploy.sh로 배포하면 됩니다.

옵션 A — 환경 변수에 API key 설정 (한 단계로 끝내기):

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

이 스크립트는 API key와 자동 생성된 Gateway 토큰이 포함된 Kubernetes Secret을 만들고 배포를 진행해요. 이미 Secret이 존재한다면, 현재의 Gateway 토큰과 변경되지 않은 프로바이더 키들은 그대로 유지합니다.

옵션 B — Secret을 별도로 생성하기:

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

로컬 테스트 중에 토큰을 터미널에 바로 출력하고 싶다면 두 명령어 중 어디에든 --show-token을 붙여주세요.

Terminal window
kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789
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

scripts/k8s/manifests/configmap.yaml 파일의 AGENTS.md를 수정하고 다시 배포하세요:

Terminal window
./scripts/k8s/deploy.sh

scripts/k8s/manifests/configmap.yaml의 openclaw.json을 수정하세요. 자세한 내용은 Gateway configuration 문서를 참고하면 좋습니다.

추가할 키를 export하고 다시 실행하세요:

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

기존 프로바이더 키는 덮어쓰지 않는 한 Secret에 그대로 유지됩니다.

또는 Secret을 직접 패치할 수도 있어요:

Terminal window
kubectl patch secret openclaw-secrets -n openclaw \
-p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
kubectl rollout restart deployment/openclaw -n openclaw
Terminal window
OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh

scripts/k8s/manifests/deployment.yaml에서 image 필드를 수정하세요:

image: ghcr.io/openclaw/openclaw:2026.3.1

Port-forward 이외의 방식으로 노출하기

섹션 제목: “Port-forward 이외의 방식으로 노출하기”

기본 매니페스트는 Gateway를 Pod 내부의 loopback에 바인딩합니다. 이 방식은 kubectl port-forward에서는 잘 작동하지만, Pod IP에 직접 접근해야 하는 Kubernetes Service나 Ingress 경로에서는 작동하지 않아요.

Ingress나 로드 밸런서를 통해 Gateway를 노출하고 싶다면 다음을 고려하세요:

  • scripts/k8s/manifests/configmap.yaml에서 Gateway 바인딩 설정을 loopback에서 배포 모델에 맞는 비루프백(non-loopback) 바인딩으로 변경하세요.
  • Gateway 인증을 활성화된 상태로 유지하고, 적절한 TLS 종료 엔드포인트를 사용하세요.
  • 원격 접속을 위해 지원되는 웹 보안 모델(예: HTTPS/Tailscale Serve 및 필요한 경우 명시적인 허용 오리진 설정)을 사용하여 Control UI를 구성하세요.
Terminal window
./scripts/k8s/deploy.sh

이 명령은 모든 매니페스트를 적용하고 Pod를 재시작하여 변경된 설정이나 Secret을 반영합니다.

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

이 명령은 네임스페이스와 PVC를 포함한 그 안의 모든 리소스를 삭제합니다.

  • Gateway는 기본적으로 Pod 내부의 loopback에 바인딩되므로, 제공된 설정은 kubectl port-forward 사용을 전제로 합니다.
  • 클러스터 범위(cluster-scoped) 리소스는 사용하지 않으며, 모든 리소스는 단일 네임스페이스 안에 존재해요.
  • 보안 설정: readOnlyRootFilesystem 적용, drop: ALL 기능 제한, 비루트(non-root) 사용자(UID 1000)를 사용합니다.
  • 기본 설정은 Control UI를 더 안전한 로컬 접속 경로로 유지해요. 즉, loopback 바인딩과 http://127.0.0.1:18789로의 kubectl port-forward를 조합합니다.
  • 로컬 호스트 접속을 넘어선 환경을 구축하려면, HTTPS/Tailscale과 적절한 Gateway 바인딩 및 Control UI 오리진 설정을 포함한 원격 모델을 사용하세요.
  • Secret은 임시 디렉토리에서 생성되어 클러스터에 직접 적용되며, 저장소 체크아웃 경로에는 어떠한 비밀 정보도 기록되지 않습니다.
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에게 물어보세요!

다음 단계:

OpenClaw

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.