Cloudflare Access VPS — Cloudflare工具

--- name: cloudflare-access-vps description: > Add Cloudflare Zero Trust Access authentication to a VPS-hosted OpenClaw agent. Puts a login screen (email OTP, Google SSO, GitHub, or TOTP MFA) in front of the entire domain before any traffic reaches the server. Use when: (1) securing a cloud-deployed OpenClaw agent behind an identity gate, (2) adding MFA to koda.teamplayers.ai or any agent subdomain, (3) enabling per-agent access policies (allowlist by email/domain), (4) generating service tokens for native app or API access that bypasses browser login, or (5) troubleshooting Cloudflare Access on an existing OpenClaw deployment. Requires Cloudflare Tunnel already running on the VPS. --- # Cloudflare Access 对于 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 活跃 (`cloudflared` 服务 running), domain 在...上 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](https://dash.cloudflare.com) → select 账户 → **Zero Trust** 2. 在...上 第一个 visit, pick team name (e.g. `teamplayers`) — becomes `teamplayers.cloudflareaccess.com` 3. Free plan: up 到 50 users, 否 credit card 必填 ### Step 2 — 添加 Identity Provider **Zero Trust → Settings → Authentication → 添加 新的** — 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 — 创建 Access Application **Zero Trust → Access → Applications → 添加 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 — 创建 Access Policy **Policy name:** `Owners 仅` (或 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. --- ## 服务 Tokens (对于 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 → 服务 Auth → 创建 服务 令牌** Copy the `CF-Access-Client-Id` and `CF-Access-Client-Secret`. Attach the token to the application: - 在...中 Access Application, 添加 第二个 policy: - Action: **Allow**, Include → **服务 令牌** → select 令牌 您 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 带有 OpenClaw 令牌 + 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" 之后 登录 - WebSocket connections failing 通过 Access - 服务 令牌 auth 不 working - Bypassing Access 对于 localhost development