一、概述

1.1 背景介绍

AI Agent 落地到企业内部，第一个挡在路上的问题就是接入层。微信、Telegram、Slack、企业微信，每个渠道的协议不一样，消息格式不一样，认证方式不一样。自己写网关代码？写到第三个渠道就想掀桌了。

OpenClaw 就是解决这个问题的。它是一个开源 AI Agent Gateway，用 Node.js 运行时构建，把多渠道消息接入、模型路由、Token 认证这些脏活累活全包了。后端对接任意 OpenAI 兼容 API（包括 vLLM、Ollama 等自托管方案），前端对接各种 IM 渠道，中间做协议转换和流量管理。

官方只提供了 Docker 部署方案，没有 K8s 支持。但生产环境跑 Docker Compose 迟早要出事——单点故障、手动扩容、没有滚动更新，哪个都是定时炸弹。这篇文章把 Docker 方案和 K8s 方案都写清楚，Docker 方案用于开发测试快速验证，K8s 方案用于生产环境长期运行。

1.2 技术特点

• 多渠道网关统一接入：HTTP API、WebSocket 双协议复用同一端口（18789），支持 Telegram Bot、企业微信、Slack 等 IM 渠道接入。消息格式在网关层统一转换，后端模型服务不需要关心渠道差异。

• 插件式模型路由：通过 models.providers 配置自定义 Provider，支持同时对接多个推理后端。模型标识使用 provider/model 格式（如 vllm-local/Qwen3.5-35B），路由逻辑在配置文件中声明，不需要写代码。

• 自托管模型原生支持：内置 OpenAI Responses API 兼容层，可以直接对接 vLLM、TGI、Ollama 等主流推理引擎。配置一个 baseUrl 加一个模型列表就能用，不需要额外的适配层。

• 轻量级 Token 认证：Gateway 内置 Token 认证机制（gateway.auth.token），每个接入方分配独立 Token，在网关层完成鉴权。生产环境可配合 K8s NetworkPolicy 实现网络层隔离。

1.3 适用场景

• 企业内部 AI 助手平台：统一管理多个部门的 AI 助手，每个部门分配独立 Token 和模型配额。通过 K8s 多租户隔离实现部门间的资源和网络隔离，避免互相影响。

• 多平台消息聚合：同一个 AI Agent 同时在 Telegram、企业微信、Slack 上提供服务。OpenClaw 在网关层做消息协议转换，后端只需要维护一套模型服务。

• 私有化大模型部署：数据不出企业网络，用 vLLM 部署 Qwen、LLaMA 等开源模型，OpenClaw 作为 API 网关对外提供标准化接口。GPU 资源通过 K8s 调度，按需分配给不同的推理实例。

1.4 环境要求

二、详细步骤

2.1 准备工作

2.1.1 系统检查

# 检查系统版本
cat /etc/os-release

# 检查内核版本
uname -r

# 检查 Docker 版本（需要 24.0+）
docker --version
docker compose version

# 检查系统资源
free -h
df -h

# 如果部署 K8s 方案，检查集群状态
kubectl cluster-info
kubectl get nodes -o wide

预期输出：Docker 版本 24.0 以上，Docker Compose V2 正常输出版本号。K8s 集群所有节点 Ready 状态。

2.1.2 安装 Docker（如果还没装）

# Ubuntu/Debian 安装 Docker
curl -fsSL https://get.docker.com | bash -s docker

# 将当前用户加入 docker 组（避免每次 sudo）
sudo usermod -aG docker $USER
newgrp docker

# 验证安装
docker run hello-world

2.1.3 准备 OpenClaw 配置目录

# 创建配置目录
mkdir -p ~/.openclaw

# 创建工作空间目录
mkdir -p ~/openclaw-workspace

OpenClaw 的配置文件是 JSON5 格式，文件路径固定在 ~/.openclaw/openclaw.json。容器内部以 node 用户（uid 1000）运行，挂载目录时需要注意权限问题。

# 确保目录权限正确（容器内 node 用户 uid=1000）
sudo chown -R 1000:1000 ~/.openclaw
sudo chown -R 1000:1000 ~/openclaw-workspace

2.2 Docker Compose 部署（官方方案）

这是官方推荐的部署方式，适合开发测试和小规模生产环境。

2.2.1 使用官方安装脚本

OpenClaw 提供了 docker-setup.sh 一键安装脚本，流程是：拉取镜像 → 初始化配置（onboard）→ 启动服务。

# 拉取官方安装脚本并执行
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-setup.sh | bash

如果网络环境不方便直接执行远程脚本，也可以手动操作：

# 手动拉取镜像
docker pull ghcr.io/openclaw/openclaw:latest

# 初始化配置（交互式，会引导设置 Token 和基础配置）
docker run --rm -it \
  -v "$HOME/.openclaw:/home/node/.openclaw" \
  ghcr.io/openclaw/openclaw:latest \
  openclaw onboard

2.2.2 环境变量配置

docker-setup.sh 支持通过环境变量定制行为：

# 自定义启动示例
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
export OPENCLAW_GATEWAY_BIND="0.0.0.0:18789"
export OPENCLAW_HOME_VOLUME="$HOME/.openclaw"

2.2.3 编写 Docker Compose 文件

生产环境建议用 docker-compose.yml 管理，比裸 docker run 更容易维护：

# docker-compose.yml
version:"3.8"

services:
openclaw-gateway:
    image:ghcr.io/openclaw/openclaw:latest
    container_name:openclaw-gateway
    restart:unless-stopped
    ports:
      -"18789:18789"
    volumes:
      -./config:/home/node/.openclaw
      -./workspace:/home/node/workspace
    environment:
      -NODE_ENV=production
    user:"1000:1000"
    healthcheck:
      test:["CMD","curl","-f","http://localhost:18789/healthz"]
      interval:30s
      timeout:10s
      retries:3
      start_period:15s
    deploy:
      resources:
        limits:
          memory:2G
          cpus:"2.0"
        reservations:
          memory:512M
          cpus:"0.5"
    logging:
      driver:json-file
      options:
        max-size:"50m"
        max-file:"5"

2.2.4 编写 OpenClaw 配置文件

在 ./config/ 目录下创建 openclaw.json（JSON5 格式，支持注释）：

// ./config/openclaw.json
{
  // 网关配置
  gateway: {
    bind: "0.0.0.0:18789",
    auth: {
      // 生产环境必须改成随机生成的强 Token
      token: "oc-prod-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    }
  },

  // 模型配置
  models: {
    // 默认模型（客户端不指定模型时使用）
    default: "vllm-local/Qwen3.5-35B",

    providers: {
      // 自托管 vLLM 推理服务
      "vllm-local": {
        baseUrl: "http://vllm-service:8000/v1",
        api: "openai-responses",
        models: [
          "Qwen/Qwen3.5-35B-A3B-FP8"
        ]
      }
    }
  }
}

注意：gateway.auth.token 这个值必须是强随机字符串，别用示例里的值。生成方法：

# 生成 32 字节随机 Token
openssl rand -hex 32

2.2.5 启动并验证

# 启动服务（后台运行）
docker compose up -d

# 查看日志，确认启动成功
docker compose logs -f openclaw-gateway

# 健康检查
curl -s http://localhost:18789/healthz
# 预期输出：{"status":"ok"}

# 就绪检查
curl -s http://localhost:18789/readyz
# 预期输出：{"status":"ready"}

# 带 Token 认证的请求测试
curl -s -H "Authorization: Bearer oc-prod-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  http://localhost:18789/v1/models

如果 /healthz 返回 {"status":"ok"} 就说明网关启动成功了。/readyz 还会检查后端模型连通性，如果 vLLM 还没部署，/readyz 可能返回 not ready，这是正常的。

2.3 Kubernetes 部署方案

官方没有提供 K8s 部署方案，以下配置是基于 Docker 方案转写的。核心思路：把 Docker 的 bind mount 换成 PVC，把环境变量和配置文件换成 ConfigMap/Secret，把容器换成 Deployment + Service。

2.3.1 创建 Namespace

kubectl create namespace openclaw

所有 OpenClaw 相关资源都放在 openclaw Namespace 下，方便管理和 RBAC 隔离。

2.3.2 ConfigMap：OpenClaw 配置文件

# openclaw-configmap.yaml
apiVersion:v1
kind:ConfigMap
metadata:
name:openclaw-config
namespace:openclaw
labels:
    app:openclaw
    component:gateway
data:
openclaw.json:|
    {
      // 网关配置
      "gateway": {
        "bind": "0.0.0.0:18789",
        "auth": {
          // Token 从 Secret 注入，这里用环境变量占位
          // 实际运行时由 entrypoint 脚本替换
          "token": "${OPENCLAW_AUTH_TOKEN}"
        }
      },
      "models": {
        "default": "vllm-local/Qwen3.5-35B",
        "providers": {
          "vllm-local": {
            "baseUrl": "http://vllm-service.openclaw.svc.cluster.local:8000/v1",
            "api": "openai-responses",
            "models": [
              "Qwen/Qwen3.5-35B-A3B-FP8"
            ]
          }
        }
      }
    }

模型服务地址使用 K8s 内部 DNS：vllm-service.openclaw.svc.cluster.local:8000，不需要走集群外部网络。

2.3.3 Secret：敏感信息

# 生成随机 Token
GATEWAY_TOKEN=$(openssl rand -hex 32)

# 创建 Secret
kubectl create secret generic openclaw-secrets \
  --namespace=openclaw \
  --from-literal=gateway-token="${GATEWAY_TOKEN}" \
  --from-literal=openai-api-key="sk-your-openai-key-if-needed"

# 验证 Secret 创建成功
kubectl get secret openclaw-secrets -n openclaw

也可以用 YAML 声明式创建（Token 需要 base64 编码）：

# openclaw-secret.yaml
apiVersion:v1
kind:Secret
metadata:
name:openclaw-secrets
namespace:openclaw
labels:
    app:openclaw
type:Opaque
data:
# echo -n "your-token" | base64
gateway-token:"b2MtcHJvZC1hMWIyYzNkNGU1ZjZnN2g4aTlqMGsxbDJtM240bzVwNg=="
openai-api-key:""

2.3.4 PersistentVolumeClaim：持久化存储

# openclaw-pvc.yaml
apiVersion:v1
kind:PersistentVolumeClaim
metadata:
name:openclaw-data
namespace:openclaw
labels:
    app:openclaw
spec:
accessModes:
    -ReadWriteOnce
storageClassName:standard
resources:
    requests:
      storage:10Gi
---
apiVersion:v1
kind:PersistentVolumeClaim
metadata:
name:openclaw-workspace
namespace:openclaw
labels:
    app:openclaw
spec:
accessModes:
    -ReadWriteOnce
storageClassName:standard
resources:
    requests:
      storage:50Gi

storageClassName 根据集群实际情况调整。云厂商环境一般用 gp3（AWS）、pd-ssd（GCP）、managed-csi（Azure）。自建集群用 local-path 或 NFS。

如果 Gateway 需要多副本，accessModes 要改成 ReadWriteMany，存储后端也要支持（NFS、CephFS 等）。单副本用 ReadWriteOnce 就够了。

2.3.5 Deployment：OpenClaw Gateway

# openclaw-deployment.yaml
apiVersion:apps/v1
kind:Deployment
metadata:
name:openclaw-gateway
namespace:openclaw
labels:
    app:openclaw
    component:gateway
spec:
replicas:2
selector:
    matchLabels:
      app:openclaw
      component:gateway
strategy:
    type:RollingUpdate
    rollingUpdate:
      maxSurge:1
      maxUnavailable:0
template:
    metadata:
      labels:
        app:openclaw
        component:gateway
    spec:
      securityContext:
        runAsUser:1000
        runAsGroup:1000
        fsGroup:1000
      initContainers:
        # initContainer 用于将 ConfigMap 中的配置文件复制到可写目录
        # 并替换 Token 占位符
        -name:config-init
          image:ghcr.io/openclaw/openclaw:latest
          command:
            -/bin/sh
            --c
            -|
              cp /config-readonly/openclaw.json /home/node/.openclaw/openclaw.json
              sed -i "s|\${OPENCLAW_AUTH_TOKEN}|${GATEWAY_TOKEN}|g" /home/node/.openclaw/openclaw.json
          env:
            -name:GATEWAY_TOKEN
              valueFrom:
                secretKeyRef:
                  name:openclaw-secrets
                  key:gateway-token
          volumeMounts:
            -name:config-readonly
              mountPath:/config-readonly
            -name:openclaw-data
              mountPath:/home/node/.openclaw
      containers:
        -name:openclaw-gateway
          image:ghcr.io/openclaw/openclaw:latest
          ports:
            -name:http
              containerPort:18789
              protocol:TCP
          env:
            -name:NODE_ENV
              value:"production"
            -name:OPENCLAW_AUTH_TOKEN
              valueFrom:
                secretKeyRef:
                  name:openclaw-secrets
                  key:gateway-token
          volumeMounts:
            -name:openclaw-data
              mountPath:/home/node/.openclaw
            -name:openclaw-workspace
              mountPath:/home/node/workspace
          resources:
            requests:
              cpu:"500m"
              memory:"512Mi"
            limits:
              cpu:"2000m"
              memory:"2Gi"
          livenessProbe:
            httpGet:
              path:/healthz
              port:18789
            initialDelaySeconds:15
            periodSeconds:30
            timeoutSeconds:5
            failureThreshold:3
          readinessProbe:
            httpGet:
              path:/readyz
              port:18789
            initialDelaySeconds:10
            periodSeconds:10
            timeoutSeconds:5
            failureThreshold:3
          startupProbe:
            httpGet:
              path:/healthz
              port:18789
            initialDelaySeconds:5
            periodSeconds:5
            failureThreshold:12
      volumes:
        -name:config-readonly
          configMap:
            name:openclaw-config
        -name:openclaw-data
          persistentVolumeClaim:
            claimName:openclaw-data
        -name:openclaw-workspace
          persistentVolumeClaim:
            claimName:openclaw-workspace
      terminationGracePeriodSeconds:30

几个关键设计点：

1. initContainer 处理配置：ConfigMap 挂载的目录是只读的，但 OpenClaw 运行时需要读写 ~/.openclaw 目录。所以用 initContainer 把配置文件从 ConfigMap 复制到 PVC，同时替换 Token 占位符。
2. securityContext uid=1000：OpenClaw 镜像以 node 用户运行（uid 1000），PVC 目录的 fsGroup 也设为 1000，避免权限问题。
3. 三种探针都配了：startupProbe 给容器 60 秒启动时间（5s × 12次），livenessProbe 检测进程存活，readinessProbe 检测服务就绪。
4. RollingUpdate maxUnavailable=0：更新时先拉起新 Pod 再下旧 Pod，服务零中断。

2.3.6 Service

# openclaw-service.yaml
apiVersion:v1
kind:Service
metadata:
name:openclaw-gateway
namespace:openclaw
labels:
    app:openclaw
    component:gateway
spec:
type:ClusterIP
ports:
    -name:http
      port:18789
      targetPort:18789
      protocol:TCP
selector:
    app:openclaw
    component:gateway
---
# NodePort Service（可选，用于无 Ingress 环境直接访问）
apiVersion:v1
kind:Service
metadata:
name:openclaw-gateway-nodeport
namespace:openclaw
labels:
    app:openclaw
    component:gateway
spec:
type:NodePort
ports:
    -name:http
      port:18789
      targetPort:18789
      nodePort:31789
      protocol:TCP
selector:
    app:openclaw
    component:gateway

ClusterIP Service 供集群内部访问（Ingress 转发用），NodePort Service 供没有 Ingress 的环境直接通过 节点IP:31789 访问。生产环境推荐走 Ingress + ClusterIP，不暴露 NodePort。

2.3.7 Ingress：HTTPS 暴露

# openclaw-ingress.yaml
apiVersion:networking.k8s.io/v1
kind:Ingress
metadata:
name:openclaw-gateway
namespace:openclaw
labels:
    app:openclaw
annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout:"3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout:"3600"
    # WebSocket 支持（OpenClaw 端口复用 HTTP + WS）
    nginx.ingress.kubernetes.io/proxy-http-version:"1.1"
    nginx.ingress.kubernetes.io/upstream-hash-by:"$remote_addr"
    # 请求体大小限制（Agent 对话上下文可能很长）
    nginx.ingress.kubernetes.io/proxy-body-size:"50m"
    # TLS 证书自动签发（需要 cert-manager）
    cert-manager.io/cluster-issuer:"letsencrypt-prod"
spec:
ingressClassName:nginx
tls:
    -hosts:
        -openclaw.example.com
      secretName:openclaw-tls
rules:
    -host:openclaw.example.com
      http:
        paths:
          -path:/
            pathType:Prefix
            backend:
              service:
                name:openclaw-gateway
                port:
                  number:18789

Ingress 的 proxy-read-timeout 设成 3600 秒，因为大模型推理响应时间可能很长（特别是长文本生成场景）。默认 60 秒超时在生产环境一定会出问题，这个坑踩过的人都知道。

WebSocket 的 proxy-http-version 必须设为 1.1，否则 WS 连接建不起来。

2.4 vLLM 推理服务部署

OpenClaw 网关本身不做推理，需要后端挂一个推理服务。这里用 vLLM 部署 Qwen/Qwen3.5-35B-A3B-FP8 模型。

2.4.1 vLLM Deployment

# vllm-deployment.yaml
apiVersion:apps/v1
kind:Deployment
metadata:
name:vllm-inference
namespace:openclaw
labels:
    app:openclaw
    component:vllm
spec:
replicas:1
selector:
    matchLabels:
      app:openclaw
      component:vllm
template:
    metadata:
      labels:
        app:openclaw
        component:vllm
    spec:
      containers:
        -name:vllm
          image:vllm/vllm-openai:latest
          command:
            -python3
            --m
            -vllm.entrypoints.openai.api_server
          args:
            -"--model"
            -"Qwen/Qwen3.5-35B-A3B-FP8"
            -"--host"
            -"0.0.0.0"
            -"--port"
            -"8000"
            -"--tensor-parallel-size"
            -"4"
            -"--max-model-len"
            -"32768"
            -"--gpu-memory-utilization"
            -"0.90"
            -"--block-size"
            -"16"
            -"--swap-space"
            -"8"
            -"--dtype"
            -"auto"
            -"--trust-remote-code"
          ports:
            -name:http
              containerPort:8000
              protocol:TCP
          env:
            -name:HUGGING_FACE_HUB_TOKEN
              valueFrom:
                secretKeyRef:
                  name:openclaw-secrets
                  key:openai-api-key
                  optional:true
            -name:VLLM_WORKER_MULTIPROC_METHOD
              value:"spawn"
          resources:
            requests:
              cpu:"8"
              memory:"64Gi"
              nvidia.com/gpu:"4"
            limits:
              cpu:"16"
              memory:"128Gi"
              nvidia.com/gpu:"4"
          volumeMounts:
            -name:model-cache
              mountPath:/root/.cache/huggingface
            -name:shm
              mountPath:/dev/shm
          livenessProbe:
            httpGet:
              path:/health
              port:8000
            initialDelaySeconds:120
            periodSeconds:30
            timeoutSeconds:10
            failureThreshold:5
          readinessProbe:
            httpGet:
              path:/health
              port:8000
            initialDelaySeconds:120
            periodSeconds:15
            timeoutSeconds:10
            failureThreshold:5
      volumes:
        -name:model-cache
          persistentVolumeClaim:
            claimName:vllm-model-cache
        -name:shm
          emptyDir:
            medium:Memory
            sizeLimit:16Gi
      tolerations:
        -key:nvidia.com/gpu
          operator:Exists
          effect:NoSchedule
      nodeSelector:
        gpu-type:a100
---
apiVersion:v1
kind:PersistentVolumeClaim
metadata:
name:vllm-model-cache
namespace:openclaw
spec:
accessModes:
    -ReadWriteOnce
storageClassName:standard
resources:
    requests:
      storage:200Gi

几个坑点说明：

1. /dev/shm 必须挂载 emptyDir：vLLM 多进程通信依赖共享内存，Docker 默认的 64MB shm 远远不够。这里给了 16Gi，35B 模型 4 卡并行至少需要这个量级。
2. **tensor-parallel-size=4**：Qwen3.5-35B-A3B-FP8 是 FP8 量化模型，4 张 A100 80GB 可以稳定加载。2 张卡勉强能跑但显存利用率太高，留不出 KV Cache 空间。
3. **initialDelaySeconds=120**：大模型加载需要时间，35B 模型从磁盘加载到 GPU 至少要 90 秒，设短了 Pod 会被 K8s 反复杀掉重启。
4. **gpu-memory-utilization=0.90**：给 KV Cache 留 10% 的显存余量。设成 0.95 虽然能多接几个并发，但在突发流量下容易 OOM。
5. nodeSelector：确保 Pod 调度到有 GPU 的节点，标签 gpu-type: a100 需要提前给节点打好。

2.4.2 vLLM Service

# vllm-service.yaml
apiVersion:v1
kind:Service
metadata:
name:vllm-service
namespace:openclaw
labels:
    app:openclaw
    component:vllm
spec:
type:ClusterIP
ports:
    -name:http
      port:8000
      targetPort:8000
      protocol:TCP
selector:
    app:openclaw
    component:vllm

这个 Service 只在集群内部暴露，OpenClaw 网关通过 http://vllm-service.openclaw.svc.cluster.local:8000/v1 访问。不需要对外暴露推理服务端口，安全性更好。

2.5 OpenClaw 对接 vLLM

2.5.1 配置 models.providers

OpenClaw 的 openclaw.json 中 models.providers 部分配置 vLLM 作为推理后端：

{
  models: {
    default: "vllm-local/Qwen3.5-35B",
    providers: {
      "vllm-local": {
        // K8s 环境使用 Service DNS
        baseUrl: "http://vllm-service.openclaw.svc.cluster.local:8000/v1",
        // Docker 环境使用容器名或宿主机 IP
        // baseUrl: "http://host.docker.internal:8000/v1",
        api: "openai-responses",
        models: [
          "Qwen/Qwen3.5-35B-A3B-FP8"
        ]
      }
    }
  }
}

Provider 名称 vllm-local 可以自定义，客户端请求时通过 provider/model 格式指定模型，比如 vllm-local/Qwen3.5-35B。

如果有多个推理后端，可以配置多个 Provider：

{
  models: {
    default: "vllm-local/Qwen3.5-35B",
    providers: {
      "vllm-local": {
        baseUrl: "http://vllm-service.openclaw.svc.cluster.local:8000/v1",
        api: "openai-responses",
        models: ["Qwen/Qwen3.5-35B-A3B-FP8"]
      },
      "vllm-code": {
        baseUrl: "http://vllm-code-service.openclaw.svc.cluster.local:8000/v1",
        api: "openai-responses",
        models: ["Qwen/Qwen3-Coder-30B-A3B-FP8"]
      }
    }
  }
}

2.5.2 验证模型连通性

# K8s 环境：在集群内部验证
kubectl run -it --rm debug-curl \
  --namespace=openclaw \
  --image=curlimages/curl \
  --restart=Never \
  -- curl -s http://vllm-service:8000/v1/models

# 预期输出：
# {"data":[{"id":"Qwen/Qwen3.5-35B-A3B-FP8","object":"model",...}]}

# 验证 OpenClaw 网关到 vLLM 的端到端连通性
kubectl run -it --rm debug-curl \
  --namespace=openclaw \
  --image=curlimages/curl \
  --restart=Never \
  -- curl -s -H "Authorization: Bearer <your-gateway-token>" \
     http://openclaw-gateway:18789/v1/models

2.6 启动验证

2.6.1 K8s 部署一键执行

# 按顺序部署所有资源
kubectl apply -f openclaw-configmap.yaml
kubectl apply -f openclaw-secret.yaml
kubectl apply -f openclaw-pvc.yaml
kubectl apply -f vllm-deployment.yaml
kubectl apply -f vllm-service.yaml
kubectl apply -f openclaw-deployment.yaml
kubectl apply -f openclaw-service.yaml
kubectl apply -f openclaw-ingress.yaml

# 查看所有资源状态
kubectl get all -n openclaw

# 等待所有 Pod 就绪
kubectl wait --for=condition=ready pod \
  -l app=openclaw \
  -n openclaw \
  --timeout=300s

2.6.2 健康检查验证

# Docker 方案验证
curl -s http://localhost:18789/healthz | python3 -m json.tool
curl -s http://localhost:18789/readyz | python3 -m json.tool

# K8s 方案验证（通过 Ingress）
curl -s https://openclaw.example.com/healthz | python3 -m json.tool
curl -s https://openclaw.example.com/readyz | python3 -m json.tool

# K8s 方案验证（通过 NodePort）
curl -s http://<node-ip>:31789/healthz | python3 -m json.tool

# K8s 方案验证（通过 port-forward，调试用）
kubectl port-forward svc/openclaw-gateway 18789:18789 -n openclaw &
curl -s http://localhost:18789/healthz | python3 -m json.tool

2.6.3 端到端功能测试

# 发送一个完整的对话请求，验证网关→vLLM 链路
curl -s -X POST \
  -H "Authorization: Bearer <your-gateway-token>" \
  -H "Content-Type: application/json" \
  http://localhost:18789/v1/chat/completions \
  -d '{
    "model": "vllm-local/Qwen3.5-35B",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello, what is Kubernetes?"}
    ],
    "max_tokens": 200,
    "temperature": 0.7
  }' | python3 -m json.tool

如果返回了正常的模型响应，说明整条链路跑通了：客户端 → OpenClaw Gateway（认证 + 路由）→ vLLM（推理）→ 返回结果。

三、示例代码和配置

3.1 完整 docker-compose.yml（含 vLLM）

Docker 方案的完整 Compose 文件，一个文件跑起整套服务：

# docker-compose.yml - OpenClaw + vLLM 完整部署
version:"3.8"

services:
# OpenClaw Gateway
openclaw-gateway:
    image:ghcr.io/openclaw/openclaw:latest
    container_name:openclaw-gateway
    restart:unless-stopped
    ports:
      -"18789:18789"
    volumes:
      -./config:/home/node/.openclaw
      -./workspace:/home/node/workspace
    environment:
      -NODE_ENV=production
    user:"1000:1000"
    depends_on:
      vllm:
        condition:service_healthy
    healthcheck:
      test:["CMD","curl","-f","http://localhost:18789/healthz"]
      interval:30s
      timeout:10s
      retries:3
      start_period:15s
    deploy:
      resources:
        limits:
          memory:2G
          cpus:"2.0"
        reservations:
          memory:512M
          cpus:"0.5"
    networks:
      -openclaw-net
    logging:
      driver:json-file
      options:
        max-size:"50m"
        max-file:"5"

# vLLM 推理服务
vllm:
    image:vllm/vllm-openai:latest
    container_name:vllm-inference
    restart:unless-stopped
    ports:
      -"8000:8000"
    command:
      -"--model"
      -"Qwen/Qwen3.5-35B-A3B-FP8"
      -"--host"
      -"0.0.0.0"
      -"--port"
      -"8000"
      -"--tensor-parallel-size"
      -"4"
      -"--max-model-len"
      -"32768"
      -"--gpu-memory-utilization"
      -"0.90"
      -"--block-size"
      -"16"
      -"--swap-space"
      -"8"
      -"--dtype"
      -"auto"
      -"--trust-remote-code"
    volumes:
      -model-cache:/root/.cache/huggingface
    environment:
      -HUGGING_FACE_HUB_TOKEN=${HF_TOKEN:-}
      -VLLM_WORKER_MULTIPROC_METHOD=spawn
    healthcheck:
      test:["CMD","curl","-f","http://localhost:8000/health"]
      interval:30s
      timeout:15s
      retries:10
      start_period:180s
    shm_size:"16gb"
    deploy:
      resources:
        reservations:
          devices:
            -driver:nvidia
              count:4
              capabilities:[gpu]
    networks:
      -openclaw-net

# OpenClaw CLI（管理工具，按需启动）
openclaw-cli:
    image:ghcr.io/openclaw/openclaw:latest
    container_name:openclaw-cli
    profiles:
      -tools
    volumes:
      -./config:/home/node/.openclaw
      -./workspace:/home/node/workspace
    user:"1000:1000"
    stdin_open:true
    tty:true
    networks:
      -openclaw-net

volumes:
model-cache:
    driver:local

networks:
openclaw-net:
    driver:bridge

使用方法：

# 启动网关 + 推理服务
docker compose up -d

# 查看所有服务状态
docker compose ps

# 按需启动 CLI 管理工具
docker compose --profile tools run --rm openclaw-cli openclaw --help

# 查看实时日志
docker compose logs -f

# 停止所有服务
docker compose down

# 停止并清理数据卷（谨慎操作）
docker compose down -v

3.2 完整 K8s YAML（All-in-One Manifest）

把所有 K8s 资源合并到一个文件，方便一键部署：

# openclaw-all-in-one.yaml
# 使用方法：kubectl apply -f openclaw-all-in-one.yaml

# --- Namespace ---
apiVersion:v1
kind:Namespace
metadata:
name:openclaw
labels:
    app:openclaw

---
# --- ConfigMap ---
apiVersion:v1
kind:ConfigMap
metadata:
name:openclaw-config
namespace:openclaw
data:
openclaw.json:|
    {
      "gateway": {
        "bind": "0.0.0.0:18789",
        "auth": {
          "token": "${OPENCLAW_AUTH_TOKEN}"
        }
      },
      "models": {
        "default": "vllm-local/Qwen3.5-35B",
        "providers": {
          "vllm-local": {
            "baseUrl": "http://vllm-service.openclaw.svc.cluster.local:8000/v1",
            "api": "openai-responses",
            "models": [
              "Qwen/Qwen3.5-35B-A3B-FP8"
            ]
          }
        }
      }
    }

---
# --- Secret（部署前先替换 Token） ---
apiVersion:v1
kind:Secret
metadata:
name:openclaw-secrets
namespace:openclaw
type:Opaque
stringData:
gateway-token:"REPLACE_WITH_RANDOM_TOKEN"

---
# --- PVC: Gateway 数据 ---
apiVersion:v1
kind:PersistentVolumeClaim
metadata:
name:openclaw-data
namespace:openclaw
spec:
accessModes:[ReadWriteOnce]
storageClassName:standard
resources:
    requests:
      storage:10Gi

---
# --- PVC: Gateway 工作空间 ---
apiVersion:v1
kind:PersistentVolumeClaim
metadata:
name:openclaw-workspace
namespace:openclaw
spec:
accessModes:[ReadWriteOnce]
storageClassName:standard
resources:
    requests:
      storage:50Gi

---
# --- PVC: vLLM 模型缓存 ---
apiVersion:v1
kind:PersistentVolumeClaim
metadata:
name:vllm-model-cache
namespace:openclaw
spec:
accessModes:[ReadWriteOnce]
storageClassName:standard
resources:
    requests:
      storage:200Gi

---
# --- Deployment: OpenClaw Gateway ---
apiVersion:apps/v1
kind:Deployment
metadata:
name:openclaw-gateway
namespace:openclaw
spec:
replicas:2
selector:
    matchLabels:
      app:openclaw
      component:gateway
strategy:
    type:RollingUpdate
    rollingUpdate:
      maxSurge:1
      maxUnavailable:0
template:
    metadata:
      labels:
        app:openclaw
        component:gateway
    spec:
      securityContext:
        runAsUser:1000
        runAsGroup:1000
        fsGroup:1000
      initContainers:
        -name:config-init
          image:ghcr.io/openclaw/openclaw:latest
          command:["/bin/sh","-c"]
          args:
            -|
              cp /config-readonly/openclaw.json /home/node/.openclaw/openclaw.json
              sed -i "s|\${OPENCLAW_AUTH_TOKEN}|${GATEWAY_TOKEN}|g" /home/node/.openclaw/openclaw.json
          env:
            -name:GATEWAY_TOKEN
              valueFrom:
                secretKeyRef:
                  name:openclaw-secrets
                  key:gateway-token
          volumeMounts:
            -name:config-readonly
              mountPath:/config-readonly
            -name:openclaw-data
              mountPath:/home/node/.openclaw
      containers:
        -name:gateway
          image:ghcr.io/openclaw/openclaw:latest
          ports:
            -containerPort:18789
          env:
            -name:NODE_ENV
              value:"production"
          resources:
            requests:
              cpu:"500m"
              memory:"512Mi"
            limits:
              cpu:"2000m"
              memory:"2Gi"
          livenessProbe:
            httpGet:
              path:/healthz
              port:18789
            initialDelaySeconds:15
            periodSeconds:30
          readinessProbe:
            httpGet:
              path:/readyz
              port:18789
            initialDelaySeconds:10
            periodSeconds:10
          startupProbe:
            httpGet:
              path:/healthz
              port:18789
            periodSeconds:5
            failureThreshold:12
          volumeMounts:
            -name:openclaw-data
              mountPath:/home/node/.openclaw
            -name:openclaw-workspace
              mountPath:/home/node/workspace
      volumes:
        -name:config-readonly
          configMap:
            name:openclaw-config
        -name:openclaw-data
          persistentVolumeClaim:
            claimName:openclaw-data
        -name:openclaw-workspace
          persistentVolumeClaim:
            claimName:openclaw-workspace
      terminationGracePeriodSeconds:30

---
# --- Deployment: vLLM ---
apiVersion:apps/v1
kind:Deployment
metadata:
name:vllm-inference
namespace:openclaw
spec:
replicas:1
selector:
    matchLabels:
      app:openclaw
      component:vllm
template:
    metadata:
      labels:
        app:openclaw
        component:vllm
    spec:
      containers:
        -name:vllm
          image:vllm/vllm-openai:latest
          command:["python3","-m","vllm.entrypoints.openai.api_server"]
          args:
            -"--model=Qwen/Qwen3.5-35B-A3B-FP8"
            -"--host=0.0.0.0"
            -"--port=8000"
            -"--tensor-parallel-size=4"
            -"--max-model-len=32768"
            -"--gpu-memory-utilization=0.90"
            -"--block-size=16"
            -"--swap-space=8"
            -"--dtype=auto"
            -"--trust-remote-code"
          ports:
            -containerPort:8000
          env:
            -name:VLLM_WORKER_MULTIPROC_METHOD
              value:"spawn"
          resources:
            requests:
              cpu:"8"
              memory:"64Gi"
              nvidia.com/gpu:"4"
            limits:
              cpu:"16"
              memory:"128Gi"
              nvidia.com/gpu:"4"
          volumeMounts:
            -name:model-cache
              mountPath:/root/.cache/huggingface
            -name:shm
              mountPath:/dev/shm
          livenessProbe:
            httpGet:
              path:/health
              port:8000
            initialDelaySeconds:120
            periodSeconds:30
          readinessProbe:
            httpGet:
              path:/health
              port:8000
            initialDelaySeconds:120
            periodSeconds:15
      volumes:
        -name:model-cache
          persistentVolumeClaim:
            claimName:vllm-model-cache
        -name:shm
          emptyDir:
            medium:Memory
            sizeLimit:16Gi
      tolerations:
        -key:nvidia.com/gpu
          operator:Exists
          effect:NoSchedule
      nodeSelector:
        gpu-type:a100

---
# --- Service: OpenClaw Gateway ---
apiVersion:v1
kind:Service
metadata:
name:openclaw-gateway
namespace:openclaw
spec:
type:ClusterIP
ports:
    -port:18789
      targetPort:18789
selector:
    app:openclaw
    component:gateway

---
# --- Service: vLLM ---
apiVersion:v1
kind:Service
metadata:
name:vllm-service
namespace:openclaw
spec:
type:ClusterIP
ports:
    -port:8000
      targetPort:8000
selector:
    app:openclaw
    component:vllm

---
# --- Ingress ---
apiVersion:networking.k8s.io/v1
kind:Ingress
metadata:
name:openclaw-gateway
namespace:openclaw
annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout:"3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout:"3600"
    nginx.ingress.kubernetes.io/proxy-http-version:"1.1"
    nginx.ingress.kubernetes.io/proxy-body-size:"50m"
    cert-manager.io/cluster-issuer:"letsencrypt-prod"
spec:
ingressClassName:nginx
tls:
    -hosts:[openclaw.example.com]
      secretName:openclaw-tls
rules:
    -host:openclaw.example.com
      http:
        paths:
          -path:/
            pathType:Prefix
            backend:
              service:
                name:openclaw-gateway
                port:
                  number:18789

部署命令：

# 先替换 Token（手动或用 envsubst）
export GATEWAY_TOKEN=$(openssl rand -hex 32)
sed -i "s/REPLACE_WITH_RANDOM_TOKEN/${GATEWAY_TOKEN}/g" openclaw-all-in-one.yaml

# 一键部署
kubectl apply -f openclaw-all-in-one.yaml

# 查看部署状态
kubectl get all -n openclaw

3.3 openclaw.json 生产配置

完整的生产级配置文件，包含 vLLM Provider、Qwen3.5 模型和多 Provider 路由：

// ~/.openclaw/openclaw.json
// 生产环境配置 - 多 Provider 路由 + vLLM 推理后端
{
  gateway: {
    // 监听地址，容器环境用 0.0.0.0
    bind: "0.0.0.0:18789",

    auth: {
      // 每个接入方使用独立 Token
      // 通过 openclaw CLI 管理多 Token
      token: "oc-prod-<your-random-token-here>"
    },

    // 请求限流配置
    rateLimit: {
      // 每分钟最大请求数
      maxRequestsPerMinute: 600,
      // 单个 Token 每分钟最大请求数
      maxRequestsPerMinutePerToken: 60
    }
  },

  models: {
    // 默认模型（不指定模型时使用）
    default: "vllm-local/Qwen3.5-35B",

    providers: {
      // 主力推理后端：vLLM + Qwen3.5
      "vllm-local": {
        baseUrl: "http://vllm-service.openclaw.svc.cluster.local:8000/v1",
        api: "openai-responses",
        models: [
          "Qwen/Qwen3.5-35B-A3B-FP8"
        ]
      },

      // 代码生成专用后端（可选）
      "vllm-code": {
        baseUrl: "http://vllm-code.openclaw.svc.cluster.local:8000/v1",
        api: "openai-responses",
        models: [
          "Qwen/Qwen3-Coder-30B-A3B-FP8"
        ]
      },

      // 备用云端 Provider（可选，用于降级）
      "openai-cloud": {
        baseUrl: "https://api.openai.com/v1",
        api: "openai-responses",
        apiKey: "${OPENAI_API_KEY}",
        models: [
          "gpt-4o",
          "gpt-4o-mini"
        ]
      }
    }
  },

  // 日志配置
  logging: {
    level: "info",
    // 生产环境建议 JSON 格式，方便 ELK/Loki 采集
    format: "json"
  }
}

3.4 案例一：企业微信 / Telegram 多渠道接入

场景描述：公司同时使用企业微信（内部沟通）和 Telegram（海外团队），需要同一个 AI 助手在两个平台上提供服务。OpenClaw 作为网关统一接入，后端共用同一个 vLLM 推理实例。

架构图：

企业微信 Bot ──→ Webhook ──→ OpenClaw Gateway (:18789) ──→ vLLM (:8000)
Telegram Bot ──→ Webhook ──↗                                  ↓
                                                    Qwen3.5-35B-A3B-FP8

实现步骤：

1. 在企业微信管理后台创建应用，获取 CorpID、AgentID、Secret
2. 在 Telegram 通过 @BotFather 创建 Bot，获取 BOT_TOKEN
3. 配置 OpenClaw 渠道接入

// openclaw.json - 多渠道配置
{
  gateway: {
    bind: "0.0.0.0:18789",
    auth: {
      token: "oc-prod-<your-token>"
    }
  },

  // 渠道配置
  channels: {
    // 企业微信接入
    "wechat-work": {
      type: "wechat-work",
      corpId: "ww1234567890abcdef",
      agentId: 1000002,
      secret: "${WECHAT_WORK_SECRET}",
      token: "${WECHAT_WORK_TOKEN}",
      encodingAesKey: "${WECHAT_WORK_AES_KEY}",
      // 消息回调地址：https://openclaw.example.com/webhook/wechat-work
      webhookPath: "/webhook/wechat-work"
    },

    // Telegram 接入
    "telegram": {
      type: "telegram",
      botToken: "${TELEGRAM_BOT_TOKEN}",
      // 消息回调地址：https://openclaw.example.com/webhook/telegram
      webhookPath: "/webhook/telegram"
    }
  },

  models: {
    default: "vllm-local/Qwen3.5-35B",
    providers: {
      "vllm-local": {
        baseUrl: "http://vllm-service.openclaw.svc.cluster.local:8000/v1",
        api: "openai-responses",
        models: ["Qwen/Qwen3.5-35B-A3B-FP8"]
      }
    }
  }
}

设置 Webhook 回调：

# Telegram：设置 Webhook URL
curl -s -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://openclaw.example.com/webhook/telegram"}'

# 企业微信：在管理后台「应用管理」→「接收消息」中配置
# URL: https://openclaw.example.com/webhook/wechat-work
# Token 和 EncodingAESKey 与 openclaw.json 中保持一致

验证：

# 验证 Telegram Webhook 状态
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo" | python3 -m json.tool

# 在企业微信中给 Bot 发消息，观察 OpenClaw 日志
kubectl logs -f -l app=openclaw,component=gateway -n openclaw

# 在 Telegram 中给 Bot 发消息，观察响应

3.5 案例二：K8s 多租户隔离部署

场景描述：公司有三个部门（研发部、市场部、客服部），每个部门需要独立的 AI 助手，使用不同的模型和配置。要求部门之间网络隔离，互不影响。

隔离方案：Namespace 隔离 + NetworkPolicy 网络隔离 + RBAC 权限隔离 + 独立 vLLM 实例。

3.5.1 Namespace 规划

# 创建部门级 Namespace
kubectl create namespace openclaw-dev      # 研发部
kubectl create namespace openclaw-marketing # 市场部
kubectl create namespace openclaw-support   # 客服部

# 打标签用于 NetworkPolicy 选择
kubectl label namespace openclaw-dev department=dev
kubectl label namespace openclaw-marketing department=marketing
kubectl label namespace openclaw-support department=support

3.5.2 NetworkPolicy：部门间网络隔离

# networkpolicy-isolation.yaml
# 默认拒绝所有跨 Namespace 流量，只允许同 Namespace 内通信

# 研发部 NetworkPolicy
apiVersion:networking.k8s.io/v1
kind:NetworkPolicy
metadata:
name:deny-cross-namespace
namespace:openclaw-dev
spec:
podSelector:{}
policyTypes:
    -Ingress
    -Egress
ingress:
    # 允许同 Namespace 内 Pod 互访
    -from:
        -podSelector:{}
    # 允许 Ingress Controller 访问（必须，否则外部请求进不来）
    -from:
        -namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name:ingress-nginx
egress:
    # 允许同 Namespace 内 Pod 互访
    -to:
        -podSelector:{}
    # 允许 DNS 查询
    -to:
        -namespaceSelector:{}
          podSelector:
            matchLabels:
              k8s-app:kube-dns
      ports:
        -protocol:UDP
          port:53
        -protocol:TCP
          port:53
    # 允许访问外部网络（模型下载、API 调用）
    -to:
        -ipBlock:
            cidr:0.0.0.0/0
            except:
              -10.0.0.0/8
              -172.16.0.0/12
              -192.168.0.0/16
---
# 市场部和客服部使用相同模板，修改 namespace 即可
apiVersion:networking.k8s.io/v1
kind:NetworkPolicy
metadata:
name:deny-cross-namespace
namespace:openclaw-marketing
spec:
podSelector:{}
policyTypes:[Ingress,Egress]
ingress:
    -from:
        -podSelector:{}
    -from:
        -namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name:ingress-nginx
egress:
    -to:
        -podSelector:{}
    -to:
        -namespaceSelector:{}
          podSelector:
            matchLabels:
              k8s-app:kube-dns
      ports:
        -{protocol:UDP,port:53}
        -{protocol:TCP,port:53}
    -to:
        -ipBlock:
            cidr:0.0.0.0/0
            except:[10.0.0.0/8,172.16.0.0/12,192.168.0.0/16]

3.5.3 RBAC：部门管理员权限

# rbac-dev-admin.yaml
# 研发部管理员只能管理自己 Namespace 的资源
apiVersion:rbac.authorization.k8s.io/v1
kind:Role
metadata:
name:openclaw-admin
namespace:openclaw-dev
rules:
-apiGroups:["","apps","networking.k8s.io"]
    resources:["pods","services","deployments","configmaps","ingresses"]
    verbs:["get","list","watch","create","update","patch"]
-apiGroups:[""]
    resources:["pods/log"]
    verbs:["get","list"]
# 禁止删除操作和 Secret 访问
-apiGroups:[""]
    resources:["secrets"]
    verbs:["get","list"]
---
apiVersion:rbac.authorization.k8s.io/v1
kind:RoleBinding
metadata:
name:dev-admin-binding
namespace:openclaw-dev
subjects:
-kind:User
    name:dev-admin@company.com
    apiGroup:rbac.authorization.k8s.io
roleRef:
kind:Role
name:openclaw-admin
apiGroup:rbac.authorization.k8s.io

3.5.4 各部门独立部署

每个部门在自己的 Namespace 部署独立的 OpenClaw Gateway + vLLM 实例。以研发部为例：

# 部署研发部实例
# 1. 生成独立 Token
DEV_TOKEN=$(openssl rand -hex 32)

# 2. 创建 Secret
kubectl create secret generic openclaw-secrets \
  --namespace=openclaw-dev \
  --from-literal=gateway-token="${DEV_TOKEN}"

# 3. 部署（使用 all-in-one 模板，修改 namespace）
sed 's/namespace: openclaw/namespace: openclaw-dev/g' openclaw-all-in-one.yaml | \
  kubectl apply -f -

# 4. 验证
kubectl get all -n openclaw-dev

部门间完全隔离：不同 Token、不同网络策略、不同模型配置、不同资源配额。研发部的请求不会路由到市场部的 vLLM，市场部的 Pod 也无法访问研发部的服务。

3.5.5 ResourceQuota：资源配额限制

# resourcequota-dev.yaml
apiVersion:v1
kind:ResourceQuota
metadata:
name:openclaw-quota
namespace:openclaw-dev
spec:
hard:
    requests.cpu:"16"
    requests.memory:"128Gi"
    limits.cpu:"32"
    limits.memory:"256Gi"
    requests.nvidia.com/gpu:"4"
    persistentvolumeclaims:"5"
    pods:"10"
---
# 市场部配额（不需要 GPU，使用云端 API）
apiVersion:v1
kind:ResourceQuota
metadata:
name:openclaw-quota
namespace:openclaw-marketing
spec:
hard:
    requests.cpu:"4"
    requests.memory:"8Gi"
    limits.cpu:"8"
    limits.memory:"16Gi"
    requests.nvidia.com/gpu:"0"
    persistentvolumeclaims:"3"
    pods:"5"

市场部只部署 OpenClaw Gateway，模型对接云端 API（如 OpenAI），不需要 GPU 资源。研发部自带 vLLM + GPU，资源配额更高。这样既满足了不同部门的需求差异，又避免了资源争抢。

四、最佳实践和注意事项

4.1 最佳实践

4.1.1 性能优化

# Deployment 中添加环境变量
env:
  -name:UV_THREADPOOL_SIZE
    value:"16"
  -name:NODE_OPTIONS
    value:"--max-old-space-size=1536"

args:
  -"--max-num-seqs=128"
  -"--max-num-batched-tokens=32768"
  -"--enable-chunked-prefill"

resources:
  requests:
    cpu:"500m"      # limit 的 25%
    memory:"2Gi"    # 和 limit 相同
  limits:
    cpu:"2000m"
    memory:"2Gi"

4.1.2 安全加固

# token-rotation-cronjob.yaml
apiVersion:batch/v1
kind:CronJob
metadata:
name:token-rotation
namespace:openclaw
spec:
schedule:"0 2 1 */3 *"# 每季度 1 号凌晨 2 点执行
jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName:token-rotator
          containers:
            -name:rotate
              image:bitnami/kubectl:latest
              command:["/bin/sh","-c"]
              args:
                -|
                  NEW_TOKEN=$(openssl rand -hex 32)
                  kubectl create secret generic openclaw-secrets \
                    --namespace=openclaw \
                    --from-literal=gateway-token="${NEW_TOKEN}" \
                    --dry-run=client -o yaml | kubectl apply -f -
                  kubectl rollout restart deployment/openclaw-gateway -n openclaw
                  echo "Token rotated at $(date). New token prefix: ${NEW_TOKEN:0:8}..."
          restartPolicy:OnFailure

# networkpolicy-gateway.yaml
apiVersion:networking.k8s.io/v1
kind:NetworkPolicy
metadata:
name:gateway-policy
namespace:openclaw
spec:
podSelector:
    matchLabels:
      component:gateway
policyTypes:[Ingress,Egress]
ingress:
    -from:
        -namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name:ingress-nginx
      ports:
        -port:18789
egress:
    # 允许访问 vLLM Service
    -to:
        -podSelector:
            matchLabels:
              component:vllm
      ports:
        -port:8000
    # 允许 DNS
    -to:
        -namespaceSelector:{}
          podSelector:
            matchLabels:
              k8s-app:kube-dns
      ports:
        -{protocol:UDP,port:53}
        -{protocol:TCP,port:53}

• RBAC 最小权限原则：运维人员使用 ClusterRole，开发人员只给 Namespace 级别 Role。Secret 的 get 权限要谨慎分配，能用 list 就别给 get（list 只返回 Secret 名称，get 会返回内容）。

• TLS 全链路加密：Ingress 到 Gateway 走 HTTPS（cert-manager 自动签发），Gateway 到 vLLM 在集群内部走 HTTP（性能考虑）。如果安全要求极高，可以用 Service Mesh（Istio/Linkerd）实现集群内部 mTLS。

4.1.3 高可用配置

# pdb.yaml
apiVersion:policy/v1
kind:PodDisruptionBudget
metadata:
name:openclaw-gateway-pdb
namespace:openclaw
spec:
minAvailable:1
selector:
    matchLabels:
      app:openclaw
      component:gateway

# hpa.yaml
apiVersion:autoscaling/v2
kind:HorizontalPodAutoscaler
metadata:
name:openclaw-gateway-hpa
namespace:openclaw
spec:
scaleTargetRef:
    apiVersion:apps/v1
    kind:Deployment
    name:openclaw-gateway
minReplicas:2
maxReplicas:8
metrics:
    -type:Resource
      resource:
        name:cpu
        target:
          type:Utilization
          averageUtilization:70
    -type:Resource
      resource:
        name:memory
        target:
          type:Utilization
          averageUtilization:80
behavior:
    scaleUp:
      stabilizationWindowSeconds:60
      policies:
        -type:Pods
          value:2
          periodSeconds:60
    scaleDown:
      stabilizationWindowSeconds:300
      policies:
        -type:Pods
          value:1
          periodSeconds:120

• vLLM 高可用：vLLM 本身是有状态服务（GPU 显存中有模型权重），不支持多副本负载均衡。高可用方案是部署 2 个独立的 vLLM 实例（不同 Deployment），在 OpenClaw 配置多 Provider，主 Provider 故障时手动切换到备用 Provider。未来可以用 OpenClaw 的 Provider 健康检查实现自动故障转移。

4.2 注意事项

4.2.1 配置注意事项

uid 1000 权限问题：这是新手踩得最多的坑。OpenClaw 容器以 node 用户（uid 1000）运行，如果宿主机目录的 owner 不是 1000，容器内写入会报 EACCES: permission denied。

# 修复权限（Docker 方案）
sudo chown -R 1000:1000 ./config ./workspace

# K8s 方案通过 fsGroup 自动处理
# spec.securityContext.fsGroup: 1000

bind 地址配置：容器内必须 bind 0.0.0.0，别写 127.0.0.1。写 127.0.0.1 只能容器内部访问，外部请求过来全是 connection refused。这个错误在日志里不会报错，排查起来很头疼。

配置热重载：OpenClaw 目前不支持配置文件热重载，修改 openclaw.json 后需要重启服务才能生效。K8s 环境下 kubectl rollout restart deployment/openclaw-gateway -n openclaw 就行，Docker 环境 docker compose restart openclaw-gateway。

4.2.2 常见错误

4.2.3 兼容性问题

# 检查 Device Plugin 是否安装
kubectl get ds -n kube-system | grep nvidia

# 如果没有，安装
kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.17.0/deployments/static/nvidia-device-plugin.yml

• Container Runtime：containerd 1.7+ 和 Docker 24+ 都支持 GPU 直通。CRI-O 需要额外配置 nvidia-container-runtime。

五、故障排查和监控

5.1 故障排查

5.1.1 日志查看

# K8s 环境：查看 Gateway 日志
kubectl logs -f -l app=openclaw,component=gateway -n openclaw

# K8s 环境：查看 vLLM 日志
kubectl logs -f -l app=openclaw,component=vllm -n openclaw

# K8s 环境：查看崩溃前的日志（Pod 重启后之前的日志会丢失）
kubectl logs <pod-name> -n openclaw --previous

# Docker 环境：查看实时日志
docker compose logs -f openclaw-gateway
docker compose logs -f vllm

# 容器内日志路径（如果需要进容器看）
# OpenClaw: /home/node/.openclaw/logs/
# vLLM: 标准输出（无文件日志，靠容器日志驱动收集）

# 过滤错误日志
kubectl logs -l component=gateway -n openclaw | grep -i "error\|fatal\|exception"

5.1.2 常见问题排查

问题一：Gateway Pod 状态 Pending，无法调度

# 诊断：查看 Pod 事件
kubectl describe pod -l component=gateway -n openclaw | tail -20

# 常见原因
# 1. PVC 无法绑定（storageClassName 不存在）
kubectl get pvc -n openclaw
kubectl get storageclass

# 2. 资源不足（CPU/内存不够）
kubectl describe nodes | grep -A 5 "Allocated resources"

# 3. nodeSelector 不匹配
kubectl get nodes --show-labels

解决方案：

1. PVC Pending → 检查 StorageClass 是否存在，是否有可用 PV。云环境检查 CSI Driver 是否正常
2. 资源不足 → 降低 resource requests，或扩容节点
3. nodeSelector 不匹配 → kubectl label node <node-name> gpu-type=a100

问题二：vLLM Pod OOMKilled

# 诊断：查看 Pod 终止原因
kubectl get pod -l component=vllm -n openclaw -o jsonpath='{.items[0].status.containerStatuses[0].lastState.terminated.reason}'

# 查看节点内存使用
kubectl top nodes

# 查看 Pod 内存使用趋势
kubectl top pod -l component=vllm -n openclaw

解决方案：

1. 系统内存 OOM → 增加 Pod memory limit，确保节点物理内存充足（建议 4 倍 GPU 显存）
2. GPU 显存 OOM → 降低 gpu-memory-utilization 到 0.85，减小 max-model-len，或增加 tensor-parallel-size
3. /dev/shm 不足 → 确认 emptyDir 的 sizeLimit 足够大（建议 16Gi+）

问题三：Token 认证失败，返回 401

# 诊断：确认配置的 Token 值
kubectl get secret openclaw-secrets -n openclaw -o jsonpath='{.data.gateway-token}' | base64 -d

# 确认 ConfigMap 中的占位符已被替换
kubectl exec -it <gateway-pod> -n openclaw -- cat /home/node/.openclaw/openclaw.json | grep token

# 测试请求
curl -v -H "Authorization: Bearer <token>" http://localhost:18789/healthz

解决方案：

1. 确认请求头格式：Authorization: Bearer <token>，注意 Bearer 后面有空格
2. 确认 initContainer 的 sed 替换逻辑正确执行了（查看 initContainer 日志）
3. 如果 Secret 更新了但 Pod 没重启，Token 不会自动生效。执行 kubectl rollout restart deployment/openclaw-gateway -n openclaw

5.1.3 调试模式

# OpenClaw 开启 debug 日志
# 方法一：环境变量
kubectl set env deployment/openclaw-gateway -n openclaw DEBUG=openclaw:*

# 方法二：修改 ConfigMap 中的 logging.level
kubectl edit configmap openclaw-config -n openclaw
# 将 "level": "info" 改为 "level": "debug"
# 然后重启
kubectl rollout restart deployment/openclaw-gateway -n openclaw

# vLLM 开启详细日志
# 在 args 中添加 --log-level=debug
kubectl edit deployment/vllm-inference -n openclaw

# 进入容器交互式调试
kubectl exec -it <gateway-pod> -n openclaw -- /bin/bash
# 容器内检查网络连通性
curl -s http://vllm-service:8000/health
# 容器内查看进程状态
ps aux
# 容器内查看内存使用
node -e "console.log(process.memoryUsage())"

5.2 性能监控

5.2.1 关键指标监控

# Gateway 基础监控
# CPU 使用率
kubectl top pod -l component=gateway -n openclaw

# 内存使用
kubectl top pod -l component=gateway -n openclaw

# 网络连接数（进入容器内查看）
kubectl exec -it <gateway-pod> -n openclaw -- ss -s

# vLLM 推理性能指标（vLLM 内置 metrics 端点）
curl -s http://vllm-service:8000/metrics

# 关键 vLLM 指标
curl -s http://vllm-service:8000/metrics | grep -E "vllm:num_requests|vllm:gpu_cache|vllm:avg_generation"

5.2.2 监控指标说明

5.2.3 Prometheus 监控告警配置

# prometheus-rules.yaml
apiVersion:monitoring.coreos.com/v1
kind:PrometheusRule
metadata:
name:openclaw-alerts
namespace:openclaw
labels:
    release:prometheus
spec:
groups:
    -name:openclaw-gateway
      rules:
        # Gateway Pod 挂了
        -alert:OpenClawGatewayDown
          expr:up{job="openclaw-gateway"}==0
          for:1m
          labels:
            severity:critical
          annotations:
            summary:"OpenClaw Gateway 实例不可用"
            description:"{{ $labels.pod }} 已停止响应超过 1 分钟"

        # Gateway 内存使用过高
        -alert:OpenClawGatewayHighMemory
          expr:|
            container_memory_working_set_bytes{namespace="openclaw", container="gateway"}
            / container_spec_memory_limit_bytes{namespace="openclaw", container="gateway"}
            > 0.85
          for:5m
          labels:
            severity:warning
          annotations:
            summary:"OpenClaw Gateway 内存使用超过 85%"
            description:"{{ $labels.pod }} 内存使用 {{ $value | humanizePercentage }}"

        # Gateway 重启次数过多
        -alert:OpenClawGatewayRestarts
          expr:|
            increase(kube_pod_container_status_restarts_total{
              namespace="openclaw", container="gateway"
            }[1h]) > 3
          labels:
            severity:warning
          annotations:
            summary:"OpenClaw Gateway 1 小时内重启超过 3 次"

    -name:openclaw-vllm
      rules:
        # vLLM GPU 显存使用过高
        -alert:VllmGpuMemoryHigh
          expr:|
            vllm:gpu_cache_usage_perc > 0.90
          for:10m
          labels:
            severity:warning
          annotations:
            summary:"vLLM GPU KV Cache 使用率超过 90%"
            description:"KV Cache 使用率 {{ $value | humanizePercentage }}，新请求可能排队"

        # vLLM 请求队列积压
        -alert:VllmQueueBacklog
          expr:|
            vllm:num_requests_waiting > 50
          for:5m
          labels:
            severity:warning
          annotations:
            summary:"vLLM 请求队列积压超过 50"
            description:"等待处理的请求数: {{ $value }}"

        # vLLM 推理延迟过高
        -alert:VllmHighLatency
          expr:|
            histogram_quantile(0.95,
              rate(vllm:e2e_request_latency_seconds_bucket[5m])
            ) > 30
          for:5m
          labels:
            severity:warning
          annotations:
            summary:"vLLM P95 推理延迟超过 30 秒"