OpenClaw "Pairing Required" 机制详解

holidaypenguin
9 阅读5分钟

🔐 OpenClaw "Pairing Required" 机制详解

一、这是什么问题？

当您通过 非本地地址（如 https://192.168.195.130）访问 Control UI 时，OpenClaw 会要求您进行设备配对，提示 "pairing required"。

二、为什么需要这个机制？

🔍 安全背景

OpenClaw 是一个个人助理系统，可以：

  • 📁 访问您的文件
  • 💬 读取消息（QQ、邮件等）
  • 🔧 执行系统命令
  • 🌐 浏览网页、控制浏览器

如果任何知道 IP 的人都能访问，会导致严重的安全风险。

⚠️ 威胁场景

场景风险
局域网内其他设备扫描端口发现 Gateway
未经授权的设备连接获取您的控制权
中间人攻击窃听或篡改通信

三、配对机制的工作原理

🔄 配对流程图解

┌─────────────┐                    ┌──────────────────┐
│ 浏览器/客户端 │                   │ OpenClaw Gateway │
└──────┬──────┘                    └─────────┬─────────┘
       │                                     │
       │   1. 尝试连接 WebSocket              │
       ├────────────────────────────────────>│
       │                                     │
       │   2. 检查设备身份                    │
       │          (device identity)          │
       │                                     │
       │   3. 未找到已知设备 → 拒绝连接        │
       │<────────────────────────────────────┤
       │                                     │
       │   4. 显示 "pairing required"        │
       │                                     │
       │   5. 用户输入配对码或批准设备         │
       ├────────────────────────────────────>│
       │                                     │
       │   6. Gateway 保存设备指纹            │
       │          (token/cookie/证书)        │
       │<────────────────────────────────────┤
       │                                     │
       │   7. 连接成功 ✅                    │
       │                                     │

📝 技术实现

OpenClaw 使用以下方式验证设备身份：

  1. Token 认证：Gateway 配置中的 token（openclaw.json → gateway.auth.token）
  2. 设备指纹：浏览器 Cookie、LocalStorage、证书指纹等
  3. 配对表：已知设备的白名单（存储在 Gateways 本地）

当第一次访问时，这些凭证都不存在，所以需要配对。

四、这个机制的意义

✅ 安全价值

目标实现方式
防止未授权访问只有配对过的设备才能连接
防重放攻击每次连接都有唯一的 session token
防中间人攻击HTTPS + 双向验证
设备可见性可以查看哪些设备已配对（openclaw devices list）
撤销权限可以随时移除不信任的设备

🛡️ 与 SSH 对比

对比项OpenClaw PairingSSH 密钥认证
初始设置需要配对码/批准生成公钥对
存储方式服务端白名单客户端私钥
可视化有设备列表管理需手动检查 authorized_keys
撤销权限一键移除设备需编辑文件

五、其他解决办法/绕过方式

🎯 方案对比

方案 1: 使用 SSH 隧道（最安全）⭐⭐⭐
# 在客户端执行
ssh -L 18789:localhost:18789 user@YOUR_IP

# 然后访问 localhost
http://localhost:18789/chat?session=main

优点：

  • ✅ 浏览器认为来自 localhost（本地安全上下文）
  • ✅ 无需配对
  • ✅ SSH 加密传输
  • ✅ 不暴露 Gateway 端口到公网

缺点：

  • ❌ 需要 SSH 客户端
  • ❌ 每台设备都需要建立隧道
方案 2: Nginx 伪造 Host/Origin（已采用）⭐⭐
proxy_set_header Host localhost;
proxy_set_header Origin https://localhost:18789;

优点：

  • ✅ Gateway 认为请求来自本地
  • ✅ 无需配对
  • ✅ 可直接 HTTPS 访问

缺点：

  • ❌ 本质上绕过了安全验证
  • ❌ 任何知道 IP 的人都能访问（仅靠 Token 保护）
  • ⚠️ 降低安全性
方案 3: 正式配对（最规范）⭐⭐⭐
# 1. 查看待批准的设备
openclaw devices list

# 2. 批准特定设备
openclaw devices approve <device-id>

# 3. 或临时允许所有本地请求（不推荐）

优点：

  • ✅ 官方推荐方式
  • ✅ 保留审计日志
  • ✅ 可以随时撤销设备权限

缺点：

  • ❌ 每台新设备都需要配对
  • ❌ 需要命令行操作
方案 4: 关闭 Pairing 验证（不推荐）❌

目前没有配置项可以直接关闭 pairing 验证，因为这是 OpenClaw 核心安全机制。

但可以：

// openclaw.json - 仅信任特定域名
"gateway": {
  "controlUi": {
    "allowedOrigins": ["*"]  // ⚠️ 允许所有来源（非常危险）
  }
}

⚠️ 强烈不推荐：这会完全绕过安全检查。

方案 5: 使用 Let's Encrypt HTTPS + 正式配对（最佳实践）⭐⭐⭐⭐
步骤描述
1.申请域名（如 openclaw.yourdomain.com）
2.配置 A 记录指向服务器 IP
3.使用 Certbot 获取免费 SSL 证书
4.更新 Nginx 配置使用真实证书
5.首次访问时正式配对设备

优点：

  • ✅ 浏览器信任的证书（无警告）
  • ✅ 完整的安全验证流程
  • ✅ 支持跨域、移动端访问

📊 方案总结

方案安全性便利性适用场景
SSH 隧道🔒🔒🔒🔒🔒⚡⚡⭐️⭐️个人使用、临时访问
Nginx 伪造 Origin🔒🔒⭐️⭐️⭐️⚡⚡⚡⚡家庭局域网、信任环境
正式配对🔒🔒🔒🔒🔒⚡⚡⚡⭐️生产环境、多设备
Let's Encrypt + 配对🔒🔒🔒🔒🔒⚡⚡⚡⚡公网访问、专业部署

六、当前您的配置分析

✅ 已配置的安全措施

┌─────────────────────────────────────┐
│ 🔒 Layered Security (多层防护)        │
├─────────────────────────────────────┤
│ 1. Token 认证：8e3b7...54           │
│    → Gateway API 请求需要此 token   │
├─────────────────────────────────────┤
│ 2. HTTPS (自签名证书)                │
│    → 加密传输，防窃听               │
├─────────────────────────────────────┤
│ 3. UFW 防火墙                       │
│    → 18789 仅允许 192.168.0.0/16     │
├─────────────────────────────────────┤
│ 4. Device Pairing (已完成)          │
│    → 已批准设备：4f9db1...2464e     │
└─────────────────────────────────────┘

⚠️ 潜在风险点

风险说明建议
Nginx 绕过配对验证所有请求伪造为 localhost限制 IP 或启用正式配对
QQBot allowFrom: ["*"]任何 QQ 账号都可连接改为具体账号列表
自签名证书无法防止中间人攻击（理论上）长期使用建议 Let's Encrypt

七、最佳实践建议

🏠 家庭/个人使用（当前场景）

  1. ✅ 保持现状：已配对 + Token + HTTPS
  2. ⚡ 可选优化：添加 UFW IP 限制到特定设备
  3. 📝 记录 Token，丢失后需重新配置

🌐 公网访问

  1. 🔒 必须使用正式配对流程（移除 Nginx 伪造）
  2. 🔑 申请 Let's Encrypt 证书
  3. 🛡️ 启用 Fail2ban 防暴力破解
  4. 🔍 定期审查设备列表：openclaw devices list

📚 参考命令速查

# 查看已配对设备
openclaw devices list

# 批准新设备
openclaw devices approve <device-id>

# 移除设备
openclaw devices remove <device-id>

# 修改 Token（重新生成）
nano ~/.openclaw/openclaw.json  # gateway.auth.token

# 查看访问日志
journalctl -f openclaw-gateway.service

# 检查防火墙规则
ufw status numbered

希望这个详细解读帮助您理解 OpenClaw 的安全机制！有什么具体问题可以继续问我。🔐

avatar
文章
阅读
粉丝