OpenClaw HTTPS 및 도메인 설정 완전 가이드

서문

기본적으로 OpenClaw 게이트웨이는 HTTP 프로토콜에서 실행됩니다. 공용 네트워크를 통해 Dashboard에 접속하거나 HTTPS가 필요한 채팅 플랫폼 (예: Telegram Webhook)과 연동해야 하는 경우 반드시 HTTPS를 설정해야 합니다. 본 가이드에서는 세 가지 주요 방안을 다룹니다: Let's Encrypt 무료 인증서, Cloudflare SSL, Nginx 리버스 프록시.

방안 비교

방안	난이도	비용	적합 사용 사례
Let's Encrypt + Certbot	중간	무료	자체 서버, 커스텀 도메인
Cloudflare SSL	쉬움	무료	Cloudflare에서 도메인 관리
Nginx 리버스 프록시 + SSL	중간	무료	고급 프록시 기능 필요 시

전제 조건

공인 IP가 있는 서버
등록된 도메인 (예: ai.example.com)
도메인 DNS가 서버 IP를 가리키도록 설정
OpenClaw가 설치되어 18789 포트에서 정상 실행 중

OpenClaw 실행 확인:

openclaw doctor
curl http://localhost:18789/health

방안 1: Let's Encrypt + Certbot

1.1 Certbot 설치

# Ubuntu/Debian
sudo apt update
sudo apt install certbot

# CentOS/RHEL
sudo dnf install certbot

# macOS
brew install certbot

1.2 인증서 발급

80 포트가 사용 중이 아닌지 확인합니다 (Certbot이 임시로 사용해야 함):

# 80 포트 확인
sudo lsof -i :80

# 사용 중이면 임시로 중지 (예: nginx)
sudo systemctl stop nginx

인증서 신청:

sudo certbot certonly --standalone \
  -d ai.example.com \
  --email [email protected] \
  --agree-tos \
  --no-eff-email

성공 후 인증서 파일 위치:

/etc/letsencrypt/live/ai.example.com/fullchain.pem   # 인증서 체인
/etc/letsencrypt/live/ai.example.com/privkey.pem      # 개인 키

1.3 OpenClaw에서 인증서 사용 설정

OpenClaw 설정 파일을 편집합니다:

{
  server: {
    port: 18789,
    host: "0.0.0.0",
    ssl: {
      enabled: true,
      cert: "/etc/letsencrypt/live/ai.example.com/fullchain.pem",
      key: "/etc/letsencrypt/live/ai.example.com/privkey.pem",
    }
  }
}

OpenClaw 재시작:

openclaw restart

HTTPS 적용 확인:

curl https://ai.example.com:18789/health

1.4 자동 갱신 설정

Let's Encrypt 인증서는 유효 기간이 90일이므로 자동 갱신이 필요합니다:

# 갱신 정상 작동 테스트
sudo certbot renew --dry-run

# cron 작업으로 자동 갱신 추가
sudo crontab -e

다음 내용을 추가합니다:

# 매일 새벽 3시에 인증서 확인 및 갱신
0 3 * * * certbot renew --quiet --post-hook "openclaw restart"

--post-hook은 갱신 후 자동으로 OpenClaw를 재시작하여 새 인증서를 로드합니다.

방안 2: Cloudflare SSL

도메인이 Cloudflare에서 관리되고 있다면 가장 간단한 방안입니다.

2.1 DNS 설정

Cloudflare Dashboard에서 DNS 레코드를 추가합니다:

유형: A
이름: ai (ai.example.com에 해당)
내용: 서버 IP
프록시 상태: 프록시됨 (주황색 구름)

2.2 SSL 모드 설정

Cloudflare Dashboard → SSL/TLS에서:

SSL/TLS 암호화 모드: Full (Strict)

각 모드 설명:

모드	설명	권장
Off	암호화 없음	비권장
Flexible	브라우저→Cloudflare 암호화, Cloudflare→서버 비암호화	비권장
Full	전 구간 암호화, 서버 인증서 미검증	보통
Full (Strict)	전 구간 암호화, 서버 인증서 검증	권장

2.3 Cloudflare Origin 인증서 발급

Full (Strict) 모드에서는 서버에 Origin 인증서를 설치해야 합니다:

Cloudflare Dashboard → SSL/TLS → Origin Server에 진입합니다
Create Certificate를 클릭합니다
기본 설정을 유지하고 Create를 클릭합니다
인증서와 개인 키를 복사합니다

서버에 저장:

# 인증서 저장
sudo mkdir -p /etc/cloudflare
sudo nano /etc/cloudflare/origin-cert.pem
# 인증서 내용 붙여넣기

sudo nano /etc/cloudflare/origin-key.pem
# 개인 키 내용 붙여넣기

# 권한 설정
sudo chmod 600 /etc/cloudflare/origin-key.pem

2.4 OpenClaw 설정

{
  server: {
    port: 18789,
    host: "0.0.0.0",
    ssl: {
      enabled: true,
      cert: "/etc/cloudflare/origin-cert.pem",
      key: "/etc/cloudflare/origin-key.pem",
    }
  }
}

openclaw restart

Cloudflare Origin 인증서는 최대 15년 유효하므로 빈번한 갱신이 필요 없습니다.

2.5 Cloudflare 보안 옵션 설정

Cloudflare Dashboard에서 다음을 활성화하는 것을 권장합니다:

Always Use HTTPS: HTTP를 자동으로 HTTPS로 리다이렉트
HSTS: HTTP Strict Transport Security 활성화
Minimum TLS Version: TLS 1.2로 설정
Automatic HTTPS Rewrites: 혼합 콘텐츠 자동 수정

방안 3: Nginx 리버스 프록시

가장 유연한 방안으로, 로드 밸런싱, 캐싱 등 고급 기능이 필요한 경우에 적합합니다.

3.1 Nginx 설치

# Ubuntu/Debian
sudo apt update
sudo apt install nginx

# CentOS/RHEL
sudo dnf install nginx

3.2 SSL 인증서 발급

Certbot의 Nginx 플러그인으로 원클릭 발급:

sudo apt install python3-certbot-nginx
sudo certbot --nginx -d ai.example.com

또는 수동으로 인증서를 발급합니다 (방안 1의 1.2 단계와 동일).

3.3 Nginx 설정

Nginx 설정 파일을 생성합니다:

sudo nano /etc/nginx/sites-available/openclaw

다음 내용을 작성합니다:

# HTTP를 HTTPS로 리다이렉트
server {
    listen 80;
    server_name ai.example.com;
    return 301 https://$server_name$request_uri;
}

# HTTPS 메인 설정
server {
    listen 443 ssl http2;
    server_name ai.example.com;

    # SSL 인증서
    ssl_certificate /etc/letsencrypt/live/ai.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.example.com/privkey.pem;

    # SSL 보안 설정
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    # 기타 보안 헤더
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";

    # OpenClaw로 리버스 프록시
    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 타임아웃 설정 (AI 응답에 긴 시간이 걸릴 수 있음)
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }

    # Dashboard 정적 리소스 캐싱
    location /dashboard/assets/ {
        proxy_pass http://127.0.0.1:18789;
        expires 7d;
        add_header Cache-Control "public, immutable";
    }
}

3.4 설정 활성화

# 심볼릭 링크 생성
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/

# 설정 문법 테스트
sudo nginx -t

# Nginx 리로드
sudo systemctl reload nginx

3.5 OpenClaw 프록시 신뢰 설정

Nginx 리버스 프록시를 사용할 때, OpenClaw 자체에서 SSL을 처리할 필요가 없습니다:

{
  server: {
    port: 18789,
    host: "127.0.0.1",           // 로컬만 수신, Nginx가 프록시
    trustProxy: true,             // 프록시가 전달하는 X-Forwarded-For 신뢰
    ssl: {
      enabled: false,             // Nginx가 SSL 처리, OpenClaw는 불필요
    }
  }
}

3.6 자동 갱신 (Nginx 방안)

sudo crontab -e

0 3 * * * certbot renew --quiet --post-hook "systemctl reload nginx"

커스텀 도메인 설정

DNS 설정 예시

레코드 유형	이름	값	설명
A	ai	203.0.113.1	서버 IP 지정
AAAA	ai	2001:db8::1	IPv6 주소 (선택)
CNAME	www.ai	ai.example.com	www 리다이렉트 (선택)

다중 도메인 지원

여러 도메인이 동일한 OpenClaw 인스턴스를 가리켜야 하는 경우:

server {
    listen 443 ssl http2;
    server_name ai.example.com bot.example.com assistant.example.com;

    # 인증서가 모든 도메인을 커버해야 함
    ssl_certificate /etc/letsencrypt/live/ai.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.example.com/privkey.pem;

    # ... 나머지 설정은 위와 동일
}

다중 도메인 인증서 신청:

sudo certbot certonly --standalone \
  -d ai.example.com \
  -d bot.example.com \
  -d assistant.example.com

검증 및 테스트

HTTPS 연결 테스트

# 기본 연결 테스트
curl -I https://ai.example.com

# 인증서 정보 확인
openssl s_client -connect ai.example.com:443 -servername ai.example.com </dev/null 2>/dev/null | openssl x509 -noout -dates

# SSL Labs 온라인 검사 사용 (브라우저에서 접속)
# https://www.ssllabs.com/ssltest/analyze.html?d=ai.example.com

HSTS 확인

curl -I https://ai.example.com | grep -i strict
# 다음이 보여야 함: Strict-Transport-Security: max-age=31536000; includeSubDomains

자주 묻는 질문

인증서 갱신 실패

# Certbot 로그 확인
sudo cat /var/log/letsencrypt/letsencrypt.log

# 수동 갱신 및 상세 출력 확인
sudo certbot renew --verbose

일반적인 원인: 80 포트 점유, DNS 해석 문제, 방화벽 차단.

혼합 콘텐츠 경고

브라우저에서 "일부 콘텐츠가 안전하지 않음"이 표시되는 경우, 페이지에서 HTTP 리소스를 참조하고 있기 때문입니다. Cloudflare에서 Automatic HTTPS Rewrites를 활성화하면 자동으로 수정됩니다.

WebSocket 연결 실패

Nginx 설정에 WebSocket 지원이 포함되어 있는지 확인합니다:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

요약

OpenClaw에 HTTPS를 설정하는 것은 프로덕션 환경에서 반드시 필요한 단계입니다. 대부분의 사용자에게는 Cloudflare SSL (가장 간단) 또는 Nginx + Let's Encrypt (가장 유연)를 권장합니다. 어떤 방안을 선택하든 HSTS 활성화, HTTP에서 HTTPS로의 리다이렉트 설정, 인증서 자동 갱신을 반드시 구성하십시오. 보안에 타협은 없으며, HTTPS는 여러분과 사용자의 데이터를 보호하는 첫 번째 방어선입니다.