本页内容
本页内容
托管
Kubernetes
在 Kubernetes 上运行 OpenClaw 的最低起点,而不是生产就绪部署。它涵盖了核心资源,旨在适应您的环境。
为什么不用 Helm
OpenClaw 是一个包含一些配置文件的单容器。真正有意思的定制在于代理内容(Markdown 文件、技能、配置覆盖),而不是基础设施模板。Kustomize 可以处理覆盖层,而无需 Helm chart 的开销。如果你的部署变得更复杂,可以在这些清单之上再叠加一个 Helm chart。
准备工作
- 一个正在运行的 Kubernetes 集群(AKS、EKS、GKE、k3s、kind、OpenShift 等)
- 已连接到你的集群的
kubectl - 至少一个模型提供商的 API key。
快速开始
deploy.sh 默认会创建 token 认证。为 Control UI 获取生成的 gateway token:
对于本地调试,./scripts/k8s/deploy.sh --show-token 会在部署后打印 token。
使用 Kind 在本地测试
如果你没有集群,可以使用 Kind 在本地创建一个:
然后像往常一样使用 ./scripts/k8s/deploy.sh 进行部署。
逐步说明
1) 部署
选项 A:在环境中提供 API key(一步完成)
该脚本使用 API 密钥和自动生成的网关令牌创建 Kubernetes Secret,然后进行部署。如果 Secret 已存在,它将保留当前网关令牌和任何未更改的提供商密钥。
选项 B:单独创建 secret
在任一命令中添加 --show-token,即可将 token 输出到 stdout,便于本地测试。
2) 访问 gateway
部署了什么
该部署以五分钟的启动预算检查 /readyz 的启动和流量准备情况,并检查 /healthz 的活跃度。每次检查都断言 JSON 检查合约,而不是单独的状态代码,因为 Control UI 通过包罗万象的 200 回答未知路径;对于检查路径尚不存在的图像,仅状态检查将永远通过。
/startupz 是更好的流量准入检查,因为它忽略通道运行状况,因此一个失败的通道帐户无法从服务端点中驱逐原本运行良好的网关。它需要从 2026.8.1 或更新版本(引入它的版本)构建的映像,该映像比上面固定的标签更新。固定此类映像后,将启动和就绪检查切换到 /startupz 并保留 /readyz 进行监控,其中应包括通道帐户运行状况。
定制
Agent 指令
编辑scripts/k8s/manifests/configmap.yaml中的AGENTS.md并重新部署:
网关配置
在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 有意重新写入某个文件,请删除持久化副本并重启:
根据之前模板创建的 Deployment 会在每次 Pod 启动时应用 ConfigMap 编辑内容(并丢弃通过 OpenClaw 所做的任何配置更改)。如果你依赖这种流程,请在编辑 ConfigMap 后使用上述重新写入命令。
添加提供商
重新运行并导出额外的 key:
现有的提供商 key 会保留在 Secret 中,除非你覆盖它们。
或者直接 patch Secret:
自定义命名空间
自定义镜像
编辑 scripts/k8s/manifests/deployment.yaml 中的 image 字段:
从2026.8.1开始的图像需要可写缓存位置;发货清单通过 XDG_CACHE_HOME 提供。升级较旧的部署时,请应用该环境条目以及映像更改。
超出 port-forward 的暴露方式
默认的 manifests 会将 gateway 绑定到 pod 内的 loopback。这适用于 kubectl port-forward,但不适用于需要直接访问 pod IP 的 Kubernetes Service 或 Ingress 路径。
要通过 Ingress 或负载均衡器暴露 gateway:
- 将
scripts/k8s/manifests/configmap.yaml中的 gateway 绑定从loopback改为与你的部署模型匹配的非 loopback 绑定。 - 保持网关身份验证启用并使用正确的 TLS- 终止入口点。
- 使用支持的 Web 安全模型为远程访问配置 Control UI(例如 HTTPS/Tailscale Serve,以及在需要时显式允许的来源)。
重新部署
这会应用所有清单并重启 Pod,以获取任何配置或 secret 更改。
删除部署
对于默认的 openclaw 命名空间,此操作会删除该命名空间及其中的所有内容,包括 PVC。
对于自定义命名空间,--delete 仅删除 OpenClaw 资源,并保留该命名空间及其中无关的工作负载:
在任何命名空间中,使用 --delete-resources 可显式请求执行此范围限定的清理操作。这两种范围限定模式都会删除 OpenClaw Deployment、Service、PVC、ConfigMap 以及生成的 Secret。删除 PVC 会移除 OpenClaw 的存储声明以及对其持久化数据的访问;底层卷和数据是否被删除,取决于 PersistentVolume 或 StorageClass 的回收策略(Delete 或 Retain)。
要删除自定义命名空间及其中的所有工作负载,请显式选择加入:
此操作也会删除无关的工作负载和 PVC。
架构说明
- 默认情况下,gateway 绑定到 Pod 内部的 loopback,因此所包含的设置适用于
kubectl port-forward。 - 没有集群级资源;所有内容都位于单个命名空间中。
- 安全加固:
readOnlyRootFilesystem、drop: ALLcapabilities、非 root 用户(UID 1000)。 - 可写缓存:网关在
XDG_CACHE_HOME(默认~/.cache)下暂存私有 SQLite 快照。清单将其指向 PVC 上的/home/node/.openclaw/.cache,因为根文件系统是只读的。如果您自定义安装,请保留等效的可写缓存位置。 - 默认配置将 Control UI 保持在更安全的本地访问路径上:loopback 绑定,再通过
kubectl port-forward访问http://127.0.0.1:18789。 - 如果你要超出 localhost 访问,请使用受支持的远程模式:HTTPS/Tailscale,以及相应的 gateway 绑定和 Control UI origin 设置。
- Secret 会在临时目录中生成,并直接应用到集群;不会将任何 secret 内容写入仓库检出目录。