灼眼者的官方网站

第六章：网关服务与运维

网关服务架构

OpenClaw 网关是整个系统的统一入口，负责接收来自不同平台的消息请求，并将其路由到对应的机器人实例进行处理。网关层的设计遵循微服务架构的最佳实践，实现了关注点分离和水平扩展能力。

网关的核心职责包括：

统一入口：屏蔽后端多机器人实例的复杂性，对外提供统一的 API 端点
协议转换：将不同平台的消息格式转换为内部统一的消息模型
路由分发：根据消息来源和目标，将请求路由到正确的处理单元
负载均衡：在多个机器人实例之间分发请求，避免单点过载

配置示例详解

OpenClaw 网关的配置通过 gateway.config.ts 文件进行管理。以下是一个完整的生产环境配置示例：

import { defineGatewayConfig } from 'openclaw/gateway';

export default defineGatewayConfig({
  server: {
    port: 443,
    host: '0.0.0.0',
    ssl: {
      enabled: true,
      cert: '/etc/letsencrypt/live/api.example.com/fullchain.pem',
      key: '/etc/letsencrypt/live/api.example.com/privkey.pem',
    },
  },
  rateLimit: {
    windowMs: 60 * 1000,
    maxRequests: 100,
  },
  auth: {
    type: 'jwt',
    secret: process.env.GATEWAY_JWT_SECRET,
    expiresIn: '24h',
  },
  upstream: [
    {
      name: 'support-bot',
      target: 'http://localhost:3001',
      weight: 3,
      healthCheck: '/health',
    },
    {
      name: 'assistant-bot',
      target: 'http://localhost:3002',
      weight: 2,
      healthCheck: '/health',
    },
  ],
});

端口与 SSL 配置

端口配置决定了网关监听的网络端口。开发环境通常使用 3000 端口，而生产环境建议直接使用 443 端口（HTTPS）并启用 SSL 加密。注意，如果使用 443 或 80 等特权端口，需要以 root 权限运行或配置能力授权。

认证配置

网关支持多种认证方式：

认证方式	适用场景	安全等级	配置复杂度
JWT	Web 应用、API 调用	高	中等
API Key	服务间通信	中	低
Basic Auth	内部调试	低	低
OAuth 2.0	企业集成	高	高

推荐生产环境使用 JWT 或 OAuth 2.0 认证，并结合 IP 白名单实现多层防护。

SSL 证书部署

SSL 证书是保障通信安全的基础。对于生产环境，推荐使用 Let's Encrypt 免费证书并通过 Certbot 实现自动续签。

# 安装 Certbot
sudo apt install certbot

# 申请证书
sudo certbot certonly --standalone \
  -d api.example.com \
  --non-interactive \
  --agree-tos \
  -m [email protected]

# 验证证书文件
ls -la /etc/letsencrypt/live/api.example.com/

Let's Encrypt 自动续签

Let's Encrypt 证书有效期为 90 天，需要定期续签。配置 crontab 实现自动续签和网关重启：

# 每两个月执行一次续签
0 3 1 */2 * certbot renew --quiet \
  && docker restart openclaw-gateway

# 或者使用 systemd timer
sudo systemctl enable certbot-renew.timer

安全配置最佳实践

生产环境的安全防护需要从多个层面入手：

请求限流：为每个客户端 IP 设置请求频率上限，防止恶意攻击
请求体大小限制：限制最大请求体为 10MB，防止大 payload 攻击
CORS 配置：严格限制允许的跨域来源，禁止使用通配符
Header 安全加固：配置 CSP、X-Frame-Options 等安全相关的 HTTP 头
IP 白名单：管理后台接口仅允许内网或 VPN 地址访问
日志审计：记录所有认证失败和异常请求，便于追溯问题

故障排除常见问题

问题现象	可能原因	解决方案
连接超时	后端服务未启动	检查上游服务健康状态，确认 target 地址正确
SSL 握手失败	证书过期或配置错误	检查 cert/key 路径，运行 certbot renew
请求被限流	短时间内请求过多	调整 rateLimit 参数，检查是否有异常流量
路由 404	路由规则配置错误	检查路由前缀和匹配规则
Webhook 签名验证失败	Token 不匹配	在平台后台重新配置 Webhook Secret

实战：部署生产级网关

下面演示一个完整的生产级网关部署流程：

# docker-compose.gateway.yml
version: '3.8'
services:
  gateway:
    image: openclaw/gateway:latest
    ports:
      - '443:443'
      - '80:80'
    environment:
      - GATEWAY_JWT_SECRET=${GATEWAY_JWT_SECRET}
      - NODE_ENV=production
    volumes:
      - ./gateway.config.ts:/app/gateway.config.ts
      - /etc/letsencrypt:/etc/letsencrypt:ro
      - ./logs:/app/logs
    depends_on:
      - support-bot
      - assistant-bot
    restart: unless-stopped
    logging:
      driver: 'json-file'
      options:
        max-size: '10m'
        max-file: '3'

  support-bot:
    image: openclaw/bot:latest
    environment:
      - BOT_TYPE=customer-support
      - MODEL_API_KEY=${MODEL_API_KEY}
    volumes:
      - ./bots/support:/app/bot
    expose:
      - '3001'
    restart: unless-stopped

  assistant-bot:
    image: openclaw/bot:latest
    environment:
      - BOT_TYPE=assistant
      - MODEL_API_KEY=${MODEL_API_KEY}
    volumes:
      - ./bots/assistant:/app/bot
    expose:
      - '3002'
    restart: unless-stopped

部署完成后，使用 docker-compose -f docker-compose.gateway.yml up -d 启动服务，并通过 docker-compose logs -f gateway 监控网关日志。一个精心配置的网关不仅能保证系统稳定运行，还能在流量高峰时提供可靠的服务质量保障。