Fly.io Deployment

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

필요한 것

설치된 flyctl CLI
Fly.io 계정(무료 티어 가능)
모델 인증: 선택한 모델 provider의 API 키
채널 자격 증명: Discord bot 토큰, Telegram 토큰 등

초보자용 빠른 경로

리포지토리 clone → fly.toml 사용자 지정
앱 + 볼륨 생성 → secrets 설정
fly deploy로 배포
SSH 접속 후 config 생성 또는 Control UI 사용

Fly 앱 생성

# 리포지토리 clone
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 (산호세)

fly.toml 구성

앱 이름과 요구 사항에 맞게 fly.toml을 편집하세요.보안 참고: 기본 config는 공개 URL을 노출합니다. 공용 IP가 없는 강화된 배포를 원하면 비공개 배포 또는 fly.private.toml을 사용하세요.

app = "my-openclaw"  # 앱 이름
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"

핵심 설정:

설정	이유
`--bind lan`	Fly 프록시가 gateway에 도달할 수 있도록 `0.0.0.0`에 바인딩
`--allow-unconfigured`	config 파일 없이 시작(이후 생성 예정)
`internal_port = 3000`	Fly 상태 확인과 일치하도록 `--port 3000`(또는 `OPENCLAW_GATEWAY_PORT`)과 동일해야 함
`memory = "2048mb"`	512MB는 너무 작고 2GB 권장
`OPENCLAW_STATE_DIR = "/data"`	상태를 볼륨에 영속화

Secrets 설정

# 필수: Gateway 토큰(non-loopback 바인드용)
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

# 모델 provider API 키
fly secrets set ANTHROPIC_API_KEY=sk-ant-...

# 선택 사항: 다른 providers
fly secrets set OPENAI_API_KEY=sk-...
fly secrets set GOOGLE_API_KEY=...

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

참고:

non-loopback 바인드(--bind lan)에는 유효한 gateway 인증 경로가 필요합니다. 이 Fly.io 예제는 OPENCLAW_GATEWAY_TOKEN을 사용하지만, gateway.auth.password 또는 올바르게 구성된 non-loopback trusted-proxy 배포도 요구 사항을 충족합니다.
이 토큰은 비밀번호처럼 취급하세요.
모든 API 키와 토큰은 config 파일보다 env vars를 우선 사용하세요. 이렇게 하면 secrets가 openclaw.json에 들어가 실수로 노출되거나 로그에 남는 일을 방지할 수 있습니다.

배포

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

Config 파일 생성

적절한 config를 만들기 위해 머신에 SSH로 접속합니다.

fly ssh console

config 디렉터리와 파일을 생성합니다.

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"
  },
  "meta": {}
}
EOF

참고: OPENCLAW_STATE_DIR=/data를 사용하므로 config 경로는 /data/openclaw.json입니다.참고: Discord 토큰은 다음 둘 중 하나에서 가져올 수 있습니다.

환경 변수: DISCORD_BOT_TOKEN (secrets에 권장)
config 파일: channels.discord.token

env var를 사용하는 경우 config에 토큰을 추가할 필요가 없습니다. gateway가 DISCORD_BOT_TOKEN을 자동으로 읽습니다.적용하려면 재시작하세요.

exit
fly machine restart <machine-id>

Gateway 접근

Control UI

브라우저에서 열기:

fly open

또는 https://my-openclaw.fly.dev/ 방문구성된 shared secret으로 인증하세요. 이 가이드는 OPENCLAW_GATEWAY_TOKEN의 gateway 토큰을 사용합니다. password auth로 전환했다면 대신 해당 비밀번호를 사용하세요.

로그

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

SSH 콘솔

fly ssh console

문제 해결

”App is not listening on expected address”

gateway가 0.0.0.0이 아니라 127.0.0.1에 바인딩되고 있습니다. 해결: fly.toml의 프로세스 명령에 --bind lan을 추가하세요.

상태 확인 실패 / connection refused

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도 동작할 수는 있지만 부하가 있거나 verbose 로깅 시 OOM이 발생할 수 있습니다. 2GB를 권장합니다.

Gateway 잠금 문제

Gateway가 “already running” 오류와 함께 시작을 거부합니다. 이는 컨테이너가 재시작되었지만 PID 잠금 파일이 볼륨에 남아 있을 때 발생합니다. 해결: 잠금 파일 삭제:

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

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

Config가 읽히지 않음

--allow-unconfigured는 시작 가드만 우회합니다. /data/openclaw.json을 생성하거나 복구하지는 않으므로, 실제 config가 존재하고 일반적인 로컬 gateway 시작을 원할 때 gateway.mode="local"이 포함되어 있는지 확인하세요. config 존재 여부 확인:

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

SSH를 통한 Config 쓰기

fly ssh console -C 명령은 셸 리디렉션을 지원하지 않습니다. config 파일을 쓰려면:

# 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"

상태가 영속되지 않음

재시작 후 auth profiles, 채널/provider 상태 또는 세션이 사라진다면 상태 디렉터리가 컨테이너 파일시스템에 기록되고 있는 것입니다. 해결: 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를 할당하므로 gateway가 https://your-app.fly.dev에서 접근 가능해집니다. 편리하지만 인터넷 스캐너(Shodan, Censys 등)에서 배포가 발견될 수 있다는 뜻이기도 합니다. 공개 노출이 전혀 없는 강화된 배포를 원하면 비공개 템플릿을 사용하세요.

비공개 배포를 사용해야 하는 경우

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

설정

표준 config 대신 fly.private.toml을 사용하세요.

# 비공개 config로 배포
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를 다시 할당하지 않도록 비공개 config로 전환
# ([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 config 생성(1회)
fly wireguard create

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

옵션 3: SSH만 사용

fly ssh console -a my-openclaw

비공개 배포에서 Webhooks 사용

공개 노출 없이도 webhook 콜백(Twilio, Telnyx 등)이 필요하면:

ngrok 터널 - 컨테이너 내부 또는 사이드카로 ngrok 실행
Tailscale Funnel - Tailscale을 통해 특정 경로 노출
아웃바운드 전용 - 일부 providers(Twilio)는 webhook 없이도 아웃바운드 호출에 문제없이 동작

ngrok을 사용하는 음성 통화 config 예시:

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

ngrok 터널은 컨테이너 내부에서 실행되며 Fly 앱 자체를 노출하지 않고도 공개 webhook URL을 제공합니다. 전달된 host 헤더가 허용되도록 webhookSecurity.allowedHosts를 공개 터널 호스트명으로 설정하세요.

보안 이점

측면	Public	Private
인터넷 스캐너	발견 가능	숨김
직접 공격	가능	차단
Control UI 접근	브라우저	프록시/VPN
Webhook 전달	직접	터널 경유

참고

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

비용

권장 config(shared-cpu-2x, 2GB RAM) 기준:

사용량에 따라 월 약 $10~15
무료 티어에 일부 할당량 포함

자세한 내용은 Fly.io pricing을 참조하세요.

다음 단계

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

Install overview

Containers

Hosting

Maintenance

Fly.io

Fly.io Deployment

필요한 것

초보자용 빠른 경로

Control UI

로그

SSH 콘솔

문제 해결

”App is not listening on expected address”

상태 확인 실패 / connection refused

OOM / 메모리 문제

Gateway 잠금 문제

Config가 읽히지 않음

SSH를 통한 Config 쓰기

상태가 영속되지 않음

업데이트

머신 명령 업데이트

비공개 배포(강화)

비공개 배포를 사용해야 하는 경우

설정

비공개 배포에 접근하는 방법

비공개 배포에서 Webhooks 사용

보안 이점

참고

비용

다음 단계

Install overview

Containers

Hosting

Maintenance

​Fly.io Deployment

​필요한 것

​초보자용 빠른 경로

​Control UI

​로그

​SSH 콘솔

​문제 해결

​”App is not listening on expected address”

​상태 확인 실패 / connection refused

​OOM / 메모리 문제

​Gateway 잠금 문제

​Config가 읽히지 않음

​SSH를 통한 Config 쓰기

​상태가 영속되지 않음

​업데이트

​머신 명령 업데이트

​비공개 배포(강화)

​비공개 배포를 사용해야 하는 경우

​설정

​비공개 배포에 접근하는 방법

​비공개 배포에서 Webhooks 사용

​보안 이점

​참고

​비용

​다음 단계

Fly.io Deployment

필요한 것

초보자용 빠른 경로

Control UI

로그

SSH 콘솔

문제 해결

”App is not listening on expected address”

상태 확인 실패 / connection refused

OOM / 메모리 문제

Gateway 잠금 문제

Config가 읽히지 않음

SSH를 통한 Config 쓰기

상태가 영속되지 않음

업데이트

머신 명령 업데이트

비공개 배포(강화)

비공개 배포를 사용해야 하는 경우

설정

비공개 배포에 접근하는 방법

비공개 배포에서 Webhooks 사용

보안 이점

참고

비용

다음 단계