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를 활성화하여 거부된 요청을 모니터링하며, 정기적으로 화이트리스트를 검토하여 더 이상 필요하지 않은 항목을 제거하세요. 보안은 일회성 설정이 아니라 지속적인 과정입니다.