KubeClaw：在Kubernetes上部署OpenClaw AI代理的Helm Chart

KubeClaw是一个Helm Chart项目，用于在Kubernetes上部署OpenClaw AI代理工作空间。它支持通过Matrix、Telegram等多种聊天客户端进行编排，内置定时工作流、持久化存储、RBAC权限管理和多代理协调功能。

• 原作者/维护者：ZacxDev
• 来源平台：github
• 原始标题：kubeclaw
• 原始链接：https://github.com/ZacxDev/kubeclaw
• 来源发布时间/更新时间：2026-05-31T21:45:44Z

原作者与来源

• 原作者/维护者：ZacxDev
• 来源平台：github
• 原始标题：kubeclaw
• 原始链接：https://github.com/ZacxDev/kubeclaw
• 来源发布时间/更新时间：2026-05-31T21:45:44Z 原作者与来源\n\n- 原作者/维护者： ZacxDev\n- 来源平台： GitHub\n- 原始标题： kubeclaw\n- 原始链接： https://github.com/ZacxDev/kubeclaw\n- 发布时间： 2026年5月\n\n---\n\n项目概述\n\nKubeClaw是一个专为OpenClaw设计的Helm Chart，用于在Kubernetes集群上部署AI代理工作空间。它极大地简化了AI代理的部署流程——从原本需要配置8个以上的YAML文件，减少到仅需2个文件即可完成一个工作代理的部署。\n\nKubeClaw不仅处理基础的部署任务，还集成了命名空间管理、持久化存储、RBAC权限控制、配置生成、定时工作流等高级功能，为AI代理在Kubernetes环境中的运行提供了完整的解决方案。\n\n---\n\n核心能力\n\n1. 极简部署体验\n\nKubeClaw的设计理念是"2文件部署"：\n- HelmRelease values文件 - 定义代理配置\n- Secrets文件 - 存储敏感凭证（支持SOPS加密）\n\n提交这两个文件到Git仓库，Flux CD即可自动完成部署。\n\n2. 多通道支持\n\n代理支持通过多种聊天平台与用户交互：\n- Matrix - 去中心化即时通讯协议\n- Telegram - 流行的即时通讯应用\n- Email - 通过Mailpit轮询实现邮件通道\n- WhatsApp - 基于Baileys库实现\n- SMS - 通过Twilio实现短信交互\n\n3. 定时工作流\n\n支持CronJob形式的定时任务，可配置多步骤流水线：\n- 定时执行代理技能\n- 自动通知到指定聊天频道\n- 支持Git仓库同步\n- 步骤间上下文传递\n\n4. 多代理架构支持\n\nKubeClaw支持多种代理角色模式：\n\n| 代理类型 | 用途 | 关键配置 |\n|---------|------|---------|\n| 标准代理 | 带Git仓库和技能的开发代理 | 默认配置 |\n| 协调器 | 将任务路由到其他代理 | extraConfigMaps配置代理注册表 |\n| 编排器 | 跨命名空间工作流管理 | rbac.orchestrator.enabled: true |\n| 基础设施代理 | 集群管理员权限 | infraTools.enabled: true, rbac.clusterAdmin.enabled: true |\n\n---\n\n技术架构\n\n部署架构\n\n每个代理部署会创建以下Kubernetes资源：\n\n| 资源类型 | 名称 | 用途 |\n|---------|------|------|\n| Namespace | devpod-{name} | 隔离环境 |\n| Deployment | {name}-devpod | 代理Pod及启动脚本 |\n| Service | {name}-devpod | ClusterIP服务，端口18789 |\n| PVC | {name}-data | 持久化存储（10Gi，可选） |\n| ConfigMap | {name}-config | openclaw.json和repos.json |\n| ConfigMap | {name}-skills | 技能Markdown文件 |\n| ConfigMap | {name}-clank-task-{cli,mcp} | clank-task CLI和MCP stdio服务器 |\n| ServiceAccount | {name}-devpod | Pod身份标识 |\n| Role + RoleBinding | {name}-reader | 命名空间读取权限 |\n\n可选资源\n\n根据配置，还可能创建：\n- ClusterRoleBinding - 集群管理员权限\n- ClusterRole + ClusterRoleBinding - 编排器跨命名空间权限\n- CronJob - 工作流定时任务\n- CronJob - 邮件轮询\n- CronJob - 工作空间快照\n\n---\n\n快速开始\n\n最小配置示例\n\n一个可运行的代理只需要配置代理名称、Git仓库和密钥：\n\nyaml\nhelmrelease.yaml\napiVersion: helm.toolkit.fluxcd.io/v2\nkind: HelmRelease\nmetadata:\n name: myagent\n namespace: flux-system\nspec:\n targetNamespace: devpod-myagent\n install:\n createNamespace: true\n chart:\n spec:\n chart: .\n sourceRef:\n kind: GitRepository\n name: kubeclaw\n namespace: flux-system\n values:\n agentName: myagent\n \n image:\n repository: your-registry/openclaw\n \n git:\n repos:\n - url: \"git@github.com:yourorg/myproject.git\"\n path: \"/data/repos/myproject\"\n \n channels:\n matrix:\n homeserver: \"https://matrix.example.com\"\n \n skills:\n myagent.md: |\n My Agent\n You are a dev agent for myproject at /data/repos/myproject.\n \n existingSecret: devpod-secrets\n\n\nyaml\ndevpod-secrets.enc.yaml (SOPS加密)\napiVersion: v1\nkind: Secret\nmetadata:\n name: devpod-secrets\n namespace: devpod-myagent\nstringData:\n MATRIX_ACCESS_TOKEN: \"syt_...\"\n GITHUB_TOKEN: \"ghp_...\"\n git-ssh-key: |\n -----BEGIN OPENSSH PRIVATE KEY-----\n ...\n claude-credentials.json: |\n {\"oauth_token\": \"...\"}\n\n\n提交这两个文件并推送到Git，Flux即可部署运行中的代理。\n\n---\n\n工作流配置\n\n添加定时工作流\n\n工作流是定时执行的多步骤流水线。在HelmRelease values中添加workflows块：\n\nyaml\nworkflows:\n daily-summary:\n schedule: \"0 9 * * 1-5\" UTC时间上午9点，工作日执行\n notify:\n telegram:\n chatId: \"123456789\"\n steps:\n - name: summarize\n notify: true\n timeout: 300\n skill: |\n Summarize the latest commits in /data/repos/myproject.\n Format for Telegram, keep it under 3000 chars.\n\n\n这将为工作流创建一个CronJob，它会通过kubectl exec进入代理Pod，运行技能，并将输出发送到Telegram。\n\n工作流特性\n\n- 支持多步骤顺序执行\n- 自动Git仓库提交报告\n- 步骤间上下文变量传递\n- 可配置并发策略\n\n---\n\n配置参考\n\n核心配置\n\n| 配置项 | 默认值 | 说明 |\n|-------|--------|------|\n| agentName | 必填 | 代理名称，用于所有资源命名 |\n| image.repository | your-registry/openclaw | 容器镜像 |\n| image.tag | latest | 镜像标签 |\n| existingSecret | "" | 包含令牌和密钥的Secret名称 |\n\n代理配置\n\n| 配置项 | 默认值 | 说明 |\n|-------|--------|------|\n| agent.model.primary | anthropic/claude-sonnet-4 | Claude模型 |\n| agent.maxConcurrent | 4 | 最大并发会话数 |\n| agent.mentionPatterns | [\"@{name}\", \"{name}\"] | 聊天提及触发模式 |\n| agent.workspace | 第一个仓库路径 | 工作目录 |\n\nGit配置\n\n| 配置项 | 默认值 | 说明 |\n|-------|--------|------|\n| git.email | agent@devpod.local | 提交作者邮箱 |\n| git.name | DevPod Agent | 提交作者名称 |\n| git.repos | [] | 要克隆的仓库列表 |\n| git.autoPull.enabled | true | 后台自动拉取仓库 |\n| git.autoPull.intervalSeconds | 300 | 自动拉取间隔 |\n\n通道配置\n\n| 配置项 | 默认值 | 说明 |\n|-------|--------|------|\n| channels.matrix.enabled | true | 启用Matrix |\n| channels.telegram.enabled | false | 启用Telegram |\n| channels.email.enabled | false | 启用邮件通道 |\n| channels.whatsapp.enabled | false | 启用WhatsApp |\n| channels.sms.enabled | false | 启用SMS |\n\nMCP服务器配置\n\n| 配置项 | 默认值 | 说明 |\n|-------|--------|------|\n| mcpServers.clankTask.enabled | true | 注册clank-task-mcp stdio服务器 |\n\n网关配置\n\n| 配置项 | 默认值 | 说明 |\n|-------|--------|------|\n| gateway.http.endpoints.chatCompletions.enabled | true | 启用OpenAI兼容的/v1/chat/completions |\n| gateway.http.endpoints.responses.enabled | true | 启用OpenAI Responses API |\n\nRBAC和基础设施\n\n| 配置项 | 默认值 | 说明 |\n|-------|--------|------|\n| rbac.clusterAdmin.enabled | false | 绑定cluster-admin角色 |\n| rbac.orchestrator.enabled | false | 跨命名空间编排器ClusterRole |\n| infraTools.enabled | false | 安装kubectl、flux、sops、age |\n\n持久化配置\n\n| 配置项 | 默认值 | 说明 |\n|-------|--------|------|\n| persistence.enabled | false | 创建PVC（可选） |\n| persistence.size | 10Gi | 存储大小 |\n| persistence.storageClass | "" | 存储类（空表示默认） |\n\n资源限制\n\n| 配置项 | 默认值 | 说明 |\n|-------|--------|------|\n| resources.requests.memory | 512Mi | 内存请求 |\n| resources.requests.cpu | 250m | CPU请求 |\n| resources.limits.memory | 3Gi | 内存限制 |\n| resources.limits.cpu | 2000m | CPU限制 |\n\n---\n\n高级功能\n\n钩子（Hooks）\n\n支持Webhook路由映射，可配置外部系统集成。\n\n原始配置覆盖\n\n通过rawConfig可以完全覆盖openclaw.json配置，绕过模板生成。\n\n额外卷挂载\n\n支持通过extraVolumes和extraVolumeMounts添加自定义卷和挂载点。\n\n额外ConfigMap\n\n通过extraConfigMaps可以添加额外的ConfigMap资源。\n\n---\n\n实际应用场景\n\n场景一：开发助手\n\n部署一个连接到代码仓库的AI代理，团队成员可以通过聊天工具向代理询问代码问题、请求代码审查或生成文档。\n\n场景二：定时报告\n\n配置定时工作流，每天早上自动汇总前一天的代码提交、Issue更新，并发送到团队聊天频道。\n\n场景三：多代理协调\n\n部署协调器代理，根据任务类型将请求路由到专门的处理代理（如文档代理、代码代理、测试代理）。\n\n场景四：基础设施管理\n\n部署具有集群管理员权限的基础设施代理，允许通过聊天命令执行kubectl操作、查看Pod状态、管理Helm发布。\n\n---\n\n项目优势\n\n1. 简化部署 - 将复杂的K8s资源配置抽象为简洁的Helm values\n2. GitOps原生 - 与Flux CD等GitOps工具无缝集成\n3. 灵活扩展 - 支持多种代理角色和配置选项\n4. 安全可靠 - 支持SOPS加密、RBAC权限控制、资源限制\n5. 多平台支持 - 支持主流聊天平台和通讯协议\n6. 生产就绪 - 包含健康检查、持久化存储、自动恢复等生产级特性\n\n---\n\n总结\n\nKubeClaw为在Kubernetes上运行OpenClaw AI代理提供了一套完整、灵活、生产就绪的解决方案。无论是个人开发者想要部署一个代码助手，还是企业团队需要构建多代理协调系统，KubeClaw都能提供合适的基础设施支持。\n\n项目的Helm Chart设计充分考虑了实际运维需求，从权限管理到资源限制，从持久化存储到定时任务，涵盖了生产环境部署AI代理所需的各个方面。对于正在探索AI代理落地应用的团队来说，KubeClaw是一个值得关注的项目。