Kubernetes

Kubernetes 문서는 OpenClaw 공식 문서(install/kubernetes)를 한국어로 정리한 가이드입니다. Deploy OpenClaw Gateway to a Kubernetes cluster with Kustomize 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Deploy OpenClaw Gateway to a Kubernetes cluster with Kustomize

한국어 가이드 범위: install/kubernetes 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Why not Helm
What you need
빠른 시작
Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
Local testing with Kind
Step by step
1) Deploy
Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
2) Access the gateway
What gets deployed
Customization
Agent instructions
Gateway config
Add providers
Custom namespace
Custom image
Expose beyond port-forward
Re-deploy
Teardown
Architecture notes
File structure
관련 문서

상세 내용

본문

A minimal starting point for running OpenClaw on Kubernetes, not a production-ready deployment. It covers the core resources and is meant to be adapted to your environment.

Why not Helm

OpenClaw is a single container with some config files. The interesting customization is in agent content (Markdown files, skills, config overrides), not infrastructure templating. Kustomize handles overlays without the overhead of a Helm chart. Layer a Helm chart on top of these manifests if your deployment grows more complex.

What you need

주요 항목:

A running Kubernetes cluster (AKS, EKS, GKE, k3s, kind, OpenShift, etc.)
kubectl connected to your cluster
An API key for at least one model provider

빠른 시작


### Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER

kubectl port-forward svc/openclaw 18789:18789 -n openclaw open http://localhost:18789 bash kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

```text
`deploy.sh` creates token auth by default. Retrieve the generated gateway token for the Control UI:

Local testing with Kind

If you do not have a cluster, create one locally with Kind:

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

Step by step

이 섹션의 세부 항목은 공식 문서 Step by step를 참고하세요.

1) Deploy

Option A: API key in environment (one step)


### Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER

./scripts/k8s/deploy.sh --create-secret ./scripts/k8s/deploy.sh ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

```text
The script creates a Kubernetes Secret with the API key and an auto-generated gateway token, then deploys. If the Secret already exists, it preserves the current gateway token and any provider keys not being changed.

**Option B: create the secret separately**

2) Access the gateway

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

What gets deployed

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

Customization

이 섹션의 세부 항목은 공식 문서 Customization를 참고하세요.

Agent instructions

Edit the AGENTS.md in scripts/k8s/manifests/configmap.yaml and redeploy:

./scripts/k8s/deploy.sh

Gateway config

Edit openclaw.json in scripts/k8s/manifests/configmap.yaml. See Gateway configuration for the full reference.

Add providers

Existing provider keys stay in the Secret unless you overwrite them.

./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

kubectl patch secret openclaw-secrets -n openclaw \
  -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
kubectl rollout restart deployment/openclaw -n openclaw

Custom namespace

OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh

Custom image

Edit the image field in scripts/k8s/manifests/deployment.yaml:

image: ghcr.io/openclaw/openclaw:slim # primary; official Docker Hub mirror: openclaw/openclaw

Expose beyond port-forward

The default manifests bind the gateway to loopback inside the pod. That works with kubectl port-forward, but not with a Kubernetes Service or Ingress path that needs to reach the pod IP directly.

주요 항목:

Change the gateway bind in scripts/k8s/manifests/configmap.yaml from loopback to a non-loopback bind that matches your deployment model.
Keep gateway auth enabled and use a proper TLS-terminated entrypoint.
Configure the Control UI for remote access using the supported web security model (for example HTTPS/Tailscale Serve and explicit allowed origins when needed).

Re-deploy

This applies all manifests and restarts the pod to pick up any config or secret changes.

./scripts/k8s/deploy.sh

Teardown

This deletes the namespace and all resources in it, including the PVC.

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

Architecture notes

주요 항목:

The gateway binds to loopback inside the pod by default, so the included setup is for kubectl port-forward.
No cluster-scoped resources; everything lives in a single namespace.
Security hardening: readOnlyRootFilesystem, drop: ALL capabilities, non-root user (UID 1000).
The default config keeps the Control UI on the safer local-access path: loopback bind plus kubectl port-forward to http://127.0.0.1:18789.
If you move beyond localhost access, use the supported remote model: HTTPS/Tailscale plus the appropriate gateway bind and Control UI origin settings.
Secrets are generated in a temp directory and applied directly to the cluster; no secret material is written to the repo checkout.

File structure

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/kubernetes
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER

./scripts/k8s/deploy.sh

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

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

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

# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER

./scripts/k8s/deploy.sh

./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

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

Kubernetes

핵심 요약

Deploy OpenClaw Gateway to a Kubernetes cluster with Kustomize

한국어 가이드 범위: install/kubernetes 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Why not Helm
What you need
빠른 시작
Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
Local testing with Kind
Step by step
1) Deploy
Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER
2) Access the gateway
What gets deployed
Customization
Agent instructions
Gateway config
Add providers
Custom namespace
Custom image
Expose beyond port-forward
Re-deploy
Teardown
Architecture notes
File structure
관련 문서

상세 내용

본문

A minimal starting point for running OpenClaw on Kubernetes, not a production-ready deployment. It covers the core resources and is meant to be adapted to your environment.

Why not Helm

What you need

주요 항목:

A running Kubernetes cluster (AKS, EKS, GKE, k3s, kind, OpenShift, etc.)
kubectl connected to your cluster
An API key for at least one model provider

빠른 시작


### Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER

kubectl port-forward svc/openclaw 18789:18789 -n openclaw open http://localhost:18789 bash kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

```text
`deploy.sh` creates token auth by default. Retrieve the generated gateway token for the Control UI:

Local testing with Kind

If you do not have a cluster, create one locally with Kind:

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

Step by step

이 섹션의 세부 항목은 공식 문서 Step by step를 참고하세요.

1) Deploy

Option A: API key in environment (one step)


### Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER

./scripts/k8s/deploy.sh --create-secret ./scripts/k8s/deploy.sh ```

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

```text
The script creates a Kubernetes Secret with the API key and an auto-generated gateway token, then deploys. If the Secret already exists, it preserves the current gateway token and any provider keys not being changed.

**Option B: create the secret separately**

2) Access the gateway

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

What gets deployed

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

Customization

이 섹션의 세부 항목은 공식 문서 Customization를 참고하세요.

Agent instructions

Edit the AGENTS.md in scripts/k8s/manifests/configmap.yaml and redeploy:

./scripts/k8s/deploy.sh

Gateway config

Edit openclaw.json in scripts/k8s/manifests/configmap.yaml. See Gateway configuration for the full reference.

Add providers

Existing provider keys stay in the Secret unless you overwrite them.

./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

kubectl patch secret openclaw-secrets -n openclaw \
  -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
kubectl rollout restart deployment/openclaw -n openclaw

Custom namespace

OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh

Custom image

Edit the image field in scripts/k8s/manifests/deployment.yaml:

image: ghcr.io/openclaw/openclaw:slim # primary; official Docker Hub mirror: openclaw/openclaw

Expose beyond port-forward

The default manifests bind the gateway to loopback inside the pod. That works with kubectl port-forward, but not with a Kubernetes Service or Ingress path that needs to reach the pod IP directly.

주요 항목:

Change the gateway bind in scripts/k8s/manifests/configmap.yaml from loopback to a non-loopback bind that matches your deployment model.
Keep gateway auth enabled and use a proper TLS-terminated entrypoint.
Configure the Control UI for remote access using the supported web security model (for example HTTPS/Tailscale Serve and explicit allowed origins when needed).

Re-deploy

This applies all manifests and restarts the pod to pick up any config or secret changes.

./scripts/k8s/deploy.sh

Teardown

This deletes the namespace and all resources in it, including the PVC.

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

Architecture notes

주요 항목:

The gateway binds to loopback inside the pod by default, so the included setup is for kubectl port-forward.
No cluster-scoped resources; everything lives in a single namespace.
Security hardening: readOnlyRootFilesystem, drop: ALL capabilities, non-root user (UID 1000).
The default config keeps the Control UI on the safer local-access path: loopback bind plus kubectl port-forward to http://127.0.0.1:18789.
If you move beyond localhost access, use the supported remote model: HTTPS/Tailscale plus the appropriate gateway bind and Control UI origin settings.
Secrets are generated in a temp directory and applied directly to the cluster; no secret material is written to the repo checkout.

File structure

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/kubernetes
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER

./scripts/k8s/deploy.sh

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

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

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

# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTER

./scripts/k8s/deploy.sh

./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh

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

Kubernetes

핵심 요약

문서 구성

상세 내용

본문

Why not Helm

What you need

빠른 시작

Local testing with Kind

Step by step

1) Deploy

2) Access the gateway

What gets deployed

Customization

Agent instructions

Gateway config

Add providers

Custom namespace

Custom image

Expose beyond port-forward

Re-deploy

Teardown

Architecture notes

File structure

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Kubernetes

핵심 요약

문서 구성

상세 내용

본문

Why not Helm

What you need

빠른 시작

Local testing with Kind

Step by step

1) Deploy

2) Access the gateway

What gets deployed

Customization

Agent instructions

Gateway config

Add providers

Custom namespace

Custom image

Expose beyond port-forward

Re-deploy

Teardown

Architecture notes

File structure

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드