在 Kubernetes 上部署 OpenClaw:快速啟動指南
想要在 Kubernetes 上跑 AI Agent,但又不想被複雜的設定搞瘋?很多時候我們只是想找個地方穩定運行 OpenClaw,而不是去寫幾百行的 YAML。這份指南會帶你用最簡單的方式,在 K8s 上把 OpenClaw 跑起來。
這是一個在 Kubernetes 上運行 OpenClaw 的最小起點,並非針對生產環境設計。它涵蓋了核心資源,你可以根據自己的環境進行調整。
為什麼不用 Helm?
Section titled “為什麼不用 Helm?”OpenClaw 是一個單一容器配上一些設定檔。真正的自定義重點在於 Agent 的內容(Markdown 檔案、Skills、設定覆蓋),而不是基礎設施的模板化。Kustomize 可以處理 Overlay,而不需要 Helm Chart 那樣的額外負擔。如果你的部署變得更複雜,可以在這些 Manifests 之上再疊加一層 Helm。
你需要準備什麼
Section titled “你需要準備什麼”- 一個運作中的 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:18789取得 Gateway token 並將它貼到 Control UI 中:
kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d如果是為了本地除錯,執行 ./scripts/k8s/deploy.sh --show-token 會在部署後直接印出 token。
使用 Kind 進行本地測試
Section titled “使用 Kind 進行本地測試”如果你手邊沒有叢集,可以用 Kind 在本地建立一個:
./scripts/k8s/create-kind.sh # auto-detects docker or podman./scripts/k8s/create-kind.sh --delete # tear down接著按照平常的方式使用 ./scripts/k8s/deploy.sh 進行部署。
逐步操作指南
Section titled “逐步操作指南”選項 A — 在環境變數中設定 API key(一步到位):
# Replace with your provider: ANTHROPIC, GEMINI, OPENAI, or OPENROUTERexport <PROVIDER>_API_KEY="..."./scripts/k8s/deploy.sh這個腳本會建立一個包含 API key 和自動生成的 Gateway token 的 Kubernetes Secret,然後進行部署。如果 Secret 已經存在,它會保留目前的 Gateway token 以及任何未被修改的提供者金鑰。
選項 B — 分開建立 Secret:
export <PROVIDER>_API_KEY="..."./scripts/k8s/deploy.sh --create-secret./scripts/k8s/deploy.sh如果你希望在本地測試時將 token 印在螢幕上,可以在任一指令後面加上 --show-token。
2) 存取 Gateway
Section titled “2) 存取 Gateway”kubectl port-forward svc/openclaw 18789:18789 -n openclawopen http://localhost:18789部署了哪些資源
Section titled “部署了哪些資源”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 keysAgent 指令
Section titled “Agent 指令”編輯 scripts/k8s/manifests/configmap.yaml 中的 AGENTS.md 並重新部署:
./scripts/k8s/deploy.shGateway 設定
Section titled “Gateway 設定”編輯 scripts/k8s/manifests/configmap.yaml 中的 openclaw.json。完整的參考資料請看 Gateway configuration。
匯出額外的金鑰後重新執行:
export ANTHROPIC_API_KEY="..."export OPENAI_API_KEY="..."./scripts/k8s/deploy.sh --create-secret./scripts/k8s/deploy.sh除非你覆蓋它們,否則現有的提供者金鑰會保留在 Secret 中。
或者直接對 Secret 進行 Patch:
kubectl patch secret openclaw-secrets -n openclaw \ -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'kubectl rollout restart deployment/openclaw -n openclaw自定義 Namespace
Section titled “自定義 Namespace”OPENCLAW_NAMESPACE=my-namespace ./scripts/k8s/deploy.sh自定義 Image
Section titled “自定義 Image”編輯 scripts/k8s/manifests/deployment.yaml 中的 image 欄位:
image: ghcr.io/openclaw/openclaw:2026.3.1暴露服務(Port-forward 以外)
Section titled “暴露服務(Port-forward 以外)”預設的 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,並在需要時明確設定允許的來源)。
./scripts/k8s/deploy.sh這會套用所有的 Manifests 並重啟 Pod,以載入任何設定或 Secret 的變更。
./scripts/k8s/deploy.sh --delete這會刪除 Namespace 及其中的所有資源,包括 PVC。
- Gateway 預設綁定在 Pod 內部的 loopback,因此內建的設定是為了
kubectl port-forward設計的。 - 沒有叢集層級(cluster-scoped)的資源 — 所有東西都放在單一 Namespace 中。
- 安全性:使用了
readOnlyRootFilesystem、drop: ALLcapabilities 以及非 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 18789OpenClaw Expert
還是卡住了?
如果這篇文件沒有解決你的情境,直接問 OpenClaw Expert,拿到可執行步驟。