Kubernetes
这是在 Kubernetes 上运行 OpenClaw 的最小起点,并非生产就绪的部署方案。它涵盖核心资源,并旨在根据你的环境进行调整。
为什么不用 Helm¶
OpenClaw 是一个带有若干配置文件的单个容器。真正有价值的自定义在于 agent 内容(Markdown 文件、skills、配置覆盖),而不是基础设施模板化。Kustomize 可以处理 overlays,而无需 Helm chart 的额外开销。如果你的部署变得更加复杂,可以在这些 manifests 之上叠加一个 Helm chart。
你需要什么¶
- 一个正在运行的 Kubernetes 集群(AKS、EKS、GKE、k3s、kind、OpenShift 等)
- 已连接到你的集群的
kubectl - 至少一个模型提供商的 API key
快速开始¶
# Export the key for the provider you configured. Use ANTHROPIC_API_KEY,
# GEMINI_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY.
export ANTHROPIC_API_KEY="..."
./scripts/k8s/deploy.sh
kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://127.0.0.1:18789
deploy.sh 默认创建 token 认证。获取为 Control UI 生成的 gateway token:
kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.OPENCLAW_GATEWAY_TOKEN}' | base64 -d
对于本地调试,./scripts/k8s/deploy.sh --show-token 会在部署后打印 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 key(一步完成)
# Export the key for the provider you configured. Use ANTHROPIC_API_KEY,
# GEMINI_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY.
export ANTHROPIC_API_KEY="..."
./scripts/k8s/deploy.sh
该脚本会创建一个包含 API key 和自动生成的 gateway token 的 Kubernetes Secret,然后部署。如果 Secret 已存在,它会保留当前的 gateway token 以及未被更改的任何提供商 key。
选项 B:单独创建 secret
在任一命令中添加 --show-token,可将 token 打印到 stdout,用于本地测试。
2) 访问 Gateway¶
部署内容¶
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
Deployment 会检查 /readyz 以判断启动和流量就绪状态,启动预算为五分钟,并检查 /healthz 以判断存活状态。每个检查都会断言 JSON 检查契约,而不仅仅依赖状态码,因为 Control UI 会用兜底的 200 响应未知路径;如果只检查状态码,那么对于检查路由尚不存在的镜像,检查会永远通过。
/startupz 是更好的流量准入检查,因为它会忽略 channel 健康状态,因此一个失败的 channel account 不会将一个否则健康的 Gateway 从 Service endpoints 中驱逐。它要求使用基于 2026.8.1 或更新版本构建的镜像,该版本引入了此检查,且比上面固定的 tag 更新。固定此类镜像后,将启动检查和就绪检查切换到 /startupz,并保留 /readyz 用于应包含 channel-account 健康状态的监控。
自定义¶
Agent 指令¶
编辑 scripts/k8s/manifests/configmap.yaml 中的 AGENTS.md,然后重新部署:
Gateway 配置¶
编辑 scripts/k8s/manifests/configmap.yaml 中的 openclaw.json。完整参考见 网关配置。
init 容器仅当 PVC 中缺少每个文件时,才会为 openclaw.json 和工作区 AGENTS.md 播种初始内容。首次启动后,持久化副本即为事实来源:通过 OpenClaw(onboard、channels add、doctor --fix、Control UI)所做的更改会在 pod 重启后保留,并且更新 ConfigMap 不会覆盖已有的 PVC 副本。若要有意从更新后的 ConfigMap 重新播种某个文件,请删除持久化副本并重启:
kubectl exec -n openclaw deploy/openclaw -- rm /home/node/.openclaw/openclaw.json
kubectl rollout restart -n openclaw deploy/openclaw
使用旧模板创建的 Deployment 会在每次 pod 启动时应用 ConfigMap 编辑(并丢弃通过 OpenClaw 所做的任何配置更改)。如果你依赖该流程,请在编辑 ConfigMap 后使用上述重新播种命令。
添加提供商¶
导出额外的 key 后重新运行:
export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
./scripts/k8s/deploy.sh --create-secret
./scripts/k8s/deploy.sh
除非你覆盖它们,否则现有提供商 key 会保留在 Secret 中。
或者直接 patch Secret:
kubectl patch secret openclaw-secrets -n openclaw \
-p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
kubectl rollout restart deployment/openclaw -n openclaw
自定义命名空间¶
自定义镜像¶
编辑 scripts/k8s/manifests/deployment.yaml 中的 image 字段:
# Bump this immutable versioned tag when upgrading OpenClaw.
image: ghcr.io/openclaw/openclaw:2026.7.1-2-slim
在 port-forward 之外暴露¶
默认 manifests 会将 gateway 绑定到 pod 内部的 loopback。这与 kubectl port-forward 配合可用,但不适用于需要直接访问 pod IP 的 Kubernetes Service 或 Ingress 路径。
要通过 Ingress 或负载均衡器暴露 gateway:
- 将
scripts/k8s/manifests/configmap.yaml中的 gateway 绑定从loopback更改为与你的部署模型匹配的非 loopback 绑定。 - 保持启用 gateway 认证,并使用正确的 TLS 终结入口点。
- 使用受支持的 web 安全模型为 Control UI 配置远程访问(例如 HTTPS/Tailscale Serve,以及必要时显式允许的 origins)。
重新部署¶
这会应用所有清单并重启 Pod,以获取任何配置或 Secret 变更。
拆除¶
对于默认 openclaw 命名空间,这会删除该命名空间及其中的所有内容,包括 PVC。
对于自定义命名空间,--delete 仅删除 OpenClaw 资源,并保留命名空间以及无关工作负载:
使用 --delete-resources 可在任意命名空间中显式请求这种范围受限的拆除。两种范围模式都会删除 OpenClaw Deployment、Service、PVC、ConfigMap 以及生成的 Secret。删除 PVC 会移除 OpenClaw 的申领及其对持久化数据的访问;底层卷和数据是否会被删除,取决于 PersistentVolume 或 StorageClass 的回收策略(Delete 或 Retain)。
要删除自定义命名空间及其中的每个工作负载,请显式选择加入:
这也会删除无关工作负载和 PVC。
架构说明¶
- 网关默认在 Pod 内绑定到回环地址,因此包含的设置用于
kubectl port-forward。 - 没有集群范围资源;所有内容都位于单个命名空间中。
- 安全加固:
readOnlyRootFilesystem、drop: ALLcapabilities、非 root 用户(UID 1000)。 - 默认配置将 Control UI 保持在更安全的本地访问路径上:回环绑定加上通过
kubectl port-forward访问http://127.0.0.1:18789。 - 如果超出 localhost 访问,请使用受支持的远程模型:HTTPS/Tailscale 加上适当的网关绑定和 Control UI origin 设置。
- Secret 在临时目录中生成并直接应用到集群;不会将任何 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
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw