// LLM knowledge base for the gateway system · ExoClaw bridge · phases · post-training paths
#id, a type badge, a one-paragraph description, and chips linking to neighbors. Load this page as context when an LLM needs to reason about gateway operation — onboarding, scaling, phase rollover, post-training upgrades.
OPENCLAW GATEWAY — NODE GRAPH
trainee ─────────────► organized-gateway (CF Worker)
│
┌─── KV ──────────┼──────────── D1 ───┐
│ rate:{u}:{m} │ requests │
│ oauth:{u} │ user_summary │
│ tier:{u} │ monthly_usage │
└─────────────────┼───────────────────┘
│ Tailscale
▼
claws-mac-mini ──► OpenClaw :18789
Hermes :7700
NoClaw :11434
phases: Phase 1 (BYOK) ─► Phase 2 (Codex OAuth) ─► Phase 3 (Tiered/Stripe)
paths: A (shared) · B (ClawBox local) · C (ClaudeFlare full stack)
HICAM workshop attendee. Non-technical business owner / executive. Sets OPENCLAW_GATEWAY_URL, OPENAI_API_KEY, and USER_ID in .env. Runs setup.sh; gets a working agent in < 5 minutes.
Owns the gateway. Provisions CF infra, runs claws-mac-mini, monitors D1 during the event, handles scaling decisions across Phase 1 → 2 → 3. Single-DRI for ops.
Post-training paying user on Path A. Stripe subscription assigns a tier; tier:{user_id} in KV controls per-month limits.
The single Cloudflare Worker. Hono app routing /v1/* through rate limit + D1 log + Tailscale proxy. The only public component of the system.
Claude CLI OAuth daemon on claws-mac-mini. Routes BYOK OpenAI in Phase 1; native Claude via Codex OAuth in Phase 2. Reachable only over Tailscale.
Memory + context server on claws-mac-mini. Persists agent sessions across requests so trainee state survives idle gaps.
Local Gemma 3 27B inference on claws-mac-mini. Free fallback for non-billable work — internal Jordan tools, not a trainee path.
Outbound-only encrypted tunnel from claws-mac-mini to Cloudflare's edge. The Worker reaches OpenClaw through this URL, never via public internet.
Cloudflare KV namespace. Holds three key shapes: rate:{user_id}:{minute} (counter), oauth:{user_id} (Phase 2 token), tier:{user_id} (Phase 3 tier).
Cloudflare D1 (SQLite) database. Holds requests table + user_summary view. Source of truth for "who used the gateway, how much, at what cost."
OpenAI-compatible passthrough. Headers: X-User-ID, Authorization: Bearer sk-…, CF-Connecting-IP. Hits rate-limit → log → upstream-fetch → log-response.
Liveness probe. Returns {"status":"ok","gateway":"organized-gateway"}. Used by post-deploy smoke tests + uptime monitors.
Organized Codebase shell + pre-wired .claude/agents/project-agent.json + .env.example + setup.sh. Hosted on R2 (not iCloud — file IDs would shift). Distributed via QR code at HICAM.
Per-user per-minute counter. Value = integer. TTL 120 s so old buckets auto-evict. Hard cap 50 req/min; over → HTTP 429.
Trainee's Codex OAuth token, written at onboarding. Worker resolves it on each request and forwards as X-Codex-Token. Refresh-on-401 path TBD.
Customer tier (tier1 | tier2 | tier3). Written by Stripe webhook on checkout.session.completed. Read on every request to enforce monthly cap.
Append-only log. Columns: id, user_id, endpoint, status, latency_ms, tokens_est, ip_hash, created_at. Indexes on user_id + created_at.
Aggregates requests by user_id: total_requests, total_tokens, avg_latency, last_seen. Powers post-event review + upgrade-path emails.
Per-customer per-month counter. Reset on the 1st by a CF Cron Worker. ExoClaw checks against the customer's tier cap; over → HTTP 402.
Inserts one row into requests. Called twice per request — once on rate-limit reject, once on upstream response. Failure mode: silent — D1 errors don't break the proxy.
Reads rate:{userId}:{minute}, increments if < 50, returns boolean. Race-condition tolerant via TTL — counter resets every minute.
SHA-256 over the CF-Connecting-IP; returns first 8 hex chars. Stored in requests.ip_hash for analytics without retaining raw IPs.
Main proxy route. Hono pattern. Sequence: extract → rate-check → log → upstream-fetch → estimate-tokens → log → return. Pass-through preserves OpenAI-compat for client SDKs.
Workshop launch. Trainees bring their own sk-… key in Authorization header; Worker pass-through to OpenClaw → OpenAI. Cost lands on the trainee. Auth Worker setting: AUTH_MODE=openai.
Before the next event. AUTH_MODE=codex. Trainees log in with Anthropic Codex ($20/mo); OAuth token stored in oauth:{user_id}. No sk- in .env; cleaner repos.
Stripe-driven SaaS. Per-tier rate limits + monthly quotas. Compute scales by customer count from M4 Mini → Hetzner AX41 → AX52 → multi-node Tailscale cluster.
Lowest friction. Nothing changes in .env. Stripe link → tier in KV → access continues. For non-technical execs who just want it to work.
Tauri v2 desktop app. Spins up local OpenClaw at localhost:18789. .env changes one line: OPENCLAW_GATEWAY_URL=http://localhost:18789. Codex OAuth handles auth.
Fork organized-gateway as a customer's own ExoClaw on their CF account. Optionally extend into ephemeral Workers, auto-doc generation, and ACP-driven invocation. Zero dependency on Jordan.
Public CF Worker fronting a Tailscale-private origin. Cloudflare's edge does TLS, WAF, rate limiting; the origin stays unreachable from the public internet. Same pattern as Tunnel-fronted home labs but with logic at the edge.
"Bring Your Own Key." Trainee's sk-… rides the Authorization header through the Worker to OpenClaw to OpenAI. Cost lands on the trainee, not Jordan. Phase 1 only.
Anthropic's $20/mo Codex plan grants an OAuth refresh token via claude auth login. Stored in KV under oauth:{user_id}; Worker forwards as X-Codex-Token. Phase 2 onward.
Per-user 50 req/min, hard cap, no burst. Window is a single minute key in KV with TTL 120 s. Anonymous traffic falls in a shared bucket — incentivizes setting USER_ID.
Raw CF-Connecting-IP never lands in D1. SHA-256 → first 8 hex chars → ip_hash. Enough for "is this the same person across requests" without retaining IPs.
50 attendees × 50 req/min × ~8 hours ≈ ~1.2 M log rows worst case. M4 Mini holds rate-limited burst at ~8 GB. Hetzner CX41 ($18/mo) provisioned only if pre-event 50-concurrent stress fails.
Problem Solved!: OpenClaw Workshop. 6201 Quinn Luke Trail, Austin TX 78724. $100 suggested / $20 minimum, token-gated. Different network from claws-mac-mini → ExoClaw is the bridge.
Project root config for the Worker. Declares name, main, KV binding (GATEWAY_KV), D1 binding (DB), env vars. Account ID 691fe25d377abac03627d6a88d3eeac9.
Three lines. OPENCLAW_GATEWAY_URL, OPENAI_API_KEY (Phase 1) or unset (Phase 2), USER_ID. Pre-baked into the boilerplate ZIP.
Stable per-trainee identifier (firstname-lastname). Header X-User-ID derives from it. Pre-assigned and baked into .env.example before the event so attendees never set it themselves.
Worker-side secret. Tailscale bridge URL or Cloudflare Tunnel URL pointing at OpenClaw :18789 on claws-mac-mini. Set with wrangler secret put OPENCLAW_URL.
"openai" for Phase 1, "codex" for Phase 2. Worker branches on this to either pass through Authorization or resolve oauth:{user_id} from KV.
3-step onboarding script. Validates .env, hits /health, makes a single test request to /v1/chat/completions, prints "Agent ready." Total runtime < 30 s.
Three commands: bootstrap.sh (KV + D1 + migrations), wrangler secret put (×2), wrangler deploy. Smoke-test with curl /health + a synthetic /v1/* request.
Tauri v2 desktop client for OpenClaw Gateway. Path B's anchor — local OpenClaw at localhost:18789, no CF dashboard round-trips.
DuraClaw fork with ephemeral one-time-use Workers + auto-doc generation. Path C's destination for builders who want their own stack.
JSON-RPC 2.0 standard for editor↔agent. Lets any ACP-compliant client (Zed, VSCode, acpx, ClawBox) drive a gateway-fronted agent through one protocol.
Cloudflare's deploy tool. Deploys the Worker, manages KV + D1, sets secrets. The operational mouth of the system.
The boilerplate template used in the trainee ZIP. Includes CLAUDE.md, .claude/, PLANNING/, and the Boris/Ralphy/GSD methodology hooks.
Narrative walkthrough — what / why / architecture / phases / deploy / pitfalls. Read alongside this wiki.
Tighter pair focused on just the CF Worker as a deliverable — deploy runbook, request flow, code shape, KV/D1 details. For someone running just the Worker without context on Phases or paths.