How to Deploy OpenClaw on Fly.io (Step by Step)

OpenClaw is an open-source AI agent framework with over 68K GitHub stars. It turns large language models into always-on personal assistants that connect to Discord, Telegram, WhatsApp, and other messaging platforms.

Fly.io is one of the most popular platforms for hosting OpenClaw. It offers persistent volumes, automatic HTTPS, and global edge deployment — all things an always-on AI agent needs. This guide walks through every step of a production-ready Fly.io deployment.

References: This guide is based on the official OpenClaw Fly.io docs and the Chinese community guide.

What You Need

Before you start, make sure you have:

• flyctl CLI installed and authenticated
• A Fly.io account (the free tier works for getting started)
• An Anthropic API key (or keys for other providers like OpenAI, Google, etc.)
• Channel credentials — a Discord bot token, Telegram bot token, or WhatsApp setup, depending on which messaging platforms you want to connect

Step 1: Create the Fly App

Clone the OpenClaw repository and create a new Fly app with a persistent volume:

# 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 (1 GB is usually enough)
fly volumes create openclaw_data --size 1 --region iad

Choose a region close to you. Common options include lhr (London), iad (Virginia), and sjc (San Jose). Your AI agent’s response latency depends partly on this choice.

Step 2: Configure fly.toml

Edit fly.toml in the cloned repo to match your app name:

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"

A few settings to pay attention to:

Setting	Why It Matters
--bind lan	Binds to 0.0.0.0 so Fly’s proxy can reach the gateway
--allow-unconfigured	Lets the gateway start without a config file (you create one after)
internal_port = 3000	Must match the --port flag for Fly health checks to pass
memory = "2048mb"	512 MB is too small — 2 GB is the recommended minimum
OPENCLAW_STATE_DIR = "/data"	Persists state (sessions, memory, credentials) on the volume

Step 3: Set Secrets

Use environment variables for all sensitive values. This keeps them out of your config file where they could be accidentally logged or exposed:

# Required: gateway auth token (needed for non-loopback binds)
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)

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

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

# Channel tokens (add whichever you need)
fly secrets set DISCORD_BOT_TOKEN=MTQ...

Save your OPENCLAW_GATEWAY_TOKEN somewhere safe — you will need it to access the Control UI later.

Step 4: Deploy

fly deploy

The first deployment builds the Docker image and typically takes 2–3 minutes. Subsequent deploys are faster.

After deployment, verify everything is running:

fly status
fly logs

You should see output like:

[gateway] listening on ws://0.0.0.0:3000 (PID xxx)

If you set a Discord token, you should also see:

[discord] logged in to discord as YourBot#1234

Step 5: Create the Config File

SSH into the running machine to create a proper configuration:

fly ssh console

Then create the config file on the persistent volume:

cat > /data/openclaw.json << 'EOF'
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5",
        "fallbacks": ["openai/gpt-4o"]
      }
    },
    "list": [
      {
        "id": "main",
        "default": true
      }
    ]
  },
  "auth": {
    "profiles": {
      "anthropic:default": { "mode": "token", "provider": "anthropic" }
    }
  },
  "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"
  }
}
EOF

Replace YOUR_GUILD_ID with your actual Discord server ID. The Discord bot token is read automatically from the DISCORD_BOT_TOKEN environment variable — no need to put it in the config file.

Exit SSH and restart the machine to apply:

exit
fly machine restart <machine-id>

You can find your machine ID with fly machines list.

Step 6: Access and Verify

Control UI

Open your browser and visit:

https://my-openclaw.fly.dev

Paste your gateway token (the OPENCLAW_GATEWAY_TOKEN you generated earlier) to authenticate. The Control UI lets you chat with your agent, view logs, and manage configuration.

Logs and SSH

# Live logs
fly logs

# SSH into the machine
fly ssh console

Troubleshooting

Here are the most common issues and how to fix them:

“App is not listening on expected address”

The gateway is binding to 127.0.0.1 instead of 0.0.0.0. Add --bind lan to your process command in fly.toml.

Health checks failing

Fly cannot reach the gateway. Make sure internal_port in fly.toml matches the --port flag in your process command.

OOM / memory issues

If the container keeps restarting or you see SIGABRT errors, your machine needs more memory. Update fly.toml to use at least 2048 MB, or run:

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

Gateway lock errors

If the gateway refuses to start with “already running” errors after a restart, delete the stale lock file:

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

State not persisting after restarts

Make sure OPENCLAW_STATE_DIR=/data is set in your fly.toml environment section and that the volume is mounted at /data.

Updates

To update OpenClaw to the latest version:

git pull
fly deploy

After fly deploy, check that everything is healthy with fly status and fly logs.

Cost

With the recommended configuration (shared-cpu-2x, 2 GB RAM, 1 GB volume), expect to pay roughly $10–15 per month depending on usage. Fly.io’s free tier covers some of the allowance, so your first month may cost less. See Fly.io pricing for details.

12-Month Cost Comparison

	Self-Hosting (Fly.io)	OCLauncher
Compute (2 GB VM)	~$12/mo	Included
AI API tokens	$20–60/mo (your own key)	3M tokens included
Storage (volume)	~$0.15/mo	8GB included
Dashboard / UI	None (CLI only)	Full web dashboard
Setup time	1–3 hours	30 seconds
Maintenance	You (updates, monitoring, crashes)	Managed
12-month total	~$250–870 (compute + tokens)	$228 ($19 × 12)

The biggest cost difference comes from AI tokens. If you self-host, you pay your own API provider directly — at Anthropic’s current rates, 3M tokens/month costs roughly $20–60 depending on model and input/output mix. OCLauncher includes 3M tokens in the $19/month price.

A Simpler Alternative

Self-hosting on Fly.io gives you full control, and for developers who enjoy managing infrastructure it can be a rewarding setup. But it does mean owning the full lifecycle: provisioning machines, configuring secrets, writing TOML files, SSHing in to create config files, monitoring uptime, and handling updates.

If you would rather skip all of that — OCLauncher deploys OpenClaw for you in 30 seconds at US$19/month with 3M AI tokens, 8GB storage, all messaging channels, and a full dashboard included. It runs on the same Fly.io infrastructure under the hood, so you get the same performance without the operational overhead.