OpenClaw 部署到 Kubernetes

这是在 Kubernetes 上运行 OpenClaw 的最小化起点——并非生产级完整方案，仅覆盖核心资源，供你根据自身环境调整适配。

为什么不用 Helm？

OpenClaw 是一个带少量配置文件的单容器应用。有价值的自定义点在于 Agent 内容（Markdown 文件、skills、配置覆盖），而不是基础设施模板化。Kustomize 可以处理覆盖层，同时避免 Helm chart 的额外复杂度。如果部署变得更复杂，可以在这些 manifests 基础上叠加 Helm chart。

所需条件

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

快速启动

# 将 PROVIDER 替换为你的提供商：ANTHROPIC、GEMINI、OPENAI 或 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：

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           # 自动检测 docker 或 podman
./scripts/k8s/create-kind.sh --delete  # 销毁集群

然后正常使用 ./scripts/k8s/deploy.sh 部署。

分步操作

1) 部署

方式 A — 环境变量传入 API Key（一步完成）：

# 将 PROVIDER 替换为你的提供商：ANTHROPIC、GEMINI、OPENAI 或 OPENROUTER
export <PROVIDER>_API_KEY="..."
./scripts/k8s/deploy.sh

脚本会创建一个包含 API Key 和自动生成 Gateway Token 的 Kubernetes Secret，然后执行部署。如果 Secret 已存在，会保留当前的 Gateway Token 和未被覆盖的 Provider 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://localhost:18789

部署内容

Namespace: openclaw（可通过 OPENCLAW_NAMESPACE 配置）
├── Deployment/openclaw        # 单 Pod，包含 init 容器 + gateway
├── Service/openclaw           # ClusterIP，端口 18789
├── PersistentVolumeClaim      # 10Gi，用于 Agent 状态和配置
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # Gateway Token + API Keys

自定义配置

Agent 指令

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

./scripts/k8s/deploy.sh

Gateway 配置

编辑 scripts/k8s/manifests/configmap.yaml 中的 openclaw.json。完整配置参考参见 Gateway 配置。

添加模型提供商

导出额外的 Key 后重新运行：

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

已有的 Provider Key 会保留在 Secret 中，除非你主动覆盖。

或者直接 patch Secret：

kubectl patch secret openclaw-secrets -n openclaw \
  -p '{"stringData":{"<PROVIDER>_API_KEY":"..."}}'
kubectl rollout restart deployment/openclaw -n openclaw

自定义 Namespace

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

自定义镜像

编辑 scripts/k8s/manifests/deployment.yaml 中的 image 字段：

image: ghcr.io/openclaw/openclaw:latest # 或固定到 https://github.com/openclaw/openclaw/releases 中的特定版本

暴露到 port-forward 以外

默认 manifests 将 Gateway 绑定到 Pod 内的回环地址，这与 kubectl port-forward 配合没问题，但无法通过 Kubernetes Service 或 Ingress 路径访问 Pod IP。

如果需要通过 Ingress 或负载均衡器暴露：

• 将 scripts/k8s/manifests/configmap.yaml 中的 Gateway bind 从 loopback 改为与你部署模型匹配的非回环绑定
• 保持 Gateway 认证开启，并使用正确的 TLS 终止入口点
• 按远程访问支持的 Web 安全模型（如 HTTPS/Tailscale Serve 以及必要时配置显式 allowed origins）设置 Control UI

重新部署

./scripts/k8s/deploy.sh

这会应用所有 manifests 并重启 Pod，以读取最新的配置和 Secret 变更。

销毁

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

这会删除 namespace 及其中所有资源，包括 PVC。

架构说明

• Gateway 默认绑定到 Pod 内的回环地址，即包含的设置适用于 kubectl port-forward
• 无集群范围资源——所有资源都在单一 namespace 中
• 安全加固：readOnlyRootFilesystem、drop: ALL capabilities、非 root 用户（UID 1000）
• 默认配置保持 Control UI 在更安全的本地访问路径：回环绑定 + kubectl port-forward 到 http://127.0.0.1:18789
• 如需超出 localhost 访问，使用支持的远程模型：HTTPS/Tailscale + 适当的 Gateway 绑定和 Control UI origin 设置
• Secret 在临时目录中生成并直接应用到集群——没有 secret 材料写入仓库检出

文件结构

scripts/k8s/
├── deploy.sh                   # 创建 namespace + secret，通过 kustomize 部署
├── create-kind.sh              # 本地 Kind 集群（自动检测 docker/podman）
└── manifests/
    ├── kustomization.yaml      # Kustomize base
    ├── configmap.yaml          # openclaw.json + AGENTS.md
    ├── deployment.yaml         # 带安全加固的 Pod spec
    ├── pvc.yaml                # 10Gi 持久化存储
    └── service.yaml            # ClusterIP，端口 18789