在 Kubernetes 上运行 OpenClaw

这是在 Kubernetes 上运行 OpenClaw 的最小起步方案——不是生产就绪的部署。它涵盖核心资源，需要根据你的环境进行调整。

为什么不用 Helm？

OpenClaw 就是一个容器加几个配置文件。真正需要定制的是 Agent 内容（markdown 文件、技能、配置覆盖），而非基础设施模板。Kustomize 处理 overlay 不需要 Helm chart 的开销。如果你的部署变得更复杂，可以在这些 manifest 之上叠加 Helm chart。

前置条件

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

快速开始

# 替换为你的提供商：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

获取网关 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（一步完成）：

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

脚本会创建一个 Kubernetes Secret（包含 API key 和自动生成的网关 token），然后部署。如果 Secret 已存在，会保留当前网关 token 和未被修改的提供商 key。

方式 B — 单独创建 secret：

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

本地测试时在任一命令后加 --show-token 可将 token 打印到标准输出。

2) 访问网关

kubectl port-forward svc/openclaw 18789:18789 -n openclaw
open http://localhost:18789

部署了什么

Namespace: openclaw (可通过 OPENCLAW_NAMESPACE 配置)
├── Deployment/openclaw        # 单 Pod，init 容器 + 网关
├── Service/openclaw           # ClusterIP，端口 18789
├── PersistentVolumeClaim      # 10Gi，用于 Agent 状态和配置
├── ConfigMap/openclaw-config  # openclaw.json + AGENTS.md
└── Secret/openclaw-secrets    # 网关 token + API key

定制化

Agent 指令

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

./scripts/k8s/deploy.sh

网关配置

编辑 scripts/k8s/manifests/configmap.yaml 中的 openclaw.json。完整参考请参阅网关配置。

添加提供商

带上额外的 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

自定义 namespace

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

自定义镜像

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

image: ghcr.io/openclaw/openclaw:2026.3.1

超越 port-forward 的暴露方式

默认 manifest 将网关绑定到 Pod 内的回环地址。这在 kubectl port-forward 下可以正常工作，但对于需要访问 Pod IP 的 Kubernetes Service 或 Ingress 路径则不行。

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

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

重新部署

./scripts/k8s/deploy.sh

这会应用所有 manifest 并重启 Pod 以拾取配置或 secret 变更。

销毁

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

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

架构说明

  • 网关默认绑定到 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 + 相应的网关绑定和 Control UI origin 设置
  • Secret 在临时目录中生成并直接应用到集群——没有 secret 材料写入仓库 checkout

文件结构

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
arrow_back
上一页
VPS
下一页
Fly
arrow_forward