Gateway 认证机制详解

为什么需要认证

OpenClaw Gateway 暴露的 API 端点如果不加保护，任何人都可以发送请求消耗你的模型额度或访问敏感数据。认证机制确保只有授权的客户端才能访问 Gateway 服务。

认证方式概览

OpenClaw 支持多种认证方式：

API Key 认证：简单直接，适合内部使用
JWT Token 认证：适合与 Web 应用集成
OAuth 2.0：适合企业级集成
Webhook 签名验证：用于频道 Webhook 安全

API Key 认证

最基础的认证方式，通过请求头传递 API Key：

{
  "security": {
    "auth": {
      "type": "api-key",
      "keys": [
        {
          "name": "admin",
          "key": "{{GATEWAY_ADMIN_KEY}}",
          "permissions": ["*"]
        },
        {
          "name": "readonly",
          "key": "{{GATEWAY_READ_KEY}}",
          "permissions": ["read", "chat"]
        }
      ]
    }
  }
}

生成 API Key：

openclaw secrets set GATEWAY_ADMIN_KEY "$(openssl rand -hex 32)"
openclaw secrets set GATEWAY_READ_KEY "$(openssl rand -hex 32)"

客户端使用：

curl -H "Authorization: Bearer your-api-key" \
  https://gateway.example.com/api/chat

权限控制

为不同的 API Key 分配不同权限：

{
  "security": {
    "auth": {
      "keys": [
        {
          "name": "full-access",
          "key": "{{KEY_FULL}}",
          "permissions": ["*"]
        },
        {
          "name": "chat-only",
          "key": "{{KEY_CHAT}}",
          "permissions": ["chat"]
        },
        {
          "name": "admin",
          "key": "{{KEY_ADMIN}}",
          "permissions": ["admin", "config", "secrets"]
        }
      ]
    }
  }
}

可用权限列表：

chat：发送和接收消息
read：读取配置和状态
admin：管理配置和用户
config：修改配置
secrets：管理密钥
*：所有权限

JWT 认证

配置 JWT Token 认证：

{
  "security": {
    "auth": {
      "type": "jwt",
      "jwt": {
        "secret": "{{JWT_SECRET}}",
        "algorithm": "HS256",
        "issuer": "openclaw",
        "expiresIn": "24h",
        "claims": {
          "requiredClaims": ["sub", "role"]
        }
      }
    }
  }
}

生成 JWT Token：

openclaw auth token --user admin --role admin --expires 24h

Webhook 签名验证

确保频道 Webhook 请求来自合法来源：

{
  "channels": {
    "telegram": {
      "webhookSecret": "{{TELEGRAM_WEBHOOK_SECRET}}",
      "verifySignature": true
    }
  }
}

IP 白名单

限制可以访问 Gateway 的 IP 地址：

{
  "security": {
    "ipWhitelist": {
      "enabled": true,
      "addresses": [
        "10.0.0.0/8",
        "192.168.1.0/24",
        "203.0.113.50"
      ]
    }
  }
}

CORS 配置

控制哪些域名可以访问 Gateway API：

{
  "gateway": {
    "cors": {
      "origins": ["https://your-app.com"],
      "methods": ["GET", "POST"],
      "headers": ["Authorization", "Content-Type"],
      "credentials": true
    }
  }
}

速率限制与认证结合

为不同认证级别设置不同的速率限制：

{
  "security": {
    "rateLimit": {
      "authenticated": {
        "maxRequests": 100,
        "window": 60
      },
      "unauthenticated": {
        "maxRequests": 10,
        "window": 60
      }
    }
  }
}

审计日志

记录所有认证相关事件：

{
  "security": {
    "audit": {
      "enabled": true,
      "events": ["auth.success", "auth.failure", "auth.token.created"],
      "logFile": "~/.openclaw/logs/auth-audit.log"
    }
  }
}

查看认证审计日志：

openclaw security audit --filter auth --since "24h"

故障排查

401 Unauthorized：

检查 API Key 是否正确
检查 Authorization 头格式是否为 Bearer <key>

403 Forbidden：

API Key 有效但权限不足
检查 Key 的 permissions 配置

IP 被拒绝：

检查 IP 白名单配置
确认客户端实际 IP（注意代理和负载均衡器的影响）

总结

Gateway 认证是保护 OpenClaw 服务安全的第一道防线。根据使用场景选择合适的认证方式：内部使用选 API Key，Web 集成选 JWT，企业级集成选 OAuth。无论哪种方式，都建议配合 IP 白名单和速率限制使用。