Fly.io

목표: 영구 스토리지, 자동 HTTPS, Discord/채널 접근이 포함된 Fly.io 머신에서 OpenClaw Gateway 실행.

# 필요한 것

• flyctl CLI 설치
• Fly.io 계정(무료 티어 사용 가능)
• 모델 인증: 선택한 모델 제공업체의 API 키
• 채널 자격 증명: Discord 봇 토큰, Telegram 토큰 등

# 초보자 빠른 경로

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

# Clone the repo
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Create a new Fly app (pick your own name)
fly apps create my-openclaw

# Create a persistent volume (1GB is usually enough)
fly volumes create openclaw_data --size 1 --region iad

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"

# Required: Gateway token (for non-loopback binding)
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

# Model provider API keys
fly secrets set ANTHROPIC_API_KEY=sk-ant-...

# Optional: Other providers
fly secrets set OPENAI_API_KEY=sk-...
fly secrets set GOOGLE_API_KEY=...

# Channel tokens
fly secrets set DISCORD_BOT_TOKEN=MTQ...

fly deploy

fly status
fly logs

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

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-6", "openai/gpt-5.4"]
      },
      "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",
    "controlUi": {
      "allowedOrigins": [
        "https://my-openclaw.fly.dev",
        "http://localhost:3000",
        "http://127.0.0.1:3000"
      ]
    }
  },
  "meta": {}
}
EOF

exit
fly machine restart <machine-id>

fly open

fly logs              # Live logs
fly logs --no-tail    # Recent logs

fly ssh console

# 문제 해결

# "App is not listening on expected address"

Gateway가 0.0.0.0 대신 127.0.0.1에 바인딩하고 있습니다.

수정: fly.toml의 프로세스 명령에 --bind lan을 추가하세요.

# 헬스 체크 실패 / 연결 거부

Fly가 구성된 포트에서 Gateway에 도달할 수 없습니다.

수정: internal_port가 Gateway 포트와 일치하는지 확인하세요(--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를 권장합니다.

# Gateway 잠금 문제

Gateway가 "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을 생성하거나 복구하지 않으므로, 일반적인 로컬 Gateway 시작을 원할 때 실제 구성이 존재하고 gateway.mode="local"을 포함하는지 확인하세요.

구성이 존재하는지 확인하세요.

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

# SSH를 통한 구성 작성

fly ssh console -C 명령은 셸 리디렉션을 지원하지 않습니다. 구성 파일을 작성하려면 다음을 사용하세요.

# Use echo + tee (pipe from local to remote)
echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"

# Or use 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가 설정되어 있는지 확인하고 다시 배포하세요.

# 업데이트

# Pull latest changes
git pull

# Redeploy
fly deploy

# Check health
fly status
fly logs

# 머신 명령 업데이트

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

# Get machine ID
fly machines list

# Update command
fly machine update <machine-id> --command "node dist/index.js gateway --port 3000 --bind lan" -y

# Or with memory increase
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를 할당하여 Gateway를 https://your-app.fly.dev에서 접근 가능하게 만듭니다. 편리하지만 배포가 인터넷 스캐너(Shodan, Censys 등)에 발견될 수 있다는 의미입니다.

공개 노출이 없는 강화된 배포에는 비공개 템플릿을 사용하세요.

# 비공개 배포를 사용할 때

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

# 설정

표준 구성 대신 deploy/fly.private.toml을 사용하세요.

# Deploy with private config
fly deploy -c deploy/fly.private.toml

또는 기존 배포를 전환하세요.

# List current IPs
fly ips list -a my-openclaw

# Release public IPs
fly ips release <public-ipv4> -a my-openclaw
fly ips release <public-ipv6> -a my-openclaw

# Switch to private config so future deploys don't re-allocate public IPs
# (remove [http_service] or deploy with the private template)
fly deploy -c deploy/fly.private.toml

# Allocate private-only 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: 로컬 프록시(가장 간단)

# Forward local port 3000 to the app
fly proxy 3000:3000 -a my-openclaw

# Then open http://localhost:3000 in browser

옵션 2: WireGuard VPN

# Create WireGuard config (one-time)
fly wireguard create

# Import to WireGuard client, then access via internal IPv6
# Example: http://[fdaa:x:x:x:x::x]:3000

옵션 3: SSH 전용

fly ssh console -a my-openclaw

# 비공개 배포에서의 Webhook

공개 노출 없이 Webhook 콜백(Twilio, Telnyx 등)이 필요한 경우:

1. ngrok 터널 - 컨테이너 내부 또는 사이드카로 ngrok 실행
2. Tailscale Funnel - Tailscale을 통해 특정 경로 노출
3. 아웃바운드 전용 - 일부 제공업체(Twilio)는 Webhook 없이도 아웃바운드 통화에 문제없이 작동합니다

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

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

ngrok 터널은 컨테이너 내부에서 실행되며 Fly 앱 자체를 노출하지 않고 공개 Webhook 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 가격을 참조하세요.

# 다음 단계

• 메시징 채널 설정: 채널
• Gateway 구성: Gateway 구성
• OpenClaw를 최신 상태로 유지: 업데이트

# 관련

• 설치 개요
• Hetzner
• Docker
• VPS 호스팅