OpenClaw 보안 설정 및 접근 제어 가이드

소개

OpenClaw은 AI 게이트웨이를 보호하기 위해 다층 보안 메커니즘을 제공합니다. 접근 제어부터 샌드박스 격리까지, 인증 관리부터 오류 처리까지, 이러한 보안 기능은 완전한 방어 체계를 구성합니다. 본 문서에서는 OpenClaw 공식 문서를 기반으로 각 보안 기능의 설정과 활용 방법을 체계적으로 다룹니다.

접근 제한: openclaw.json의 보안 설정

OpenClaw의 보안 정책은 openclaw.json 설정 파일에서 중앙 집중식으로 관리됩니다. 누가 서비스에 접근할 수 있는지, 어떻게 접근하는지, 사용 범위는 어디까지인지 정의할 수 있습니다.

{
  security: {
    // 전역 접근 제어 토글
    accessControl: {
      enabled: true,
      defaultPolicy: "deny",  // 기본적으로 모든 미인가 접근 거부
    }
  }
}

defaultPolicy를 "deny"로 설정하는 것이 권장 방식입니다 — 이는 명시적으로 인가된 사용자만 AI 어시스턴트와 상호작용할 수 있음을 의미하며, 개방형 접근으로 인한 남용을 방지합니다.

허용 목록 메커니즘: 정밀한 상호작용 제어

허용 목록은 OpenClaw의 주요 접근 제어 메커니즘입니다. 사용자 ID, 사용자 이름 또는 사용자 그룹별로 허용 사용자를 설정할 수 있습니다.

{
  security: {
    allowlist: {
      // 플랫폼별 설정
      telegram: {
        userIds: [123456789, 987654321],
        usernames: ["alice", "bob"],
      },
      discord: {
        userIds: ["1100000000000000001"],
        roleIds: ["1100000000000000099"],  // 역할별 인가
      },
      wechat: {
        remarkNames: ["Zhang San", "Li Si"],
      }
    }
  }
}

허용 목록은 여러 매칭 차원을 지원하며, 플랫폼마다 고유한 식별자를 사용할 수 있습니다. 사용자가 메시지를 보내면 OpenClaw은 먼저 사용자가 허용 목록에 있는지 확인합니다. 확인에 통과하지 못한 메시지는 API 할당량을 소비하지 않고 즉시 폐기됩니다.

DM 페어링 메커니즘

DM(다이렉트 메시지) 시나리오에서 OpenClaw은 보안을 보장하기 위해 페어링 메커니즘을 도입합니다. 이 메커니즘은 사용자가 첫 상호작용 시 신원 확인 페어링을 완료해야 정상적인 대화를 할 수 있도록 합니다.

페어링 플로우의 핵심 로직은 다음과 같습니다: 사용자가 봇에 DM을 보내면 시스템이 사용자의 페어링 여부를 확인합니다. 페어링되지 않은 사용자는 사전 설정된 인증 방식(비밀 문구 또는 초대 코드 등)을 통해 초기 바인딩을 완료해야 합니다. 페어링이 완료되면 이후 상호작용에서는 재인증이 필요하지 않습니다.

이 설계는 각 사용자를 수동으로 허용 목록에 추가하지 않고도 DM 접근을 제한해야 하는 시나리오에 특히 적합합니다. 관리자는 페어링 정책을 설정하여 입장 규칙을 유연하게 제어할 수 있습니다.

그룹 채팅 규칙과 보안

그룹 채팅 환경은 DM보다 복잡하며, OpenClaw은 전용 그룹 채팅 보안 규칙을 제공합니다.

{
  channels: {
    telegram: {
      groupRules: {
        // 그룹 채팅에서의 트리거 모드
        triggerMode: "mention",     // @멘션된 경우에만 응답
        allowedGroups: ["-100123456789"],  // 특정 그룹으로 제한
        adminOnly: false,           // 관리자만 사용 가능 여부
        cooldown: 5,                // 그룹당 최소 응답 간격 (초)
      }
    }
  }
}

triggerMode를 "mention"으로 설정하면 봇이 그룹의 모든 메시지에 응답하는 것을 방지하여 API 호출을 절약하고 정보 유출을 방지합니다. allowedGroups는 봇이 지정된 그룹에서만 작동하도록 제한하여 공격 표면을 더욱 좁힙니다. 그룹 쿨다운은 그룹 내 스팸성 남용도 효과적으로 완화합니다.

다중 계정 인증: 장애 조치와 쿨다운

OpenClaw은 동일한 AI 공급자에 대해 여러 API 계정을 설정하여 자동 장애 조치를 지원합니다. 주 계정이 인증 오류나 속도 제한을 만나면 시스템이 자동으로 백업 계정으로 전환하여 서비스를 계속합니다.

{
  providers: {
    openai: {
      accounts: [
        {
          name: "primary",
          apiKey: "${OPENAI_KEY_1}",
          priority: 1,
        },
        {
          name: "backup",
          apiKey: "${OPENAI_KEY_2}",
          priority: 2,
        }
      ],
      failover: {
        enabled: true,
        cooldownSeconds: 60,    // 계정 실패 후 쿨다운 기간
        maxRetries: 3,          // 최대 재시도 횟수
      }
    }
  }
}

계정이 속도 제한(429 오류)이나 인증 실패(401/403 오류)를 트리거하면 쿨다운 기간에 들어갑니다. 쿨다운 중에는 요청이 다른 사용 가능한 계정으로 라우팅됩니다. 쿨다운이 종료되면 계정이 순환 풀에 다시 합류합니다. 이 메커니즘은 단일 계정에 대한 과도한 의존을 피하면서 고가용성을 보장합니다.

오류 처리 전략

OpenClaw은 인증 오류와 속도 제한에 대해 명확한 처리 로직을 가지고 있습니다:

인증 오류 (401/403): 계정을 사용 불가로 표시하고 즉시 장애 조치를 트리거하며 알림 로그를 기록합니다.
속도 제한 (429): 응답 헤더의 Retry-After 값을 읽어 쿨다운 기간을 설정하고, 이 시간 동안 자동으로 백업 계정으로 전환합니다.
서버 오류 (5xx): 짧은 쿨다운 후 재시도하며, 실패가 지속되면 계정을 전환합니다.

샌드박스 격리: 도구 및 실행 환경 보안

도구 사용 기능을 통합하는 시나리오에서 OpenClaw은 샌드박스 메커니즘을 통해 안전한 실행을 보장합니다.

경로 및 도구 제약

샌드박스 설정은 모든 도구의 파일 접근을 지정된 루트 디렉토리로 제한하여 AI가 민감한 시스템 파일에 접근하는 것을 방지합니다.

{
  sandbox: {
    enabled: true,
    roots: ["/data/openclaw/workspace"],  // 도구가 이 디렉토리만 접근 가능
    allowedTools: ["web_search", "calculator", "file_reader"],
  }
}

도구 목록은 허용 목록 방식을 사용합니다 — allowedTools에 명시적으로 나열된 도구만 호출할 수 있습니다. 경로 제약은 파일 작업 도구를 활성화해도 접근 범위가 샌드박스 루트 디렉토리로 엄격히 제한되도록 보장합니다.

명령 실행 격리

AI가 시스템 명령을 실행해야 할 때, OpenClaw은 호스트와 완전히 격리된 컨테이너 환경에서 실행합니다. exec 유형 도구의 모든 호출은 독립적인 컨테이너 인스턴스에서 실행되며, 컨테이너 소멸 후에는 흔적이 남지 않습니다.

브라우저 브리지

샌드박스 내의 브라우저 도구는 호스트 네트워크에서 직접 요청하는 대신 브리지 URL을 통해 외부 리소스에 접근합니다. 이 프록시 격리 레이어는 SSRF(Server-Side Request Forgery) 공격을 효과적으로 방지하며 네트워크 트래픽을 감사 가능하고 제어 가능하게 만듭니다.

Anthropic 공급자 특수 보안 조치

Anthropic(Claude)을 AI 공급자로 사용할 때, OpenClaw은 추가적인 보안 검사를 구현합니다:

매직 스트링 클리어링 거부: 시스템은 특수 문자열을 통해 컨텍스트나 시스템 프롬프트를 지우려는 요청을 감지하고 차단하여 프롬프트 인젝션 공격을 방지합니다.
연속 역할 검증: OpenClaw은 대화 메시지의 역할 순서가 적법한지 검증하여 동일한 역할의 연속 메시지가 나타나지 않도록 합니다. 이는 Anthropic API 형식 요구 사항이자 메시지 위조에 대한 보안 장벽입니다.

보안 설정 모범 사례

최소 권한 원칙: 기본 정책을 거부로 설정하고 필요한 허용 목록 항목만 개방합니다.
환경 변수로 키 관리: 모든 API 키를 설정 파일에 하드코딩하지 않고 ${ENV_VAR}로 참조합니다.
샌드박스 활성화: 도구 호출 기능을 사용하는 경우 항상 샌드박스 격리를 활성화합니다.
다중 계정 장애 조치 설정: 단일 장애 지점을 피하면서 속도 제한 압력을 분산합니다.
허용 목록 정기 검토: 더 이상 필요하지 않은 사용자 인가를 제거하여 접근 목록을 간결하게 유지합니다.
그룹 채팅에 멘션 모드 사용: 불필요한 API 호출과 정보 노출을 줄입니다.

요약

OpenClaw의 보안 시스템은 사용자 입장부터 실행 환경까지 전체 체인을 포괄합니다. 허용 목록, DM 페어링, 그룹 채팅 규칙, 다중 계정 인증, 샌드박스 격리를 적절히 설정하면 개방적이면서도 안전한 AI 게이트웨이를 구축할 수 있습니다. 이러한 보안 설정은 사고 발생 후가 아닌 배포 초기에 완료하는 것이 좋습니다. 보안 예방 비용은 사고 복구 비용보다 훨씬 낮습니다.