安全概览
安全是 OpenClaw Gateway 设计的核心关注点。本文档概述 Gateway 的整体安全架构和各层防护机制。
安全模型
Gateway 采用纵深防御（Defense in Depth）策略，通过多层安全机制协同保护：
text
┌─────────────────────────────────────────┐
│ 网络安全层 │
│ TLS 加密 · 防火墙 · 可信代理 │
│ ┌─────────────────────────────────┐ │
│ │ 认证层 │ │
│ │ Token · 密码 · 设备配对 │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ 授权层 │ │ │
│ │ │ 工具策略 · 沙箱 · 提权 │ │ │
│ │ │ ┌─────────────────┐ │ │ │
│ │ │ │ 数据保护层 │ │ │ │
│ │ │ │ 密钥加密存储 │ │ │ │
│ │ │ │ 日志脱敏 │ │ │ │
│ │ │ └─────────────────┘ │ │ │
│ │ └─────────────────────────┘ │ │
│ └─────────────────────────────────┘ │
└─────────────────────────────────────────┘认证层
认证（Authentication）确认"你是谁"。
支持的认证方式
| 方式 | 说明 | 适用场景 |
|---|---|---|
| Token | 环境变量 OPENCLAW_GATEWAY_TOKEN | 推荐 — 程序化访问 |
| 密码 | 交互式密码验证 | 人工操作 |
| 设备配对 | 新设备安全接入流程 | 多设备环境 |
| 可信代理 | 反向代理委托认证 | 企业部署 |
首帧认证
所有 WebSocket 连接的第一帧必须是 connect 认证消息。未认证的连接在超时后自动断开。
速率限制
连续认证失败会触发速率限制（Rate Limiting），防止暴力破解（Brute Force）攻击：
json5
{
"gateway": {
"auth": {
"rateLimitAttempts": 5, // 5 次失败后锁定
"rateLimitWindow": 60 // 锁定 60 秒
}
}
}详见 认证。
授权层
授权（Authorization）确认"你能做什么"。
三大安全机制
Gateway 提供三种互补的授权机制：
| 机制 | 作用 | 粒度 |
|---|---|---|
| 沙箱 (Sandbox) | 隔离执行环境 | 进程级 |
| 工具策略 (Tool Policy) | 控制可用工具 | 工具级 |
| 提权 (Elevated) | 临时授予额外权限 | 操作级 |
text
用户请求 → 工具策略检查 → 沙箱执行 → 结果返回
│
├─ 允许 → 直接执行
├─ 需审批 → 等待用户确认
└─ 拒绝 → 返回错误详见 沙箱 vs 工具策略 vs 提权。
沙箱模式
| 模式 | 说明 |
|---|---|
off | 不使用沙箱（⚠️ 不推荐） |
standard | 标准沙箱，限制文件和网络访问 |
strict | 严格沙箱，最小权限原则 |
详见 沙箱机制。
数据保护
密钥管理
API Key 和敏感凭证通过加密存储（Encrypted Storage）管理，不以明文保存在配置文件中。
bash
# 安全存储密钥
openclaw secrets set OPENAI_API_KEY "sk-..."
# 在配置中引用（不暴露明文）
# "apiKey": "${OPENAI_API_KEY}"详见 密钥管理。
日志脱敏
Gateway 日志自动脱敏（Redaction）以下敏感信息：
- API Key 和 Token
- 用户对话内容（可配置）
- 密码和凭证
text
[INFO] Channel connected: openai (apiKey: sk-...****7f2a)
[INFO] Auth success: token=****89ab device=MacBook传输加密
| 场景 | 加密 | 说明 |
|---|---|---|
| 本地连接 | 不需要 | Loopback 不经过网络 |
| 局域网 | 可选 | Tailscale 提供端到端加密 |
| 远程连接 | 必须 | 通过反向代理提供 TLS |
网络安全
默认安全
Gateway 默认配置遵循最小暴露原则：
- ✅ 仅绑定
127.0.0.1 - ✅ 需要 Token 认证
- ✅ 启用标准沙箱
- ✅ 命令执行需要审批
防火墙建议
bash
# 仅允许必要端口
sudo ufw default deny incoming
sudo ufw allow 443/tcp # HTTPS（反向代理）
sudo ufw deny 18789/tcp # 禁止直接访问 Gateway可信代理
通过反向代理进行认证委托：
json5
{
"security": {
"trustedProxy": {
"enabled": true,
"headers": ["X-Forwarded-For", "X-Real-IP"]
}
}
}详见 可信代理认证。
安全检查清单
开发环境
- [x] 使用默认 loopback 绑定
- [x] 设置 Gateway Token
- [x] 启用标准沙箱
生产环境
- [x] 配置强 Token（32+ 字符）
- [x] 启用 TLS 加密
- [x] 配置反向代理
- [x] 启用严格沙箱
- [x] 配置防火墙规则
- [x] 限制认证失败次数
- [x] 定期审查设备列表
- [x] 配置日志监控与告警
安全审计
定期使用 openclaw doctor 检查安全配置。该命令会自动识别常见的安全风险并给出修复建议。