openclaw-fly-template

Deploy OpenClaw to Fly.io with:

• GitHub Actions deploy automation
• persistent state volume
• Cloudflare Tunnel
• Cloudflare Zero Trust Access in front of Control UI
• optional internet webhooks (/hooks/*) guarded by Cloudflare Access + OpenClaw hook token

This README is intentionally high-level. Use the runbook as the source of truth for setup and operations:

• onboarding-and-operations.md

Recommended security model

This template is tuned for private Fly deployment + Cloudflare Zero Trust:

• The Fly app runs without a public Fly http_service.
• cloudflared makes outbound-only tunnel connections.
• Access to Control UI is through your Cloudflare hostname and Access policies.

Quick start

1. Complete prerequisites and Cloudflare Tunnel setup.
2. Add required GitHub Actions secrets.
3. Deploy by pushing to main or running the workflow manually (recommended first deploy: reset_config=true).
4. Validate deploy health and access OpenClaw via your Cloudflare-protected hostname.
5. If the Control UI shows disconnected (1008): pairing required, approve the pending device request from inside the Fly machine.
6. For Discord setup, set DISCORD_BOT_TOKEN and DISCORD_GUILD_ID (optionally DISCORD_CHANNEL_ID); startup auto-configures Discord with open guild-channel policy and seeds a default channel key (DISCORD_CHANNEL_ID or general).
7. For webhook setup, set OPENCLAW_HOOKS_TOKEN (optionally OPENCLAW_HOOKS_PATH and OPENCLAW_HOOKS_ALLOWED_AGENT_IDS), and target agentId: "hooks" in /hooks/agent payloads.

For exact commands and values, follow the runbook sections:

• prerequisites: 1) Prerequisites
• Fly app + region: 2) Choose Fly app + region
• tunnel + access: 3) Configure Cloudflare Tunnel ingress
• secrets: 4) Set GitHub Actions secrets
• deployment: 5) Deploy
• validation: 6) Validate after deploy
• operations + troubleshooting: 7) Operations and 8) Common troubleshooting

Agent docs shipped in the image:

• /app/docs/agent/readme.md
• /app/docs/agent/env.md

Recommended bootstrap prompts for Jarvis

Use prompts like:

1. Read /app/docs/agent/readme.md and /app/docs/agent/env.md, then summarize runtime commands and key paths.
2. Diagnose startup issues using bounded app log reads and identify the first fatal error.
3. Verify gateway liveness on ws://127.0.0.1:3000 and summarize channel status.

Reference docs

• OpenClaw Fly deployment docs: https://docs.openclaw.ai/install/fly
• OpenClaw Control UI docs: https://docs.openclaw.ai/web/control-ui
• OpenClaw getting started: https://docs.openclaw.ai/start/getting-started
• OpenClaw environment variables: https://docs.openclaw.ai/help/environment
• OpenClaw gateway runbook: https://docs.openclaw.ai/gateway
• Cloudflare Tunnel docs: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/
• Cloudflare Access policies: https://developers.cloudflare.com/cloudflare-one/access-controls/policies/