본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

Fly.io에 OpenClaw 배포하기

원문 보기 위키 갱신

OpenClaw는 어디에서나 접근 가능한 상시 AI 어시스턴트를 실행할 수 있게 해주는 오픈소스 AI 에이전트 게이트웨이예요. 이 페이지에서는 배포 패키지를 내려받아 스크립트 하나로 Fly.io에 OpenClaw를 배포하는 방법을 설명해요. 앱 생성, 볼륨, 시크릿, 배포까지 모든 것을 처리해 줘요.

출처: 문서

본문

OpenClaw를 Fly.io에 배포하려면 배포 패키지를 내려받고 스크립트를 실행하면 돼요. 스크립트가 앱 생성, 볼륨, 시크릿, 배포 등 모든 것을 처리해 줘요.

Download Deploy Package

unzip Openclaw-Fly-Deploy-main.zip
cd Openclaw-Fly-Deploy-main
bash deploy.sh

**flyctl**이 설치되어 있고, Fly.io 계정(무료 체험 가능)과 LLM API 키(Anthropic, OpenAI, Google Gemini, OpenRouter, Moonshot AI, MiniMax 중 하나)가 필요해요.

OpenClaw란 무엇인가요?

OpenClaw는 오픈소스 AI 에이전트 게이트웨이로, Discord, Telegram, Slack 또는 로컬 CLI 등 어디에서나 접근할 수 있는 지속적인 AI 어시스턴트를 실행할 수 있게 해 줘요. 단일 게이트웨이 프로세스를 통해 여러 채널에서 대화, 도구 사용, 연결을 관리해요.

작동 방식 (How it works)

배포 패키지는 OpenClaw 게이트웨이를 관리하고 브라우저 기반 설정 마법사를 제공하는 래퍼(wrapper) 서버를 구성해요:

Internet → Fly.io proxy → Wrapper server (:3000) → OpenClaw gateway (:18789)
                              ├── /setup      → Setup wizard (password-protected)
                              ├── /healthz    → Health check (no auth)
                              └── /*          → Proxied to gateway

모든 상태는 /data에 마운트된 영구 볼륨에 저장되어요. 그래서 설정, 대화 기록, 설치된 도구가 재시작과 재배포 후에도 유지돼요.

스크립트는 다음 항목을 물어봐요:

  1. 앱 이름 — 기본값은 openclaw-XXXX(임의 접미사)예요. 이것이 여러분의 URL이 돼요: https://your-app-name.fly.dev
  2. 리전 — Machine을 실행할 위치예요(기본값은 iad / 버지니아). 지연 시간을 줄이려면 가까운 곳을 선택하세요. 전체 목록은 Fly.io 리전을 참고하세요.
  3. 설정 비밀번호 — 인터넷에서 /setup 마법사를 보호해요. 안전한 값을 선택하세요.
  4. LLM 제공자 — Anthropic, OpenAI, Google Gemini, OpenRouter, Moonshot AI, MiniMax 중에서 선택
  5. LLM API 키 — 선택한 제공자의 키
  6. 채널 토큰(선택) — 채팅 채널을 연결하려면 Discord 봇 토큰, Telegram 봇 토큰, 또는 Slack 봇+앱 토큰

그다음 스크립트는 Fly 앱을 만들고, 영구 볼륨을 프로비저닝하고, 자격 증명을 암호화된 Fly 시크릿으로 설정하고, Docker 이미지를 Fly의 원격 빌더에서 빌드해 배포해요. 첫 배포는 몇 분 걸려요. 자격 증명은 여러분의 머신을 떠나지 않아요. flyctl을 통해 Fly.io로 직접 전달되거든요.

배포 후 설정 (Post-deploy setup)

배포가 완료되면 스크립트가 여러분의 앱 세부 정보를 출력해요:

=== Deployment Complete ===

  App URL:       https://your-app-name.fly.dev
  Setup wizard:  https://your-app-name.fly.dev/setup
  Gateway URL:   wss://your-app-name.fly.dev
  Gateway token: <your-generated-token>

설정 마법사 (Setup wizard)

브라우저에서 https://your-app-name.fly.dev/setup을 방문하세요. 아무 사용자 이름과 선택한 설정 비밀번호로 로그인하면 돼요. 마법사에서 다음을 할 수 있어요:

  • LLM 제공자와 API 키 변경
  • Discord, Telegram, Slack 채널 연결 추가 또는 업데이트
  • 원시 OpenClaw 설정 파일 편집
  • 게이트웨이에 디버그 명령 실행
  • 설정 백업 내보내기 및 가져오기
  • 디바이스 페어링 요청 승인

로컬 CLI 연결하기

OpenClaw가 로컬에 설치되어 있다면 원격 게이트웨이를 가리키도록 설정하세요:

openclaw config set gateway.mode remote
openclaw config set gateway.remote.url wss://your-app-name.fly.dev
openclaw config set gateway.remote.token <your-gateway-token>
openclaw health  # verify the connection

이렇게 하면 랩톱에서 openclaw CLI를 사용하면서 게이트웨이는 Fly.io에서 실행할 수 있어요. 랩톱을 닫아도 대화와 상태가 유지되죠.

설정 (Configuration)

시크릿 (Secrets)

모든 민감한 값은 Fly 시크릿으로 저장되며, 저장 시 암호화되고 부팅 시 환경 변수로 주입돼요. 로그, 설정 파일, Fly 대시보드에는 절대 표시되지 않아요.

Secret Required Description
SETUP_PASSWORD Yes Protects the /setup wizard with HTTP Basic Auth
OPENCLAW_GATEWAY_TOKEN Yes Auth token for gateway connections (auto-generated)
OPENCLAW_API_KEY Yes Your LLM provider API key
OPENCLAW_AUTH_CHOICE Yes Provider identifier (set by deploy script)
OPENCLAW_API_KEY_FLAG Yes CLI flag for the provider (set by deploy script)
OPENCLAW_DISCORD_TOKEN No Discord bot token
OPENCLAW_TELEGRAM_TOKEN No Telegram bot token
OPENCLAW_SLACK_BOT_TOKEN No Slack bot token (xoxb-...)
OPENCLAW_SLACK_APP_TOKEN No Slack app token (xapp-..., required if bot token is set)

배포 후에 시크릿을 업데이트하려면:

fly secrets set OPENCLAW_API_KEY=«redacted:sk-…» -a your-app-name

시크릿이 변경되면 Machine이 자동으로 재시작돼요.

VM 크기 (VM sizing)

기본 설정은 4GB RAM의 shared-cpu-2x Machine을 사용하며, 연속 실행 시 한 달에 약 $20–25 정도 들어요. 자동 중지(auto-stop)가 기본으로 켜져 있어서 실제로 Machine이 실행되는 시간만큼만 비용을 내요.

리소스를 조정하려면:

fly scale memory 4096 -a your-app-name
fly scale vm shared-cpu-4x -a your-app-name

영구 저장소 (Persistent storage)

OpenClaw는 모든 상태를 /data에 마운트된 Fly 볼륨에 저장해요. 여기에는 다음이 포함돼요:

  • openclaw.json — 게이트웨이 설정
  • 대화 기록과 컨텍스트
  • 설치된 도구와 플러그인
  • 사용자가 설치한 패키지용 npm/pnpm 캐시

기본 볼륨 크기는 1GB예요. 확장하려면:

fly volumes extend <volume-id> -s 3 -a your-app-name

유용한 명령 (Useful commands)

Command Description
fly logs -a your-app-name Stream live logs
fly ssh console -a your-app-name SSH into the Machine
fly apps restart your-app-name Restart after config changes
fly scale memory 4096 -a your-app-name Increase memory
fly status -a your-app-name Check Machine status
fly volumes list -a your-app-name List attached volumes

문제 해결 (Troubleshooting)

"SETUP\_PASSWORD is not set" 설정 비밀번호 시크릿이 없어요. 설정하세요:

fly secrets set SETUP_PASSWORD=your-password -a your-app-name

메모리 부족 / 크래시 Machine의 메모리를 늘리세요:

fly scale memory 4096 -a your-app-name

게이트웨이가 시작되지 않아요 브라우저에서 /setup을 방문해 디버그 콘솔에서 오류를 확인하세요. 흔한 원인: 잘못된 API 키, 설정 파일 누락, 상태 디렉터리 손상.

잠금 파일 오류 게이트웨이가 깨끗하게 종료되지 않았다면 오래된 잠금 파일 때문에 시작되지 않을 수 있어요:

fly ssh console -a your-app-name
rm -f /data/gateway.*.lock
exit
fly apps restart your-app-name

처음부터 다시 시작하고 싶다면 설정 마법사의 "Reset" 버튼을 사용해 설정을 지우고 온보딩을 다시 실행하거나, SSH로 접속해 설정을 제거하세요:

fly ssh console -a your-app-name
rm /data/openclaw.json
exit
fly apps restart your-app-name

지원되는 LLM 제공자 (Supported LLM providers)

Provider What you need
Anthropic API key from console.anthropic.com
OpenAI API key from platform.openai.com
Google Gemini API key from aistudio.google.com
OpenRouter API key from openrouter.ai
Moonshot AI API key from Moonshot's developer portal
MiniMax API key from MiniMax's developer portal

언제든지 설정 마법사를 통해 제공자를 바꿀 수 있어요. 재배포가 필요 없어요.

더 알아보기 (Learn more)