OpenClaw频道安全配置：白名单与私信配对

当你将AI代理暴露在公开的聊天平台上时，安全控制变得至关重要。不受限制的AI Bot可能被滥用——无论是消耗大量API额度、生成不当内容，还是泄露敏感信息。OpenClaw提供了多层次的安全机制来帮助你控制谁可以与AI交互以及如何交互。

安全威胁概述

在开放的聊天平台上运行AI Bot面临的主要风险包括：

未授权用户滥用AI资源，产生高额API费用
恶意用户通过提示注入（Prompt Injection）尝试操纵AI行为
在群聊中AI被不当触发，回复不恰当的内容
敏感信息通过AI回复泄露给未授权的人

OpenClaw的安全机制就是为了应对这些场景而设计的。

Allowlist白名单机制

Allowlist是OpenClaw最基本也最有效的访问控制手段。它的原理很简单：只有白名单中的用户才能与AI交互，其他用户的消息会被静默忽略。

全局白名单

你可以在 openclaw.json 的顶层设置全局白名单，它会对所有频道生效：

{
  "security": {
    "allowlist": {
      "enabled": true,
      "users": [
        {"platform": "telegram", "id": "123456789"},
        {"platform": "whatsapp", "id": "[email protected]"},
        {"platform": "discord", "id": "987654321098765432"}
      ]
    }
  }
}

全局白名单使用平台名加用户ID的格式标识用户。这样你可以在一个地方管理所有平台的授权用户。

频道级白名单

每个频道也可以有自己的白名单，它会与全局白名单取并集——也就是说，全局白名单和频道白名单中的用户都可以访问：

{
  "channels": {
    "telegram": {
      "allowlist": [123456789, 111222333]
    },
    "whatsapp": {
      "allowlist": ["[email protected]"]
    }
  }
}

频道级白名单只需要填写该平台的用户ID，格式更简洁。

白名单模式

OpenClaw支持两种白名单模式：

严格模式（strict）：只有白名单中的用户可以交互。这是默认模式，适合私有部署。

宽松模式（permissive）：所有用户都可以交互，但白名单用户享有更高的优先级和更多的功能权限。例如，普通用户每天只能发送10条消息，而白名单用户没有限制。

{
  "security": {
    "allowlist": {
      "mode": "strict"
    }
  }
}

私信配对机制

私信配对（Private Message Pairing）是OpenClaw独特的安全特性。它要求用户先通过私信与Bot完成身份验证，然后才能在群聊等场景中使用AI功能。

工作流程

配对流程如下：

用户在群聊中首次尝试与AI交互
Bot检测到该用户未配对，发送一条私信给用户（或提示用户主动私信Bot）
用户在私信中收到一个一次性配对码
用户在私信中回复配对码完成验证
验证成功后，用户即可在群聊中正常使用AI功能

配置私信配对

{
  "security": {
    "pairing": {
      "enabled": true,
      "codeExpiry": 300,
      "codeLength": 6,
      "maxAttempts": 3,
      "pairingMessage": "请在5分钟内回复以下配对码以激活AI助手：{code}"
    }
  }
}

codeExpiry 是配对码的有效时间（秒），codeLength 是配对码的位数，maxAttempts 是最大尝试次数，超过后需要重新发起配对。pairingMessage 是发送给用户的提示信息模板，{code} 会被替换为实际的配对码。

配对状态持久化

配对成功后，用户的认证状态会被持久化存储。即使OpenClaw重启，用户也无需重新配对。配对记录存储在本地数据库中，你可以通过命令管理：

openclaw pairing list          # 查看所有已配对用户
openclaw pairing revoke <id>   # 撤销特定用户的配对
openclaw pairing clear         # 清除所有配对记录

群聊权限控制

群聊场景的安全控制更为复杂，因为涉及群组级别和用户级别的双重权限。

群组白名单

限制Bot只在特定群组中工作：

{
  "security": {
    "groups": {
      "allowedGroups": {
        "telegram": [-1001234567890],
        "whatsapp": ["[email protected]"],
        "discord": ["guild_id_here"]
      }
    }
  }
}

如果Bot被添加到白名单以外的群组，它会静默忽略所有消息。你也可以配置让Bot在被添加到未授权群组时自动退出。

群组角色权限

在支持角色系统的平台（如Discord、Telegram）上，你可以基于用户的群组角色来控制访问：

{
  "security": {
    "groups": {
      "roleBasedAccess": {
        "adminOnly": false,
        "allowedRoles": ["ai-user", "premium"]
      }
    }
  }
}

adminOnly 设为true时只有管理员可以使用。allowedRoles 指定哪些角色的用户可以使用AI功能（适用于Discord等有角色系统的平台）。

速率限制

除了访问控制，速率限制也是重要的安全措施。它可以防止单个用户过度使用AI资源：

{
  "security": {
    "rateLimit": {
      "enabled": true,
      "maxRequests": 30,
      "windowSeconds": 3600,
      "cooldownMessage": "你的使用次数已达上限，请稍后再试。"
    }
  }
}

上述配置限制每个用户每小时最多30次AI交互。速率限制按用户独立计算，跨频道共享——也就是说，同一个用户在Telegram用了20次，在Discord只剩10次。

内容安全

OpenClaw还提供了基本的内容安全过滤功能。你可以配置关键词过滤，当用户输入或AI回复中包含特定关键词时进行拦截：

{
  "security": {
    "contentFilter": {
      "enabled": true,
      "blockedPatterns": ["敏感词1", "敏感词2"],
      "action": "block_and_warn"
    }
  }
}

action 支持 block_silently（静默拦截）和 block_and_warn（拦截并提示用户）两种模式。

安全配置最佳实践

对于生产环境，建议采用以下安全策略组合：启用全局白名单的严格模式，只允许已知用户访问；对群聊场景启用私信配对，增加一层验证；配置合理的速率限制防止滥用；设置群组白名单，避免Bot被拉入未知群组；定期审查配对记录和使用日志。

这些安全机制可以灵活组合。对于内部团队使用，白名单加速率限制通常就足够了。对于面向公众的服务，建议启用全套安全措施。