OpenClaw 접근 제어 및 보안 강화 가이드

서문

OpenClaw는 여러 채팅 플랫폼을 연결하는 AI 게이트웨이로, 보안이 매우 중요합니다. 비인가 사용자에 의해 악용될 경우, 고액의 API 비용이 발생할 수 있을 뿐만 아니라 민감한 정보가 유출될 수 있습니다. 본 가이드에서는 Dashboard 인증, 사용자 접근 제어, 속도 제한, 감사 로그 등 여러 층면에서 OpenClaw의 보안을 강화하는 방법을 안내합니다.

보안 위협 개요

위협 유형	위험 등급	설명
Dashboard 비인가 접근	높음	공격자가 설정 수정, 대화 열람 가능
API Key 유출	높음	타인이 사용자의 API 할당량 사용 가능
사용자 남용	중간	인가된 사용자의 과도한 사용으로 고비용 발생
대화 내용 유출	중간	대화 기록에 대한 비인가 접근
DDoS 공격	중간	악의적 요청으로 서비스 마비
인젝션 공격	낮음	악의적 프롬프트로 AI 행동 조작

1단계: Dashboard 인증

1.1 비밀번호 인증 활성화

기본적으로 Dashboard에 비밀번호 보호가 없을 수 있습니다. 즉시 설정하십시오:

{
  dashboard: {
    enabled: true,
    port: 18789,
    auth: {
      enabled: true,
      username: "admin",
      password: "${OPENCLAW_DASHBOARD_PASSWORD}",  // 환경 변수 사용
    }
  }
}

환경 변수 설정:

# 강력한 비밀번호 생성
openssl rand -base64 32
# 출력 예시: K7x9mP2vQ4wR1tY6uI3oA8sD5fG0hJ=

# 환경 변수에 추가
echo 'export OPENCLAW_DASHBOARD_PASSWORD="K7x9mP2vQ4wR1tY6uI3oA8sD5fG0hJ="' >> ~/.bashrc
source ~/.bashrc

1.2 세션 관리 설정

{
  dashboard: {
    auth: {
      enabled: true,
      username: "admin",
      password: "${OPENCLAW_DASHBOARD_PASSWORD}",
      session: {
        timeout: 3600,           // 세션 만료 시간 (초), 1시간
        maxSessions: 3,          // 최대 동시 로그인 수
        secureCookie: true,      // HTTPS를 통해서만 Cookie 전송
      }
    }
  }
}

1.3 다중 사용자 관리

팀에서 OpenClaw를 관리해야 하는 경우:

{
  dashboard: {
    auth: {
      enabled: true,
      users: [
        {
          username: "admin",
          password: "${ADMIN_PASSWORD}",
          role: "admin",          // 전체 제어 권한
        },
        {
          username: "operator",
          password: "${OPERATOR_PASSWORD}",
          role: "operator",       // 로그 및 상태 조회 가능, 설정 변경 불가
        },
        {
          username: "viewer",
          password: "${VIEWER_PASSWORD}",
          role: "viewer",         // 읽기 전용 권한
        }
      ]
    }
  }
}

역할 권한 비교:

권한	admin	operator	viewer
Dashboard 조회	✓	✓	✓
로그 조회	✓	✓	✓
대화 기록 조회	✓	✓	✗
설정 수정	✓	✗	✗
사용자 관리	✓	✗	✗
서비스 재시작	✓	✓	✗

2단계: API Key 보호

2.1 환경 변수 저장 (필수)

API Key를 절대로 설정 파일에 평문으로 작성하지 마십시오:

// 잘못된 예시 ✗
{
  models: {
    openai: {
      apiKey: "sk-proj-abc123..."   // 이렇게 하지 마세요!
    }
  }
}

// 올바른 방법 ✓
{
  models: {
    openai: {
      apiKey: "${OPENAI_API_KEY}"   // 환경 변수를 통해 참조
    }
  }
}

2.2 파일 권한 제어

# 설정 파일 권한 제한
chmod 600 ~/.config/openclaw/openclaw.json5

# 파일 소유자 확인
chown $(whoami) ~/.config/openclaw/openclaw.json5

# 권한 확인
ls -la ~/.config/openclaw/openclaw.json5
# -rw------- (소유자만 읽기/쓰기 가능)이 표시되어야 합니다

2.3 Git 제외

Git으로 설정을 관리하는 경우, 민감한 파일이 제외되어 있는지 확인합니다:

# .gitignore에 추가
echo "openclaw.json5" >> ~/.config/openclaw/.gitignore
echo ".env" >> ~/.config/openclaw/.gitignore
echo "*.key" >> ~/.config/openclaw/.gitignore
echo "*.pem" >> ~/.config/openclaw/.gitignore

3단계: 사용자 화이트리스트/블랙리스트

3.1 사용자 화이트리스트 (권장)

지정된 사용자만 AI 어시스턴트를 사용할 수 있도록 합니다:

{
  accessControl: {
    mode: "whitelist",            // whitelist 또는 blacklist
    whitelist: {
      telegram: [
        "123456789",              // Telegram 사용자 ID
        "987654321",
      ],
      whatsapp: [
        "+8613800138000",         // WhatsApp 전화번호
        "+8613900139000",
      ],
      discord: [
        "112233445566778899",     // Discord 사용자 ID
      ]
    },
    denyMessage: "抱歉，你没有使用该助手的权限。请联系管理员。",
  }
}

3.2 사용자 블랙리스트

대부분의 사용자가 사용 가능하고 특정 사용자만 차단해야 하는 경우:

{
  accessControl: {
    mode: "blacklist",
    blacklist: {
      telegram: [
        "111111111",              // 차단된 사용자
      ],
      global: [
        "[email protected]",   // 전체 채널 차단
      ]
    },
    blockMessage: "你的访问权限已被暂停。",
  }
}

3.3 그룹 권한 제어

그룹 내 봇의 경우, 어떤 그룹에서 사용을 허용할지 제한할 수 있습니다:

{
  accessControl: {
    groups: {
      telegram: {
        allowedGroups: [
          "-1001234567890",       // 허용된 그룹 ID
          "-1009876543210",
        ],
        allowPrivate: true,       // 개인 대화 허용
      },
      discord: {
        allowedServers: [
          "1234567890123456",     // 허용된 서버 ID
        ],
        allowedChannels: [
          "9876543210987654",     // 허용된 채널 ID (더 세밀한 제어)
        ]
      }
    }
  }
}

4단계: 속도 제한

4.1 전역 속도 제한

개별 사용자의 과도한 사용을 방지합니다:

{
  rateLimit: {
    global: {
      maxRequestsPerMinute: 30,     // 전역 분당 최대 30회 요청
      maxRequestsPerHour: 500,      // 전역 시간당 최대 500회
      maxRequestsPerDay: 5000,      // 전역 일일 최대 5000회
    }
  }
}

4.2 사용자별 속도 제한

{
  rateLimit: {
    perUser: {
      maxRequestsPerMinute: 5,      // 사용자당 분당 5회
      maxRequestsPerHour: 60,       // 사용자당 시간당 60회
      maxRequestsPerDay: 500,       // 사용자당 일일 500회
      cooldownMessage: "你发送消息太频繁了，请稍后再试。",
    }
  }
}

4.3 등급별 속도 제한

사용자 그룹별로 다른 제한을 설정합니다:

{
  rateLimit: {
    tiers: {
      vip: {
        users: ["123456789", "+8613800138000"],
        maxRequestsPerMinute: 20,
        maxRequestsPerDay: 2000,
      },
      standard: {
        default: true,               // 지정되지 않은 사용자는 이 등급 적용
        maxRequestsPerMinute: 5,
        maxRequestsPerDay: 200,
      },
      restricted: {
        users: ["987654321"],
        maxRequestsPerMinute: 1,
        maxRequestsPerDay: 20,
      }
    }
  }
}

5단계: IP 제한

5.1 Dashboard IP 화이트리스트

특정 IP만 Dashboard에 접근할 수 있도록 합니다:

{
  dashboard: {
    auth: {
      enabled: true,
      username: "admin",
      password: "${OPENCLAW_DASHBOARD_PASSWORD}",
    },
    ipWhitelist: [
      "203.0.113.0/24",            // 사무실 IP 대역
      "198.51.100.1",              // 자택 IP
      "127.0.0.1",                 // 로컬 접근
    ]
  }
}

5.2 방화벽을 이용한 제한

시스템 레벨의 IP 제한이 더 안정적입니다:

# ufw 사용 (Ubuntu)
sudo ufw allow from 203.0.113.0/24 to any port 18789
sudo ufw deny 18789

# iptables 사용
sudo iptables -A INPUT -p tcp --dport 18789 -s 203.0.113.0/24 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 18789 -j DROP

5.3 Fail2ban으로 무차별 대입 공격 방지

Fail2ban을 설정하여 로그인 실패가 여러 번 발생한 IP를 자동 차단합니다:

sudo apt install fail2ban

OpenClaw용 Fail2ban 규칙을 생성합니다:

sudo nano /etc/fail2ban/jail.d/openclaw.conf

[openclaw]
enabled = true
port = 18789
filter = openclaw
logpath = /var/log/openclaw/access.log
maxretry = 5
findtime = 600
bantime = 3600

필터를 생성합니다:

sudo nano /etc/fail2ban/filter.d/openclaw.conf

[Definition]
failregex = ^.*authentication failed.*from <HOST>.*$
ignoreregex =

sudo systemctl restart fail2ban

6단계: 감사 로그

6.1 상세 로깅 활성화

{
  logging: {
    level: "info",                   // debug, info, warn, error
    file: "/var/log/openclaw/openclaw.log",
    audit: {
      enabled: true,
      file: "/var/log/openclaw/audit.log",
      events: [
        "auth.login",                // 로그인 이벤트
        "auth.failed",               // 로그인 실패
        "config.change",             // 설정 변경
        "user.blocked",              // 사용자 차단
        "rateLimit.exceeded",        // 속도 제한 트리거
        "message.received",          // 메시지 수신 (선택, 양 많음)
      ]
    }
  }
}

6.2 로그 로테이션

로그 파일이 무한히 커지는 것을 방지합니다:

sudo nano /etc/logrotate.d/openclaw

/var/log/openclaw/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 640 openclaw openclaw
    postrotate
        openclaw restart > /dev/null 2>&1 || true
    endscript
}

6.3 감사 로그 조회

# 최근 감사 이벤트 확인
openclaw logs --audit --since 24h

# 로그인 실패 이벤트 필터링
openclaw logs --audit --filter "auth.failed"

# 특정 사용자의 활동 조회
openclaw logs --audit --user "123456789"

7단계: 보안 모범 사례 체크리스트

배포 전 점검

# 보안 점검 실행
openclaw doctor --security

보안 체크리스트

점검 항목	상태	설명
Dashboard 비밀번호 설정 완료	□	강력한 비밀번호 사용, 최소 16자리
API Key 환경 변수 사용	□	설정 파일에 평문 저장 안 함
설정 파일 권한 600	□	소유자만 읽기/쓰기 가능
HTTPS 활성화	□	프로덕션 환경 필수
사용자 화이트리스트 설정	□	사용 가능한 사용자 제한
속도 제한 활성화	□	남용 방지
감사 로그 활성화	□	주요 작업 기록
방화벽 설정	□	필요한 포트만 개방
자동 업데이트 활성화	□	보안 취약점 신속 수정
정기 백업	□	데이터 손실 방지

정기 보안 유지보수

# 매주: 감사 로그에서 이상 징후 확인
openclaw logs --audit --since 7d --filter "auth.failed"

# 매월: OpenClaw를 최신 버전으로 업데이트
npm update -g openclaw@latest

# 매월: Dashboard 비밀번호 변경
# 환경 변수의 비밀번호 업데이트 후 재시작

# 분기별: 화이트리스트 검토, 비활성 사용자 제거

자주 묻는 질문

Dashboard 비밀번호를 잊어버린 경우

# 환경 변수의 비밀번호 직접 변경
export OPENCLAW_DASHBOARD_PASSWORD="새비밀번호"
openclaw restart

자신의 IP를 실수로 차단한 경우

# SSH로 서버에 접속한 후
# Fail2ban이 차단한 경우
sudo fail2ban-client set openclaw unbanip 자신의IP

# 설정 파일의 IP 화이트리스트인 경우
# 설정 파일을 편집하여 IP를 추가한 후 재시작
openclaw restart

속도 제한이 너무 엄격한 경우

로그에서 rateLimit.exceeded 이벤트의 빈도를 관찰하고 적절히 조정합니다:

openclaw logs --audit --filter "rateLimit.exceeded" --since 24h

실제 사용 상황에 따라 제한 값을 조정합니다.

요약

보안 강화는 프로덕션급 OpenClaw 인스턴스를 운영하기 위한 필수 단계입니다. 핵심 조치는 Dashboard 인증 활성화, 환경 변수를 통한 API Key 보호, 사용자 화이트리스트 설정, 속도 제한 구성, 감사 로그 활성화입니다. 이러한 조치들은 복잡하지 않지만 보안성을 크게 향상시킵니다. 본 문서의 보안 체크리스트를 항목별로 확인하고 설정하여, AI 어시스턴트가 안전하고 통제 가능한 환경에서 운영되도록 보장하시기 바랍니다.