OpenClaw 身份配对与访问控制：Pairing、Node 设备与群组策略

在分布式AI Agent架构中，"谁有权访问"比"能做什么"更基础。OpenClaw通过基于配对码（Pairing Code）的信任建立机制与细粒度的群组策略，实现了从设备准入到会话隔离的完整身份生命周期管理。本文深度拆解其短时效凭证、多节点拓扑与动态访问控制的设计哲学。

一、身份配对架构概览

OpenClaw的身份体系采用"去中心化身份验证 + 集中式策略管控"的混合模型。Gateway作为信任锚点，通过配对机制（Pairing）建立与Client（DM用户）及Node（设备节点）的安全关联。

+-------------------+        +-------------------+        +-------------------+
|   身份发起方       |        |   Gateway 配对服务  |        |   凭证存储层       |
| (User/Node/Admin) |------->|  (Pairing Service) |------->| (File System/KMS) |
+-------------------+        +-------------------+        +-------------------+
         |                            |                            |
         v                            v                            v
+--------+----------+        +---------+---------+        +---------+---------+
| 配对请求生成       |        | 8字符配对码       |        | ~/.openclaw/      |
| - DM私聊请求      |        | - 1小时TTL        |        | credentials/      |
| - Node设备申请    |        | - 3并发限制        |        | - pairing.json    |
| - 管理员预授权    |        | - 加密传输        |        | - allowlist/      |
+-------------------+        +-------------------+        +-------------------+

二、DM配对机制：短时效信任建立

私聊（DM）场景的配对是OpenClaw安全模型的第一道防线，采用短时有效、有限并发、人工确认的三重保护策略。

2.1 配对流程与状态机

+-------------------+        +-------------------+        +-------------------+
|   用户首次发起对话  |        |   配对码生成与投递   |        |   管理员确认      |
|  (Telegram/Discord|   -->  |  (Gateway生成8字符) |   -->  |  (Approve/Reject) |
|   WhatsApp等)     |        |                   |        |                   |
+-------------------+        +-------------------+        +-------------------+
         |                            |                            |
         v                            v                            v
+--------+----------+        +---------+---------+        +---------+---------+
| 1. 用户发送/start  |        | 2. 生成8字符配对码   |        | 3. 管理员收到通知  |
|                   |        |    (如: X7K9M2P4)  |        |    (CLI/Web UI)   |
| 系统检查：         |        | - 大写字母+数字     |        | 验证用户身份：     |
| - 是否在allowlist?|        | - 熵值: 36^8组合    |        | - 已知联系人？    |
| - 是否有待处理请求?|        | - 1小时过期时间戳   |        | - 业务合理性？    |
| - 并发数<3?       |        | - 绑定用户ID        |        |                   |
+-------------------+        +-------------------+        +-------------------+
                                                                  |
+-----------------------------------------------------------------+
                         |
                         v
                  +---------+---------+
                  |   配对完成/拒绝    |
                  |  - 成功:写入allowlist|
                  |  - 失败:记录审计日志 |
                  |  - 过期:自动清理     |
                  +-------------------+

2.2 配对码安全设计

8字符配对码规范：

属性	设计值	安全考量
长度	8字符	平衡安全性与输入便捷性（36^8 ≈ 2.8万亿组合）
字符集	A-Z, 0-9	排除易混淆字符（I/L/O/0）
TTL	3600秒（1小时）	减少暴力破解时间窗口
并发限制	最多3个待处理请求	防止请求泛洪攻击
绑定粒度	userId + channel	防止配对码截获后跨渠道复用

生成算法示例（架构层面）：

// 伪代码：CSPRNG生成
const charset = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // 排除 I,L,O,0,1
const code = Array.from({length: 8}, () => 
  charset[crypto.randomInt(charset.length)]
).join('');

// 存储结构
pairingStore.set(code, {
  userId: msg.from.id,
  channel: 'telegram',
  expiresAt: Date.now() + 3600000,
  status: 'pending'
});

2.3 待处理请求管理

当多个用户同时发起配对请求时，Gateway维护有限队列：

# 查看待处理配对请求
openclaw pairing list --status pending

# 输出示例
ID      | Code    | User        | Channel   | Created             | Expires
--------+---------+-------------+-----------+---------------------+------------------
pair-1  | X7K9M2P4| @alice      | telegram  | 2026-03-09 14:00:00 | 2026-03-09 15:00
pair-2  | Q3N8R5T1| @bob        | discord   | 2026-03-09 14:05:00 | 2026-03-09 15:05
pair-3  | M2P7K9X4| @charlie    | whatsapp  | 2026-03-09 14:10:00 | 2026-03-09 15:10

# 队列已满时（第4个请求）
# 系统返回: "配对队列已满，请1小时后再试或联系管理员"

队列管理策略：

• FIFO驱逐：新请求到来时若队列已满，自动驱逐最早过期请求
• 主动清理：每分钟扫描过期条目，释放槽位
• 持久化：待处理状态写入 ~/.openclaw/credentials/pending.json，Gateway重启后可恢复

2.4 管理员审批流程

配对确认支持自动化规则与人工审核两种模式：

# 人工审批
openclaw pairing approve X7K9M2P4 --expires 30d  # 授权30天
openclaw pairing reject X7K9M2P4 --reason "未识别用户"

# 批量审批（基于规则）
openclaw pairing approve-all --domain "@company.com" --expires 90d

审批后状态转换：

Pending(待处理) 
    |
    |--[Approve]--> Active(已授权) --> 写入 allowlist.json
    |                    |
    |                    |--[时间到期]--> Expired(过期)
    |                    |--[手动撤销]--> Revoked(吊销)
    |
    |--[Reject]--> Denied(已拒绝) --> 保留审计记录7天
    |
    |--[1小时无操作]--> Expired(过期) --> 自动清理

三、Node设备配对：多节点拓扑接入

除了DM用户，OpenClaw支持多设备节点（iOS/Android/macOS/Headless）接入同一Gateway，构成分布式Agent网络。

3.1 Node设备类型与角色

设备类型	典型实例	接入方式	安全等级
移动端	iOS App, Android App	Token + TLS	中（设备易丢失）
桌面端	macOS App	Token + 本地验证	高
无头节点	Linux Server, VPS	Token + IP白名单	高
Web客户端	Browser PWA	Session Cookie	中

3.2 Token短生命周期管理

Node配对采用短时效Token + 刷新令牌的双层机制，避免长期凭证泄露风险：

+-------------------+        +-------------------+        +-------------------+
|   Node设备首次接入  |        |   Token生成与分发   |        |   运行时刷新       |
|  (iOS/Android等)   |   -->  |  (Gateway签发)     |   -->  |  (自动续期)        |
+-------------------+        +-------------------+        +-------------------+
         |                            |                            |
         v                            v                            v
+--------+----------+        +---------+---------+        +---------+---------+
| 1. 设备生成密钥对   |        | 2. Gateway签发Token|        | 3. 定期刷新        |
|    (ECDSA P-256)  |        | - Access Token:    |        | - 默认TTL: 24小时  |
|                   |        |   24小时有效       |        | - 提前2小时刷新    |
| 2. 提交公钥+设备信息|        | - Refresh Token:   |        | - 旧Token立即失效  |
|                   |        |   7天有效          |        |                   |
+-------------------+        +-------------------+        +-------------------+

Token存储结构（~/.openclaw/credentials/nodes.json）：

{
  "nodes": [
    {
      "nodeId": "ios-abc123",
      "type": "ios",
      "name": "Alice's iPhone",
      "publicKey": "MFYwEAYHKoZIzj0CAQYFK4EEAAoDQgAE...",
      "accessToken": "ogt_a1b2c3d4...",
      "accessTokenExpires": "2026-03-10T14:00:00Z",
      "refreshToken": "ogr_e5f6g7h8...",
      "refreshTokenExpires": "2026-03-16T14:00:00Z",
      "pairedAt": "2026-03-09T14:00:00Z",
      "lastSeen": "2026-03-09T20:30:00Z",
      "allowedChannels": ["telegram", "slack"],
      "ipWhitelist": ["192.168.1.0/24"]
    }
  ]
}

短生命周期优势：

• 泄露窗口小：即使Access Token泄露，24小时后自动失效
• 吊销即时性：刷新时可检查节点状态，立即吊销异常设备
• 权限收敛：刷新时可动态调整权限范围（如缩小allowedChannels）

3.3 Node配对CLI管理

# 列出已配对节点
openclaw node list
# NodeID      | Type   | Name            | Last Seen           | Status
# ------------+--------+-----------------+---------------------+--------
# ios-abc123  | ios    | Alice's iPhone  | 2026-03-09 20:30:00 | active
# mac-xyz789  | macos  | Alice's MacBook | 2026-03-09 20:25:00 | active
# android-456 | android| Bob's Phone     | 2026-03-08 10:00:00 | expired

# 查看节点详情
openclaw node info ios-abc123

# 吊销节点（立即生效）
openclaw node revoke ios-abc123

# 强制刷新所有Token（安全事件响应）
openclaw node rotate-tokens

四、群组安全策略：动态访问控制

对于群组（Group）场景，OpenClaw提供三级安全策略与智能触发规则，平衡开放性与安全性。

4.1 groupPolicy三级策略

策略	行为	适用场景	风险等级
allowlist	仅允许显式授权的用户交互	企业内群、敏感项目组	极低
disabled	完全禁用群组交互，仅记录消息	监控模式、合规审计	无交互风险
open	允许所有群成员交互（需mention触发）	社区群、公开频道	中（需配合mentionPatterns）

配置示例（openclaw.json）：

{
  channels: {
    telegram: {
      groupPolicy: "allowlist",  // 全局默认
      allowlist: {
        // 显式允许的群组
        groups: ["-1001234567890", "-1009876543210"],
        // 显式允许的用户（跨群组生效）
        users: ["@admin_alice", "@bot_manager_bob"]
      }
    },
    discord: {
      groupPolicy: "open",
      mentionPatterns: ["@OpenClaw", "@Assistant"],  // 触发词
      rateLimit: {
        perUser: "5/m",      // 每用户每分钟5次
        perGroup: "20/m"     // 每群组每分钟20次
      }
    }
  }
}

4.2 mentionPatterns触发规则

在open模式下，通过mention机制防止误触发与消息泛洪：

触发规则优先级：

• 直接@提及：@BotName 或 @OpenClaw
• 关键词触发：配置的关键词出现在消息中
• 回复消息：用户回复Bot的历史消息
• 命令前缀：/command 格式的显式命令

+-------------------+        +-------------------+        +-------------------+
|   群组消息流入     |        |   触发条件检查     |        |   权限与限流检查    |
|  (Group Message)  |   -->  |  (mentionPatterns) |   -->  |  (Policy enforce)  |
+-------------------+        +-------------------+        +-------------------+
         |                            |                            |
         v                            v                            v
+--------+----------+        +---------+---------+        +---------+---------+
| 提取消息元数据     |        | 检查触发条件：     |        | 检查：             |
| - text content    |        | - @BotName?       |        | - 用户在allowlist?|
| - mentions[]      |        | - 关键词匹配？     |        | - 是否超频？       |
| - reply_to        |        | - 回复Bot消息？    |        | - 群组策略允许？   |
| - from.id         |        |                   |        |                   |
+-------------------+        +---------+---------+        +---------+---------+
                                       |                            |
                                       v                            v
                              +--------+--------+          +--------+--------+
                              | 未触发：NO_REPLY |          | 拒绝：静默丢弃   |
                              | (无响应)         |          | 或返回错误       |
                              +-----------------+          +-----------------+
                                                                        |
                                                                        v
                                                               +--------+--------+
                                                               | 允许：路由到Agent|
                                                               +-----------------+

智能触发配置：

{
  mentionPatterns: {
    // 精确匹配Bot用户名
    exact: ["@OpenClawBot", "@MyAssistant"],
    
    // 模糊匹配（包含即可）
    fuzzy: ["hey bot", "assistant help", "need help"],
    
    // 正则匹配（高级）
    regex: ["^@Bot.*\\?$", "(urgent|asap|紧急)"],
    
    // 白名单时段（仅工作时间响应）
    timeWindow: {
      timezone: "Asia/Shanghai",
      workDays: "1-5",
      workHours: "9:00-18:00"
    }
  }
}

五、凭证存储安全架构

所有配对状态、Token与允许列表存储于本地文件系统，遵循最小权限原则与加密存储规范。

5.1 目录结构与权限

~/.openclaw/credentials/
├── pairing.json          # 当前配对状态（待处理/已完成）
│   └── 权限: 600 (owner read/write only)
├── allowlist.json        # 已授权用户/设备列表
│   └── 权限: 600
├── nodes.json            # Node设备Token与密钥
│   └── 权限: 600
├── auth-profiles.json    # 渠道OAuth凭证（如Slack Token）
│   └── 权限: 600
└── revoked/              # 吊销记录（审计用途）
    ├── 2026-03-09_revoked.json
    └── 权限: 644 (只读审计)

安全加固措施：

• 文件权限：所有敏感文件设置为600（仅所有者读写）
• 目录权限：credentials目录设置为700（禁止其他用户列出）
• 加密存储：支持通过OPENCLAW_CREDENTIALS_KEY环境变量启用AES-256-GCM加密
• 定期轮换：建议每90天执行openclaw credentials rotate

5.2 凭证内容示例

allowlist.json（已授权实体）：

{
  "version": "1.0",
  "entries": [
    {
      "id": "user_alice",
      "type": "dm",
      "channel": "telegram",
      "userId": "123456789",
      "username": "@alice",
      "authorizedAt": "2026-03-01T10:00:00Z",
      "expiresAt": null,
      "permissions": ["read", "write", "tools:exec"],
      "boundAgent": "main"
    },
    {
      "id": "node_ios_abc123",
      "type": "node",
      "deviceType": "ios",
      "nodeId": "ios-abc123",
      "authorizedAt": "2026-03-09T14:00:00Z",
      "expiresAt": "2026-06-09T14:00:00Z",
      "permissions": ["gateway:read", "session:write"],
      "ipRange": ["192.168.1.0/24"]
    }
  ]
}

六、生产环境安全建议

6.1 最小权限配置模板

{
  security: {
    // DM场景：严格审批制
    dm: {
      pairing: {
        enabled: true,
        codeLength: 8,
        expiresIn: "1h",
        maxPending: 3,
        autoApprove: false,  // 必须人工审批
        requireAdminMFA: true  // 审批需二次验证
      }
    },
    
    // 群组场景：白名单制
    groups: {
      defaultPolicy: "disabled",  // 默认禁用
      allowlistOnly: true,
      mentionRequired: true,
      maxMembers: 100  // 超大群单独审批
    },
    
    // Node设备：短时效+IP限制
    nodes: {
      tokenTTL: "24h",
      refreshTokenTTL: "7d",
      requireIPWhitelist: true,
      maxDevicesPerUser: 3
    }
  }
}

6.2 安全运维检查清单

# 每日检查
openclaw pairing list --status pending  # 清理过期请求
openclaw node list --expired           # 吊销过期节点

# 每周审计
openclaw security audit --check-permissions
openclaw credentials verify --integrity

# 月度轮换
openclaw credentials rotate --strategy rolling  # 滚动轮换无停机

七、总结

OpenClaw的身份配对与访问控制体系通过短时凭证（8字符配对码、24小时Token）、显式授权（人工审批、allowlist）与动态策略（groupPolicy三级、mentionPatterns触发），构建了从设备准入到会话管控的完整安全边界。
架构设计要点：

• 时效性安全：1小时配对码与24小时Access Token将泄露窗口压缩至最小
• 并发控制：3个待处理请求限制防止配对服务泛洪
• 分层策略：DM（严格配对）、Group（三级策略）、Node（短效Token）差异化管控
• 存储安全：600文件权限+可选加密+定期轮换

对于生产环境，建议始终启用allowlist模式，禁用自动审批，并配合定期Token轮换与审计日志分析，确保多节点、多用户场景下的身份安全。

本文章基于OpenClaw官方文档学习撰写。仅供学习参考，请勿用于商业用途。