Cloudflare Access for OpenClaw VPS Agents
Gates the entire domain with Cloudflare Zero Trust Access — every URL, including /ws, /api/,
and the control UI, requires authentication before a byte reaches the VPS.
Architecture
Browser / app hits https://koda.yourdomain.com
↓
Cloudflare Edge
├── Access policy check → BLOCKED if unauthenticated (login screen shown)
└── Authenticated → Cloudflare Tunnel → localhost:18789 → OpenClaw
↓
Gateway token auth (layer 2)
↓
Device pairing (layer 3)
Prerequisites: Cloudflare Tunnel active (cloudflared service running), domain on Cloudflare DNS.
See cloudflare-agent-tunnel skill if tunnel is not yet set up.
Quick Setup (5 Steps)
Step 1 — Enable Zero Trust
- dash.cloudflare.com → select your account → Zero Trust
- On first visit, pick a team name (e.g.
teamplayers) — this becomes teamplayers.cloudflareaccess.com
- Free plan: up to 50 users, no credit card required
Step 2 — Add an Identity Provider
Zero Trust → Settings → Authentication → Add new — pick one:
| Provider | Best for | Setup effort |
|---|
| One-time PIN (email OTP) | Simplest, no external app | Zero — built-in |
| Google | Teams with Google Workspace | ~5 min (OAuth app in Google Console) |
| GitHub | Developer teams | ~5 min (OAuth app in GitHub) |
For most solo/small team deployments, One-time PIN is sufficient and needs no external setup.
Step 3 — Create an Access Application
Zero Trust → Access → Applications → Add an application → Self-hosted
| Field | Value |
|---|
| Application name | OpenClaw - Koda (or agent name) |
| Session duration | 24 hours (reduce for higher security) |
| Application domain | koda.yourdomain.com |
| Path | (leave blank to gate entire domain) |
Click Next.
Step 4 — Create an Access Policy
Policy name: Owners only (or similar)
| Rule | Setting |
|---|
| Action | Allow |
| Include → Selector | Emails |
| Include → Value | charles@yourdomain.com (your email) |
To require MFA: Add require rule → Authentication Method → mfa (forces TOTP/hardware key on top of identity provider).
Click Next → Save.
Step 5 — Test
Open a private/incognito window → visit https://koda.yourdomain.com.
You should see a Cloudflare login page. After authenticating, OpenClaw loads normally.
Multi-Agent Setup
Each agent subdomain gets its own Access Application with its own policy.
koda.teamplayers.ai → Application: "OpenClaw - Koda" → Policy: owners only
agent2.teamplayers.ai → Application: "OpenClaw - Agent 2" → Policy: client X only
To add a second agent: repeat Steps 3–4 with the new subdomain.
Service Tokens (for API / Native App Access)
Browser-based Cloudflare login doesn't work for programmatic or native app connections.
Use Service Tokens instead — static credentials sent as HTTP headers.
Zero Trust → Access → Service Auth → Create Service Token
Copy the CF-Access-Client-Id and CF-Access-Client-Secret.
Attach the token to the application:
- In the Access Application, add a second policy:
- Action: Allow, Include → Service Token → select the token you created
The caller then sends:
CF-Access-Client-Id: <id>.access
CF-Access-Client-Secret: <secret>
For WebSocket connections (OpenClaw gateway): pass these as HTTP headers on the WS upgrade request.
Full details → references/service-tokens.md
Interaction with OpenClaw Token + Pairing
Cloudflare Access is the outer gate. OpenClaw's own auth layers still apply after it:
| Layer | What it blocks |
|---|
| Cloudflare Access | Unauthenticated internet users (never reach the UI) |
| Gateway token | Anyone who bypasses Cloudflare (e.g. VPS localhost, misconfigured tunnel) |
| Device pairing | Someone with the token but on an unapproved browser |
For existing deployments, no OpenClaw config changes are needed — Access just wraps the outside.
Troubleshooting
See references/troubleshooting.md for common issues including:
- "Access denied" after login
- WebSocket connections failing through Access
- Service token auth not working
- Bypassing Access for localhost development
