Fly.io

Fly.io 문서는 OpenClaw 공식 문서(install/fly)를 한국어로 정리한 가이드입니다. Step-by-step Fly.io deployment for OpenClaw with persistent storage and HTTPS 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Step-by-step Fly.io deployment for OpenClaw with persistent storage and HTTPS

한국어 가이드 범위: install/fly 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What you need
Beginner quick path
트러블슈팅
"App is not listening on expected address"
Health checks failing / connection refused
OOM / memory issues
Gateway lock issues
Config not being read
Writing config via SSH
echo + tee (pipe from local to remote)
or sftp
State not persisting
Updating
Updating the machine command
or with a memory increase
Private deployment (hardened)
When to use private deployment
설정
list current IPs
release public IPs
switch to the private config so future deploys do not re-allocate public IPs
allocate private-only IPv6
Accessing a private deployment
open http://localhost:3000 in a browser
import to a WireGuard client, then access via internal IPv6
example: http://[fdaa:x:x:x:x::x]:3000
Webhooks with private deployment
Security tradeoffs
참고
Cost

상세 내용

본문

Goal: OpenClaw Gateway running on a Fly.io machine with persistent storage, automatic HTTPS, and Discord/channel access.

What you need

주요 항목:

flyctl CLI installed
Fly.io account (free tier works)
Model auth: API key for your chosen model provider
Channel credentials: Discord bot token, Telegram token, etc.

Beginner quick path

Clone repo, customize fly.toml 2. Create app + volume, set secrets 3. Deploy with fly deploy 4. SSH in to create config, or use the Control UI

주요 항목:

Environment variable DISCORD_BOT_TOKEN (recommended for secrets); no need to add it to config, the gateway reads it automatically
Config file channels.discord.token

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

    # pick your own name
    fly apps create my-openclaw

    # 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 auth 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=example-anthropic-key-not-real

    # optional: other providers
    fly secrets set OPENAI_API_KEY=example-openai-key-not-real
    fly secrets set GOOGLE_API_KEY=...

    # channel tokens
    fly secrets set DISCORD_BOT_TOKEN=example-discord-bot-token

fly deploy

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

"App is not listening on expected address"

The gateway is binding to 127.0.0.1 instead of 0.0.0.0.

Health checks failing / connection refused

Fly cannot reach the gateway on the configured port.

OOM / memory issues

Container keeps restarting or getting killed. Signs: SIGABRT, v8::internal::Runtime_AllocateInYoungGeneration, or silent restarts.

[[vm]]
  memory = "2048mb"

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

Gateway lock issues

Gateway refuses to start with "already running" errors after a container restart.

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

Config not being read

--allow-unconfigured only bypasses the startup guard. It does not create or repair /data/openclaw.json, so make sure your real config exists and includes "gateway": { "mode": "local" } for a normal local gateway start.

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

Writing config via SSH

fly ssh console -C does not support shell redirection. To write a config file:

echo + tee (pipe from local to remote)

echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"

or sftp

fly sftp shell > put /local/path/config.json /data/openclaw.json bash fly ssh console --command "rm /data/openclaw.json" ```

`fly sftp` may fail if the file already exists; delete first:

State not persisting

If you lose auth profiles, channel/provider state, or sessions after a restart, the state dir is writing to the container filesystem instead of the volume.

Updating

git pull + fly deploy is the supervised path here: it rebuilds the image from the Dockerfile, so the CLI/gateway version, the base OS image, and any Dockerfile changes all update together. openclaw update inside the running container is not the same operation, since the image ships as a Docker-built dist/ tree with no .git checkout and no npm-managed global install for it to detect; see Updating for that flow on VM-style installs.

git pull
fly deploy
fly status
fly logs

Updating the machine command

To change the startup command without a full redeploy:

or with a memory increase

fly machine update --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y ```

Private deployment (hardened)

By default, Fly allocates public IPs, so your gateway is reachable at https://your-app.fly.dev and discoverable by internet scanners (Shodan, Censys, etc.).

When to use private deployment

주요 항목:

Only outbound calls/messages (no inbound webhooks)
ngrok or Tailscale tunnels handle any webhook callbacks
Gateway access is via SSH, proxy, or WireGuard instead of a browser
The deployment should be hidden from internet scanners

설정

fly deploy -c deploy/fly.private.toml

list current IPs

fly ips list -a my-openclaw

release public IPs

fly ips release -a my-openclaw fly ips release -a my-openclaw

switch to the private config so future deploys do not re-allocate public IPs

fly deploy -c deploy/fly.private.toml

allocate private-only IPv6

fly ips allocate-v6 --private -a my-openclaw text VERSION IP TYPE REGION v6 fdaa:x:x:x:x::x private global ```

After this, `fly ips list` should show only a `private` type IP:

Accessing a private deployment


> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

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

```text
**Option 2: WireGuard VPN**

import to a WireGuard client, then access via internal IPv6

이 섹션의 세부 항목은 공식 문서 import to a WireGuard client, then access via internal IPv6를 참고하세요.

example: http://[fdaa:x:x:x:x::x]:3000

**Option 3: SSH only**

Webhooks with private deployment

For webhook callbacks (Twilio, Telnyx, etc.) without public exposure:

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

Security tradeoffs

Aspect	Public	Private
Internet scanners	Discoverable	Hidden
Direct attacks	Possible	Blocked
Control UI access	Browser	Proxy/VPN
Webhook delivery	Direct	Via tunnel

참고

주요 항목:

Fly.io uses x86 architecture; the Dockerfile is compatible with both x86 and ARM.
For WhatsApp/Telegram onboarding, use fly ssh console.
Persistent data lives on the volume at /data.
Signal requires signal-cli (a Java-based CLI) on the image; use a custom image and keep memory at 2GB+.

Cost

With the recommended config (shared-cpu-2x, 2GB RAM), expect roughly $10-15/month depending on usage; the free tier covers some baseline allowance. See Fly.io pricing for current rates.

다음 단계

주요 항목:

Set up messaging channels: Channels
Configure the Gateway: Gateway configuration
Keep OpenClaw up to date: Updating

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/fly
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

    # pick your own name
    fly apps create my-openclaw

    # 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 auth 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=example-anthropic-key-not-real

    # optional: other providers
    fly secrets set OPENAI_API_KEY=example-openai-key-not-real
    fly secrets set GOOGLE_API_KEY=...

    # channel tokens
    fly secrets set DISCORD_BOT_TOKEN=example-discord-bot-token

fly deploy

fly status
    fly logs

fly ssh console

Fly.io

핵심 요약

Step-by-step Fly.io deployment for OpenClaw with persistent storage and HTTPS

한국어 가이드 범위: install/fly 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What you need
Beginner quick path
트러블슈팅
"App is not listening on expected address"
Health checks failing / connection refused
OOM / memory issues
Gateway lock issues
Config not being read
Writing config via SSH
echo + tee (pipe from local to remote)
or sftp
State not persisting
Updating
Updating the machine command
or with a memory increase
Private deployment (hardened)
When to use private deployment
설정
list current IPs
release public IPs
switch to the private config so future deploys do not re-allocate public IPs
allocate private-only IPv6
Accessing a private deployment
open http://localhost:3000 in a browser
import to a WireGuard client, then access via internal IPv6
example: http://[fdaa:x:x:x:x::x]:3000
Webhooks with private deployment
Security tradeoffs
참고
Cost

상세 내용

본문

Goal: OpenClaw Gateway running on a Fly.io machine with persistent storage, automatic HTTPS, and Discord/channel access.

What you need

주요 항목:

flyctl CLI installed
Fly.io account (free tier works)
Model auth: API key for your chosen model provider
Channel credentials: Discord bot token, Telegram token, etc.

Beginner quick path

Clone repo, customize fly.toml 2. Create app + volume, set secrets 3. Deploy with fly deploy 4. SSH in to create config, or use the Control UI

주요 항목:

Environment variable DISCORD_BOT_TOKEN (recommended for secrets); no need to add it to config, the gateway reads it automatically
Config file channels.discord.token

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

    # pick your own name
    fly apps create my-openclaw

    # 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 auth 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=example-anthropic-key-not-real

    # optional: other providers
    fly secrets set OPENAI_API_KEY=example-openai-key-not-real
    fly secrets set GOOGLE_API_KEY=...

    # channel tokens
    fly secrets set DISCORD_BOT_TOKEN=example-discord-bot-token

fly deploy

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

"App is not listening on expected address"

The gateway is binding to 127.0.0.1 instead of 0.0.0.0.

Health checks failing / connection refused

Fly cannot reach the gateway on the configured port.

OOM / memory issues

Container keeps restarting or getting killed. Signs: SIGABRT, v8::internal::Runtime_AllocateInYoungGeneration, or silent restarts.

[[vm]]
  memory = "2048mb"

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

Gateway lock issues

Gateway refuses to start with "already running" errors after a container restart.

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

Config not being read

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

Writing config via SSH

fly ssh console -C does not support shell redirection. To write a config file:

echo + tee (pipe from local to remote)

echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"

or sftp

fly sftp shell > put /local/path/config.json /data/openclaw.json bash fly ssh console --command "rm /data/openclaw.json" ```

`fly sftp` may fail if the file already exists; delete first:

State not persisting

If you lose auth profiles, channel/provider state, or sessions after a restart, the state dir is writing to the container filesystem instead of the volume.

Updating

git pull
fly deploy
fly status
fly logs

Updating the machine command

To change the startup command without a full redeploy:

or with a memory increase

fly machine update --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y ```

Private deployment (hardened)

By default, Fly allocates public IPs, so your gateway is reachable at https://your-app.fly.dev and discoverable by internet scanners (Shodan, Censys, etc.).

When to use private deployment

주요 항목:

Only outbound calls/messages (no inbound webhooks)
ngrok or Tailscale tunnels handle any webhook callbacks
Gateway access is via SSH, proxy, or WireGuard instead of a browser
The deployment should be hidden from internet scanners

설정

fly deploy -c deploy/fly.private.toml

list current IPs

fly ips list -a my-openclaw

release public IPs

fly ips release -a my-openclaw fly ips release -a my-openclaw

switch to the private config so future deploys do not re-allocate public IPs

fly deploy -c deploy/fly.private.toml

allocate private-only IPv6

fly ips allocate-v6 --private -a my-openclaw text VERSION IP TYPE REGION v6 fdaa:x:x:x:x::x private global ```

After this, `fly ips list` should show only a `private` type IP:

Accessing a private deployment


> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

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

```text
**Option 2: WireGuard VPN**

import to a WireGuard client, then access via internal IPv6

이 섹션의 세부 항목은 공식 문서 import to a WireGuard client, then access via internal IPv6를 참고하세요.

example: http://[fdaa:x:x:x:x::x]:3000

**Option 3: SSH only**

Webhooks with private deployment

For webhook callbacks (Twilio, Telnyx, etc.) without public exposure:

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

Security tradeoffs

Aspect	Public	Private
Internet scanners	Discoverable	Hidden
Direct attacks	Possible	Blocked
Control UI access	Browser	Proxy/VPN
Webhook delivery	Direct	Via tunnel

참고

주요 항목:

Fly.io uses x86 architecture; the Dockerfile is compatible with both x86 and ARM.
For WhatsApp/Telegram onboarding, use fly ssh console.
Persistent data lives on the volume at /data.
Signal requires signal-cli (a Java-based CLI) on the image; use a custom image and keep memory at 2GB+.

Cost

With the recommended config (shared-cpu-2x, 2GB RAM), expect roughly $10-15/month depending on usage; the free tier covers some baseline allowance. See Fly.io pricing for current rates.

다음 단계

주요 항목:

Set up messaging channels: Channels
Configure the Gateway: Gateway configuration
Keep OpenClaw up to date: Updating

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/install/fly
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

    # pick your own name
    fly apps create my-openclaw

    # 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 auth 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=example-anthropic-key-not-real

    # optional: other providers
    fly secrets set OPENAI_API_KEY=example-openai-key-not-real
    fly secrets set GOOGLE_API_KEY=...

    # channel tokens
    fly secrets set DISCORD_BOT_TOKEN=example-discord-bot-token

fly deploy

fly status
    fly logs

fly ssh console

Fly.io

핵심 요약

문서 구성

상세 내용

본문

What you need

Beginner quick path

트러블슈팅

"App is not listening on expected address"

Health checks failing / connection refused

OOM / memory issues

Gateway lock issues

Config not being read

Writing config via SSH

echo + tee (pipe from local to remote)

or sftp

State not persisting

Updating

Updating the machine command

or with a memory increase

Private deployment (hardened)

When to use private deployment

설정

list current IPs

release public IPs

switch to the private config so future deploys do not re-allocate public IPs

allocate private-only IPv6

Accessing a private deployment

import to a WireGuard client, then access via internal IPv6

example: http://[fdaa:x:x:x:x::x]:3000

Webhooks with private deployment

Security tradeoffs

참고

Cost

다음 단계

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Fly.io

핵심 요약

문서 구성

상세 내용

본문

What you need

Beginner quick path

트러블슈팅

"App is not listening on expected address"

Health checks failing / connection refused

OOM / memory issues

Gateway lock issues

Config not being read

Writing config via SSH

echo + tee (pipe from local to remote)

or sftp

State not persisting

Updating

Updating the machine command

or with a memory increase

Private deployment (hardened)

When to use private deployment

설정

list current IPs

release public IPs

switch to the private config so future deploys do not re-allocate public IPs

allocate private-only IPv6

Accessing a private deployment

import to a WireGuard client, then access via internal IPv6

example: http://[fdaa:x:x:x:x::x]:3000

Webhooks with private deployment

Security tradeoffs

참고

Cost

다음 단계

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드