Skip to main content

Fly.io 배포

목표: 영구 스토리지, 자동 HTTPS, Discord/채널 액세스를 갖춘 Fly.io 머신에서 실행되는 OpenClaw Gateway.

필요한 사항

  • flyctl CLI 설치됨
  • Fly.io 계정 (무료 티어 사용 가능)
  • 모델 인증: Anthropic API 키 (또는 다른 프로바이더 키)
  • 채널 자격 증명: Discord 봇 토큰, Telegram 토큰 등

초보자를 위한 빠른 경로

  1. 저장소 클론 → fly.toml 사용자 지정
  2. 앱 + 볼륨 생성 → 시크릿 설정
  3. fly deploy 로 배포
  4. SSH 접속하여 설정 생성 또는 Control UI 사용

1) Fly 앱 생성

팁: 가까운 리전을 선택하십시오. 일반적인 옵션: lhr (런던), iad (버지니아), sjc (산호세).

2. fly.toml 구성

앱 이름과 요구 사항에 맞게 fly.toml 를 편집하십시오. 보안 참고: 기본 설정은 공개 URL 을 노출합니다. 공개 IP 가 없는 강화된 배포를 원한다면 Private Deployment를 참고하거나 fly.private.toml 를 사용하십시오.
주요 설정:

3. 시크릿 설정

참고 사항:
  • non-loopback 바인딩 (--bind lan) 은 보안을 위해 OPENCLAW_GATEWAY_TOKEN 가 필요합니다.
  • 이러한 토큰은 비밀번호처럼 취급하십시오.
  • 모든 API 키와 토큰은 설정 파일보다 환경 변수를 우선 사용하십시오. 이렇게 하면 openclaw.json 에서 실수로 노출되거나 로그에 기록되는 것을 방지할 수 있습니다.

4. 배포

첫 배포 시 Docker 이미지가 빌드되며 (~2-3 분) 이후 배포는 더 빠릅니다. Subsequent deploys are faster. 배포 후 다음을 확인하십시오:
다음이 표시되어야 합니다:

5. 설정 파일 생성

머신에 SSH 로 접속하여 적절한 설정을 생성하십시오:
설정 디렉토리와 파일을 생성합니다:
참고: OPENCLAW_STATE_DIR=/data 를 사용하는 경우 설정 경로는 /data/openclaw.json 입니다. 참고: Discord 토큰은 다음 중 하나에서 제공될 수 있습니다:
  • 환경 변수: DISCORD_BOT_TOKEN (시크릿에 권장)
  • 설정 파일: channels.discord.token
환경 변수를 사용하는 경우 설정에 토큰을 추가할 필요가 없습니다. 게이트웨이는 DISCORD_BOT_TOKEN 를 자동으로 읽습니다. 적용을 위해 재시작하십시오:

6. Gateway 접근

제어 UI

브라우저에서 열기:
또는 https://my-openclaw.fly.dev/ 방문 인증을 위해 게이트웨이 토큰 (OPENCLAW_GATEWAY_TOKEN 에서 생성된 것) 을 붙여넣으십시오.

로그

SSH 콘솔

문제 해결

”앱이 예상된 주소에서 수신 대기하고 있지 않습니다”

게이트웨이가 0.0.0.0 대신 127.0.0.1 에 바인딩되어 있습니다. 해결: fly.toml 의 프로세스 명령에 --bind lan 를 추가하십시오.

헬스 체크 실패 / 연결 거부

Fly 가 구성된 포트에서 게이트웨이에 도달할 수 없습니다. 해결: internal_port 이 게이트웨이 포트와 일치하는지 확인하십시오 (--port 3000 또는 OPENCLAW_GATEWAY_PORT=3000 설정).

OOM / 메모리 문제

컨테이너가 계속 재시작되거나 종료됩니다. 징후: SIGABRT, v8::internal::Runtime_AllocateInYoungGeneration, 또는 무음 재시작. 해결: fly.toml 에서 메모리를 늘리십시오:
또는 기존 머신을 업데이트하십시오:
참고: 512MB 는 너무 작습니다. 1GB 는 동작할 수 있으나 부하가 있거나 상세 로그 사용 시 OOM 이 발생할 수 있습니다. 2GB 를 권장합니다.

Gateway 잠금 문제

Gateway 가 “already running” 오류로 시작을 거부합니다. 컨테이너가 재시작되었지만 PID 잠금 파일이 볼륨에 남아 있을 때 발생합니다. 해결: 잠금 파일을 삭제하십시오:
잠금 파일은 /data/gateway.*.lock 에 있습니다 (하위 디렉토리 아님).

구성이 읽히지 않음

--allow-unconfigured 를 사용하는 경우 게이트웨이는 최소 설정을 생성합니다. /data/openclaw.json 의 사용자 지정 설정은 재시작 시 읽혀야 합니다. 설정이 존재하는지 확인하십시오:

SSH 를 통한 설정 작성

fly ssh console -C 명령은 셸 리다이렉션을 지원하지 않습니다. 설정 파일을 작성하려면 다음을 사용하십시오:
참고: 파일이 이미 존재하면 fly sftp 가 실패할 수 있습니다. 먼저 삭제하십시오:

상태가 유지되지 않는 경우

재시작 후 자격 증명이나 세션이 사라진다면 상태 디렉토리가 컨테이너 파일 시스템에 기록되고 있습니다. 해결: fly.toml 에서 OPENCLAW_STATE_DIR=/data 이 설정되어 있는지 확인하고 재배포하십시오.

업데이트

머신 명령 업데이트

전체 재배포 없이 시작 명령을 변경해야 하는 경우:
참고: fly deploy 이후에는 머신 명령이 fly.toml 에 있는 값으로 재설정될 수 있습니다. 수동 변경을 했다면 배포 후 다시 적용하십시오.

비공개 배포 (강화됨)

기본적으로 Fly 는 공개 IP 를 할당하여 게이트웨이가 https://your-app.fly.dev 에서 접근 가능해집니다. 이는 편리하지만 인터넷 스캐너 (Shodan, Censys 등) 에 의해 발견될 수 있음을 의미합니다. 공개 노출이 없는 강화된 배포를 위해 private 템플릿을 사용하십시오.

private 배포를 사용해야 하는 경우

  • 아웃바운드 호출/메시지만 수행 (인바운드 웹훅 없음)
  • 웹훅 콜백에 ngrok 또는 Tailscale 터널 사용
  • 브라우저 대신 SSH, 프록시, 또는 WireGuard 로 게이트웨이에 접근
  • 배포를 인터넷 스캐너로부터 숨기고 싶은 경우

설정

표준 설정 대신 fly.private.toml 를 사용하십시오:
또는 기존 배포를 변환하십시오:
이후 fly ips list 에서는 private 유형의 IP 만 표시되어야 합니다:

private 배포 접근 방법

공개 URL 이 없으므로 다음 중 하나를 사용하십시오: 옵션 1: 로컬 프록시 (가장 간단)
옵션 2: WireGuard VPN
옵션 3: SSH 전용

private 배포에서의 웹훅

공개 노출 없이 웹훅 콜백 (Twilio, Telnyx 등) 이 필요한 경우: without public exposure:
  1. ngrok 터널 - 컨테이너 내부 또는 사이드카로 ngrok 실행
  2. Tailscale Funnel - Tailscale 을 통해 특정 경로 노출
  3. 아웃바운드 전용 - 일부 프로바이더 (Twilio) 는 웹훅 없이도 아웃바운드 호출이 정상 동작
ngrok 를 사용하는 음성 통화 설정 예시:
ngrok 터널은 컨테이너 내부에서 실행되며 Fly 앱 자체를 노출하지 않고 공개 웹훅 URL 을 제공합니다. 전달된 Host 헤더가 허용되도록 webhookSecurity.allowedHosts 를 공개 터널 호스트명으로 설정하십시오.

보안 이점

참고 사항

  • Fly.io 는 x86 아키텍처 를 사용합니다 (ARM 아님)
  • Dockerfile 은 두 아키텍처 모두와 호환됩니다
  • WhatsApp/Telegram 온보딩에는 fly ssh console 를 사용하십시오
  • 영구 데이터는 /data 의 볼륨에 저장됩니다
  • Signal 은 Java + signal-cli 가 필요하므로 커스텀 이미지를 사용하고 메모리는 2GB 이상으로 유지하십시오.

비용

권장 설정 (shared-cpu-2x, 2GB RAM) 기준:
  • 사용량에 따라 월 ~$10-15
  • 무료 티어에 일부 사용량 포함
자세한 내용은 Fly.io pricing 을 참고하십시오.