메인 콘텐츠로 건너뛰기

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.

OpenClaw를 Kubernetes에서 실행하기 위한 최소 시작점입니다. 프로덕션 준비가 완료된 배포가 아닙니다. 핵심 리소스를 다루며, 사용자의 환경에 맞게 조정하는 것을 전제로 합니다.

​
Helm을 사용하지 않는 이유

OpenClaw는 몇 가지 구성 파일이 있는 단일 컨테이너입니다. 중요한 사용자 지정은 인프라 템플릿이 아니라 에이전트 콘텐츠(마크다운 파일, skills, 구성 재정의)에 있습니다. Kustomize는 Helm 차트의 오버헤드 없이 오버레이를 처리합니다. 배포가 더 복잡해지면 이 매니페스트 위에 Helm 차트를 계층화할 수 있습니다.

​
필요한 것

  • 실행 중인 Kubernetes 클러스터(AKS, EKS, GKE, k3s, kind, OpenShift 등)
  • 클러스터에 연결된 kubectl
  • 하나 이상의 모델 제공자용 API 키

​
빠른 시작

# 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
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로 로컬에 하나를 생성하세요. 
./scripts/k8s/create-kind.sh           # auto-detects docker or podman
./scripts/k8s/create-kind.sh --delete  # tear down
그런 다음 평소처럼 ./scripts/k8s/deploy.sh로 배포합니다.

​
단계별 안내

​
1) 배포

옵션 A — 환경 변수의 API 키(한 단계): 
# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh
스크립트는 API 키와 자동 생성된 Gateway 토큰이 포함된 Kubernetes Secret을 만든 다음 배포합니다. Secret이 이미 있으면 현재 Gateway 토큰과 변경되지 않는 모든 제공자 키를 보존합니다. 옵션 B — 시크릿을 별도로 생성: 
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh
로컬 테스트를 위해 토큰을 stdout에 출력하려면 어느 명령에서든 --show-token을 사용하세요.

​
2) Gateway에 접근

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를 편집하고 다시 배포합니다. 
./scripts/k8s/deploy.sh

​
Gateway 구성

scripts/k8s/manifests/configmap.yaml의 openclaw.json을 편집합니다. 전체 참조는 Gateway 구성을 참조하세요.

​
제공자 추가

추가 키를 내보낸 상태로 다시 실행합니다. 
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:latest # or pin to a specific version from https://github.com/openclaw/openclaw/releases

​
포트 포워딩을 넘어 노출

기본 매니페스트는 pod 내부에서 Gateway를 loopback에 바인딩합니다. 이는 kubectl port-forward와 함께 작동하지만, pod IP에 도달해야 하는 Kubernetes Service 또는 Ingress 경로에서는 작동하지 않습니다. Ingress 또는 로드 밸런서를 통해 Gateway를 노출하려는 경우:
  • scripts/k8s/manifests/configmap.yaml의 Gateway 바인딩을 loopback에서 배포 모델에 맞는 non-loopback 바인딩으로 변경합니다
  • Gateway 인증을 활성화된 상태로 유지하고 적절한 TLS 종료 엔트리포인트를 사용합니다
  • 지원되는 웹 보안 모델을 사용하여 원격 접근용 Control UI를 구성합니다(예: HTTPS/Tailscale Serve 및 필요 시 명시적으로 허용된 origin)

​
재배포

./scripts/k8s/deploy.sh
이 명령은 모든 매니페스트를 적용하고 pod를 다시 시작하여 구성 또는 시크릿 변경 사항을 반영합니다.

​
정리

./scripts/k8s/deploy.sh --delete
이 명령은 네임스페이스와 그 안의 모든 리소스(PVC 포함)를 삭제합니다.

​
아키텍처 참고 사항

  • Gateway는 기본적으로 pod 내부의 loopback에 바인딩되므로 포함된 설정은 kubectl port-forward용입니다
  • 클러스터 범위 리소스가 없습니다. 모든 것은 단일 네임스페이스 안에 있습니다
  • 보안: readOnlyRootFilesystem, drop: ALL capabilities, non-root 사용자(UID 1000)
  • 기본 구성은 Control UI를 더 안전한 로컬 접근 경로에 유지합니다. loopback 바인딩과 kubectl port-forward를 http://127.0.0.1:18789로 사용합니다
  • localhost 접근을 넘어서는 경우 지원되는 원격 모델을 사용하세요. HTTPS/Tailscale과 적절한 Gateway 바인딩 및 Control UI origin 설정
  • 시크릿은 임시 디렉터리에서 생성되어 클러스터에 직접 적용됩니다. repo checkout에는 시크릿 자료가 기록되지 않습니다

​
파일 구조

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

​
관련 항목