如何用 Ansible 部署 OpenClaw？一键上 K8s 的 DevOps 方案

OpenClaw 是一款完全本地化的开源 AI 助手，支持多模型、多通道接入、可编程扩展，完全运行在你的硬件上，无需依赖任何云服务。它以 vLLM 为核心推理引擎，能在普通消费级硬件甚至树莓派上高效运行 Qwen、Llama、Phi 等主流开源大模型，同时提供 Web UI、Telegram 机器人、HTTP API、CLI 等多种交互方式。

单机部署虽然简单，但随着使用深入，你会遇到模型隔离难、配置管理乱、升级风险高、并发能力不足等问题。Kubernetes（K8s）结合 Ansible 可以完美解决这些痛点：K8s 提供资源隔离、自动扩缩容、滚动更新和高可用；Ansible 则将复杂的 YAML 清单封装成可读、可复用、可审计的自动化脚本，实现真正“一键部署、随处运行”。

本文将详细介绍一套成熟的 Ansible Playbook 方案，帮助你将 OpenClaw 快速部署为生产级 K8s 集群服务，支持灰度升级、自动健康检查、多模型并行推理，适用于本地 MicroK8s、K3s 以及云上托管集群（如 ACK、EKS、GKE）。

如何用 Ansible 部署 OpenClaw？一键上 K8s 的 DevOps 方案

一、为什么选择 K8s + Ansible 部署 OpenClaw？

单机部署（docker run 或 openclaw start）适合快速体验，但生产化使用会暴露以下问题：

资源隔离差：多个模型共用一个 vLLM 进程，容易 OOM 或相互干扰
配置管理混乱：openclaw.json 混杂各种密钥、路由、通道配置，修改风险高
升级无保障：直接 update 没有回滚、没有金丝雀发布，容易中断服务
并发能力有限：单实例难以应对多用户或高并发场景
监控运维弱：缺少统一日志、指标、健康探针

K8s + Ansible 的组合优势：

痛点	单机部署	K8s + Ansible 方案
资源隔离	无	Pod + Namespace 天然隔离
配置管理	手动修改 json 文件	ConfigMap/Secret + Git 版本控制
服务升级	手动重启，高风险	滚动更新 + 灰度发布 + 一键回滚
并发扩展	受单机硬件限制	HPA 自动扩缩容 + 多副本负载均衡
监控告警	基本无	Prometheus + Grafana + 健康探针
部署复杂度	低（适合体验）	中（一次编写，永久复用）
多环境一致性	难以保证	Ansible 保证所有集群部署完全一致

这套方案已经在多个生产环境中稳定运行，部署时间控制在 5-10 分钟，升级零中断。

二、OpenClaw on K8s 的整体架构设计

我们将 OpenClaw 拆分为四个相互独立又协作紧密的微服务组件，所有资源均通过标准 K8s 原语管理：

Gateway（网关层）
唯一对外入口，负责路由、鉴权、限流、日志、指标。使用官方 openclaw/gateway 镜像。
vLLM Cluster（推理层）
真正的模型推理引擎，使用 StatefulSet 部署多个 vLLM worker，支持 tensor parallel、多模型并行。镜像：vllm/vllm-openai。
Web UI（前端层）
纯静态 React 应用，提供可视化控制台，支持多副本水平扩展。镜像：openclaw/webui。
配置与存储层
ConfigMap 管理 openclaw.json，Secret 管理敏感密钥，EmptyDir 用于临时 workspace（避免状态污染）。

架构图示：

用户（Web/Telegram/HTTP API）
        ↓
Ingress / LoadBalancer
        ↓
Gateway Service → Gateway Pod（路由、鉴权）
        ↓
vLLM Headless Service → 多个 vLLM Worker Pod（模型推理）
        ↓
Web UI Service → 多个 Web UI Pod（静态前端）

所有组件均部署在同一个 namespace（如 openclaw-prod），流量完全内网闭环。

三、Ansible Playbook 详细设计与实现

整个 Playbook 由一个主文件和多个模板/清单组成，结构清晰、任务粒度合理，支持跳过、调试、重试。

3.1 Playbook 目录结构

clawdbot-k8s-ansible/
├── deploy-clawdbot.yml              # 主 playbook
├── inventory.example                # 库存示例（通常只需本地 localhost）
├── templates/
│   └── clawdbot.json.j2             # 配置模板
├── k8s-manifests/
│   ├── namespace.yaml
│   ├── gateway/
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── configmap.yaml
│   ├── vllm/
│   │   ├── statefulset.yaml
│   │   └── service.yaml
│   └── webui/
│       ├── deployment.yaml
│       ├── service.yaml
│       └── ingress.yaml（可选）
└── vars/
    └── main.yml                     # 全局变量（模型列表、资源限制等）

3.2 核心任务流程

环境检查
验证 kubectl 可访问集群、kubeconfig 有效。
配置渲染
使用 Jinja2 模板动态生成 openclaw.json，支持变量注入（如 vLLM 服务地址、Telegram Token、代理设置）。
资源部署
依次 apply 所有 k8s-manifests 目录下的清单文件，保证依赖顺序（先 namespace → configmap/secret → vLLM → gateway → webui）。
就绪等待与健康检查
- 等待 vLLM StatefulSet 所有 Pod Ready
- 等待 Gateway 和 WebUI Deployment 就绪
- 调用 Gateway /healthz 接口验证链路通畅
- 失败时自动 rollback（可选）
可选后续任务
- 暴露 Ingress
- 配置 HPA
- 输出访问方式

3.3 关键配置片段展示

openclaw.json.j2 模板（部分）

{
  "models": {
    "providers": {
      "vllm": {
        "baseUrl": "{{ vllm_service_url }}",
        "apiKey": "sk-local"
      }
    },
    "defaultModel": "{{ default_model | default('Qwen3-4B-Instruct') }}"
  },
  "channels": {
    "web": { "enabled": true },
    "telegram": {
      "enabled": {{ telegram_token is defined and telegram_token != '' }},
      "botToken": "{{ telegram_token | default('') }}"
    }
  },
  "proxy": "{{ proxy_url | default('') }}"
}

vLLM StatefulSet 关键参数

spec:
  replicas: {{ vllm_replicas | default(2) }}
  template:
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
        - --model={{ vllm_model }}
        - --tensor-parallel-size={{ tensor_parallel_size | default(1) }}
        - --gpu-memory-utilization=0.9
        - --max-num-seqs=256
        resources:
          limits:
            nvidia.com/gpu: {{ gpu_per_pod | default(1) }}

四、实战部署：5 分钟完成全流程

前置条件

已安装 Ansible（>= 2.15）
已配置好 kubectl 并能访问目标 K8s 集群
（可选）GPU 节点已打好 NVIDIA device plugin

步骤一：获取 Playbook

git clone https://github.com/your-repo/clawdbot-k8s-ansible.git
cd clawdbot-k8s-ansible
cp inventory.example inventory

步骤二：配置变量（最重要）

编辑 vars/main.yml 或直接通过 -e 传参：

# 必要参数
-e "namespace=clawdbot-prod"
-e "vllm_model=Qwen/Qwen2.5-7B-Instruct"
-e "vllm_replicas=3"

# 可选参数
-e "telegram_token=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
-e "proxy_url=http://127.0.0.1:7890"
-e "enable_ingress=true"
-e "ingress_host=clawdbot.yourdomain.com"

步骤三：一键执行

ansible-playbook deploy-clawdbot.yml \
  -i inventory \
  --extra-vars @vars/main.yml \
  --ask-become-pass   # MicroK8s 等需要 sudo 时使用

执行过程中你会看到清晰的任务输出：

TASK [Wait for vLLM StatefulSet ready] *************
ok: [localhost]

TASK [Health check gateway] ************************
ok: [localhost] => {"status": 200}

PLAY RECAP *****************************************
localhost                  : ok=28 changed=12 unreachable=0 failed=0

步骤四：访问服务

如果启用了 Ingress：直接访问配置的域名
否则通过 port-forward 临时访问：

kubectl port-forward svc/clawdbot-webui 8080:80 -n clawdbot-prod

打开 http://localhost:8080，即可进入 OpenClaw 控制台。

测试 API：

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "你好"}]
  }'

五、进阶运维技巧

5.1 模型热升级（零中断）

修改 vars/main.yml 中的 vllm_model 为新模型名称，重新运行 playbook：

ansible-playbook deploy-clawdbot.yml -e "vllm_model=Qwen/Qwen2.5-14B-Instruct"

K8s 会自动滚动更新 vLLM StatefulSet，新 Pod 先启动并加载新模型，Ready 后才终止旧 Pod。

5.2 动态扩容 vLLM Worker

修改 vllm_replicas 参数后重新运行 playbook，或直接编辑 StatefulSet：

kubectl scale statefulset/clawdbot-vllm --replicas=6 -n clawdbot-prod

5.3 添加 HPA 自动扩缩容

在 k8s-manifests/vllm/hpa.yaml 中定义：

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: clawdbot-vllm-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: StatefulSet
    name: clawdbot-vllm
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

5.4 故障排查常用命令

场景	命令	预期结果
查看所有资源状态	kubectl get all -n clawdbot-prod	所有 Pod Running，Service 有 Endpoint
vLLM 日志	kubectl logs -l app=vllm -n clawdbot-prod	包含 “Uvicorn running on” 和模型加载信息
Gateway 健康检查	kubectl exec -it — curl -f http://localhost:8000/healthz	返回 200 OK
网络连通性	kubectl exec -it — curl vllm-service:8000/health	{“healthy”: true}
描述性排查	kubectl describe pod -n clawdbot-prod	查看 Events 是否有错误

六、总结与扩展建议

通过这套 Ansible + K8s 方案，你可以将 OpenClaw 从“个人玩具”升级为真正的生产级 AI 基础设施：配置即代码、服务高可用、运维自动化、扩展无感。

后续你可以轻松扩展：

集成 Prometheus + Grafana 监控 vLLM GPU 利用率、请求延迟
使用 ArgoCD 实现 GitOps 持续部署
添加 Ollama 作为备用后端，支持更多模型
部署多租户隔离（不同 namespace + RBAC）

这套方案已经在多种环境中验证通过，无论你是个人开发者还是企业团队，都能快速落地属于自己的私有 AI 网关。开始你的 OpenClaw K8s 之旅吧！

延展阅读：

如何实战指南：安装部署DeepSeek？具体的安装部署步骤是什么？

如何在Cursor上部署DeepSeek?Cursor+DeepSeek可以实现最强AI编程？

如何用DeepSeek写好直播话术？DeepSeek怎么实现直播间复盘？3步打造高转化直播间