Research Preview

Deploy OpenClaw on Vercel

Get a personal OpenClaw instance running in a Vercel Sandbox with one command.

Recommended: the vclaw CLI

npx @vercel/vclaw create --scope your-team

This is the only fully supported install path. Use it unless you have a specific reason not to.

Why vclaw over the Deploy button

The Deploy button starts a project but stops short of a working OpenClaw. vclaw takes you end-to-end:

Step	vclaw create	Deploy button
Uses or clones vercel-labs/vercel-openclaw	yes	yes
Links a Vercel project in the scope you pick	yes	partial (browser flow)
Provisions Redis via the Marketplace integration	yes	yes
Prompts for and sets ADMIN_SECRET	yes	yes
Can set CRON_SECRET for independent cron rotation	yes, with --cron-secret	no
Enables Deployment Protection and wires VERCEL_AUTOMATION_BYPASS_SECRET	yes (--deployment-protection)	no
Runs a production deploy	yes	yes
Runs launch verification against the live URL	yes	no
Works headlessly with VERCEL_TOKEN	yes	no

Result: after vclaw create finishes, channel webhooks can reach OpenClaw through protection when bypass is configured, and you have proof the sandbox can complete a real chat roundtrip. Cron auth rotates independently from your admin login only when you pass --cron-secret; otherwise the runtime falls back to ADMIN_SECRET. The Deploy button gets you a booted UI, nothing more.

Prerequisites

• Node.js 20 or newer
• git
• The Vercel CLI: npm i -g vercel
• Authenticated: run vercel login, or export VERCEL_TOKEN for non-interactive runs

Check your environment before you start:

npx @vercel/vclaw doctor

Quick start with vclaw

npx @vercel/vclaw create --scope your-team

For the full onboarding path across the CLI, dashboard, sandbox runtime, and release contracts, read the Getting Started Guide. It is the main guide for maintainers and agents working across vclaw, vercel-openclaw, and the OpenClaw fork.

This walks through the full setup:

1. Verifies local prerequisites.
2. Picks a Vercel scope (prompts if you have more than one).
3. Uses a managed workspace under ~/.vclaw by default, or uses the directory passed with --dir. Pass --clone to clone or update vercel-labs/vercel-openclaw into that directory.
4. Creates and links a Vercel project (prompts for a unique name if openclaw is taken).
5. Provisions Redis via the Redis Cloud Marketplace integration.
6. Optionally enables Deployment Protection (sso or password) and sets the automation bypass secret so webhooks still reach the app.
7. Prompts for ADMIN_SECRET (masked, confirmed). This is the password you will type into the admin UI.
8. Pushes managed env vars: ADMIN_SECRET, CRON_SECRET (if --cron-secret is set), VERCEL_AUTOMATION_BYPASS_SECRET (if protection is enabled).
9. Runs a production deploy.
10. Runs launch verification against the new URL and reports channelReadiness.
11. Optionally wires a Telegram bot with --telegram, or Slack through the interactive --slack flow, non-interactive --slack-config-token, or --slack-bot-token --slack-signing-secret flows.

Common vclaw flows

Choose a project name and use an existing checkout:

vclaw create --scope your-team --name my-openclaw --dir ~/dev/vercel-openclaw

Clone or update into a chosen directory:

vclaw create --scope your-team --name my-openclaw --dir ~/dev/my-openclaw --clone

Enable SSO deployment protection (auto-configures webhook bypass):

vclaw create --scope your-team --deployment-protection sso

Prepare a project but skip the deploy step:

vclaw create --scope your-team --skip-deploy

Wire up a Telegram bot in the same run:

vclaw create --scope your-team --telegram "123456:AA...BotFatherToken"

After launch verification passes, vclaw calls PUT /api/channels/telegram on the new deployment. The app validates the token via Telegram's getMe, generates a webhook secret, registers the Vercel URL with Telegram, and syncs slash commands — no admin-panel clicks needed.

Wire up Slack in the same run:

vclaw create --scope your-team --slack

--slack opens the interactive Slack setup menu. For non-interactive Slack setup, choose one flow:

# Create a new Slack app, then complete OAuth in the browser.
vclaw create --scope your-team \
  --slack-config-token "$SLACK_CONFIG_TOKEN" \
  --slack-app-name "My OpenClaw"

# Connect an existing Slack app.
vclaw create --scope your-team \
  --slack-bot-token "xoxb-..." \
  --slack-signing-secret "abcd1234..."

--slack-config-token creates a new app and opens the OAuth install flow. --slack-bot-token and --slack-signing-secret must be passed together for an existing app.

Slack setup requires a live deployment and is mutually exclusive with --skip-deploy.

Re-run launch verification against an existing deployment:

vclaw verify \
  --url https://my-openclaw.vercel.app \
  --admin-secret "$ADMIN_SECRET"

For protected deployments, include the automation bypass secret:

vclaw verify \
  --url https://my-openclaw.vercel.app \
  --admin-secret "$ADMIN_SECRET" \
  --protection-bypass "$VERCEL_AUTOMATION_BYPASS_SECRET"

Full reference: github.com/vercel-labs/vclaw.

---

Alternative: Deploy button (not recommended)

Use this only if you cannot install Node locally. It provisions Redis and prompts for ADMIN_SECRET, but leaves Deployment Protection, CRON_SECRET, and launch verification for you to do by hand afterward.

After the deploy finishes, you still need to:

1. Sign in with your ADMIN_SECRET.
2. Run destructive launch verification from the admin panel before connecting any channel.
3. Manually set CRON_SECRET if you want cron auth separate from admin login.
4. Manually enable Deployment Protection and set VERCEL_AUTOMATION_BYPASS_SECRET if you want protected previews that channels can still reach.

---

What is this?

A Next.js app that wraps OpenClaw in a full control plane (auth, persistent sandboxes, channel integrations, egress firewall) and runs it inside a Vercel Sandbox.

Getting started

After vclaw create finishes:

1. Sign in. Open the printed deployment URL and enter your ADMIN_SECRET.
2. Use OpenClaw. Visit /gateway or click Start in the admin panel. First boot takes about a minute while OpenClaw installs into the sandbox. Resumes after that take about 10 seconds (the sandbox auto-snapshots on stop and auto-resumes on get).
3. Verify. vclaw already ran launch verification once. Re-run it from the admin panel any time you change config. Preflight is only a config-readiness check; it does not prove the sandbox can complete a real channel delivery.
4. Connect channels. Wire up Slack, Telegram, WhatsApp (experimental), or Discord (experimental) from the admin panel — or pre-wire Telegram and Slack during vclaw create itself with --telegram / --slack --slack-signing-secret. For Slack OAuth install, set SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, and SLACK_SIGNING_SECRET, or enter credentials manually. A deployment is channel-ready only after destructive launch verification passes and channelReadiness.ready is true.

See Hosted Feature Support for the exact hosted surface. Upstream-only OpenClaw features such as companion nodes, voice, canvas, arbitrary channel adapters, and arbitrary plugin/skill installation are not presented as hosted support until this wrapper has setup, persistence, wake/proxy behavior, and verification for them.

What you get

• Full OpenClaw UI proxied at /gateway with auth and WebSocket rewriting.
• Persistent sandboxes. State is preserved on stop and restored on resume.
• Slack, Telegram, WhatsApp (experimental), and Discord (experimental) channels with durable delivery.
• Bundled OpenClaw plugins and skills only. Arbitrary plugin, skill, ClawHub, MCP, and tool installation is a local/upstream OpenClaw path until a hosted lifecycle contract exists.
• Egress firewall. Learn which domains your agent talks to, then lock it down.
• Auto-wake. A cron watchdog wakes your sandbox when scheduled OpenClaw jobs are due.

Built with

Technology	Role
Next.js	App framework
Vercel Sandbox	Runs the OpenClaw instance (persistent sandboxes, auto-snapshot on stop, auto-resume on get)
Vercel AI Gateway	OIDC-authenticated model access for the agent
Redis Cloud	Persistent state for metadata, snapshots, and channel config (any Redis-wire-protocol endpoint works)
Vercel Workflow	Durable channel message delivery (Slack, Telegram; WhatsApp and Discord experimental)
Vercel Queues	Launch verification probe delivery
Vercel Cron	Watchdog health checks and scheduled wake

Configuration

For the default path (VERCEL_AUTH_MODE=admin-secret), the only value you must provide up front is ADMIN_SECRET. Everything else auto-configures:

• Redis. Provisioned by vclaw (or the Deploy button) via the Redis Cloud Marketplace integration, which sets REDIS_URL.
• AI Gateway auth. Handled via Vercel OIDC on deployed environments.
• Cron secret. Falls back to ADMIN_SECRET when CRON_SECRET is unset. Set CRON_SECRET separately on deployed environments if you want cron auth to rotate independently from admin login. vclaw --cron-secret sets this for you.
• Watchdog cron. Runs once daily by default so Hobby-plan deploys succeed. Pro plans can increase the schedule in vercel.json up to every minute for more responsive auto-wake.

Switching to VERCEL_AUTH_MODE=sign-in-with-vercel also requires NEXT_PUBLIC_VERCEL_APP_CLIENT_ID, VERCEL_APP_CLIENT_SECRET, and SESSION_SECRET.

See docs/environment-variables.md for the full reference, including optional tuning (vCPU count, sleep timeout, version pinning) and alternative auth modes.

Local development

pnpm install
vercel link && vercel env pull   # pulls OIDC credentials for AI Gateway
pnpm dev                         # http://localhost:3000

Running locally against production data

For production debugging, prefer a linked local workspace created by vclaw create --auto-link. It links the Vercel project under --dir, writes the production admin/protection values into that directory's .env.local, and makes sure local-only files stay ignored. That keeps the local checkout you inspect, the .vercel/project.json link, and the auth values used by admin/debug commands in one place.

npx @vercel/vclaw create \
  --scope your-team \
  --auto-project-name \
  --dir ~/dev/vercel-openclaw \
  --admin-secret "$ADMIN_SECRET" \
  --auto-link

cd ~/dev/vercel-openclaw
# .env.local now contains the admin secret, automation bypass secret, and vclaw project metadata.
# Keep it local; do not paste it into logs, commits, issues, or agent handoffs.

For read-only UI work against real prod Redis/metadata, edit that .env.local before pnpm dev:

# in .env.local:
#   VERCEL_ENV=development     # flips the Vercel-deployment gate so Redis connects
#   LOCAL_READ_ONLY=1          # blocks every admin mutation route with 403 LOCAL_READ_ONLY
#   unset VERCEL_AUTH_MODE     # use admin-secret auth locally
pnpm dev

With LOCAL_READ_ONLY=1, POST /api/admin/stop, /ensure, /reset, /snapshot, and channel config writes all return 403 { error: "LOCAL_READ_ONLY" } before touching the sandbox SDK. Reads (/api/status, /api/admin/preflight, /api/admin/logs) still work. Unset the variable only when you intentionally want to test a mutation.

Debugging channels with agents

Channel delivery has several independent states: the app can be connected, the sandbox can be running, the native handler can accept a forward, and the user still might not see a reply. When Slack, Telegram, Discord, or WhatsApp is stuck, use the repo-local Codex agents and skills to split evidence gathering by channel instead of guessing from one readiness label.

Codex custom agent roles live in .codex/agents/*.toml; shared debugging playbooks live in .agents/skills/*/SKILL.md. Use the channel agents for parallel triage and the skills for repeatable evidence collection:

Channel	Agent	Primary skill	Focus
Telegram	channel_telegram	telegram-native-8787	Native port 8787, webhook secret flow, boot cleanup, user-visible replies
Slack	channel_slack	slack-delivery	OAuth vs delivery readiness, raw-body signature forwarding, /slack/events fast path
Discord	channel_discord	discord-delivery	Ed25519 verification, interaction deferral, token expiry, workflow forwarding
WhatsApp	channel_whatsapp	whatsapp-delivery	Meta verification, raw-body signatures, link-state projection, boot messages

For any channel incident, start with $channel-debug-core. It requires deployment-state proof, the admin readiness surfaces, a runtime path diagram, a hypothesis table, and a channel handoff before proposing a fix. Before changing webhook routes or the shared workflow, use $channel-forward-parity to verify every terminal path logs, updates lastForward, classifies failures, and refreshes stale sandbox port URLs when needed.

Suggested workflow:

1. Prove the deployed runtime matches the source you are reading: local git rev-parse HEAD, remote git ls-remote origin main, and live GET /api/admin/sandbox-diag.
2. Collect GET /api/admin/why-not-ready, GET /api/channels/summary, GET /api/admin/sandbox-diag, and GET /api/admin/logs before editing code.
3. If multiple channels are suspect, explicitly spawn the relevant channel agents and ask each to return .agents/skills/channel-debug-core/references/handoff-template.md.
4. Keep route-ready, native-accepted, and user-visible-reply separate in the report. A green lastForward is not proof that the user saw a message.
5. Save raw runtime evidence under .agent-runs/channel-debug/<timestamp>/ and do not commit it.

Debugging app subsystems with agents

Channel delivery is only one slice of the wrapper. For cron, lifecycle, proxy, firewall, auth/store, bootstrap, launch verification, and admin UI work, use the matching repo-local Codex agent plus its skill so each investigation starts from the right evidence and file ownership.

Area	Agent	Primary skill	Focus
Cron/watchdog	cron_watchdog	cron-watchdog-debug	Vercel Cron auth, watchdog reports, cron wake keys, token refresh, OpenClaw job evidence
Sandbox lifecycle	sandbox_lifecycle	sandbox-lifecycle-debug	create/resume/stop/snapshot/reset, stale-running reconciliation, locks, hot spares
Gateway/proxy	gateway_proxy	gateway-proxy-debug	/gateway, HTML injection, WebSocket rewrite, waiting page, gateway-token handoff
Firewall/AI Gateway	firewall_ai_gateway	firewall-ai-gateway-debug	network policy, OIDC token refresh, transform rules, egress allowlists
Auth/store	auth_store	auth-store-debug	admin-secret, Vercel auth, sessions, CSRF, Redis/memory store, keyspace
OpenClaw bootstrap	openclaw_bootstrap	openclaw-bootstrap-debug	bundle sidecars, config hashes, restore assets, plugin discovery, gateway restart
Launch verification	launch_verify	launch-verify-debug	preflight, queue ping, chat completions, wake-from-sleep, restorePrepared, remote smoke
Admin UI	admin_ui	admin-ui-debug	command shell, status panels, action helpers, operator copy, visual verification

For cron incidents, start with $cron-watchdog-debug and keep these states separate: Vercel Cron invoked, watchdog authorized, cron wake due, sandbox woke, AI Gateway token refreshed, OpenClaw cron scheduler loaded jobs, and user-visible delivery happened. Save raw runtime evidence under .agent-runs/cron-debug/<timestamp>/ and do not commit it.

Documentation

Document	Contents
Getting Started Guide	Main handoff for the three-repo system, operational paths, vclaw create, release, and reliability contracts
Architecture	System overview and subsystem map
Sandbox Lifecycle and Restore	State transitions, persistent sandboxes, resume behavior
Preflight and Launch Verification	Deployment readiness and runtime verification
Channels and Webhooks	Channel setup (Slack, Telegram, WhatsApp, Discord), readiness, protection behavior
Environment Variables	Full env var reference
API Reference	Endpoint and payload reference
Deployment Protection	Bypass secret behavior and display-safe URLs
Architecture Tradeoffs	Why the codebase is shaped this way, alternatives explored
Contributing	Architecture, routes, testing, development workflows