TokensPLS - HopGPT API Bridge

A complete pipeline that turns JHU’s HopGPT web interface into a fully programmable OpenAI-compatible API. Any tool that speaks the OpenAI protocol — IDEs, agents, chatbots, scripts — can use university-provided AI models with zero API keys and zero cost. The system spans browser automation, API translation, token management, image upload, and multi-client integration.

The Stack

┌─────────────┐
│  OpenClaw   │──┐
│  (Agents)   │  │
├─────────────┤  │     ┌─────────────────┐      ┌──────────────────┐      ┌─────────────┐
│  Claude     │──┼────►│  FastAPI Server │─────►│  Browser Service │─────►│   HopGPT    │
│  Code       │  │ HTTP│  (Port 8000)    │  ZMQ │  (Playwright)    │ CDP  │ (JHU's AI)  │
├─────────────┤  │     └─────────────────┘      └──────────────────┘      └─────────────┘
│  Any OpenAI │──┘
│  Client     │
└─────────────┘

Supported Models

12 models across 4 providers, all verified working:

Components

1. Browser Service (Playwright Daemon)

• Persistent Chromium instance with stealth settings to avoid automation detection
• Automated Microsoft SSO login flow (email, password, MFA, session persistence)
• Chrome DevTools Protocol (CDP) network interception for real-time token capture
• ZeroMQ IPC server for communication with the API layer
• Automatic session recovery when authentication expires
• Image upload to HopGPT’s file storage via /api/files/images

2. FastAPI API Server

• Full OpenAI-compatible /v1/chat/completions and /v1/models endpoints
• Two-step API flow: POST to start conversation, poll /api/messages/ for results (adapted to HopGPT v2.3.0 API changes)
• Automatic model routing based on model family:
  • Claude models → /api/agents/chat/AnthropicClaude
  • GPT/O3 models → /api/agents/chat/AzureOpenAI
  • Llama models → /api/agents/chat/MetaLlama
• Per-model context window enforcement with proper overflow errors
• System prompt passthrough (formatted as instructions prefix)
• Tool/function calling support via prompt simulation
• Legacy model aliasing (gpt-4o → gpt-4.1, gpt-3.5-turbo → gpt-5-mini)
• Retry logic with automatic token refresh on 401 errors

3. Vision / Image Support

• Accepts base64 images via the standard OpenAI image_url content format
• Automatically uploads images to HopGPT’s file storage (FormData with file_id, endpoint, dimensions)
• Attaches uploaded file references to the chat message payload
• Works across all vision-capable models (GPT, Claude, Llama 4)
• Tested: models correctly describe image content end-to-end

4. Token Management System

• CDP’s Network.requestWillBeSent event captures Authorization headers passively
• No cookie parsing or localStorage manipulation needed
• Detects null/invalid tokens and triggers refresh automatically
• Token refresh via UI automation: navigates to new chat, sends test message, captures fresh token from the authenticated request

5. OpenClaw / Multi-Client Integration

• OpenClaw agent framework configured via sams.json with all 12 models
• Model aliases for quick switching (opus, sonnet, gpt5, o3, llama4, etc.)
• Per-model metadata: context windows, max output tokens, reasoning capability, vision support
• Works with any OpenAI-compatible client: Claude Code, Cursor, Continue, custom scripts

Setup & Infrastructure

• Makefile for full service orchestration (make start, make stop, make status, make nuke)
• Daily auto-restart via launchd at 8 AM to keep sessions fresh
• PostgreSQL for conversation persistence (SQLite fallback)
• Docker Compose for database provisioning
• Environment configuration for credentials and model defaults

Technical Highlights

• Zero API Keys Required: Uses existing university authentication - if you can log into HopGPT in a browser, this works
• Transparent Proxying: Any OpenAI-compatible tool has no idea it’s talking to a browser automation layer
• Vision Support: Send images via standard base64 data URIs, get descriptions back - full multimodal pipeline
• Adaptive to API Changes: When HopGPT v2.3.0 switched from direct SSE to a two-step streaming model, the proxy adapted by intercepting the UI’s network traffic to reverse-engineer the new flow
• Graceful Degradation: Token expiration, network issues, and session timeouts are handled automatically with retry logic
• Model Agnostic: Same interface works for Claude, GPT, O3, and Llama models across 4 providers

Outcome

Full programmable access to 12 university-provided AI models. Write code with Claude Opus, run agents with GPT-5, analyze images with Llama 4 Maverick — all through standard APIs, all running through JHU infrastructure. No API keys, no usage limits beyond what HopGPT allows, no cost.

Repo Link

Private (university credentials required)