Fly.io

목표: 영구 스토리지, 자동 HTTPS 및 Discord/채널 액세스를 지원하는 Fly.io 머신에서 OpenClaw Gateway를 실행합니다.

필요한 항목

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

초보자용 빠른 경로

저장소를 복제하고 fly.toml 사용자 지정
앱과 볼륨을 생성하고 비밀 설정
fly deploy(으)로 배포
SSH로 접속하여 구성을 생성하거나 Control UI 사용

Fly 앱 생성

git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 원하는 이름을 선택하십시오
fly apps create my-openclaw

# 일반적으로 1GB면 충분합니다
fly volumes create openclaw_data --size 1 --region iad

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

fly.toml 구성

앱 이름과 요구 사항에 맞게 fly.toml을(를) 편집하십시오. 저장소에서 추적하는 fly.toml은 아래에 표시된 공개 템플릿이며, deploy/fly.private.toml은 공개 IP가 없는 강화 변형입니다(비공개 배포 참조).

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"

OpenClaw Docker 이미지의 진입점은 tini이며 기본적으로 node openclaw.mjs gateway을(를) 실행합니다. Fly의 [processes]은 ENTRYPOINT을(를) 건드리지 않고 Docker의 CMD을(를) 대체하므로(여기서는 동일한 컴파일된 진입점인 node dist/index.js gateway ...을(를) 직접 실행함), 프로세스는 계속 tini에서 실행됩니다.주요 설정:

설정	이유
`--bind lan`	Fly 프록시가 Gateway에 접근할 수 있도록 `0.0.0.0`에 바인딩합니다
`--allow-unconfigured`	구성 파일 없이 시작합니다(나중에 생성함)
`internal_port = 3000`	Fly 상태 확인을 위해 `--port 3000`(또는 `OPENCLAW_GATEWAY_PORT`)과 일치해야 합니다
`memory = "2048mb"`	512MB는 너무 작으므로 2GB를 권장합니다
`OPENCLAW_STATE_DIR = "/data"`	볼륨에 상태를 영구 저장합니다

비밀 설정

# 필수: 비루프백 바인딩용 Gateway 인증 토큰
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

# 모델 제공업체 API 키
fly secrets set ANTHROPIC_API_KEY=example-anthropic-key-not-real

# 선택 사항: 기타 제공업체
fly secrets set OPENAI_API_KEY=example-openai-key-not-real
fly secrets set GOOGLE_API_KEY=...

# 채널 토큰
fly secrets set DISCORD_BOT_TOKEN=example-discord-bot-token

비루프백 바인딩(--bind lan)에는 유효한 Gateway 인증 경로가 필요합니다. 이 예에서는 OPENCLAW_GATEWAY_TOKEN을(를) 사용하지만, gateway.auth.password 또는 올바르게 구성된 비루프백 신뢰 프록시 배포도 이 요구 사항을 충족합니다. SecretRef 계약은 비밀 관리를 참조하십시오.이러한 토큰은 비밀번호처럼 취급하십시오. 비밀이 openclaw.json에 포함되지 않도록 API 키와 토큰에는 구성 파일보다 환경 변수/fly secrets을(를) 사용하는 것이 좋습니다.

배포

fly deploy

첫 배포에서는 Docker 이미지를 빌드합니다. 배포 후 확인하십시오.

fly status
fly logs

HTTP/WebSocket 리스너가 준비되면 Gateway 시작 로그에 gateway ready이(가) 기록됩니다. Fly 자체 상태 확인은 fly.toml에 따라 internal_port = 3000을(를) 감시합니다. 이미지의 Docker HEALTHCHECK 지시문은 추가로 기본 포트 18789의 /healthz을(를) 폴링하지만, 이 배포에서는 Gateway를 --port 3000로 재정의하므로 사용되지 않습니다.

구성 파일 생성

머신에 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-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

OPENCLAW_STATE_DIR=/data을(를) 사용하는 경우 구성 경로는 /data/openclaw.json입니다.https://my-openclaw.fly.dev을(를) 실제 Fly 앱 출처로 바꾸십시오. Gateway 시작 시 런타임 --bind 및 --port 값을 사용하여 로컬 Control UI 출처를 초기화하므로 구성이 존재하기 전에도 최초 부팅을 진행할 수 있지만, Fly를 통한 브라우저 액세스에는 여전히 gateway.controlUi.allowedOrigins에 정확한 HTTPS 출처가 나열되어 있어야 합니다.Discord 토큰은 다음 중 하나에서 가져올 수 있습니다.

환경 변수 DISCORD_BOT_TOKEN(비밀에 권장); 구성에 추가할 필요가 없으며 Gateway가 자동으로 읽습니다
구성 파일 channels.discord.token

적용하려면 다시 시작하십시오.

exit
fly machine restart <machine-id>

Gateway 액세스

Control UI

fly open

또는 https://my-openclaw.fly.dev/에 방문하십시오.구성된 공유 비밀로 인증하십시오. OPENCLAW_GATEWAY_TOKEN의 Gateway 토큰을 사용하거나 비밀번호 인증으로 전환한 경우 해당 비밀번호를 사용하십시오.

로그

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

SSH 콘솔

fly ssh console

문제 해결

”앱이 예상 주소에서 수신 대기하지 않음”

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가 “이미 실행 중” 오류와 함께 시작을 거부합니다. 런타임 잠금 파일은 영구 /data 볼륨이 아닌 <tmpdir>/openclaw-<uid>/gateway.<hash>.lock 및 gateway.state.<hash>.lock(Linux: /tmp/openclaw-<uid>/gateway.*.lock)에 있으므로 전체 컨테이너를 다시 시작하면 일반적으로 나머지 컨테이너 파일 시스템과 함께 삭제됩니다. 잠금이 남아 있고(예: 컨테이너 파일 시스템을 보존하는 fly machine restart) 시작을 차단하는 경우 수동으로 제거하십시오.

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

구성을 읽지 못함

--allow-unconfigured은(는) 시작 보호 장치만 우회합니다. /data/openclaw.json을(를) 생성하거나 복구하지 않으므로 실제 구성이 존재하며 정상적인 로컬 Gateway 시작을 위한 "gateway": { "mode": "local" }이(가) 포함되어 있는지 확인하십시오. 구성이 존재하는지 확인하십시오.

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

여기서는 git pull + fly deploy이(가) 관리되는 경로입니다. Dockerfile에서 이미지를 다시 빌드하므로 CLI/Gateway 버전, 기본 OS 이미지 및 모든 Dockerfile 변경 사항이 함께 업데이트됩니다. 실행 중인 컨테이너 내부의 openclaw update은(는) 동일한 작업이 아닙니다. 이미지가 Docker로 빌드된 dist/ 트리로 제공되며 감지할 .git 체크아웃이나 npm으로 관리되는 전역 설치가 없기 때문입니다. VM 방식 설치의 해당 흐름은 업데이트를 참조하십시오.

머신 명령 업데이트

전체 재배포 없이 시작 명령을 변경하려면 다음을 실행하십시오.

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 등)에 노출됩니다. 공개 IP가 없는 강화 배포에는 deploy/fly.private.toml을(를) 사용하십시오. [http_service]을(를) 생략하므로 공개 인그레스가 할당되지 않습니다.

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

아웃바운드 호출/메시지만 사용(인바운드 Webhook 없음)
ngrok 또는 Tailscale 터널이 모든 Webhook 콜백 처리
브라우저 대신 SSH, 프록시 또는 WireGuard를 통해 Gateway에 액세스
인터넷 스캐너에서 배포를 숨겨야 함

설정

fly deploy -c deploy/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를 다시 할당하지 않도록 비공개 구성으로 전환
fly deploy -c deploy/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

비공개 배포에 액세스하기

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

fly proxy 3000:3000 -a my-openclaw
# 브라우저에서 http://localhost:3000 열기

옵션 2: WireGuard VPN

fly wireguard create
# WireGuard 클라이언트로 가져온 다음 내부 IPv6를 통해 액세스
# 예: http://[fdaa:x:x:x:x::x]:3000

옵션 3: SSH만 사용

fly ssh console -a my-openclaw

비공개 배포에서 Webhook 사용하기

공개 노출 없이 Webhook 콜백(Twilio, Telnyx 등)을 사용하려면 다음 방법을 이용하십시오.

ngrok 터널: 컨테이너 내부 또는 사이드카로 ngrok을 실행합니다.
Tailscale Funnel: Tailscale을 통해 특정 경로를 노출합니다.
아웃바운드 전용: 일부 제공업체(Twilio)는 Webhook 없이 아웃바운드 통화를 지원합니다.

plugins.entries.voice-call.config 아래에 설정하는 ngrok 음성 통화 구성 예시는 다음과 같습니다.

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

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

보안 측면의 장단점

측면	공개	비공개
인터넷 스캐너	검색 가능	숨겨짐
직접 공격	가능	차단됨
제어 UI 액세스	브라우저	프록시/VPN
Webhook 전송	직접	터널 경유

참고

Fly.io는 x86 아키텍처를 사용하며, Dockerfile은 x86과 ARM 모두와 호환됩니다.
WhatsApp/Telegram 온보딩에는 fly ssh console을 사용하십시오.
영구 데이터는 /data의 볼륨에 저장됩니다.
Signal을 사용하려면 이미지에 signal-cli(Java 기반 CLI)가 있어야 합니다. 사용자 지정 이미지를 사용하고 메모리를 2GB 이상으로 유지하십시오.

비용

권장 구성(shared-cpu-2x, 2GB RAM)을 사용하면 사용량에 따라 월간 비용은 약 $10-15이며, 무료 등급에서 일부 기본 허용량을 제공합니다. 현재 요금은 Fly.io 요금을 참조하십시오.

다음 단계

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

Install overview

Maintenance

Containers

Hosting

Advanced setup

필요한 항목

초보자용 빠른 경로

Control UI

로그

SSH 콘솔

문제 해결

”앱이 예상 주소에서 수신 대기하지 않음”

상태 확인 실패/연결 거부

OOM/메모리 문제

Gateway 잠금 문제

구성을 읽지 못함

SSH를 통해 구성 작성

상태가 유지되지 않음

업데이트

머신 명령 업데이트

비공개 배포(강화)

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

설정

비공개 배포에 액세스하기

비공개 배포에서 Webhook 사용하기

보안 측면의 장단점

참고

비용

다음 단계

관련 문서

​필요한 항목

​초보자용 빠른 경로

​Control UI

​로그

​SSH 콘솔

​문제 해결

​”앱이 예상 주소에서 수신 대기하지 않음”

​상태 확인 실패/연결 거부

​OOM/메모리 문제

​Gateway 잠금 문제

​구성을 읽지 못함

​SSH를 통해 구성 작성

​상태가 유지되지 않음

​업데이트

​머신 명령 업데이트

​비공개 배포(강화)

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

​설정

​비공개 배포에 액세스하기

​비공개 배포에서 Webhook 사용하기

​보안 측면의 장단점

​참고

​비용

​다음 단계

​관련 문서

필요한 항목

초보자용 빠른 경로

Control UI

로그

SSH 콘솔

문제 해결

”앱이 예상 주소에서 수신 대기하지 않음”

상태 확인 실패/연결 거부

OOM/메모리 문제

Gateway 잠금 문제

구성을 읽지 못함

SSH를 통해 구성 작성

상태가 유지되지 않음

업데이트

머신 명령 업데이트

비공개 배포(강화)

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

설정

비공개 배포에 액세스하기

비공개 배포에서 Webhook 사용하기

보안 측면의 장단점

참고

비용

다음 단계

관련 문서