OpenClaw Kubernetes 배포 가이드: 5분 만에 시작하기
새로운 도구를 Kubernetes에 배포하려고 할 때, 복잡한 설정 파일과 끝도 없는 Helm 차트 때문에 시작도 하기 전에 지치는 경우가 많죠. OpenClaw는 이런 복잡함을 덜어내고 핵심 기능에 집중할 수 있도록 아주 가볍게 설계되었습니다.
이 가이드는 Kubernetes에서 OpenClaw를 실행하기 위한 최소한의 시작점을 제공해요. 운영 환경에 바로 적용하기보다는, 각자의 환경에 맞춰 수정해서 사용하는 것을 추천합니다.
왜 Helm이 아닌가요?
섹션 제목: “왜 Helm이 아닌가요?”OpenClaw는 몇 개의 설정 파일만 있으면 되는 단일 컨테이너 구조예요. 인프라 템플릿을 만드는 것보다 에이전트의 내용(markdown 파일, 기술, 설정 오버라이드)을 커스텀하는 것이 훨씬 중요하죠. Kustomize를 사용하면 Helm 차트 같은 복잡한 오버헤드 없이도 레이어를 겹쳐서 설정을 관리할 수 있습니다. 만약 배포 구조가 더 복잡해진다면, 그때 이 매니페스트 위에 Helm 차트를 얹어서 사용해도 늦지 않아요.
준비물
섹션 제목: “준비물”- 실행 중인 Kubernetes 클러스터 (AKS, EKS, GKE, k3s, kind, OpenShift 등)
- 클러스터에 연결된
kubectl - 최소 하나 이상의 모델 프로바이더 API key
빠른 시작
섹션 제목: “빠른 시작”# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTERexport <PROVIDER>_API_KEY="..."./scripts/k8s/deploy.sh
kubectl port-forward svc/openclaw 18789:18789 -n openclawopen http://localhost:18789Gateway 토큰을 가져와서 Control UI에 붙여넣으세요:
kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d로컬에서 디버깅할 때는 ./scripts/k8s/deploy.sh --show-token 명령어를 사용하면 배포 후에 토큰을 바로 확인할 수 있습니다.
Kind를 이용한 로컬 테스트
섹션 제목: “Kind를 이용한 로컬 테스트”클러스터가 없다면 Kind를 사용해 로컬에 하나 만들어보세요:
./scripts/k8s/create-kind.sh # auto-detects docker or podman./scripts/k8s/create-kind.sh --delete # tear down그다음 평소처럼 ./scripts/k8s/deploy.sh로 배포하면 됩니다.
단계별 가이드
섹션 제목: “단계별 가이드”1) 배포하기
섹션 제목: “1) 배포하기”옵션 A — 환경 변수에 API key 설정 (한 단계로 끝내기):
# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTERexport <PROVIDER>_API_KEY="..."./scripts/k8s/deploy.sh이 스크립트는 API key와 자동 생성된 Gateway 토큰이 포함된 Kubernetes Secret을 만들고 배포를 진행해요. 이미 Secret이 존재한다면, 현재의 Gateway 토큰과 변경되지 않은 프로바이더 키들은 그대로 유지합니다.
옵션 B — Secret을 별도로 생성하기:
export <PROVIDER>_API_KEY="..."./scripts/k8s/deploy.sh --create-secret./scripts/k8s/deploy.sh로컬 테스트 중에 토큰을 터미널에 바로 출력하고 싶다면 두 명령어 중 어디에든 --show-token을 붙여주세요.
2) Gateway 접속
섹션 제목: “2) Gateway 접속”kubectl port-forward svc/openclaw 18789:18789 -n openclawopen 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커스텀 설정
섹션 제목: “커스텀 설정”에이전트 지침 (Agent instructions)
섹션 제목: “에이전트 지침 (Agent instructions)”scripts/k8s/manifests/configmap.yaml 파일의 AGENTS.md를 수정하고 다시 배포하세요:
./scripts/k8s/deploy.shGateway 설정
섹션 제목: “Gateway 설정”scripts/k8s/manifests/configmap.yaml의 openclaw.json을 수정하세요. 자세한 내용은 Gateway configuration 문서를 참고하면 좋습니다.
프로바이더 추가
섹션 제목: “프로바이더 추가”추가할 키를 export하고 다시 실행하세요:
export ANTHROPIC_API_KEY="..."export OPENAI_API_KEY="..."./scripts/k8s/deploy.sh --create-secret./scripts/k8s/deploy.sh기존 프로바이더 키는 덮어쓰지 않는 한 Secret에 그대로 유지됩니다.
또는 Secret을 직접 패치할 수도 있어요:
kubectl patch secret openclaw-secrets -n openclaw \ -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'kubectl rollout restart deployment/openclaw -n openclaw커스텀 네임스페이스
섹션 제목: “커스텀 네임스페이스”OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh커스텀 이미지
섹션 제목: “커스텀 이미지”scripts/k8s/manifests/deployment.yaml에서 image 필드를 수정하세요:
image: ghcr.io/openclaw/openclaw:2026.3.1Port-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를 구성하세요.
재배포
섹션 제목: “재배포”./scripts/k8s/deploy.sh이 명령은 모든 매니페스트를 적용하고 Pod를 재시작하여 변경된 설정이나 Secret을 반영합니다.
./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 Expert
아직 막혀 있나요?
이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.