跳转至

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

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

在任一命令中添加 --show-token,可将 token 打印到 stdout,用于本地测试。

2) 访问 Gateway

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://127.0.0.1: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

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,然后重新部署:

./scripts/k8s/deploy.sh

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

自定义命名空间

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

自定义镜像

编辑 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)。

重新部署

./scripts/k8s/deploy.sh

这会应用所有清单并重启 Pod,以获取任何配置或 Secret 变更。

拆除

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

对于默认 openclaw 命名空间,这会删除该命名空间及其中的所有内容,包括 PVC。

对于自定义命名空间,--delete 仅删除 OpenClaw 资源,并保留命名空间以及无关工作负载:

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

使用 --delete-resources 可在任意命名空间中显式请求这种范围受限的拆除。两种范围模式都会删除 OpenClaw Deployment、Service、PVC、ConfigMap 以及生成的 Secret。删除 PVC 会移除 OpenClaw 的申领及其对持久化数据的访问;底层卷和数据是否会被删除,取决于 PersistentVolume 或 StorageClass 的回收策略(Delete 或 Retain)。

要删除自定义命名空间及其中的每个工作负载,请显式选择加入:

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

这也会删除无关工作负载和 PVC。

架构说明

  • 网关默认在 Pod 内绑定到回环地址,因此包含的设置用于 kubectl port-forward。
  • 没有集群范围资源;所有内容都位于单个命名空间中。
  • 安全加固:readOnlyRootFilesystem、drop: ALL capabilities、非 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