OpenClaw用户白名单与访问权限配置

前言

当你的 OpenClaw 网关对外开放后，任何知道你 Bot 账号的人都可以与之交互——这意味着潜在的 API 成本失控和隐私风险。OpenClaw 提供了多层次的访问控制机制：从全局白名单到按群组、按频道的精细权限配置，让你精确控制"谁可以使用 AI"。

访问控制架构

OpenClaw 的权限判断按以下优先级逐层检查：

全局黑名单（最高优先级，直接拒绝）
  ↓
频道级白名单
  ↓
群组白名单
  ↓
用户白名单
  ↓
全局默认策略（允许或拒绝）

只要在任何一层被拒绝，消息就不会被处理。这种层级设计既能应对简单的"只允许我自己使用"场景，也能满足复杂的多团队权限管理需求。

全局默认策略

首先确定全局的默认行为——当消息来源不在任何白名单或黑名单中时，是允许还是拒绝：

{
  "security": {
    "accessControl": {
      "defaultPolicy": "deny",
      "logDenied": true
    }
  }
}

defaultPolicy	行为
`"allow"`	默认允许所有人，仅黑名单中的用户被拒绝
`"deny"`	默认拒绝所有人，仅白名单中的用户被允许

推荐使用 "deny"——在白名单模式下运行更加安全，明确授权才能使用。

logDenied 设为 true 时，被拒绝的消息会记录到日志中，方便你发现需要加入白名单的合法用户。

用户白名单

按用户 ID

每个即时通讯平台都有唯一的用户标识。在 openclaw.json 中，你可以按频道分别配置允许的用户：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "your-token",
      "allowedUsers": [123456789, 987654321]
    },
    "discord": {
      "enabled": true,
      "token": "your-token",
      "allowedUsers": ["1234567890123456", "9876543210987654"]
    },
    "whatsapp": {
      "enabled": true,
      "allowedUsers": ["+8613800138000", "+8613900139000"]
    }
  }
}

用户 ID 的格式因平台而异。Telegram 使用数字 ID，Discord 使用字符串形式的雪花 ID，WhatsApp 使用手机号。

如何获取用户 ID

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

平台	获取方式
Telegram	向 @userinfobot 发消息，或在 OpenClaw 日志中查看
Discord	开启开发者模式，右键用户 → 复制 ID
WhatsApp	直接使用手机号（含国际区号）
Slack	在个人资料中查看 Member ID

最简单的方式是先将 defaultPolicy 设为 "allow"，让所有人都能使用，然后查看 OpenClaw 日志中记录的用户 ID，再切换为 "deny" 模式并添加白名单。

群组白名单

你可能希望 AI 只在特定的群组中响应，而不是被拉入任何群组都会回复：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "your-token",
      "allowedGroups": [-100123456789, -100987654321]
    },
    "discord": {
      "enabled": true,
      "token": "your-token",
      "allowedChannels": ["general", "ai-chat"],
      "allowedGuilds": ["1234567890"]
    }
  }
}

群组内的用户过滤

即使群组在白名单中，你仍然可以限制群组内哪些用户能够触发 AI：

{
  "channels": {
    "telegram": {
      "allowedGroups": [-100123456789],
      "groupUserPolicy": "allowlist",
      "groupAllowedUsers": {
        "-100123456789": [123456789, 111222333]
      }
    }
  }
}

这样，即使在已授权的群组中，也只有指定的用户可以触发 AI 回复，其他人的 @提及会被忽略。

全局白名单

如果你希望某些用户在所有频道上都被允许，可以使用全局白名单，避免在每个频道中重复配置：

{
  "security": {
    "accessControl": {
      "defaultPolicy": "deny",
      "globalAllowlist": {
        "users": ["tg:123456789", "dc:1234567890123456", "wa:+8613800138000"],
        "groups": ["tg:-100123456789", "dc:1234567890"]
      }
    }
  }
}

全局白名单中的标识格式为 <频道前缀>:<ID>，支持的前缀包括：

前缀	平台
`tg`	Telegram
`dc`	Discord
`wa`	WhatsApp
`sl`	Slack
`im`	iMessage
`sg`	Signal
`mx`	Matrix

黑名单

黑名单的优先级高于白名单。即使用户在白名单中，只要同时出现在黑名单中，就会被拒绝：

{
  "security": {
    "accessControl": {
      "blacklist": {
        "users": ["tg:999888777"],
        "groups": ["tg:-100111222333"],
        "reason": {
          "tg:999888777": "滥用 API，已封禁"
        }
      }
    }
  }
}

黑名单适合处理已知的恶意用户或被滥用的群组。

角色与权限

OpenClaw 还支持更细粒度的角色权限系统，控制用户可以执行哪些操作：

{
  "security": {
    "accessControl": {
      "roles": {
        "admin": {
          "permissions": ["chat", "manage", "config", "dashboard"],
          "users": ["tg:123456789"]
        },
        "user": {
          "permissions": ["chat"],
          "users": ["tg:987654321", "tg:111222333"]
        },
        "viewer": {
          "permissions": ["chat:readonly"],
          "users": ["tg:444555666"]
        }
      }
    }
  }
}

可用权限

权限	说明
`chat`	与 AI 对话
`chat:readonly`	只能查看对话，不能发消息
`manage`	管理会话（清除历史、切换模型等）
`config`	修改配置（通过聊天指令）
`dashboard`	访问 Web Dashboard
`admin`	所有权限

私聊配对认证

对于支持私聊配对的频道（如 WhatsApp、iMessage），OpenClaw 提供了配对验证机制：

{
  "security": {
    "accessControl": {
      "pairingRequired": true,
      "pairingMessage": "请发送配对码以开始使用。获取配对码请联系管理员。"
    }
  }
}

启用后，新用户首次私聊 Bot 时会收到配对提示，需要输入正确的配对码才能开始使用。配对码通过命令行生成：

# 生成一次性配对码
openclaw access pair-code --generate
# 输出: PAIR-A3F2-C1D8

# 生成指定用户的配对码
openclaw access pair-code --generate --user "tg:123456789"

访问日志与监控

开启访问日志后，OpenClaw 会记录所有的权限判断结果：

# 查看最近的访问日志
openclaw access log --tail 50

# 输出示例：
# 2026-03-14 14:30:22 ALLOW tg:123456789 chat "你好"
# 2026-03-14 14:30:25 DENY  tg:999888777 chat "测试" (blacklisted)
# 2026-03-14 14:31:10 DENY  tg:555666777 chat "hi" (not in allowlist)

在 Dashboard 的安全监控页面中，你可以看到访问统计图表：

每小时/每天的允许与拒绝次数
被拒绝最多的用户 ID（可能是需要加入白名单的合法用户，也可能是恶意探测）
各频道的使用量分布

实战配置示例

个人使用（只允许自己）

{
  "security": {
    "accessControl": {
      "defaultPolicy": "deny",
      "globalAllowlist": {
        "users": ["tg:123456789"]
      }
    }
  }
}

小团队使用

{
  "security": {
    "accessControl": {
      "defaultPolicy": "deny",
      "roles": {
        "admin": {
          "permissions": ["admin"],
          "users": ["tg:123456789"]
        },
        "member": {
          "permissions": ["chat", "manage"],
          "users": ["tg:111111111", "tg:222222222", "tg:333333333"]
        }
      }
    }
  }
}

公开服务（限制滥用）

{
  "security": {
    "accessControl": {
      "defaultPolicy": "allow",
      "blacklist": {
        "users": ["tg:999888777"]
      }
    },
    "rateLimit": {
      "enabled": true,
      "maxRequests": 10,
      "windowMs": 60000
    }
  }
}

总结

OpenClaw 的访问控制系统从简单的白名单到角色权限，覆盖了从个人使用到团队部署的各种场景。核心建议：生产环境中始终将 defaultPolicy 设为 "deny"，明确授权每一个用户和群组；开启 logDenied 监控被拒绝的请求；定期审查白名单，移除不再需要的条目。安全是一个持续的过程，而非一次性配置。