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

1. dash.cloudflare.com → select your account → Zero Trust
2. On first visit, pick a team name (e.g. teamplayers) — this becomes teamplayers.cloudflareaccess.com
3. Free plan: up to 50 users, no credit card required

Step 2 — Add an Identity Provider

Zero Trust → Settings → Authentication → Add new — pick one:

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

Click Next.

Step 4 — Create an Access Policy

Policy name: Owners only (or similar)

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:

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