OpenClaw 원격 접속 및 포트 포워딩 설정

서문

기본적으로 OpenClaw은 127.0.0.1에서만 리스닝하여 로컬 접속만 허용합니다. 하지만 실제 배포에서는 외부 네트워크에서 Dashboard에 접속하거나, 인스턴트 메시징 플랫폼의 Webhook 콜백을 수신하거나, 모바일 디바이스 페어링 연결이 필요한 경우가 많습니다. 본 문서에서는 기본 포트 설정부터 프로덕션급 리버스 프록시 배포까지 OpenClaw의 원격 접속 방안을 체계적으로 소개합니다.

기본: 네트워크 접근 개방

가장 간단한 방법은 리스닝 주소를 0.0.0.0으로 변경하는 것입니다:

{
  "gateway": {
    "host": "0.0.0.0",
    "port": 18789
  }
}

변경 후 게이트웨이를 재시작합니다:

openclaw gateway --port 18789

이제 로컬 네트워크의 다른 디바이스에서 http://<서버IP>:18789로 OpenClaw에 접속할 수 있습니다. 하지만 공인 네트워크에서의 연결을 수신하려면 추가 설정이 필요합니다.

방법 1: 라우터 포트 포워딩

OpenClaw이 홈 네트워크에서 실행 중이라면 라우터에서 포트 포워딩(Port Forwarding)을 설정해야 합니다:

라우터 관리 페이지에 로그인
"포트 포워딩" 또는 "가상 서버" 설정 찾기
규칙 추가: 외부 포트 18789 -> 내부 IP 192.168.x.x 포트 18789
저장 및 적용

동적 DNS

가정용 인터넷의 공인 IP는 일반적으로 변경되므로 DDNS 서비스와 함께 사용하는 것이 좋습니다:

# 일반적인 DDNS 서비스
# Cloudflare DDNS
# DuckDNS
# No-IP

DDNS를 설정하면 고정 도메인(예: myserver.duckdns.org)으로 OpenClaw에 접속할 수 있으며, IP 변경을 신경 쓸 필요가 없습니다.

방법 2: Nginx 리버스 프록시

프로덕션 환경에서는 TLS 종료, 로드 밸런싱, 추가 보안 레이어를 제공하는 Nginx를 리버스 프록시로 사용하는 것을 권장합니다.

Nginx 설치

# Ubuntu / Debian
sudo apt install nginx

# CentOS / RHEL
sudo yum install nginx

설정 파일

Nginx 설정 파일 /etc/nginx/sites-available/openclaw 생성:

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

    # HTTP를 HTTPS로 리디렉션
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    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;

    # 권장 SSL 설정
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    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 지원 (Dashboard 실시간 업데이트 및 모바일 연결에 필요)
        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;
    }

    # 요청 본문 크기 제한 (OpenClaw의 maxBodySize와 매칭)
    client_max_body_size 20m;
}

설정 활성화

sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

방법 3: Caddy 리버스 프록시

더 간결한 설정을 선호한다면 Caddy가 훌륭한 대안입니다. Let's Encrypt 인증서를 자동으로 신청하고 갱신합니다.

Caddyfile 설정

openclaw.yourdomain.com {
    reverse_proxy localhost:18789
}

네, 이것이 전부입니다. Caddy가 HTTPS 인증서, HTTP-HTTPS 리디렉션, WebSocket 프록시 등을 자동으로 처리합니다.

# Caddy 시작
caddy start

방법 4: 내부 네트워크 터널링

포트 포워딩이 불가능한 네트워크 환경(회사 네트워크, 캠퍼스 네트워크 등)에서는 내부 네트워크 터널링 도구를 사용할 수 있습니다.

Cloudflare Tunnel 사용

# cloudflared 설치
# Cloudflare 로그인
cloudflared tunnel login

# 터널 생성
cloudflared tunnel create openclaw

# 터널 설정
# ~/.cloudflared/config.yml
tunnel: your-tunnel-id
credentials-file: ~/.cloudflared/your-tunnel-id.json

ingress:
  - hostname: openclaw.yourdomain.com
    service: http://localhost:18789
  - service: http_status:404

# 터널 시작
cloudflared tunnel run openclaw

frp 사용

# frpc.ini (클라이언트 설정)
[common]
server_addr = your-frp-server.com
server_port = 7000
token = your-auth-token

[openclaw]
type = tcp
local_ip = 127.0.0.1
local_port = 18789
remote_port = 18789

HTTPS 인증서 설정

Let's Encrypt (권장)

certbot을 사용하여 무료 SSL 인증서를 발급받습니다:

# certbot 설치
sudo apt install certbot python3-certbot-nginx

# Nginx + 인증서 자동 설정
sudo certbot --nginx -d openclaw.yourdomain.com

# 인증서 자동 갱신
sudo certbot renew --dry-run

OpenClaw 내장 TLS

리버스 프록시를 사용하지 않는 경우 OpenClaw에서 직접 TLS를 설정할 수 있습니다:

{
  "security": {
    "tls": {
      "enabled": true,
      "cert": "/etc/letsencrypt/live/yourdomain.com/fullchain.pem",
      "key": "/etc/letsencrypt/live/yourdomain.com/privkey.pem"
    }
  }
}

Webhook 콜백 주소 설정

많은 인스턴트 메시징 플랫폼(Telegram, WhatsApp 등)은 Webhook을 통해 서버로 메시지를 푸시합니다. 원격 접속 설정 후 Webhook 기본 주소를 업데이트해야 합니다:

{
  "gateway": {
    "webhookBase": "https://openclaw.yourdomain.com"
  }
}

OpenClaw이 webhookBase와 각 채널의 webhookPath를 자동으로 결합하여 완전한 콜백 URL을 생성하고 해당 플랫폼에 등록합니다. 예를 들어 Telegram의 Webhook은 https://openclaw.yourdomain.com/webhook/telegram으로 설정됩니다.

방화벽 설정

관련 포트가 방화벽에서 허용되어 있는지 확인합니다:

# UFW (Ubuntu)
sudo ufw allow 18789/tcp
sudo ufw allow 443/tcp
sudo ufw allow 80/tcp

# firewalld (CentOS)
sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p tcp --dport 18789 -j ACCEPT

보안 모범 사례

원격 접속은 공인 네트워크에 노출되는 것을 의미하므로 반드시 보안 조치를 취해야 합니다:

항상 HTTPS 사용: 전송 중인 데이터, 특히 API 키와 대화 내용 보호
Dashboard 비밀번호 설정: 승인되지 않은 관리 작업 방지
속도 제한 설정: 남용 및 DDoS 공격 방지
IP 화이트리스트 사용: 접속 출처가 고정된 경우 허용 IP 범위 제한
정기적 업데이트: OpenClaw과 리버스 프록시 소프트웨어를 최신 버전으로 유지
로그 모니터링: 접속 로그에서 비정상적인 요청을 정기적으로 확인

{
  "security": {
    "rateLimit": {
      "enabled": true,
      "maxRequests": 60,
      "windowMs": 60000
    },
    "ipWhitelist": ["203.0.113.0/24"]
  }
}

연결 검증

설정 완료 후 다음 방법으로 원격 접속이 정상인지 확인할 수 있습니다:

# 외부에서 HTTPS 연결 테스트
curl -I https://openclaw.yourdomain.com/dashboard

# WebSocket 연결 테스트
wscat -c wss://openclaw.yourdomain.com/ws

# OpenClaw 내장 연결 테스트
openclaw doctor --remote

요약

원격 접속 설정은 OpenClaw을 실제 사용에 투입하는 핵심 단계입니다. 개인 사용의 경우 라우터 포트 포워딩과 DDNS로 충분하며, 프로덕션 배포에서는 Nginx 또는 Caddy를 리버스 프록시로 사용하고 Let's Encrypt 인증서와 결합하여 안전한 HTTPS 접속을 구현하는 것을 권장합니다. 어떤 방안을 선택하든 보안 모범 사례를 반드시 준수하여 AI 게이트웨이가 남용되지 않도록 보호하세요.