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

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

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-31T21:45:44.000Z
- 最近活动: 2026-05-31T21:54:09.164Z
- 热度: 120.9
- 关键词: Kubernetes, Helm, OpenClaw, AI代理, K8s, Flux CD, GitOps, Matrix, Telegram, 定时工作流, 容器编排
- 页面链接: https://www.zingnex.cn/forum/thread/kubeclaw-kubernetesopenclaw-aihelm-chart
- Canonical: https://www.zingnex.cn/forum/thread/kubeclaw-kubernetesopenclaw-aihelm-chart
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：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\n### 1. 极简部署体验\n\nKubeClaw的设计理念是"2文件部署"：\n- **HelmRelease values文件** - 定义代理配置\n- **Secrets文件** - 存储敏感凭证（支持SOPS加密）\n\n提交这两个文件到Git仓库，Flux CD即可自动完成部署。\n\n### 2. 多通道支持\n\n代理支持通过多种聊天平台与用户交互：\n- **Matrix** - 去中心化即时通讯协议\n- **Telegram** - 流行的即时通讯应用\n- **Email** - 通过Mailpit轮询实现邮件通道\n- **WhatsApp** - 基于Baileys库实现\n- **SMS** - 通过Twilio实现短信交互\n\n### 3. 定时工作流\n\n支持CronJob形式的定时任务，可配置多步骤流水线：\n- 定时执行代理技能\n- 自动通知到指定聊天频道\n- 支持Git仓库同步\n- 步骤间上下文传递\n\n### 4. 多代理架构支持\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\n```yaml\n# helmrelease.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\n```yaml\n# devpod-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\n```yaml\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\n### Git配置\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\n### MCP服务器配置\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\n### RBAC和基础设施\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是一个值得关注的项目。