Why Choose Fly.io
Fly.io is a modern cloud platform designed for developers, supporting application deployment across multiple global edge nodes. For an AI Agent gateway like OpenClaw, Fly.io offers several notable advantages: a free tier sufficient to run a small-scale instance, a streamlined deployment process, support for persistent storage volumes, and the ability to choose data centers closest to your users.
This article will walk you through the complete process of deploying OpenClaw on Fly.io from scratch.
Prerequisites
Before getting started, you need to prepare the following:
- A Fly.io account (visit fly.io to register)
- The flyctl CLI tool installed locally
- An already configured OpenClaw project (or be ready to start from scratch)
Installing flyctl
On macOS or Linux, run the following command to install flyctl:
curl -L https://fly.io/install.sh | sh
After installation, log in to your Fly.io account:
fly auth login
Creating a Dockerfile
Fly.io natively supports Docker deployments. First, create a Dockerfile in your project directory:
FROM node:22-slim
WORKDIR /app
RUN npm install -g openclaw@latest
RUN mkdir -p /root/.openclaw
EXPOSE 3000
CMD ["openclaw", "start"]
This Dockerfile uses the official Node.js 22 image as its base, installs OpenClaw globally, and exposes the default port 3000. Note that we use node:22-slim rather than other runtimes, because OpenClaw requires Node.js 22+ and using Bun is not recommended (it has known issues with WhatsApp and Telegram connections).
Initializing the Fly.io Application
Run the following in your project directory:
fly launch
flyctl will automatically detect the Dockerfile and guide you through initialization. During the interactive process, you will need to choose:
- Application name: e.g.,
my-openclaw-gateway - Deployment region: Choose the region closest to your target users, such as
hkg(Hong Kong) ornrt(Tokyo) - Resource configuration: OpenClaw is recommended to have at least 256MB of memory, with 512MB preferred
After initialization, a fly.toml configuration file will be generated in the project root directory.
Configuring fly.toml
Open the generated fly.toml file and verify the following key settings:
app = "my-openclaw-gateway"
primary_region = "hkg"
[build]
[http_service]
internal_port = 3000
force_https = true
auto_stop_machines = false
auto_start_machines = true
min_machines_running = 1
[mounts]
source = "openclaw_data"
destination = "/root/.openclaw"
There are several important configuration items to note here. Setting auto_stop_machines to false prevents Fly.io from shutting down your instance when idle — OpenClaw as a messaging gateway needs to run continuously to receive messages from chat platforms like WhatsApp, Telegram, and Discord. The mounts section mounts a persistent storage volume to OpenClaw's configuration directory ~/.openclaw, ensuring that configuration and data are not lost after restarts.
Creating a Persistent Storage Volume
Before deploying, create the storage volume first:
fly volumes create openclaw_data --region hkg --size 1
This creates a 1GB storage volume in the Hong Kong region for storing OpenClaw's configuration files and data.
Setting Environment Variables
Sensitive OpenClaw configuration can be securely managed through Fly.io's Secrets feature:
fly secrets set OPENCLAW_API_KEY="your-api-key"
fly secrets set OPENCLAW_WEBHOOK_URL="https://my-openclaw-gateway.fly.dev/webhook"
Deploying
Once everything is ready, run the deploy command:
fly deploy
flyctl will automatically build the Docker image, push it to Fly.io's image registry, and start your application. The entire process typically takes 2-5 minutes.
After deployment, check the application status:
fly status
View the runtime logs to confirm OpenClaw started successfully:
fly logs
Post-Deployment Configuration
After the application is running successfully, you need to complete the OpenClaw initialization configuration. Connect to the instance via SSH:
fly ssh console
Run the OpenClaw onboarding wizard inside the instance:
openclaw onboard --install-daemon
Follow the interactive prompts to complete AI model configuration and chat platform connection setup. Then run the diagnostic command to confirm everything is working:
openclaw doctor
You can also access the OpenClaw management dashboard with:
openclaw dashboard
The dashboard runs on port 3000 by default and can be accessed at https://my-openclaw-gateway.fly.dev.
Custom Domain
If you want to use your own domain, you can add it with:
fly certs create openclaw.yourdomain.com
Then add the appropriate CNAME record at your DNS provider, pointing to the address assigned by Fly.io.
Scaling and Monitoring
As your user base grows, you can easily scale up:
fly scale count 2
fly scale vm shared-cpu-2x
Fly.io's built-in monitoring dashboard helps you track CPU usage, memory utilization, and network traffic.
Troubleshooting
If you encounter issues after deployment, start by checking the logs:
fly logs --app my-openclaw-gateway
Ensure the storage volume is correctly mounted, the port configuration is correct, and the Node.js version is 22+. If the application keeps crashing, try increasing the memory quota or checking that the OpenClaw configuration file ~/.openclaw/openclaw.json is correct.
Summary
Deploying OpenClaw on Fly.io is a lightweight and cost-effective solution, especially suitable for individual developers and small teams. With global multi-region deployment capabilities and a streamlined CLI tool, you can get your OpenClaw AI Agent gateway up and running within minutes, connecting your favorite chat platforms with AI models.