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)

koda.teamplayers.ai    → Application: "OpenClaw - Koda"    → Policy: owners only
agent2.teamplayers.ai  → Application: "OpenClaw - Agent 2" → Policy: client X only

CF-Access-Client-Id: .access
CF-Access-Client-Secret: 

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: .access
CF-Access-Client-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