跳到內容

在 Kubernetes 上部署 OpenClaw:快速啟動指南

想要在 Kubernetes 上跑 AI Agent,但又不想被複雜的設定搞瘋?很多時候我們只是想找個地方穩定運行 OpenClaw,而不是去寫幾百行的 YAML。這份指南會帶你用最簡單的方式,在 K8s 上把 OpenClaw 跑起來。

這是一個在 Kubernetes 上運行 OpenClaw 的最小起點,並非針對生產環境設計。它涵蓋了核心資源,你可以根據自己的環境進行調整。

OpenClaw 是一個單一容器配上一些設定檔。真正的自定義重點在於 Agent 的內容(Markdown 檔案、Skills、設定覆蓋),而不是基礎設施的模板化。Kustomize 可以處理 Overlay,而不需要 Helm Chart 那樣的額外負擔。如果你的部署變得更複雜,可以在這些 Manifests 之上再疊加一層 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 token 並將它貼到 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 會在部署後直接印出 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 token 的 Kubernetes Secret,然後進行部署。如果 Secret 已經存在,它會保留目前的 Gateway token 以及任何未被修改的提供者金鑰。

選項 B — 分開建立 Secret:

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

如果你希望在本地測試時將 token 印在螢幕上,可以在任一指令後面加上 --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。

匯出額外的金鑰後重新執行:

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

除非你覆蓋它們,否則現有的提供者金鑰會保留在 Secret 中。

或者直接對 Secret 進行 Patch:

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

預設的 Manifests 會將 Gateway 綁定到 Pod 內部的 loopback。這在配合 kubectl port-forward 時運作良好,但如果你需要透過 Kubernetes Service 或 Ingress 路徑存取 Pod IP,這就行不通了。

如果你想透過 Ingress 或負載平衡器暴露 Gateway:

  • 將 scripts/k8s/manifests/configmap.yaml 中的 Gateway 綁定從 loopback 改為符合你部署模式的非 loopback 綁定。
  • 保持 Gateway 認證開啟,並使用適當的 TLS 終端入口。
  • 根據支援的網路安全模型配置 Control UI 的遠端存取(例如使用 HTTPS/Tailscale Serve,並在需要時明確設定允許的來源)。
Terminal window
./scripts/k8s/deploy.sh

這會套用所有的 Manifests 並重啟 Pod,以載入任何設定或 Secret 的變更。

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

這會刪除 Namespace 及其中的所有資源,包括 PVC。

  • Gateway 預設綁定在 Pod 內部的 loopback,因此內建的設定是為了 kubectl port-forward 設計的。
  • 沒有叢集層級(cluster-scoped)的資源 — 所有東西都放在單一 Namespace 中。
  • 安全性:使用了 readOnlyRootFilesystem、drop: ALL capabilities 以及非 root 使用者 (UID 1000)。
  • 預設設定讓 Control UI 走較安全的本地存取路徑:loopback 綁定加上 kubectl port-forward 到 http://127.0.0.1:18789。
  • 如果你不再侷限於 localhost 存取,請使用支援的遠端模型:HTTPS/Tailscale 加上適當的 Gateway 綁定和 Control UI 來源設定。
  • Secret 會在臨時目錄中生成並直接套用到叢集 — 不會有任何 Secret 資料被寫入你的 Repo 目錄中。
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,拿到可執行步驟。