Fly.io 배포

목표: Fly.io 머신에서 영구 스토리지, 자동 HTTPS, Discord/채널 접근이 가능한 OpenClaw 게이트웨이를 실행합니다.

필요한 것

• flyctl CLI 설치
• Fly.io 계정 (무료 티어로 가능)
• 모델 인증: 선택한 모델 프로바이더의 API 키
• 채널 인증 정보: Discord 봇 토큰, Telegram 토큰 등

초보자 빠른 경로

1. 저장소 클론 → fly.toml 커스터마이즈
2. 앱 + 볼륨 생성 → 시크릿 설정
3. fly deploy로 배포
4. SSH 접속하여 설정 파일 생성 또는 Control UI 사용

1) Fly 앱 생성

# 저장소 클론
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 새 Fly 앱 생성 (원하는 이름으로)
fly apps create my-openclaw

# 영구 볼륨 생성 (1GB면 보통 충분합니다)
fly volumes create openclaw_data --size 1 --region iad

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

2) fly.toml 구성

앱 이름과 요구사항에 맞게 fly.toml을 편집하세요.

보안 참고: 기본 설정은 공개 URL을 노출합니다. 퍼블릭 IP 없이 보안 강화된 배포를 하려면 비공개 배포를 참고하거나 fly.private.toml을 사용하세요.

app = "my-openclaw"  # Your app name
primary_region = "iad"

[build]
  dockerfile = "Dockerfile"

[env]
  NODE_ENV = "production"
  OPENCLAW_PREFER_PNPM = "1"
  OPENCLAW_STATE_DIR = "/data"
  NODE_OPTIONS = "--max-old-space-size=1536"

[processes]
  app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = false
  auto_start_machines = true
  min_machines_running = 1
  processes = ["app"]

[[vm]]
  size = "shared-cpu-2x"
  memory = "2048mb"

[mounts]
  source = "openclaw_data"
  destination = "/data"

주요 설정:

3) 시크릿 설정

# 필수: 게이트웨이 토큰 (비루프백 바인딩에 필요)
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

# 모델 프로바이더 API 키
fly secrets set ANTHROPIC_API_KEY=sk-ant-...

# 선택사항: 기타 프로바이더
fly secrets set OPENAI_API_KEY=sk-...
fly secrets set GOOGLE_API_KEY=...

# 채널 토큰
fly secrets set DISCORD_BOT_TOKEN=MTQ...

참고:

• 비루프백 바인드(--bind lan)는 보안을 위해 OPENCLAW_GATEWAY_TOKEN이 필요합니다.
• 이 토큰들은 비밀번호처럼 취급하세요.
• 모든 API 키와 토큰은 설정 파일보다 환경 변수를 권장합니다. 이렇게 하면 실수로 노출되거나 로깅될 수 있는 openclaw.json에서 시크릿을 분리할 수 있습니다.

4) 배포

fly deploy

첫 배포는 Docker 이미지를 빌드하므로 약 2-3분 걸립니다. 이후 배포는 더 빠릅니다.

배포 후 확인:

fly status
fly logs

다음과 같은 출력이 보여야 합니다:

[gateway] listening on ws://0.0.0.0:3000 (PID xxx)
[discord] logged in to discord as xxx

5) 설정 파일 생성

머신에 SSH 접속하여 적절한 설정을 생성합니다:

fly ssh console

설정 디렉토리와 파일을 생성합니다:

mkdir -p /data
cat > /data/openclaw.json << 'EOF'
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-6",
        "fallbacks": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o"]
      },
      "maxConcurrent": 4
    },
    "list": [
      {
        "id": "main",
        "default": true
      }
    ]
  },
  "auth": {
    "profiles": {
      "anthropic:default": { "mode": "token", "provider": "anthropic" },
      "openai:default": { "mode": "token", "provider": "openai" }
    }
  },
  "bindings": [
    {
      "agentId": "main",
      "match": { "channel": "discord" }
    }
  ],
  "channels": {
    "discord": {
      "enabled": true,
      "groupPolicy": "allowlist",
      "guilds": {
        "YOUR_GUILD_ID": {
          "channels": { "general": { "allow": true } },
          "requireMention": false
        }
      }
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "auto"
  },
  "meta": {
    "lastTouchedVersion": "2026.1.29"
  }
}
EOF

참고: OPENCLAW_STATE_DIR=/data이므로 설정 파일 경로는 /data/openclaw.json입니다.

참고: Discord 토큰은 다음 중 하나에서 가져올 수 있습니다:

• 환경 변수: DISCORD_BOT_TOKEN (시크릿에 권장)
• 설정 파일: channels.discord.token

환경 변수를 사용하면 설정에 토큰을 추가할 필요가 없습니다. 게이트웨이가 DISCORD_BOT_TOKEN을 자동으로 읽습니다.

적용을 위해 재시작합니다:

exit
fly machine restart <machine-id>

6) 게이트웨이 접속

Control UI

브라우저에서 열기:

fly open

또는 https://my-openclaw.fly.dev/에 접속합니다.

인증을 위해 게이트웨이 토큰(OPENCLAW_GATEWAY_TOKEN의 값)을 붙여넣으세요.

로그

fly logs              # 실시간 로그
fly logs --no-tail    # 최근 로그

SSH 콘솔

fly ssh console

문제 해결

”App is not listening on expected address”

게이트웨이가 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에서 메모리를 늘리세요:

[[vm]]
  memory = "2048mb"

또는 기존 머신을 업데이트합니다:

fly machine update <machine-id> --vm-memory 2048 -y

참고: 512MB는 부족합니다. 1GB는 작동할 수 있지만 부하 시 또는 상세 로깅 시 OOM이 발생할 수 있습니다. 2GB를 권장합니다.

게이트웨이 잠금 문제

게이트웨이가 “already running” 오류로 시작을 거부합니다.

컨테이너가 재시작되었지만 볼륨의 PID 잠금 파일이 유지될 때 발생합니다.

수정: 잠금 파일을 삭제합니다:

fly ssh console --command "rm -f /data/gateway.*.lock"
fly machine restart <machine-id>

잠금 파일은 /data/gateway.*.lock에 있습니다(하위 디렉토리가 아님).

설정이 읽히지 않음

--allow-unconfigured를 사용하면 게이트웨이가 최소 설정을 생성합니다. /data/openclaw.json의 커스텀 설정은 재시작 시 읽힙니다.

설정 파일이 존재하는지 확인합니다:

fly ssh console --command "cat /data/openclaw.json"

SSH를 통한 설정 파일 작성

fly ssh console -C 명령은 쉘 리다이렉션을 지원하지 않습니다. 설정 파일을 작성하려면:

# echo + tee 사용 (로컬에서 원격으로 파이프)
echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"

# 또는 sftp 사용
fly sftp shell
> put /local/path/config.json /data/openclaw.json

참고: 파일이 이미 존재하면 fly sftp가 실패할 수 있습니다. 먼저 삭제하세요:

fly ssh console --command "rm /data/openclaw.json"

상태가 유지되지 않음

재시작 후 인증 정보나 세션이 사라지면 상태 디렉토리가 컨테이너 파일시스템에 기록되고 있는 것입니다.

수정: fly.toml에 OPENCLAW_STATE_DIR=/data가 설정되어 있는지 확인하고 재배포하세요.

업데이트

# 최신 변경사항 가져오기
git pull

# 재배포
fly deploy

# 상태 확인
fly status
fly logs

머신 명령어 업데이트

전체 재배포 없이 시작 명령어를 변경해야 하는 경우:

# 머신 ID 확인
fly machines list

# 명령어 업데이트
fly machine update <machine-id> --command "node dist/index.js gateway --port 3000 --bind lan" -y

# 또는 메모리 증가와 함께
fly machine update <machine-id> --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y

참고: fly deploy 후 머신 명령어가 fly.toml의 내용으로 리셋될 수 있습니다. 수동 변경을 했다면 배포 후 다시 적용하세요.

비공개 배포 (보안 강화)

기본적으로 Fly는 퍼블릭 IP를 할당하여 게이트웨이를 https://your-app.fly.dev에서 접근할 수 있게 합니다. 편리하지만 인터넷 스캐너(Shodan, Censys 등)에 검색됩니다.

외부 노출 없이 보안 강화된 배포를 하려면 비공개 템플릿을 사용하세요.

비공개 배포가 적합한 경우

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

설정

표준 설정 대신 fly.private.toml을 사용합니다:

# 비공개 설정으로 배포
fly deploy -c fly.private.toml

기존 배포를 전환하려면:

# 현재 IP 목록 확인
fly ips list -a my-openclaw

# 퍼블릭 IP 해제
fly ips release <public-ipv4> -a my-openclaw
fly ips release <public-ipv6> -a my-openclaw

# 비공개 설정으로 전환하여 이후 배포에서 퍼블릭 IP 재할당 방지
# ([http_service] 제거 또는 비공개 템플릿으로 배포)
fly deploy -c fly.private.toml

# 프라이빗 전용 IPv6 할당
fly ips allocate-v6 --private -a my-openclaw

이후 fly ips list에는 private 타입 IP만 표시되어야 합니다:

VERSION  IP                   TYPE             REGION
v6       fdaa:x:x:x:x::x      private          global

비공개 배포 접속

퍼블릭 URL이 없으므로 다음 방법 중 하나를 사용합니다:

옵션 1: 로컬 프록시 (가장 간단)

# 로컬 포트 3000을 앱으로 포워딩
fly proxy 3000:3000 -a my-openclaw

# 브라우저에서 http://localhost:3000 열기

옵션 2: WireGuard VPN

# WireGuard 설정 생성 (최초 1회)
fly wireguard create

# WireGuard 클라이언트에 가져오기, 내부 IPv6로 접근
# 예: http://[fdaa:x:x:x:x::x]:3000

옵션 3: SSH만 사용

fly ssh console -a my-openclaw

비공개 배포에서의 웹훅

퍼블릭 노출 없이 웹훅 콜백(Twilio, Telnyx 등)이 필요한 경우:

1. ngrok 터널 — 컨테이너 내부 또는 사이드카로 ngrok 실행
2. Tailscale Funnel — Tailscale을 통해 특정 경로 노출
3. 아웃바운드 전용 — 일부 프로바이더(Twilio)는 웹훅 없이 아웃바운드 호출만으로도 작동

ngrok을 사용한 음성 통화 설정 예시:

{
  "plugins": {
    "entries": {
      "voice-call": {
        "enabled": true,
        "config": {
          "provider": "twilio",
          "tunnel": { "provider": "ngrok" },
          "webhookSecurity": {
            "allowedHosts": ["example.ngrok.app"]
          }
        }
      }
    }
  }
}

ngrok 터널은 컨테이너 내부에서 실행되며 Fly 앱 자체를 노출하지 않고 퍼블릭 웹훅 URL을 제공합니다. 포워딩된 호스트 헤더가 수락되도록 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 가격을 참고하세요.