1. 项目概述一个Kubernetes原生的AI机器人运维平台如果你和我一样在Kubernetes上跑过几个AI机器人或者自动化助手大概率会碰到一个头疼的问题管理起来太散了。每个机器人一个Helm Chart日志要看不同的Pod配置要改一堆YAML备份恢复更是手动操作毫无优雅可言。更别提安全隔离和密钥管理搞不好就是一个配置泄露或者资源争抢。我花了几个月时间就是为了解决这个痛点于是有了ClawMachine。简单说ClawMachine是一个用Go写的、Kubernetes原生的控制面板专门用来部署、监控和管理像OpenClaw这样的AI机器人。它的核心目标就一个通过一个Helm安装包和一个统一的仪表盘给你对集群里所有AI机器人的完全控制权。你不用再在各个终端和YAML文件之间反复横跳所有操作——从创建机器人、注入密钥、配置网络策略到查看实时日志、执行备份恢复——都能在一个地方搞定。而且所有东西都跑在你自己的基础设施上数据不出集群这是很多SaaS方案给不了的安全感。目前项目还处于预发布状态我自己就在重度使用它也就是所谓的“吃自己的狗粮”所以功能迭代会很快也欢迎大家一起反馈。下面我就把这个项目的设计思路、核心实现、实操细节以及我踩过的坑毫无保留地分享出来。2. 核心架构与设计哲学2.1 为什么是Kubernetes原生选择基于Kubernetes来构建ClawMachine不是追热点而是基于几个非常实际的考量。首先资源与隔离。AI机器人尤其是像OpenClaw这种多通道助手对CPU/内存的需求波动可能很大也可能会调用不同的外部服务。Kubernetes的Pod和Resource Quota机制能天然地为每个机器人提供资源隔离和限制避免一个机器人的异常行为拖垮整个节点。其次声明式配置与运维自动化。机器人的部署规格需要多少CPU/内存、挂载哪些配置文件、需要什么环境变量都可以用Kubernetes的Manifest通过Helm模板化来描述。ClawMachine的仪表盘本质上是一个生成和操作这些Manifest的友好界面。一旦定义好扩缩容、滚动更新都由Kubernetes控制器自动完成可靠性远超手动SSH操作。最后生态集成。Kubernetes庞大的生态系统意味着很多复杂问题都有现成的解决方案。比如我们用External Secrets Operator来集成1Password用NetworkPolicy来实现网络微隔离用CronJob来调度备份任务。ClawMachine不需要重复造轮子而是作为“胶水层”把这些优秀的CNCF项目组合起来形成一个针对AI机器人运维的垂直解决方案。2.2 控制平面与数据平面分离这是ClawMachine一个关键的设计决策。整个系统清晰地分为两层控制平面 (Control Plane) 就是ClawMachine自身以一个Helm Chart的形式部署在你的Kubernetes集群里。它包含API Server、前端Dashboard、控制器Controller等组件。它不运行任何用户业务逻辑只负责管理。数据平面 (Data Plane) 就是一个个具体的AI机器人实例例如一个OpenClaw机器人。每个机器人都是一个独立的Kubernetes Deployment或StatefulSet运行在独立的Pod中。这种分离的好处非常明显稳定性 即使某个机器人Pod崩溃、死循环也不会影响控制面板和其他机器人的管理。安全性 控制平面可以拥有更高的权限来管理集群资源而数据平面的机器人Pod则遵循最小权限原则通过ServiceAccount限制其权限。可扩展性 你可以轻松地横向扩展机器人实例的数量控制平面无需做任何改动。在ClawMachine的Helm Chart中你会看到两个主要的Deploymentclawmachine-controller和clawmachine-dashboard它们共同构成了控制平面。而通过Dashboard创建的每一个“Bot”都会在指定的Namespace默认为bot-bot-name中生成一套独立的Kubernetes资源。2.3 支持的机器人生态与选型建议ClawMachine设计上支持多种机器人后端目前主要聚焦三个机器人项目状态特点与适用场景个人建议OpenClaw✅ 推荐、主要支持路径功能全面的多通道如Slack, Discord, Telegram个人AI助手。社区活跃插件生态丰富。新手入门或需要强大功能的首选。它的配置模型最成熟与ClawMachine的集成度最高文档和示例也最全。IronClaw⚠️ Beta由NEAR AI用Rust编写主打隐私优先通过WASM沙箱提供更强的运行时隔离。适合对安全性和隐私有极致要求的场景。Rust带来的内存安全优势和WASM沙箱是亮点但生态和易用性还在完善中。PicoClaw⚠️ Beta轻量级Go机器人专注于健康检查、简单自动化等单一任务。适合作为辅助机器人或执行特定、简单的后台任务。资源占用极小启动速度快。注意 虽然框架支持多后端但在预发布阶段强烈建议从OpenClaw开始。它的集成最稳定我踩过的坑和提供的修复也最多。当你熟悉了整个ClawMachine的运维流程后再尝试将IronClaw或PicoClaw用于特定场景。3. 核心功能深度解析与实操要点3.1 容器与网络隔离不只是“跑起来”更要“安全地跑”很多人在本地跑机器人时不太在意隔离但一旦上Kubernetes这就是必须严肃对待的问题。ClawMachine在这方面做了两层防护。容器隔离 每个机器人Pod都配置了严格的securityContext。例如我们会设置runAsNonRoot: true禁止以root用户运行设置readOnlyRootFilesystem: true将根文件系统设为只读仅/workspace等数据目录可写定义明确的resources.limits来防止资源耗尽。这些配置都通过Helm模板固化确保每个新建的机器人都具备基本的安全基线。网络隔离核心特性 这是ClawMachine的杀手锏之一。我们利用Kubernetes的NetworkPolicy资源。在Dashboard上创建机器人时你可以为其配置一个“允许访问的域名列表”例如api.openai.com,slack.com。ClawMachine的后台控制器会根据这个列表自动生成并应用一个NetworkPolicy。这个Policy默认采用“拒绝所有出口流量”的白名单模式。只有目的地址是你在列表中指定的域名解析为CIDR块的流量才会被放行。这意味着即使机器人被注入恶意代码它也无法随意扫描内网或连接外部未知服务器极大地减少了攻击面。实操心得 配置网络策略时一定要用clawmachine doctor命令或Dashboard的“网络检查”功能验证你的域名列表是否正确。我曾经因为漏掉了某个API所需的子域名比如oauth2.googleapis.com导致机器人认证失败排查了半天。建议先用一个宽松的策略如允许所有出口让机器人跑通流程通过Pod日志观察它实际访问了哪些地址再逐步收紧策略。3.2 密钥管理与1Password的无缝集成让AI机器人访问OpenAI API、Slack Bot Token等敏感信息传统做法是把密钥写在环境变量或配置文件里这非常不安全。ClawMachine选择了与1Password通过External Secrets Operator (ESO)集成。工作原理你在1Password中创建一个Vault例如叫AI-Bots在里面以Secure Note或Password条目形式保存你的密钥。在ClawMachine Dashboard上配置1Password连接需要Service Account Token和Vault ID。创建机器人时你可以从下拉菜单中选择需要注入的1Password条目。ClawMachine会创建一个ExternalSecretCRD资源。ESO控制器监听到这个资源会去1Password拉取对应的密钥值。ESO将拉取到的密钥值在Kubernetes中创建为一个标准的Secret资源。机器人的Deployment配置中通过envFrom或volumeMount引用这个KubernetesSecret。整个过程密钥的明文从未出现在你的Git仓库、Helm Chart值文件或CI/CD系统中。只有Kubernetes集群内的ESO有权限从1Password读取并且最终的Secret也是加密存储在etcd中的。注意事项 确保你的Kubernetes集群所在网络能够访问1Password的API端点https://api.1password.com。对于私有集群可能需要配置出口网关或代理。另外定期轮换1Password的Service Account Token也是一个好习惯。3.3 自动化备份与恢复给机器人的“记忆”上保险AI机器人往往有状态比如OpenClaw的对话历史、知识库索引等这些数据通常保存在Pod内的一个持久化卷比如/workspace中。如果Pod被意外删除这些“记忆”就丢失了。ClawMachine内置了基于S3的自动化备份方案。备份流程你在Dashboard上为机器人启用备份并配置S3的Bucket、区域和认证信息同样推荐通过1Password管理S3密钥。ClawMachine会为该机器人创建一个KubernetesCronJob。这个Job会定期例如每天凌晨2点运行一个备份容器。备份容器内会执行打包命令如tar -czf将/workspace目录压缩然后通过aws-cli或rclone上传到指定的S3路径。路径名通常包含机器人名和日期戳便于版本管理。你可以在Dashboard上看到每次备份的状态和记录。恢复流程“大脑移植” 这是非常酷的功能。当你要重建一个机器人或者想把它迁移到新版本时在创建或更新机器人的配置页找到一个“从备份恢复”的复选框。勾选后你可以选择一个时间点的备份快照。ClawMachine会在机器人Pod的初始化容器Init Container阶段先执行恢复操作从S3下载对应的备份包解压到/workspace目录然后再启动主容器。机器人醒来后就能接上之前的“记忆”用户几乎无感知。踩坑记录 备份恢复功能对持久化卷的类型有要求。最初我仅测试了hostPath但在云环境的ReadWriteManyPVC上失败了原因是Init Container和主容器对同一PVC的挂载模式冲突。后来改为在Job中使用一个sidecar容器先挂载PVC完成恢复主容器启动后再同步数据才解决了这个问题。如果你使用动态PVC务必在ClawMachine的配置中指明StorageClass和访问模式。3.4 实时遥测与运维界面告别kubectl logsDashboard提供的实时运维能力极大提升了效率Pod日志流 直接查看机器人容器的标准输出和错误日志支持自动滚动和关键字高亮。再也不用开多个终端执行kubectl logs -f了。资源监控 直观看到每个机器人Pod的CPU、内存实时使用量以及设定的Limit。对于调试性能问题或优化资源分配非常有用。网络流量可视化 集成类似kube-ovn或ciliumHubble的轻量级视图可以图形化看到Pod当前的网络连接情况辅助调试NetworkPolicy。CLI访问 对于高级调试Dashboard提供了“执行命令”功能背后是kubectl exec可以快速进入容器内部执行诊断命令。配置与健康状态总览 所有环境变量、挂载卷、健康检查探针的配置一目了然。4. 从零开始部署与配置实战4.1 前期准备与集群健康检查在运行安装脚本之前你需要一个可用的Kubernetes集群。可以是本地的minikube、kind也可以是云上的EKS、GKE、AKS。确保你的kubectl已经正确配置能连接到目标集群。第一步强烈建议运行健康检查# 使用ClawMachine CLI的doctor命令 clawmachine doctor这个命令会检查以下项目并给出修复建议Kubernetes集群版本是否兼容1.24。kubectl上下文和权限是否足够需要cluster-admin或等效权限。必要的CRD如externalsecrets.external-secrets.io是否已安装。集群的StorageClass是否配置了默认值用于备份的临时卷。节点资源是否充足。如果doctor命令报错请根据提示先解决问题。最常见的两个问题是权限不足和缺少ESO CRD。安装ESO可以参照其官方文档通常也是一条Helm命令helm repo add external-secrets https://charts.external-secrets.io helm install external-secrets external-secrets/external-secrets -n external-secrets --create-namespace4.2 一键安装与控制平面初始化当集群状态健康后安装就非常简单了# 下载安装脚本并执行安装 curl -fsSL https://theclawmachine.dev/install.sh | bash clawmachine install --namespace claw-machine安装脚本会自动下载对应你操作系统和架构的clawmachineCLI工具。clawmachine install命令会创建指定的命名空间claw-machine。添加ClawMachine的Helm仓库。使用一份默认的values.yaml安装Helm Chart。安装完成后需要将控制面板的服务端口转发到本地才能访问kubectl port-forward -n claw-machine svc/clawmachine-dashboard 8080:80现在打开浏览器访问http://localhost:8080你就会看到初始化设置向导。初始化向导关键步骤管理员账户设置 创建第一个管理员用户和密码。这个账户信息会以Secret形式存储在集群内用于Dashboard的Basic认证。1Password集成配置 输入你的1Password服务账号凭证和Vault ID。这一步非必须但强烈建议配置它是安全密钥管理的基础。默认存储类设置 选择用于机器人数据持久化和备份作业的StorageClass。网络策略默认模式 选择创建机器人时是否默认启用严格的出口网络策略。完成向导后核心控制平面就就绪了。你可以通过kubectl get pods -n claw-machine看到clawmachine-controller-xxx和clawmachine-dashboard-xxx两个Pod在运行。4.3 部署你的第一个OpenClaw机器人现在我们进入最激动人心的环节通过Dashboard部署一个机器人。创建机器人 在Dashboard点击“New Bot”选择“OpenClaw”作为模板。基础配置Name:my-personal-assistant(这也会是Kubernetes命名空间的一部分如bot-my-personal-assistant)。Resource Limits: 根据你的集群情况设置。对于测试CPU: 500m,Memory: 512Mi是个不错的起点。Limit一定要设这是保证集群稳定的关键。镜像版本 选择稳定的OpenClaw镜像Tag如latest-stable。密钥注入在“Secrets”部分点击“Add from 1Password”。系统会列出你之前配置的Vault中的条目。选择你存放了OPENAI_API_KEY和SLACK_BOT_TOKEN的条目。ClawMachine会自动识别条目中的字段并将其映射为Pod内的环境变量如OPENAI_API_KEY。网络策略启用“Enable Network Policy”。在“Allowed Egress Domains”中添加这个机器人需要访问的外部服务域名例如api.openai.com slack.com hooks.slack.com持久化与备份启用“Persistent Workspace”。启用“Automated Backups”配置S3信息同样建议从1Password选择和备份频率如0 2 * * *表示每天凌晨2点。高级配置 你可以在这里以YAML格式提供OpenClaw特有的配置文件如config.yaml它会被挂载到容器内的指定路径。点击“Deploy”Dashboard背后会生成一系列Kubernetes资源Namespace, ServiceAccount, Deployment, Service, NetworkPolicy, PersistentVolumeClaim, CronJob, ExternalSecret等并提交到集群。稍等片刻你就能在机器人列表页看到它的状态变为“Running”并可以点击进入详情页查看日志、监控资源了。5. 日常运维、问题排查与进阶技巧5.1 监控与日志分析实战机器人运行起来后日常运维主要靠Dashboard。看日志定位启动失败 如果Pod状态不是“Running”首先进入“Logs”标签页。常见的启动错误有镜像拉取失败 网络问题或镜像Tag不存在。检查镜像仓库可达性。密钥注入失败 日志中可能出现“required environment variable XXX not set”。这通常是ExternalSecret没有成功创建出Kubernetes Secret。去bot-name命名空间下用kubectl get externalsecret,secret检查并查看ESO控制器的日志。配置文件错误 OpenClaw的config.yaml格式错误。日志会给出具体的解析错误行。利用资源监控做容量规划 在“Metrics”标签页观察机器人运行一段时间后的CPU/内存使用曲线。如果内存使用持续接近Limit可能会导致OOMKill如果CPU使用率长期很低可以考虑调低Request以节省集群资源。这是进行资源限额优化的直接依据。5.2 常见问题排查速查表问题现象可能原因排查步骤机器人创建后一直Pending1. 集群资源不足。2. PVC无法绑定StorageClass问题。3. 不满足NodeSelector/Affinity。1.kubectl describe pod -n bot-name查看事件。2.kubectl get pvc -n bot-name检查PVC状态。3. 检查节点资源kubectl describe nodes。Pod状态为CrashLoopBackOff1. 应用启动错误如配置错误。2. 依赖服务不可达网络策略过严。3. 初始化容器失败备份恢复失败。1. 查看Pod日志关注最后崩溃前的错误信息。2.kubectl exec进入Pod手动测试网络连通性curl,nslookup。3. 检查初始化容器的日志kubectl logs pod-name -c init-restore。机器人无法连接外部API如OpenAI1. NetworkPolicy阻止了出口。2. 节点或集群出口网络故障。3. API密钥错误。1. 检查Pod的NetworkPolicy配置确认目标域名在允许列表中。2. 在Pod内执行curl -v https://api.openai.com。3. 检查注入的Secret值是否正确。Dashboard无法访问1Password或S31. 控制平面Pod的网络策略或节点网络限制。2. 1Password/S3的API令牌过期或权限不足。3. 外部DNS解析问题。1. 检查claw-machine命名空间下控制平面Pod的日志。2. 在1Password/S3控制台验证令牌权限。3. 在控制平面Pod内测试网络连通性。备份任务执行失败1. S3凭证错误或权限不足。2. 备份容器镜像拉取失败。3. PVC空间不足。1. 查看CronJob对应Job的日志kubectl logs jobs/job-name -n bot-name。2. 检查S3 Bucket策略。3. 检查备份Pod的Events。5.3 升级、备份恢复与“大脑移植”升级ClawMachine控制平面clawmachine upgrade这个命令会拉取最新的Helm Chart并执行升级。升级前建议使用clawmachine backup为所有重要机器人手动触发一次备份。升级过程通常是滚动更新不影响已有机器人的运行。手动触发备份与恢复备份clawmachine backup --bot bot-name或在Dashboard上点击对应机器人的“Backup Now”按钮。恢复 在Dashboard上编辑机器人配置勾选“Restore from Backup”并选择备份点。这本质上会触发一次Deployment的重建。“大脑移植”实战 假设你想把机器人bot-alpha的数据迁移到一个使用新版本镜像的机器人bot-beta上。确保bot-alpha的备份是最新的。在Dashboard创建bot-beta在“Advanced Configuration”中使用与bot-alpha相同的应用配置但镜像Tag用新的。在“Backup”设置中启用恢复并选择bot-alpha的最新备份快照。部署bot-beta。启动后它就会拥有bot-alpha的全部工作区数据。验证bot-beta运行无误后可以下线bot-alpha。5.4 进阶配置与调优自定义Helm Values 对于生产部署你应该使用自定义的values.yaml文件来安装ClawMachine而不是全部用默认值。关键配置项包括# custom-values.yaml dashboard: ingress: enabled: true className: nginx hosts: - host: clawmachine.yourcompany.com paths: - path: / pathType: Prefix # 启用更严格的认证如OIDC # authProxy: ... controller: resources: requests: memory: 128Mi cpu: 100m limits: memory: 256Mi cpu: 500m # 配置默认的StorageClass global: storageClass: fast-ssd然后使用clawmachine install -f custom-values.yaml --namespace claw-machine进行安装。资源配额与限制 在集群层面建议为每个bot-开头的命名空间设置KubernetesResourceQuota防止某个机器人失控消耗过多集群资源。这可以通过ClawMachine的准入控制Webhook未来实现目前需要手动或通过GitOps工具配置。集成外部监控 Dashboard内置了基础监控但对于生产环境建议将机器人的指标暴露给Prometheus。可以在机器人的Helm模板中添加prometheus.io/scrape: true等注解并配置好ServiceMonitor让集群级的Prometheus能够抓取数据并在Grafana中制作更丰富的仪表盘。6. 开发与贡献指南如果你对ClawMachine本身如何工作感兴趣或者想为其添加对新类型机器人的支持可以参与到开发中来。项目使用Go编写前端是React通过Go的embed功能打包。本地开发环境搭建确保安装了版本管理工具mise类似asdf。克隆项目后运行mise trust mise install它会自动安装项目所需的Go、Node.js等特定版本。mise run charts用于将Helm Chart打包供Go代码嵌入。mise run test运行Go单元测试。mise run docs:serve可以在本地启动文档网站。架构概览cmd/ CLI入口点。internal/controller/ Kubernetes控制器负责监听Bot CRD并调和实际资源。internal/dashboard/ 前端React应用和后端API服务器。charts/ ClawMachine自身的Helm Chart和Bot的Helm Chart模板。pkg/ 共享库如Kubernetes客户端封装、1Password/S3客户端等。添加一个新的机器人类型主要工作是在charts/bot-templates/下创建一个新的Helm Chart子目录。在internal/controller/bot_types.go中定义新的Bot类型常量。在控制器中为该类型添加特定的资源生成逻辑如Deployment、Service等的模板渲染。在前端internal/dashboard/src/components/中添加对应的创建表单和展示组件。开发中最常打交道的就是Kubernetes的client-go库和Helm的渲染引擎。调试时我强烈建议使用Telepresence或kubectl port-forward将本地开发的控制器连接到远程集群进行测试而不是每次都在本地启动一个完整的KinD集群。最后无论是遇到Bug、有功能建议还是只是想讨论一下AI机器人在K8s上的最佳实践都欢迎在GitHub上提交Issue或发起Discussion。这个项目的目标就是让复杂的事情变简单而社区的反馈是让它变得更好的最快途径。