OpenClaw Agent Hub

OpenClaw Cloudflare Guide

A beginner-first guide to moving this OpenClaw site from local validation to Cloudflare Workers with OpenNext.
Mar 13, 2026

OpenClaw Cloudflare Guide

This page is for the moment after local setup works and you want the first safe Cloudflare deployment.

It is not the right first page if you still have not finished your local install, first build, or first sanity check.

Quick facts

  • Best for: first Cloudflare deployment after local validation
  • Current stack for this site: Next.js on Cloudflare Workers through OpenNext
  • Main commands in this repo: pnpm cf:preview, pnpm cf:deploy, pnpm cf:typegen
  • Verified on: 2026-03-13 against the current OpenNext and Cloudflare Workers docs

When Cloudflare is a good fit

  • you want one stable public URL instead of a laptop-only setup
  • you want Cloudflare observability and an edge runtime
  • your first workflow is already stable locally
  • you can keep secrets, domains, and rollback notes organized

When not to start here

  • you have not completed pnpm build locally
  • you still do not know which channel or workflow matters first
  • you have not decided the production URL
  • you are still changing core environment values every hour

What to prepare first

Before touching deploy, prepare these:

  1. A Cloudflare account and a real domain if you want a production hostname.
  2. pnpm install
  3. A working Wrangler session.
  4. The public app values you actually want to ship.

Use this check first:

npx wrangler whoami

If that fails, sign in first:

npx wrangler login

For this repo, the worker configuration lives in wrangler.toml, and the repo-safe example lives in wrangler.toml.example.

The safest beginner path

Step 1: prove the app builds before touching Cloudflare

Run:

pnpm build

Only continue if the build succeeds cleanly.

Step 2: preview the worker locally

If you changed runtime bindings or want fresh types, run:

pnpm cf:typegen

Then preview the worker locally:

pnpm cf:preview

Check the homepage and one deeper route before you deploy.

Step 3: add only the secrets you actually need

This site can ship public content pages without database or auth secrets.

Add secrets before turning on auth or database-backed features:

npx wrangler secret put AUTH_SECRET
npx wrangler secret put DATABASE_URL

If local preview uses auth, replace the placeholder AUTH_SECRET in .dev.vars with a real local secret.

Step 4: deploy the worker

Run:

pnpm cf:deploy

This repo already uses @opennextjs/cloudflare, so the deploy scripts target Cloudflare Workers directly.

Step 5: bind the real domain and run a smoke test

After the first successful deploy:

  • attach the domain in the Cloudflare Workers dashboard if it is not already bound automatically
  • open the deployed URL
  • test /, /openclaw, and one deeper route such as /skills
  • confirm request logs and errors are visible in Cloudflare before you announce the site

First production smoke test

Before calling the deployment done, confirm these:

  • the homepage loads on the real domain
  • one English route and one Chinese route both work
  • one deep content page opens without a 404
  • no secret-dependent feature is accidentally enabled
  • you can find request errors in Cloudflare observability

Common beginner mistakes

1. Treating Cloudflare as the first proof that the app works

Cloudflare should be the second proof. Local build and local preview come first.

2. Mixing old Pages assumptions with the current Workers stack

This repo is already wired for Cloudflare Workers through OpenNext. Use the repo scripts instead of inventing a different deploy path.

3. Forgetting the production URL

If the bound domain and NEXT_PUBLIC_APP_URL disagree, links and previews become confusing fast.

4. Adding secrets too late or too early

Do not block a content-only launch on database secrets you are not using yet. But do not enable auth or database features without them.

5. Shipping with no rollback note

Write down the deployed command, date, domain, and last known good config. It saves time later.