Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Kubernetes 上的 OpenClaw

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

​
为什么不用 Helm？

OpenClaw 是一个单容器应用，带有一些配置文件。真正有意思的自定义在于 agent 内容（markdown 文件、skills、配置覆盖），而不是基础设施模板化。Kustomize 可以处理覆盖层，而无需 Helm chart 的额外开销。如果你的部署变得更加复杂，可以在这些清单之上再叠加一个 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
获取为 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           # 自动检测 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
该脚本会创建一个包含 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
如果你希望在本地测试时将 token 打印到 stdout，可以在任一命令中使用 --show-token。

​
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           # 18789 端口上的 ClusterIP
├── 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 configuration。

​
添加提供商

重新运行并导出额外的 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 字段： 
image: ghcr.io/openclaw/openclaw:latest # 或从 https://github.com/openclaw/openclaw/releases 固定到某个特定版本

​
超出 port-forward 的暴露方式

默认清单将 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，以及在需要时显式允许的来源）

​
重新部署

./scripts/k8s/deploy.sh
这会应用所有清单并重启 Pod，以获取任何配置或 secret 更改。

​
删除部署

./scripts/k8s/deploy.sh --delete
这会删除命名空间及其中的所有资源，包括 PVC。

​
架构说明

  • gateway 默认绑定到 Pod 内部的 loopback，因此包含的设置适用于 kubectl port-forward
  • 不使用集群级资源——所有内容都位于单个命名空间中
  • 安全性：readOnlyRootFilesystem、drop: ALL 能力、非 root 用户（UID 1000）
  • 默认配置使 Control UI 保持在更安全的本地访问路径：loopback 绑定加上 kubectl port-forward 到 http://127.0.0.1:18789
  • 如果你要超出 localhost 访问，请使用受支持的远程模型：HTTPS/Tailscale，以及相应的 gateway 绑定和 Control UI origin 设置
  • Secret 在临时目录中生成并直接应用到集群——没有任何 secret 内容会写入仓库检出目录

​
文件结构

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

​
相关内容