1. 项目概述如果你正在寻找一种能像管理容器一样轻松管理成百上千个AI智能体Bot的方法那么ClawHost很可能就是你需要的那个“瑞士军刀”。简单来说ClawHost是一个基于Kubernetes的原生平台专门用于编排和管理OpenClaw AI智能体实例。它把一个复杂的、需要处理多租户、网络代理、技能管理和生命周期维护的AI Bot部署问题抽象成了一组简洁的RESTful API。你只需要调用几个接口就能在K8s集群里创建、启动、停止一个功能完整的AI Bot并且让它通过子域名直接对外提供服务整个过程无需手动编写任何YAML文件或配置复杂的Ingress规则。这个项目的核心价值在于“降本增效”。对于AI应用开发者或中小型团队而言自建一套稳定、可扩展的Bot托管平台门槛很高涉及到资源调度、网络隔离、数据持久化、状态监控等一系列繁琐工作。ClawHost把这些脏活累活都打包了让你能专注于Bot的业务逻辑本身。无论是想为每个用户部署一个专属的AI助手还是需要快速拉起一批Bot进行A/B测试ClawHost都能提供一套标准化的、云原生的解决方案。它特别适合那些已经在使用或计划使用OpenClaw框架并希望将其服务化、产品化的团队。2. 架构设计与核心思路拆解2.1 为什么选择Kubernetes原生ClawHost的基石是Kubernetes这个选择背后有深刻的工程考量。首先资源隔离与安全性是首要目标。每个Bot作为一个独立的Pod运行拥有自己的进程空间、文件系统和网络栈。这意味着一个Bot的崩溃或资源泄露不会影响到其他Bot从底层保障了多租户环境下的稳定性。其次Kubernetes提供了强大的声明式API和控制器模式。ClawHost本质上是一个自定义控制器Controller它监听数据库中的Bot期望状态Desired State然后通过K8s API去驱动集群的实际状态Actual State向其靠拢。例如当你通过API请求启动一个Bot时ClawHost会在数据库中将其状态标记为“启动中”然后创建对应的K8s Deployment和Service。K8s的调度器会自动为这个Pod寻找合适的节点并确保其持续运行。这种模式将复杂的运维逻辑如健康检查、故障恢复、滚动更新委托给了K8s极大地简化了ClawHost自身的代码复杂度。另一个关键优势是弹性和可扩展性。Kubernetes集群可以轻松地水平扩展节点ClawHost管理的Bot可以随之分布到更多机器上天然支持大规模部署。同时利用K8s的Resource Quota和LimitRange可以精确控制每个Bot所能使用的CPU、内存和存储资源实现精细化的成本控制。最后生态集成也是一大亮点。日志收集Fluentd、监控Prometheus、服务网格Istio等云原生工具链可以直接应用于这些Bot Pod为运维提供了极大的便利。2.2 核心架构中心化管控与边缘执行ClawHost的架构清晰地分为控制平面和数据平面。控制平面就是ClawHost服务本身它包含了管理API、代理网关和Admin UI。它不运行在K8s集群内部也可以只需要能通过kubeconfig访问集群API即可。这种设计分离了管控和运行使得ClawHost服务本身可以独立升级、维护而不影响正在运行的Bot。数据平面则是K8s集群内部运行的各个OpenClaw Bot Pod。每个Pod都是一个完整的、隔离的OpenClaw实例。ClawHost通过为每个Bot创建独立的K8s Service为其分配了一个稳定的集群内部网络标识。而对外暴露服务的关键在于其智能代理Proxy和子域名路由机制。ClawHost内置的HTTP/WebSocket代理会拦截所有进入的请求根据请求的Host头即子域名如my-bot.clawhost.loc或路径中的Bot ID将流量精准地转发到对应Bot的Service上。这意味着你不需要为成百上千个Bot配置成百上千个Ingress规则一个统一的入口点解决了所有路由问题。数据库默认PostgreSQL作为唯一的状态存储中心记录了所有App、Bot的元数据、配置和状态。Bot Pod在启动时会从数据库通过ClawHost API拉取自己的最新配置运行时的部分状态变更也会同步回数据库。这种双向同步确保了状态的一致性即使ClawHost服务重启也能恢复所有Bot的管理上下文。2.3 多租户与资源隔离策略“多租户”是ClawHost的核心特性之一它通过“应用App”这个概念来实现逻辑隔离。每个租户可以是一个团队、一个客户或一个产品线首先创建一个App并获得一个唯一的API Token。此后该租户所有Bot的创建、管理操作都必须使用这个Token进行认证。在数据库层面所有Bot记录都通过app_id字段归属于其创建者。在API层面ClawHost会严格校验Token对应的App确保一个租户只能操作自己名下的Bot无法看到或影响到其他租户的资源。在物理资源层面隔离则由Kubernetes保证。每个Bot Pod是独立的但为了节省资源所有Bot可以共享一个持久化存储卷PVC来存放模型文件、缓存等只读数据。对于需要写入的Bot个人数据则可以通过Pod内的临时存储或挂载子路径到共享PVC来实现。这种“共享只读隔离读写”的策略在保证隔离性的同时也优化了存储利用率和Bot的启动速度。3. 核心功能模块深度解析3.1 Bot全生命周期管理ClawHost对Bot生命周期的管理堪称“无微不至”覆盖了从出生到“退休”的每一个环节。创建与配置创建Bot时除了基本的名称、标识符slug外最关键的是其config字段。这里可以指定AI模型提供商如OpenAI、Anthropic Claude、API密钥、系统提示词、初始技能等。ClawHost并不存储你的敏感API Key而是将其作为环境变量注入到Bot的Pod中。一个设计精妙之处在于Bot的配置是动态可更新的。你可以通过PUT API随时修改Bot的配置ClawHost会将这些变更同步到运行中的Pod通常需要重启Bot生效这为在线调试和A/B测试提供了可能。启动与运行/startAPI是一个关键操作。它触发的不仅仅是一个kubectl run命令。ClawHost会检查Bot配置的有效性。生成一个包含所有配置和环境变量的K8s Deployment定义。为这个Deployment创建一个同名的Service作为集群内访问入口。在数据库中更新Bot状态为“运行中”并记录其K8s资源名称。等待Pod进入Ready状态并可能执行一些健康检查。状态监控与连接/statusAPI返回的不仅仅是“运行中”或“已停止”。它会通过K8s API实时查询Pod的状态ContainerCreating、Running、Error、重启次数、资源使用情况如果配置了Metrics Server等给你一个真实的运行视图。/connectAPI则返回该Bot的访问信息主要是其子域名地址这是用户或前端应用连接Bot的直接入口。停止与清理/stop操作会删除Bot对应的K8s Deployment和Service释放计算资源但保留数据库中的Bot记录和PVC中的持久化数据。这相当于“休眠”可以随时再次启动。而/delete操作则更彻底除了删除K8s资源还会将数据库中的记录标记为“已删除”软删除但根据数据保留策略记录可能仍会保留一段时间以供审计或恢复。3.2 技能Skills的动态管理OpenClaw的强大之处在于其可扩展的技能系统而ClawHost通过API将这个能力暴露了出来。技能可以理解为Bot的“插件”或“工具”比如“查询天气”、“发送邮件”、“操作数据库”等。ClawHost提供了对Bot技能的CRUD接口。这意味着你可以在Bot运行期间动态地为它添加、移除或更新技能而无需重新构建或部署Bot镜像。其实现原理是ClawHost将技能配置通常是技能的名称、参数、执行代码的URL或路径通过API写入数据库。Bot Pod内有一个Sidecar容器或主容器中的守护进程会定期或通过Webhook从ClawHost拉取最新的技能列表并加载到OpenClaw的核心运行时中。这种动态管理带来了极大的灵活性。例如你可以开发一个“数据分析”技能先部署到测试环境的Bot上进行验证验证通过后通过ClawHost API一键批量推送到所有生产环境的Bot中。它也使得技能市场或用户自定义技能成为可能用户可以通过UI选择技能后端调用ClawHost API即可完成绑定。3.3 IM通道与设备配对让AI Bot接入到日常使用的通讯工具如Telegram、Slack、钉钉是使其发挥价值的关键。ClawHost集成了OpenClaw的IM通道连接能力并提供了管理API。通道管理通过/channelsAPI你可以为一个Bot添加多个IM通道配置。每个配置包含了该通讯平台所需的凭证如Bot Token、App Secret、Webhook URL等。ClawHost会将这些配置传递给Bot Pod由Pod内的OpenClaw实例去实际建立和维护长连接或设置Webhook。设备配对这是针对某些需要端到端加密或设备级授权的场景如一些移动端IM应用。当新设备尝试连接Bot时会产生一个配对请求。ClawHost的API允许管理员查看 (/pairing) 待处理的请求并手动批准 (/approve) 或拒绝 (/revoke)。更酷的是它还支持自动审批规则例如可以配置为信任来自特定组织邮箱的请求自动通过这大大减少了运维负担。用户管理/pairing/usersAPI可以列出所有已与该Bot配对的用户/设备列表。这不仅是简单的列表更是进行用户行为分析、权限管控和提供支持服务的基础。3.4 模型提供商与代理配置大模型生态百花齐放ClawHost在设计上就支持了多模型提供商。在Bot的配置中model字段指定了默认使用的模型。但通过/config/models系列API你可以为单个Bot配置多个备用的模型提供商。例如一个Bot可以同时配置OpenAI的GPT-4、Anthropic的Claude 3以及国内的通义千问。在OpenClaw内部可以根据请求的上下文、成本或性能策略动态选择使用哪个提供商。ClawHost负责安全地存储这些提供商的API密钥以K8s Secret方式注入并在Bot配置更新时将其同步到运行环境。代理Proxy层是ClawHost网络架构的智慧核心。它承担了三个主要职责路由根据子域名或路径将请求分发到正确的Bot Service。负载均衡与高可用如果一个Bot有多个副本Pod通过Deployment的replicas设置Proxy会将流量负载均衡到这些Pod上。统一入口与安全边界所有外部流量都经过Proxy可以在这里统一实施认证、限流、日志记录和SSL/TLS终止而不需要在每个Bot中重复实现。4. 从零开始的完整部署与实操指南4.1 环境准备与前置条件在动手部署之前你需要确保以下环境就绪。这是后续所有操作的基础。Kubernetes集群这是硬性要求。你有多种选择本地开发推荐使用OrbStackmacOS或Docker Desktop内置K8s。它们提供了轻量级、一键启用的K8s环境非常适合开发和测试。确保K8s版本在1.28及以上。云服务对于生产环境可以选择阿里云ACK、腾讯云TKE、华为云CCE或AWS EKS等托管K8s服务。它们负责管理控制平面你只需关注节点和工作负载。自建集群可以使用kubeadm、k3s、RKE等工具在自有服务器上搭建。验证集群kubectl cluster-info和kubectl get nodes应返回正常信息。命令行工具kubectl必须安装且版本与集群版本兼容±1个小版本。helm(v3)如果选择Helm安装方式则需要安装。Helm能极大简化复杂应用的部署。docker或podman用于本地构建ClawHost镜像。网络与DNS考虑生产环境这是让子域名路由生效的关键。你需要一个公网域名例如your-company.com。将该域名的泛域名解析*.bots.your-company.com指向你K8s集群的Ingress Controller或LoadBalancer的公网IP。在ClawHost配置中将domain.botDomain设置为bots.your-company.com。对于本地开发后文会介绍如何使用Caddy和hosts文件模拟这一环境。4.2 方案选择Helm vs. kubectl vs. 二进制ClawHost提供了三种部署方式适用于不同场景。方案AHelm安装生产推荐这是最完整、最自动化的一键部署方案。Helm Chart不仅部署ClawHost本身还包括了PostgreSQL数据库、所需的RBAC权限、PersistentVolumeClaim以及自动清理的CronJob。# 1. 克隆代码并构建镜像 git clone https://github.com/fastclaw-ai/clawhost.git cd clawhost docker build -t your-registry/clawhost:latest . # 2. 推送镜像到你的容器仓库可选生产环境必须 docker push your-registry/clawhost:latest # 3. 使用Helm部署 helm install clawhost deploy/helm/clawhost \ -n clawhost --create-namespace \ --set adminToken一个强密码 \ --set server.image.repositoryyour-registry/clawhost \ --set domain.botDomainbots.your-company.com注意adminToken是访问Admin UI和管理API的根密钥务必使用强密码并妥善保存。生产环境务必替换默认的镜像仓库和标签。方案Bkubectl直接部署理解组件这种方式更适合学习或深度定制因为它让你清晰地看到每一个部署的K8s资源对象。你需要按顺序应用deploy/k8s/目录下的YAML文件。关键步骤是编辑secrets.yaml填入你的敏感信息如数据库密码、Admin Token。# 创建命名空间和RBAC kubectl apply -f deploy/k8s/namespace.yaml kubectl apply -f deploy/k8s/rbac.yaml kubectl apply -f deploy/k8s/pvc.yaml # 创建密钥先复制并编辑示例文件 cp deploy/k8s/secrets.yaml.example deploy/k8s/secrets.yaml # 使用vim或nano编辑secrets.yaml填入真实值 kubectl apply -f deploy/k8s/secrets.yaml # 部署数据库和应用 kubectl apply -f deploy/k8s/postgres.yaml kubectl apply -f deploy/k8s/configmap.yaml kubectl apply -f deploy/k8s/deployment.yaml这种方式让你对ClawHost依赖的每个组件ServiceAccount, Role, ConfigMap, Secret, Deployment, Service都有直观的认识。方案C本地二进制运行开发调试首选如果你主要在本地开发ClawHost功能或调试集成问题在宿主机直接运行二进制是最快捷的方式。它不需要在K8s里部署ClawHost本身只需要一个能连上的K8s集群和一个PostgreSQL实例。# 1. 构建 make build # 或分别构建前端和后端 # 2. 启动一个PostgreSQL容器 docker run -d --name clawhost-pg -e POSTGRES_PASSWORDpostgres -p 5432:5432 postgres:16 # 3. 在K8s中创建命名空间和存储声明用于Bot数据 kubectl create ns clawhost kubectl apply -f deploy/k8s/pvc.yaml # 4. 复制并编辑配置文件关键设置 # [kubernetes] local_dev true # 使用ClusterIP方便宿主机直接访问Pod # [api] admin_token dev-token cp config.example.toml config.toml vim config.toml # 5. 运行 ./clawhost server这种方式下ClawHost运行在你本地通过~/.kube/config连接K8s集群通过本地端口5432连接数据库。非常适合进行代码修改、热重载和调试。4.3 配置详解与调优建议ClawHost的配置主要通过config.toml文件或Helm的values.yaml进行。理解关键配置项对稳定运行至关重要。数据库配置[database] host postgres.clawhost.svc.cluster.local # K8s内服务名 port 5432 user postgres password # 通常通过环境变量或Secret注入 name clawhost sslmode disable # 生产环境应设为 require 或 verify-full生产建议对于重要生产环境强烈建议使用云托管的RDS或Aurora PostgreSQL而不是Chart内置的PostgreSQL。它们提供自动备份、高可用和性能监控。在Helm中设置postgresql.enabledfalse并配置externalDatabase参数。Kubernetes配置[kubernetes] namespace clawhost # Bot Pod将被创建到的命名空间 service_account clawhost # ClawHost使用的ServiceAccount local_dev false # 本地开发时设为true使用ClusterIP资源限制在Helm的values.yaml中openclaw.cpuLimit和openclaw.memoryLimit定义了每个Bot Pod的默认资源上限。务必根据你选择的OpenClaw镜像和模型加载需求来合理设置。设置过低会导致Bot OOM被杀过高则浪费资源。Bot配置[bot] image 1panel/openclaw:latest # 默认Bot镜像 cleanup_grace_hours 72 # Bot过期后数据保留多久再清理 cleanup_batch_size 50 # 每次清理任务处理的最大Bot数量镜像选择1panel/openclaw:latest是官方示例镜像。在实际生产中你应该构建自己的OpenClaw镜像包含你自定义的技能、前端界面和预加载的模型。清理策略cleanup_grace_hours提供了一个“宽限期”防止因误操作或临时需求导致立即删除。你可以根据业务需求调整。网络与域名配置[domain] bot_domain_suffix bots.your-company.com这是子域名路由的核心。确保你的DNS和Ingress控制器如Nginx Ingress配置正确能够将*.bots.your-company.com的流量路由到ClawHost的Service。4.4 创建第一个Bot从API调用到实际访问假设你已经通过Helm或二进制方式成功启动了ClawHost服务假设服务地址为http://localhost:18080并拿到了adminToken例如my-admin-token。现在让我们创建一个完整的Bot。步骤1创建应用App应用是租户隔离的单元。每个应用有一个唯一的API Token用于创建和管理其下的所有Bot。curl -X POST http://localhost:18080/bot/api/v1/admin/apps \ -H Authorization: Bearer my-admin-token \ -H Content-Type: application/json \ -d { name: 我的第一个AI应用 }保存返回的JSON中的api_token字段例如app_abc123...。后续所有对该应用下Bot的操作都将使用这个Token。步骤2使用应用Token创建Bot现在我们以这个应用管理员的身份创建一个Bot。注意这里我们指定了用户ID、Bot名称、唯一标识符slug以及最重要的AI配置。export APP_TOKENapp_abc123... curl -X POST http://localhost:18080/bot/api/v1/bots \ -H Authorization: Bearer $APP_TOKEN \ -H Content-Type: application/json \ -d { user_id: alice, name: Alice的私人助手, slug: alice-assistant, config: { model: claude-3-opus-20240229, # 使用的模型 api_key: sk-ant-..., # Claude API KeyClawHost会安全处理 system_prompt: 你是一个乐于助人且专业的助手。, # 系统提示词 max_tokens: 4096 } }创建成功后会返回Bot的详细信息包括一个唯一的id。保存这个ID。步骤3启动Bot创建Bot只是定义了它的“蓝图”启动操作才会在K8s中实际创建Pod。export BOT_IDbot_xyz789... curl -X POST http://localhost:18080/bot/api/v1/bots/$BOT_ID/start \ -H Authorization: Bearer $APP_TOKEN这个调用是异步的。ClawHost会向K8s API提交创建Deployment和Service的请求然后立即返回。你可以通过状态查询接口来了解启动进度。步骤4检查状态与获取连接信息# 查询详细状态 curl http://localhost:18080/bot/api/v1/bots/$BOT_ID/status \ -H Authorization: Bearer $APP_TOKEN # 获取连接信息主要是访问域名 curl http://localhost:18080/bot/api/v1/bots/$BOT_ID/connect \ -H Authorization: Bearer $APP_TOKEN/connect接口会返回类似{domain: alice-assistant.bots.your-company.com}的信息。这就是访问这个Bot的入口。步骤5访问你的Bot根据你的部署环境访问方式不同生产环境配置了Ingress和DNS直接在浏览器中打开https://alice-assistant.bots.your-company.com。本地开发使用Caddy配置好Caddy和hosts后访问https://alice-assistant.clawhost.loc。直接通过Proxy路径访问你也可以通过ClawHost的Proxy路径直接访问http://localhost:18080/proxy/$BOT_ID/。这在你不想或无法配置子域名时非常有用。现在你应该能看到OpenClaw的Web界面并可以开始与你的AI助手对话了。4.5 本地开发环境搭建Caddy与子域名路由为了让本地开发的体验接近生产环境使用子域名我们需要解决两个问题1) 本地DNS解析2) HTTPS和请求转发。使用Caddy作为反向代理Caddy能自动管理TLS证书即使是本地证书并处理泛域名代理。安装Caddybrew install caddy(macOS) 或参考其官网。在项目根目录创建Caddyfile# 处理API请求 clawhost.loc:18080 { tls internal # 使用Caddy内部生成的证书 reverse_proxy localhost:18080 } # 处理所有Bot子域名的请求 *.clawhost.loc:18080 { tls internal reverse_proxy localhost:18080 }启动Caddycaddy run。Caddy会自动监听18080端口并为clawhost.loc和*.clawhost.loc签发本地可信的HTTPS证书。配置本地DNS解析/etc/hosts文件不支持通配符*。有几种解决方案方案A简单需手动添加每次创建新Bot时手动在/etc/hosts里添加一行如127.0.0.1 alice-assistant.clawhost.loc。这很麻烦。方案B推荐使用dnsmasq安装dnsmasq将其配置为将.loc域名的所有请求指向127.0.0.1。这样任何*.clawhost.loc都会解析到本地。# macOS 安装 brew install dnsmasq # 配置 echo address/.loc/127.0.0.1 /usr/local/etc/dnsmasq.conf sudo brew services start dnsmasq # 将系统DNS服务器设置为127.0.0.1网络设置中方案CmacOS OrbStack如果你使用OrbStack它提供了一个神奇的域名*.orb.local。你可以直接将ClawHost配置中的bot_domain_suffix改为orb.local然后任何xxx.orb.local都会自动解析到OrbStack的网关再由它转发到你的服务。这是最无缝的体验。完成以上设置后你就能在本地通过https://alice-assistant.clawhost.loc访问你的Bot了并且拥有有效的HTTPS证书。5. 生产环境部署、运维与故障排查5.1 高可用与可扩展性部署对于生产环境单点的ClawHost服务和数据库是无法接受的。我们需要考虑高可用HA部署。ClawHost服务本身的无状态化与水平扩展ClawHost的API服务是无状态的所有状态都存储在PostgreSQL中。因此实现高可用非常简单只需部署多个ClawHost Pod副本并通过一个K8s Service类型为ClusterIP或LoadBalancer对外暴露。使用Deployment设置replicas: 3K8s会自动保证副本数量。Ingress控制器如Nginx Ingress可以将流量负载均衡到这些副本上。确保你的config.toml中关于数据库连接池的配置足够应对多个实例的连接。PostgreSQL数据库高可用这是整个系统的核心。有几种方案使用云托管数据库服务如AWS RDS Multi-AZ、Google Cloud SQL High Availability、阿里云RDS主备版。它们提供了自动故障转移、备份和读写分离是最省心的选择。在Helm Chart中禁用内置PostgreSQL配置externalDatabase指向云服务。使用K8s Operator自建如PostgreSQL Operator by Zalando或Crunchy Data PostgreSQL Operator。这些Operator能在K8s集群内自动化地部署和管理高可用的PostgreSQL集群包括备份、监控和故障恢复。Chart内置PostgreSQL仅限测试Helm Chart内置的bitnami/postgresql支持主从复制可以通过设置architecture: replication开启。但这需要你自行管理持久化存储的高可用对于严肃的生产环境仍显不足。有状态数据PVC的存储类选择Bot的持久化数据共享PVC需要高可用的存储。在K8s中这通过StorageClass实现。在云环境中选择支持ReadWriteManyRWM访问模式的存储类如Azure Files、Google Filestore或使用CSI驱动的NFS服务。确保StorageClass支持动态供应Provisioner。在pvc.yaml或Helm values中指定正确的storageClassName。5.2 监控、日志与告警没有监控的系统就像在黑暗中飞行。监控指标ClawHost服务暴露Prometheus指标如果实现了/metrics端点。监控其HTTP请求延迟、错误率、数据库连接池状态。Bot Pods使用K8s的Metrics Server结合Prometheus Adapter可以收集每个Bot Pod的CPU、内存使用量。设置HPAHorizontal Pod Autoscaler可以根据Bot的负载自动调整副本数如果Bot支持多副本。PostgreSQL监控数据库连接数、查询性能、磁盘空间和复制延迟如果用了主从。日志收集将所有PodClawHost和Bot的日志标准输出通过Fluentd或Filebeat收集并发送到中心化的日志平台如Elasticsearch Kibana (ELK) 或 Grafana Loki。为每个Bot的日志添加app_id和bot_id标签便于按租户和Bot进行筛选和排查问题。告警设置关键告警ClawHost Pod持续重启、数据库连接失败、PVC剩余空间不足10%。业务告警Bot创建失败率升高、Bot平均启动时间超过阈值、某个租户的Bot资源使用量异常飙升。使用Prometheus Alertmanager或云监控服务来配置这些告警规则并通知到钉钉、Slack或邮件。5.3 安全加固最佳实践将AI Bot部署在云端安全是重中之重。1. 密钥管理绝对不要将API Key、数据库密码等硬编码在配置文件或镜像中。使用K8s Secret来存储所有敏感信息。Helm Chart已经将adminToken和数据库密码通过Secret注入。对于Bot配置中的api_keyClawHost在创建Pod时会将其作为环境变量来自它自己的Secret注入而不是存储在Bot的配置文件中。考虑集成外部的密钥管理服务如HashiCorp Vault、AWS Secrets Manager或阿里云KMS实现密钥的动态轮转和更细粒度的访问控制。2. 网络隔离将ClawHost的管理API/admin和/bot/api/v1/admin与面向Bot的代理API/proxy/*通过不同的K8s Service或Ingress规则暴露。管理API应仅限于内部网络或VPN访问并施加严格的IP白名单和认证。使用K8s NetworkPolicy来限制Pod间的网络流量。例如只允许ClawHost Pod访问PostgreSQL的5432端口只允许Ingress Controller访问ClawHost Pod的18080端口。3. 认证与授权adminToken是最高权限密钥必须定期轮换。ClawHost提供了重置App Token的API但Admin Token需要在配置文件中修改并重启服务。考虑在ClawHost前面增加一层API网关如Kong、APISIX实现更复杂的认证OAuth2.0, JWT、限流和审计功能。定期审计K8s的RBAC配置确保ClawHost使用的ServiceAccount只有它所需的最小权限deploy/k8s/rbac.yaml已经定义了最小权限。4. 镜像安全使用私有容器镜像仓库。对基础镜像和自定义的OpenClaw Bot镜像进行漏洞扫描。使用具有非root用户运行的镜像如果OpenClaw镜像支持。5.4 自动化清理与资源回收Bot实例可能会因为用户不再使用而闲置持续占用资源。ClawHost内置的清理CronJob是控制成本的关键。清理逻辑详解 清理任务clawhost cleanup会定期执行默认每2小时它执行以下操作扫描查询数据库中所有状态为stopped或error且expires_at字段早于当前时间 -cleanup_grace_hours的Bot记录。删除K8s资源对于每个过期的Bot删除其对应的K8s Deployment和Service释放CPU和内存资源。标记状态将Bot在数据库中的状态更新为deleted软删除。注意Bot的数据库记录和PVC中的持久化数据不会被物理删除这为误操作提供了恢复的可能。分批处理通过cleanup_batch_size控制单次任务处理的Bot数量避免对数据库和K8s API造成过大压力。生产环境调整建议cleanup_grace_hours默认72小时3天比较合理。对于资源紧张的环境可以缩短至24小时。对于需要长期保留数据以备审计的场景可以延长至一周或更久。CronJob调度默认0 */2 * * *每2小时。可以根据Bot的创建频率调整。如果Bot创建非常频繁可以提高到每小时一次。监控清理任务确保CronJob正常运行。可以查看其Job的日志监控每次清理的Bot数量作为资源使用情况的一个参考指标。最终清理上述清理只释放计算资源。如果需要彻底删除Bot的所有数据数据库记录和PVC文件需要实现一个额外的、周期更长的“最终清理”任务或者在管理后台提供手动彻底删除的功能。5.5 常见问题与故障排查实录在实际部署和运维中你可能会遇到以下问题。这里记录了我的排查思路和解决方法。问题1Bot创建成功但启动失败状态一直为“启动中”或转为“错误”。排查思路检查ClawHost日志首先查看ClawHost Pod的日志看它在处理/start请求时是否报错。kubectl logs -n clawhost deployment/clawhost。检查K8s事件Bot启动的本质是创建Deployment。查看该Bot对应Deployment的详细事件这能揭示根本原因。kubectl describe deployment -n clawhost bot-deployment-name。常见的Deployment名称格式为bot-bot-id。检查Pod状态如果Deployment创建了Pod但Pod无法运行查看Pod的状态和事件。kubectl get pods -n clawhost | grep bot-id然后kubectl describe pod pod-name。常见原因与解决镜像拉取失败ImagePullBackOff。检查Bot配置中的image字段是否正确以及该镜像是否存在于可访问的仓库中且当前K8s节点有拉取权限。资源不足FailedScheduling/Insufficient cpu/memory。集群没有足够的资源来调度Pod。需要扩容节点或调整Bot的资源请求resources.requests这需要在ClawHost的Bot配置模板中调整。PVC挂载失败FailedMount。检查为Bot准备的共享PVC是否存在且状态为Bound。kubectl get pvc -n clawhost。配置错误Pod启动后立即CrashLoopBackOff。检查Bot Pod的日志。kubectl logs -n clawhost bot-pod-name。很可能是Bot的配置文件如API Key格式错误或环境变量有问题。问题2可以通过子域名访问Bot但连接超时或返回502错误。排查思路检查Bot Pod是否Readykubectl get pods -n clawhost确认对应Pod的STATUS为Running且READY为1/1。检查Bot Servicekubectl get svc -n clawhost | grep bot-id。确认Service存在并且其CLUSTER-IP和PORT(S)正确。检查ClawHost Proxy日志所有外部请求都经过ClawHost的Proxy组件。查看ClawHost Pod日志中与Proxy相关的记录看是否有路由错误或连接后端Service失败的信息。从集群内部直接访问Bot Servicekubectl run -it --rm debug --imagebusybox -n clawhost -- sh然后在调试Pod内执行wget -O- http://bot-service-name.namespace.svc.cluster.local。如果这里能通问题出在ClawHost Proxy或Ingress如果不通问题在Bot Service或Pod本身。常见原因与解决Bot应用未监听正确端口OpenClaw Bot默认可能监听3000端口但ClawHost创建的Service期望的端口是80或8080。需要确保Bot的Dockerfile中EXPOSE的端口与ClawHost配置中bot_container_port一致。网络策略NetworkPolicy阻隔如果集群启用了严格的NetworkPolicy可能阻止了ClawHost Pod访问Bot Service。需要添加允许clawhost命名空间中Pod互访的策略。Ingress或DNS配置错误生产环境中检查Ingress资源是否正确配置了泛域名主机规则以及DNS解析是否指向了正确的Ingress IP。问题3Admin UI/admin无法打开或登录失败。排查确认服务可达先访问/health端点确保ClawHost服务本身是健康的。检查Admin Token确认你在启动ClawHost时配置的adminToken与登录时输入的完全一致注意空格和大小写。可以通过查看ConfigMap或环境变量来验证kubectl get configmap -n clawhost clawhost-config -o yaml。检查前端资源Admin UI是静态资源打包在Go二进制文件中。如果页面是空白或JS加载失败可能是构建时前端资源未正确嵌入。尝试重新执行make build它会先构建前端再打包进Go二进制文件。问题4数据库连接问题ClawHost日志中频繁出现pq: connection refused或dial tcp timeout。排查检查PostgreSQL Pod状态kubectl get pods -n clawhost | grep postgres。检查数据库Servicekubectl get svc -n clawhost | grep postgres。确认Service名称和端口。验证网络连通性从ClawHost Pod内部尝试连接数据库。kubectl exec -it -n clawhost deployment/clawhost -- sh然后执行nc -zv postgres-service-name 5432。检查认证信息确认ClawHost配置中或Secret里存储的数据库用户名、密码、数据库名是否正确。解决如果是内置PostgreSQL检查其日志。如果是外部数据库检查网络防火墙、安全组设置确保K8s集群的节点IP被允许访问数据库的端口。问题5Bot清理CronJob没有执行。排查检查CronJob资源kubectl get cronjob -n clawhost。查看SCHEDULE和LAST SCHEDULE时间。检查Job历史kubectl get jobs -n clawhost --sort-by.status.startTime。查看是否有最近创建的Job。检查Job Pod日志找到最近一次Job创建的Pod查看其日志。kubectl logs -n clawhost job/job-name。可能原因K8s CronJob控制器未运行极少数情况。资源限制导致Job Pod无法调度检查Job Pod的事件描述。clawhost cleanup命令本身有bug或配置错误查看Pod日志中的具体错误信息。运维这样一个平台细致的监控和清晰的日志是快速定位问题的生命线。建议在项目初期就搭建好可观测性体系将上述常见的检查点做成Grafana仪表盘或告警规则能极大提升运维效率。