配对认证 - 渠道用户验证

Pairing（配对认证）是 OpenClaw 的安全机制，用于验证谁可以通过渠道与你的 Agent（智能体）进行私信对话。它是所有渠道的默认 DM Policy（私信策略）。

什么是配对认证

在生产环境中，你不希望任何人都能随意与你的 Agent 对话——这会消耗 API 额度，也可能泄露敏感信息。Pairing（配对）机制通过一个简单的「验证码 + 审批」流程，确保只有经过授权的用户才能与 Agent 交互。

类比理解

配对认证类似于蓝牙设备配对：设备 A 想连接设备 B 时，需要在两端确认配对码。在 OpenClaw 中，用户发起对话请求，管理员通过 CLI 或控制台批准该请求。

配对流程

完整的 Pairing Flow（配对流程）如下：

用户 (User)                     Agent                      管理员 (Owner)
    │                             │                             │
    │  1. 发送首条消息             │                             │
    │ ──────────────────────────> │                             │
    │                             │                             │
    │  2. 返回配对码              │                             │
    │ <────────────────────────── │                             │
    │  "请将配对码 A7X3 交给管理员" │                             │
    │                             │  3. 通知有新的配对请求        │
    │                             │ ──────────────────────────> │
    │                             │                             │
    │                             │  4. 批准配对                 │
    │                             │ <────────────────────────── │
    │                             │  `openclaw pairing approve` │
    │                             │                             │
    │  5. 配对成功，开始对话       │                             │
    │ <────────────────────────── │                             │
    │  "配对已通过，有什么可以帮你？"│                             │

详细步骤说明

用户发送消息：用户通过某个渠道（如 Telegram）首次向 Agent 发送消息
Agent 生成配对码：Agent 检测到该用户尚未配对，自动生成一个短配对码（Pairing Code）
用户收到提示：Agent 回复用户，告知需要将配对码交给管理员审批
管理员审批：管理员通过 CLI 或 Web 控制台批准该配对请求
配对完成：用户获得授权，可以正常与 Agent 对话

CLI 命令

OpenClaw 提供完整的 CLI 命令管理配对：

查看配对列表

bash

# 查看所有渠道的配对请求
openclaw pairing list

# 输出示例：
# Channel    User ID        Status     Code   Requested At
# telegram   user_12345     pending    A7X3   2 min ago
# slack      U0123ABCDE     approved   -      3 days ago
# feishu     ou_a1b2c3d4    pending    K9M2   just now

# 查看特定渠道的配对请求
openclaw pairing list telegram

# 只看待审批的请求
openclaw pairing list --status pending

批准配对

bash

# 通过渠道名 + 配对码批准
openclaw pairing approve telegram A7X3

# 通过渠道名 + 用户 ID 批准
openclaw pairing approve telegram user_12345

# 批量批准所有待审批请求
openclaw pairing approve --all

# 批准并添加备注
openclaw pairing approve telegram A7X3 --note "产品团队成员小王"

撤销配对

bash

# 撤销特定用户的配对
openclaw pairing revoke telegram user_12345

# 撤销特定渠道的所有配对
openclaw pairing revoke telegram --all

# 撤销所有渠道的所有配对（谨慎使用）
openclaw pairing revoke --all --confirm

注意

撤销配对后，用户的活跃会话会立即终止。如果用户再次发送消息，将需要重新进行配对流程。

其他管理命令

bash

# 查看配对统计
openclaw pairing stats

# 输出示例：
# Total paired users:    42
# Pending requests:       3
# Revoked:               5

# 导出配对列表
openclaw pairing export --format json > paired_users.json

# 导入配对列表（用于迁移）
openclaw pairing import paired_users.json

配置 DM Policy

每个渠道可以独立设置 DM Policy（私信策略），在 openclaw.yaml 中配置：

Pairing 模式（默认）Allowlist 模式Open 模式

yaml

channels:
  telegram:
    enabled: true
    dmPolicy: pairing
    # 配对码有效时间（默认 30 分钟）
    pairingCodeTTL: "30m"
    # 配对码长度（默认 4 位）
    pairingCodeLength: 4
    # 配对请求通知方式
    pairingNotify:
      - cli       # CLI 通知
      - webhook   # Webhook 通知

yaml

channels:
  slack:
    enabled: true
    dmPolicy: allowlist
    allowFrom:
      - "U001ABC"      # 用户 Slack ID
      - "U002DEF"
      - "U003GHI"
    # allowlist 模式下，未列出的用户消息将被静默忽略
    # 设置 rejectMessage 可发送拒绝提示
    rejectMessage: "抱歉，你没有权限与此 Agent 对话。请联系管理员。"

yaml

channels:
  webchat:
    enabled: true
    dmPolicy: open
    # 强烈建议配合速率限制使用
    rateLimit:
      maxRequests: 10      # 每个用户每分钟最多 10 条消息
      windowSeconds: 60

Allowlist（白名单）模式详解

Allowlist（白名单）模式允许你预先批准一组用户，无需经过配对流程。

配置方式

yaml

channels:
  feishu:
    enabled: true
    dmPolicy: allowlist
    allowFrom:
      - "ou_user001"    # 飞书用户 Open ID
      - "ou_user002"
      - "ou_user003"

动态管理白名单

bash

# 添加用户到白名单
openclaw config set channels.feishu.allowFrom '["ou_user001","ou_user002","ou_new_user"]' --json

# 或使用专用命令
openclaw pairing allow feishu ou_new_user

# 从白名单移除
openclaw pairing disallow feishu ou_user001

获取用户 ID

不同平台的用户 ID 获取方式不同：

Telegram：用户资料中的数字 ID，或通过 @userinfobot 获取
Slack：用户资料页面的 Member ID
飞书：管理后台的用户 Open ID（ou_ 开头）
企业微信：通讯录中的 UserID
钉钉：管理后台的用户 unionId

Open（开放）模式详解

Open（开放）模式跳过所有认证，任何人都可以直接对话。

安全风险

Open 模式意味着：

任何人都可以消耗你的 LLM API 额度
任何人都可以访问 Agent 配置的工具和技能
对话内容可能包含敏感信息

仅建议在以下场景使用：

内部测试或开发环境
公共服务型 Agent（如客服机器人），并配合严格的工具权限和速率限制
Web Chat 渠道，配合前端自有认证系统

yaml

channels:
  webchat:
    enabled: true
    dmPolicy: open
    rateLimit:
      maxRequests: 10
      windowSeconds: 60
    # 限制 open 模式下可用的工具
    tools:
      allow:
        - "search"
        - "faq"
      deny:
        - "file_*"
        - "system_*"

Auto-approve（自动批准）模式

对于需要一定安全性但又不想手动审批的场景，可以配置 Auto-approve Pattern（自动批准规则）：

yaml

channels:
  telegram:
    enabled: true
    dmPolicy: pairing
    autoApprove:
      # 按用户名匹配（正则表达式）
      usernamePatterns:
        - "^team_.*"        # 自动批准 team_ 开头的用户名
        - ".*@company.com$" # 自动批准公司邮箱关联的账号
      # 按来源群组匹配
      fromGroups:
        - "group_internal"  # 从内部群组发起私聊的用户自动批准
      # 自动批准的 TTL（到期后需重新配对）
      ttl: "30d"            # 30 天后过期

安全与便利的平衡

Auto-approve 提供了一种折中方案：比 Open 更安全（仍然有规则约束），比纯 Pairing 更方便（无需手动审批每个人）。

配对事件与 Webhook

配对事件可以通过 Webhook 推送到外部系统：

yaml

webhooks:
  pairingEvents:
    url: "https://your-server.com/api/pairing-webhook"
    events:
      - "pairing.requested"    # 新的配对请求
      - "pairing.approved"     # 配对被批准
      - "pairing.revoked"      # 配对被撤销
    secret: "${WEBHOOK_SECRET}" # 用于验证签名

Webhook Payload（载荷）示例：

json

{
  "event": "pairing.requested",
  "timestamp": "2026-03-05T10:30:00Z",
  "channel": "telegram",
  "userId": "user_12345",
  "userName": "张三",
  "pairingCode": "A7X3"
}

最佳实践

生产环境使用 Pairing 或 Allowlist：不要在面向外部用户的生产环境中使用 Open 模式
定期审查配对列表：使用 openclaw pairing list 定期检查，撤销不再需要的用户
配合工具权限：即使配对通过，也应通过工具权限系统限制用户可以调用的功能
启用 Webhook 通知：及时收到新的配对请求通知，避免用户等待太久
为团队用户使用 Allowlist：内部团队成员建议使用 Allowlist 模式预授权

🇨🇳 中国用户须知

配对认证机制对所有渠道（包括飞书、企业微信、钉钉等国内渠道）的工作方式完全一致。

国内渠道用户 ID 获取方式：

飞书：管理后台 → 通讯录 → 用户详情 → Open ID（ou_ 开头）
企业微信：管理后台 → 通讯录 → 成员详情 → UserID
钉钉：开放平台 → 应用管理 → 用户管理 → unionId

企业场景建议： 如果你的企业已有统一身份认证系统（如 LDAP/SSO），建议通过 Auto-approve 的 usernamePatterns 匹配企业邮箱，实现自动审批，减少管理负担。

配对认证 - 渠道用户验证 ​

什么是配对认证 ​

配对流程 ​

详细步骤说明 ​

CLI 命令 ​

查看配对列表 ​

批准配对 ​

撤销配对 ​

其他管理命令 ​

配置 DM Policy ​

Allowlist（白名单）模式详解 ​

配置方式 ​

动态管理白名单 ​

Open（开放）模式详解 ​

Auto-approve（自动批准）模式 ​

配对事件与 Webhook ​

最佳实践 ​

配对认证 - 渠道用户验证

什么是配对认证

配对流程

详细步骤说明

CLI 命令

查看配对列表

批准配对

撤销配对

其他管理命令

配置 DM Policy

Allowlist（白名单）模式详解

配置方式

动态管理白名单

Open（开放）模式详解

Auto-approve（自动批准）模式

配对事件与 Webhook

最佳实践