OpenClaw SSL 인증서 및 HTTPS 암호화 설정

서문

OpenClaw Gateway는 기본적으로 18789 포트에서 HTTP 프로토콜로 실행됩니다. 프로덕션 환경에서, 특히 Web Dashboard를 외부에 노출하거나 Webhook으로 메시지를 수신할 때, HTTPS 암호화는 안전한 운영의 기본 요구사항입니다. 이 글에서는 OpenClaw에 SSL을 설정하는 세 가지 방안을 소개합니다.

1. 방안 선택

방안	적용 시나리오	복잡도	권장도
Nginx 리버스 프록시 + Let's Encrypt	프로덕션 환경, 도메인 보유	중	가장 권장
OpenClaw 내장 SSL	간단한 배포, 빠른 적용	낮음	테스트에 적합
자체 서명 인증서	내부 네트워크 환경, 도메인 없음	낮음	내부 네트워크 전용

2. 방안 1: Nginx 리버스 프록시 (권장)

프로덕션 환경에서 권장하는 방안으로, Nginx가 SSL 종료를 처리하고 OpenClaw은 HTTP로 유지합니다.

2.1 Nginx 및 Certbot 설치

# Ubuntu/Debian
sudo apt update
sudo apt install nginx certbot python3-certbot-nginx

# CentOS/RHEL
sudo yum install nginx certbot python3-certbot-nginx

2.2 Nginx 리버스 프록시 설정

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

server {
    listen 80;
    server_name openclaw.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        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;

        # WebSocket 지원
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 타임아웃 설정 (AI 응답이 느릴 수 있음)
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

# 사이트 설정 활성화
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

2.3 Let's Encrypt 인증서 발급

# 자동 발급 및 SSL 설정
sudo certbot --nginx -d openclaw.yourdomain.com

# 안내에 따라 진행:
# 1. 이메일 주소 입력 (인증서 만료 알림용)
# 2. 서비스 약관 동의
# 3. HTTP를 HTTPS로 리다이렉트할지 선택 (예를 권장)

Certbot이 자동으로 Nginx 설정을 수정하여 SSL 관련 설정을 추가합니다. 완료 후의 설정은 다음과 비슷합니다:

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass http://127.0.0.1:18789;
        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;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 120s;
        proxy_send_timeout 120s;
    }
}

server {
    listen 80;
    server_name openclaw.yourdomain.com;
    return 301 https://$host$request_uri;
}

2.4 인증서 자동 갱신

Let's Encrypt 인증서의 유효 기간은 90일이며, Certbot은 기본적으로 자동 갱신 타이머 작업을 설정합니다:

# 갱신 타이머 작업 확인
sudo systemctl list-timers | grep certbot

# 수동 갱신 테스트
sudo certbot renew --dry-run

# 자동 갱신이 설정되지 않은 경우 수동으로 crontab 추가
# 매일 새벽 3시에 갱신 시도
echo "0 3 * * * certbot renew --quiet --post-hook 'systemctl reload nginx'" | sudo tee -a /etc/crontab

2.5 SSL 보안 강화

Nginx 설정에 보안 헤더를 추가합니다:

# server 블록에 추가
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-XSS-Protection "1; mode=block" always;

# 강력한 암호화 알고리즘만 허용
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers on;

3. 방안 2: OpenClaw 내장 SSL

OpenClaw은 Nginx 없이 직접 SSL 인증서를 설정할 수 있습니다.

3.1 내장 SSL 설정

// ~/.config/openclaw/openclaw.json5
{
  "gateway": {
    "port": 18789,
    "ssl": {
      "enabled": true,
      "cert": "/path/to/fullchain.pem",
      "key": "/path/to/privkey.pem",
      "port": 18790   // HTTPS 리스닝 포트
    }
  }
}

3.2 Let's Encrypt 인증서 사용

# standalone 모드로 인증서 발급 (80 포트를 사용하는 서비스를 임시 중지해야 함)
sudo certbot certonly --standalone -d openclaw.yourdomain.com

# 인증서 파일 위치
# /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem
# /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem

Let's Encrypt 인증서 파일은 기본적으로 root만 읽을 수 있으므로 권한을 설정해야 합니다:

# 방안 1: openclaw 사용자를 ssl-cert 그룹에 추가
sudo usermod -aG ssl-cert openclaw
sudo chgrp -R ssl-cert /etc/letsencrypt/live/ /etc/letsencrypt/archive/
sudo chmod -R g+rx /etc/letsencrypt/live/ /etc/letsencrypt/archive/

# 방안 2: 인증서를 OpenClaw이 접근 가능한 위치로 복사
sudo mkdir -p /home/openclaw/.openclaw/ssl
sudo cp /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem /home/openclaw/.openclaw/ssl/
sudo cp /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem /home/openclaw/.openclaw/ssl/
sudo chown -R openclaw:openclaw /home/openclaw/.openclaw/ssl/
sudo chmod 600 /home/openclaw/.openclaw/ssl/privkey.pem

3.3 인증서 갱신 후 자동 리로드

# 갱신 후크 스크립트 생성
sudo nano /etc/letsencrypt/renewal-hooks/post/openclaw-reload.sh

#!/bin/bash
# 새 인증서를 OpenClaw 디렉토리로 복사
cp /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem /home/openclaw/.openclaw/ssl/
cp /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem /home/openclaw/.openclaw/ssl/
chown openclaw:openclaw /home/openclaw/.openclaw/ssl/*.pem

# OpenClaw을 리로드하여 새 인증서 적용
sudo -u openclaw openclaw restart

sudo chmod +x /etc/letsencrypt/renewal-hooks/post/openclaw-reload.sh

4. 방안 3: 자체 서명 인증서

내부 네트워크 배포 또는 테스트 환경에 적합합니다.

4.1 자체 서명 인증서 생성

# 인증서 디렉토리 생성
mkdir -p ~/.openclaw/ssl && cd ~/.openclaw/ssl

# 개인 키와 인증서 생성 (유효기간 365일)
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout privkey.pem \
  -out fullchain.pem \
  -subj "/CN=openclaw.local/O=OpenClaw/C=CN"

# 권한 설정
chmod 600 privkey.pem
chmod 644 fullchain.pem

4.2 OpenClaw에서 자체 서명 인증서 사용 설정

{
  "gateway": {
    "ssl": {
      "enabled": true,
      "cert": "~/.openclaw/ssl/fullchain.pem",
      "key": "~/.openclaw/ssl/privkey.pem",
      "port": 18790
    }
  }
}

4.3 클라이언트에서 자체 서명 인증서 신뢰

브라우저에서 접속 시 안전하지 않다는 경고가 표시되며, 수동으로 신뢰를 추가할 수 있습니다:

# Linux: 시스템 신뢰 목록에 추가
sudo cp ~/.openclaw/ssl/fullchain.pem /usr/local/share/ca-certificates/openclaw.crt
sudo update-ca-certificates

# macOS: 키체인에 추가
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.openclaw/ssl/fullchain.pem

5. HTTPS 설정 검증

설정 완료 후 HTTPS가 정상적으로 작동하는지 확인합니다:

# HTTPS 연결 테스트
curl -v https://openclaw.yourdomain.com/health

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

# SSL Labs 온라인 테스트 (공용 인터넷에서 접근 가능한 경우)
# https://www.ssllabs.com/ssltest/analyze.html?d=openclaw.yourdomain.com

6. 자주 묻는 질문

Q: HTTPS 설정 후 WebSocket 연결이 실패하나요?

Nginx 설정에 WebSocket을 지원하는 Upgrade와 Connection 헤더가 포함되어 있는지 확인하세요.

Q: 인증서 갱신 후 서비스에서 새 인증서를 로드하지 않나요?

OpenClaw은 인증서 파일 변경을 자동으로 감지하지 않으므로, 갱신 후 openclaw restart를 실행하거나 갱신 후크 스크립트를 설정해야 합니다.

Q: HTTP와 HTTPS를 함께 사용할 수 있나요?

두 포트를 동시에 리스닝할 수 있지만, 프로덕션 환경에서는 HTTPS를 강제하고 301 리다이렉트로 HTTP 요청을 HTTPS로 안내하는 것을 권장합니다.

SSL 인증서를 올바르게 설정하면 OpenClaw 서비스에 전송 계층 암호화 보호가 적용되어 보안 규정 준수 요구사항을 충족하며, HTTPS Webhook이 필요한 일부 메시지 플랫폼에 연결하기 위한 전제 조건이기도 합니다.