OpenClaw의 게이트웨이 서비스는 기본적으로 18789 포트에서 실행됩니다. 보안상의 이유로 공식에서는 이 포트를 절대 외부에 직접 노출하지 말 것을 명확히 권고하고 있습니다. 올바른 방법은 Nginx를 리버스 프록시로 사용하여 프론트엔드에서 SSL 암호화와 접근 제어를 처리한 후, 요청을 OpenClaw 게이트웨이로 전달하는 것입니다. 이 가이드에서는 이 배포 과정을 완전히 설명합니다.
리버스 프록시가 필요한 이유
OpenClaw의 18789 포트를 직접 노출하면 여러 가지 위험이 있습니다:
- 암호화 없는 전송: 게이트웨이는 기본적으로 HTTP를 사용하므로, 채팅 내용과 API 키가 중간자 공격에 의해 탈취될 수 있습니다
- 접근 제어 부재: 누구나 게이트웨이 인터페이스에 접근을 시도할 수 있습니다
- 도메인 사용 불가: 많은 채팅 플랫폼의 Webhook은 HTTPS 주소를 요구합니다
Nginx 리버스 프록시를 통해 SSL 암호화, 요청 필터링, 속도 제한 등 여러 계층의 보호를 얻을 수 있습니다. 자세한 보안 권고사항은 OpenClaw 공식 문서를 참고하세요.
사전 요구사항
- OpenClaw이 배포된 Linux 서버 (Ubuntu 22.04/24.04 권장)
- 서버 IP로 해석된 도메인 (예:
ai.example.com) - OpenClaw 게이트웨이가 로컬에서 정상 실행 중
1단계: Nginx 설치
sudo apt update
sudo apt install -y nginx
Nginx가 시작되었는지 확인합니다:
sudo systemctl status nginx
sudo systemctl enable nginx
2단계: Nginx 설정 파일 생성
OpenClaw 전용 Nginx 사이트 설정을 만듭니다:
sudo nano /etc/nginx/sites-available/openclaw
다음 설정 내용을 입력합니다:
upstream openclaw_gateway {
server 127.0.0.1:18789;
keepalive 64;
}
server {
listen 80;
server_name ai.example.com;
# certbot이 나중에 HTTPS 리다이렉트를 자동으로 추가합니다
location / {
proxy_pass http://openclaw_gateway;
proxy_http_version 1.1;
# WebSocket 지원 (OpenClaw의 일부 기능이 WebSocket에 의존합니다)
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 300s;
proxy_send_timeout 300s;
# 버퍼링 설정
proxy_buffering off;
proxy_cache off;
}
}
해당 사이트 설정을 활성화합니다:
sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t # 설정 문법 검사
sudo systemctl reload nginx
nginx -t 명령이 syntax is ok와 test is successful을 표시하면 설정이 올바른 것입니다.
3단계: SSL 인증서 발급
Let's Encrypt에서 제공하는 무료 SSL 인증서를 Certbot 도구로 자동 발급하고 설정합니다:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d ai.example.com
Certbot이 자동으로 다음 작업을 수행합니다:
- 도메인 소유권 검증
- SSL 인증서 발급
- Nginx 설정을 수정하여 HTTPS 리스닝 및 HTTP에서 HTTPS로의 자동 리다이렉트 추가
- 인증서 자동 갱신 설정
인증서는 기본 90일간 유효하며, Certbot이 자동으로 갱신 작업을 예약합니다. 갱신이 정상적으로 작동하는지 수동으로 확인할 수 있습니다:
sudo certbot renew --dry-run
4단계: OpenClaw 신뢰 프록시 설정
리버스 프록시를 사용하면, OpenClaw이 어떤 프록시를 신뢰해야 하는지 알아야 클라이언트의 실제 IP 주소를 올바르게 가져올 수 있습니다. OpenClaw 설정을 편집합니다:
nano ~/.config/openclaw/openclaw.json5
신뢰 프록시 설정을 추가합니다:
{
gateway: {
// 로컬 Nginx의 요청을 신뢰
trustedProxies: ["127.0.0.1", "::1"],
// 로컬에만 바인딩하여 외부 요청을 더 이상 수신하지 않음
host: "127.0.0.1",
port: 18789,
}
}
host를 127.0.0.1로 설정하면 게이트웨이가 로컬 연결만 수락합니다. 방화벽 설정에 실수가 있더라도 외부에서 18789 포트에 직접 접근할 수 없습니다.
게이트웨이를 재시작하여 설정을 적용합니다:
openclaw gateway restart
5단계: 방화벽 설정
UFW로 필요한 포트만 개방합니다:
sudo ufw allow 22/tcp # SSH
sudo ufw allow 80/tcp # HTTP (인증서 검증 및 리다이렉트용)
sudo ufw allow 443/tcp # HTTPS
sudo ufw deny 18789/tcp # 게이트웨이 포트 직접 접근 명시적 거부
sudo ufw enable
sudo ufw status
6단계: 전체 연결 검증
모든 설정이 완료된 후, 종단 간 검증을 수행합니다:
# Nginx가 정상적으로 프록시하는지 확인
curl -I https://ai.example.com
# OpenClaw 게이트웨이 상태 확인
openclaw doctor
# 18789 포트가 외부에 개방되지 않았는지 확인
# 다른 서버에서 실행:
curl http://서버IP:18789 # 연결이 거부되어야 합니다
고급: 속도 제한 추가
남용을 방지하기 위해 Nginx에 속도 제한을 추가할 수 있습니다. http 블록 (보통 /etc/nginx/nginx.conf에 위치)에 다음을 추가합니다:
# 속도 제한 영역 정의
limit_req_zone $binary_remote_addr zone=openclaw_limit:10m rate=10r/s;
그런 다음 사이트 설정의 location 블록에서 참조합니다:
location / {
limit_req zone=openclaw_limit burst=20 nodelay;
proxy_pass http://openclaw_gateway;
# ... 기타 설정은 그대로 유지
}
이 설정은 각 IP의 요청 빈도를 초당 10회로 제한하며, 최대 20회의 버스트 요청을 허용합니다.
마무리
Nginx 리버스 프록시와 SSL 인증서를 통해, OpenClaw 게이트웨이에 믿을 수 있는 보안 장치가 마련되었습니다. 모든 통신이 암호화되고, 게이트웨이 포트가 더 이상 노출되지 않으며, Nginx의 다양한 보안 기능을 유연하게 추가할 수 있습니다. Caddy 등 다른 웹 서버를 사용하는 경우에도 설정 개념은 유사하며, 구체적인 문법은 OpenClaw 공식 문서의 배포 가이드를 참고하세요. 설정 문제가 발생하면 OpenClaw GitHub 저장소에서 커뮤니티의 도움을 받을 수 있습니다.