diff --git a/blueprints/deploy-openclaw.html.md b/blueprints/deploy-openclaw.html.md new file mode 100644 index 0000000000..b68a8251c4 --- /dev/null +++ b/blueprints/deploy-openclaw.html.md @@ -0,0 +1,194 @@ +--- +title: Deploy OpenClaw on Fly.io +layout: docs +nav: guides +date: 2026-03-25 +--- + +To deploy [OpenClaw](https://github.com/openclaw/openclaw) to Fly.io, download the deploy package and run the script. It handles everything — app creation, volumes, secrets, and deployment. + +Download Deploy Package + +```bash +unzip Openclaw-Fly-Deploy-main.zip +cd Openclaw-Fly-Deploy-main +bash deploy.sh +``` + +You'll need **[flyctl](https://fly.io/docs/flyctl/install/)** installed, a **Fly.io account** ([free trial](https://fly.io/docs/about/free-trial/) works), and an **LLM API key** (Anthropic, OpenAI, Google Gemini, OpenRouter, Moonshot AI, or MiniMax). + +## What is OpenClaw? + +OpenClaw is an open-source AI agent gateway that lets you run a persistent AI assistant reachable from anywhere — Discord, Telegram, Slack, or your local CLI. It manages conversations, tool use, and connections across multiple channels through a single gateway process. + +## How it works + +The deploy package sets up a wrapper server that manages the OpenClaw gateway and provides a browser-based setup wizard: + +``` +Internet → Fly.io proxy → Wrapper server (:3000) → OpenClaw gateway (:18789) + ├── /setup → Setup wizard (password-protected) + ├── /healthz → Health check (no auth) + └── /* → Proxied to gateway +``` + +All state lives on a persistent volume mounted at `/data`, so your configuration, conversation history, and installed tools survive restarts and redeployments. + +The script will prompt you for: + +1. **App name** — defaults to `openclaw-XXXX` (random suffix). This becomes your URL: `https://your-app-name.fly.dev` +2. **Region** — where to run your Machine (defaults to `iad` / Virginia). Pick one close to you for lower latency. See [Fly.io regions](/docs/reference/regions/) for the full list. +3. **Setup password** — protects the `/setup` wizard from the internet. Pick something strong. +4. **LLM provider** — choose from Anthropic, OpenAI, Google Gemini, OpenRouter, Moonshot AI, or MiniMax +5. **LLM API key** — the key for your chosen provider +6. **Channel tokens** (optional) — Discord bot token, Telegram bot token, or Slack bot + app tokens if you want to connect chat channels + +The script then creates a Fly app, provisions a persistent volume, sets your credentials as encrypted [Fly secrets](/docs/apps/secrets/), and builds and deploys the Docker image on Fly's remote builders. The first deploy takes a few minutes. Your credentials never leave your machine — they go directly to Fly.io via `flyctl`. + +## Post-deploy setup + +Once deployment completes, the script prints your app details: + +``` +=== Deployment Complete === + + App URL: https://your-app-name.fly.dev + Setup wizard: https://your-app-name.fly.dev/setup + Gateway URL: wss://your-app-name.fly.dev + Gateway token: +``` + +### Setup wizard + +Visit `https://your-app-name.fly.dev/setup` in your browser. Log in with any username and the setup password you chose. From the wizard you can: + +- Change your LLM provider and API key +- Add or update Discord, Telegram, and Slack channel connections +- Edit the raw OpenClaw config file +- Run debug commands against the gateway +- Export and import configuration backups +- Approve device pairing requests + +### Connect your local CLI + +If you have OpenClaw installed locally, point it at your remote gateway: + +```bash +openclaw config set gateway.mode remote +openclaw config set gateway.remote.url wss://your-app-name.fly.dev +openclaw config set gateway.remote.token +openclaw health # verify the connection +``` + +This lets you use the `openclaw` CLI on your laptop while the gateway runs on Fly.io, keeping conversations and state persistent even when your laptop is closed. + +## Configuration + +### Secrets + +All sensitive values are stored as [Fly secrets](/docs/apps/secrets/), encrypted at rest and injected as environment variables at boot. They are never visible in logs, config files, or the Fly dashboard. + +| Secret | Required | Description | +|--------|----------|-------------| +| `SETUP_PASSWORD` | Yes | Protects the `/setup` wizard with HTTP Basic Auth | +| `OPENCLAW_GATEWAY_TOKEN` | Yes | Auth token for gateway connections (auto-generated) | +| `OPENCLAW_API_KEY` | Yes | Your LLM provider API key | +| `OPENCLAW_AUTH_CHOICE` | Yes | Provider identifier (set by deploy script) | +| `OPENCLAW_API_KEY_FLAG` | Yes | CLI flag for the provider (set by deploy script) | +| `OPENCLAW_DISCORD_TOKEN` | No | Discord bot token | +| `OPENCLAW_TELEGRAM_TOKEN` | No | Telegram bot token | +| `OPENCLAW_SLACK_BOT_TOKEN` | No | Slack bot token (`xoxb-...`) | +| `OPENCLAW_SLACK_APP_TOKEN` | No | Slack app token (`xapp-...`, required if bot token is set) | + +To update a secret after deployment: + +```bash +fly secrets set OPENCLAW_API_KEY=sk-new-key-here -a your-app-name +``` + +The Machine restarts automatically when secrets change. + +### VM sizing + +The default configuration uses a `shared-cpu-2x` Machine with 4 GB RAM, which costs roughly $20–25/month when running continuously. With auto-stop enabled (the default), you only pay for time the Machine is actually running. + +To adjust resources: + +```bash +fly scale memory 4096 -a your-app-name +fly scale vm shared-cpu-4x -a your-app-name +``` + +### Persistent storage + +OpenClaw stores all state on a [Fly Volume](/docs/volumes/overview/) mounted at `/data`. This includes: + +- `openclaw.json` — gateway configuration +- Conversation history and context +- Installed tools and plugins +- npm/pnpm caches for user-installed packages + +The default volume size is 1 GB. To extend it: + +```bash +fly volumes extend -s 3 -a your-app-name +``` + +## Useful commands + +| Command | Description | +|---------|-------------| +| `fly logs -a your-app-name` | Stream live logs | +| `fly ssh console -a your-app-name` | SSH into the Machine | +| `fly apps restart your-app-name` | Restart after config changes | +| `fly scale memory 4096 -a your-app-name` | Increase memory | +| `fly status -a your-app-name` | Check Machine status | +| `fly volumes list -a your-app-name` | List attached volumes | + +## Troubleshooting + +**"SETUP_PASSWORD is not set"** +The setup password secret is missing. Set it: +```bash +fly secrets set SETUP_PASSWORD=your-password -a your-app-name +``` + +**Out of memory / crashes** +Increase the Machine's memory: +```bash +fly scale memory 4096 -a your-app-name +``` + +**Gateway won't start** +Visit `/setup` in your browser and check the debug console for errors. Common causes: invalid API key, missing config file, or a corrupted state directory. + +**Lock file errors** +If the gateway didn't shut down cleanly, stale lock files can prevent it from starting: +```bash +fly ssh console -a your-app-name +rm -f /data/gateway.*.lock +exit +fly apps restart your-app-name +``` + +**Need to start fresh** +Use the "Reset" button in the setup wizard to clear the config and re-run onboarding, or SSH in and remove the config: +```bash +fly ssh console -a your-app-name +rm /data/openclaw.json +exit +fly apps restart your-app-name +``` + +## Supported LLM providers + +| Provider | What you need | +|----------|---------------| +| Anthropic | API key from [console.anthropic.com](https://console.anthropic.com/) | +| OpenAI | API key from [platform.openai.com](https://platform.openai.com/) | +| Google Gemini | API key from [aistudio.google.com](https://aistudio.google.com/) | +| OpenRouter | API key from [openrouter.ai](https://openrouter.ai/) | +| Moonshot AI | API key from Moonshot's developer portal | +| MiniMax | API key from MiniMax's developer portal | + +You can switch providers at any time through the setup wizard — no redeployment needed. diff --git a/blueprints/index.html.md b/blueprints/index.html.md index fd815ab12f..237aa6f95f 100644 --- a/blueprints/index.html.md +++ b/blueprints/index.html.md @@ -17,6 +17,7 @@ Guides for the structure your app on Fly.io. Layouts, tradeoffs, moving parts. - [Session Affinity (a.k.a. Sticky Sessions)](/docs/blueprints/sticky-sessions/) - [Multi-region databases and fly-replay](/docs/blueprints/multi-region-fly-replay/) - [Deploying Remote MCP Servers](/docs/blueprints/remote-mcp-servers/) +- [Deploy OpenClaw on Fly.io](/docs/blueprints/deploy-openclaw/) ## Deployment & Developer Workflow diff --git a/partials/_guides_nav.html.erb b/partials/_guides_nav.html.erb index 56bdce5fb4..d70d38a60e 100644 --- a/partials/_guides_nav.html.erb +++ b/partials/_guides_nav.html.erb @@ -19,7 +19,8 @@ { text: "Shared Nothing Architecture", path: "/docs/blueprints/shared-nothing/" }, { text: "Session Affinity (a.k.a. Sticky Sessions)", path: "/docs/blueprints/sticky-sessions/" }, { text: "Multi-region databases and fly-replay", path: "/docs/blueprints/multi-region-fly-replay/" }, - { text: "Deploying Remote MCP Servers", path: "/docs/blueprints/remote-mcp-servers/" } + { text: "Deploying Remote MCP Servers", path: "/docs/blueprints/remote-mcp-servers/" }, + { text: "Deploy OpenClaw on Fly.io", path: "/docs/blueprints/deploy-openclaw/" } ] }, {