跳转至

Kubernetes

这是在 Kubernetes 上运行 OpenClaw 的最小起点，并非生产就绪的部署。它涵盖了核心资源，旨在根据你的环境进行调整。

为什么不用 Helm

OpenClaw 是一个带有一些配置文件的单一容器。有价值的自定义在于 agent 内容（Markdown 文件、技能、配置覆盖），而非基础设施模板化。Kustomize 无需 Helm chart 的开销即可处理覆盖（overlay）。如果你的部署变得更复杂，可以在这些 manifest 之上再加一层 Helm chart。

你需要什么

  • 一个运行中的 Kubernetes 集群（AKS、EKS、GKE、k3s、kind、OpenShift 等）
  • kubectl 已连接到你的集群
  • 至少一个模型提供商的 API 密钥

快速开始

# 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 生成的网关 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 密钥（一步完成）

# 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 密钥和自动生成的网关 token 的 Kubernetes Secret，然后进行部署。如果 Secret 已存在，它会保留当前的网关 token 以及所有未更改的提供商密钥。

选项 B：单独创建 Secret

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

在任一命令中添加 --show-token 可将 token 打印到 stdout，以便进行本地测试。

2) 访问网关

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 账户无法将原本健康的 Gateway 从 Service endpoints 中驱逐。它要求使用 2026.8.1 或更新版本构建的镜像，该版本引入了此端点，比上面固定的标签更新。固定此类镜像后，将启动和就绪探测切换到 /startupz，并保留 /readyz 用于应包含 channel 账户健康状况的监控。

自定义

Agent 指令

编辑 scripts/k8s/manifests/configmap.yaml 中的 AGENTS.md 并重新部署：

./scripts/k8s/deploy.sh

网关配置

编辑 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 后使用上面的重新写入命令。

添加提供商

导出额外的密钥后重新运行：

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

现有的提供商密钥会保留在 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

在端口转发之外暴露

默认的 manifest 将网关绑定到 pod 内部的 loopback。这适用于 kubectl port-forward，但不适用于需要直接访问 pod IP 的 Kubernetes Service 或 Ingress 路径。

要通过 Ingress 或负载均衡器暴露网关：

  • 将 scripts/k8s/manifests/configmap.yaml 中的网关绑定从 loopback 改为符合你部署模型的非 loopback 绑定。
  • 保持网关认证启用，并使用正确的 TLS 终止入口点。
  • 使用受支持的 Web 安全模型配置 Control UI 以进行远程访问（例如 HTTPS/Tailscale Serve，并在需要时设置明确的允许来源）。

重新部署

./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 能力、非 root 用户（UID 1000）。
  • 默认配置将 Control UI 保持在更安全的本地访问路径上：回环绑定加上 kubectl port-forward 到 http://127.0.0.1:18789。
  • 如果不再局限于 localhost 访问，请使用受支持的远程模式：HTTPS/Tailscale 加上适当的网关绑定和 Control UI 来源设置。
  • 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