CliRelay
Wrap Gemini CLI, Antigravity, ChatGPT Codex, Claude Code, Qwen Code, iFlow as an OpenAI/Gemini/Claude/Codex compatible API service, allowing you to enjoy the free Gemini 2.5 Pro, GPT 5, Claude, Qwen model through API
Install / Use
/learn @kittors/CliRelayQuality Score
Category
Development & EngineeringSupported Platforms
README
⚡ What is CliRelay?
✨ Heavily enhanced fork of the CLIProxyAPI project — rebuilt with a production-grade management layer, web control panel hosting, and a terminal TUI for day-2 operations.
CliRelay lets you proxy requests from AI coding tools and compatible API clients (Claude Code, Gemini CLI, OpenAI Codex, Amp CLI, OpenAI-compatible clients, etc.) through a single unified endpoint. Authenticate with OAuth, API keys, cookies, or a mix of them, and CliRelay handles routing, failover, usage logging, /manage web hosting, and terminal management workflows automatically.
┌───────────────────────┐ ┌──────────────┐ ┌────────────────────┐
│ AI Coding Tools │ │ │ │ Upstream Providers │
│ │ │ │ ──────▶ │ Google Gemini │
│ Claude Code │ ──────▶ │ CliRelay │ ──────▶ │ OpenAI / Codex │
│ Gemini CLI │ │ :8317 │ ──────▶ │ Anthropic Claude │
│ OpenAI Codex │ │ │ ──────▶ │ Qwen / iFlow │
│ Amp CLI / IDE │ │ │ ──────▶ │ Antigravity │
│ Any OAI-compatible │ └──────────────┘ │ Vertex / OpenAI │
└───────────────────────┘ │ iFlow / Qwen / │
│ Kimi / Claude │
└────────────────────┘
✨ Key Features
🔌 Multi-Provider Proxy Engine
| Feature | Description |
|:--------|:------------|
| 🌐 Unified Endpoint | One http://localhost:8317 fronts Gemini, Claude, Codex, Qwen, iFlow, Antigravity, Vertex-compatible endpoints, OpenAI-compatible upstreams, and Amp integration |
| ⚖️ Smart Load Balancing | Round-robin or fill-first scheduling across multiple API keys for the same provider |
| 🔄 Auto Failover | Automatically switches to backup channels when quotas are exhausted or errors occur |
| 🧠 Multimodal Support | Full support for text + image inputs, function calling (tools), and streaming SSE responses |
| 🔗 OpenAI-Compatible | Works with any upstream that speaks the OpenAI Chat Completions protocol |
📊 Request Logging & Monitoring (SQLite)
| Feature | Description |
|:--------|:------------|
| 📝 Full Request Capture | Every API request is logged to SQLite with timestamp, model, tokens (in/out/reasoning/cache), latency, status, and source channel |
| 💬 Message Body Storage | Full request/response message content captured in compressed SQLite storage, with separate retention for content vs. metadata |
| 🔍 Advanced Querying | Filter logs by API Key, model, status, time range with efficient pagination (LIMIT/OFFSET) |
| 📈 Analytics Aggregation | Pre-computed dashboards: daily trends, model distribution, hourly heatmaps, per-key statistics |
| 🏥 Health Score Engine | Real-time 0–100 health score considering success rate, latency, active channels, and error patterns |
| 📡 WebSocket Monitoring | Live system stats streamed via WebSocket: CPU, memory, goroutines, network I/O, DB size |
| 🗄️ No-CGO SQLite | Uses modernc.org/sqlite — pure Go, no CGO dependency, easy cross-compilation |
🔐 API Key & Access Management
| Feature | Description |
|:--------|:------------|
| 🔑 API Key CRUD | Create, edit, delete API keys via Management API — each with custom name, notes, and independent enable/disable toggle |
| 📊 Per-Key Quotas | Set max token / request quotas per key with automatic enforcement |
| ⏱️ Rate Limiting | Per-key rate limiting (requests per minute/hour) |
| 🔒 Key Masking | API keys are always displayed masked (sk-***xxx) in UI and logs |
| 🌍 Public Lookup Page | End users can query their own usage stats and request logs via a public self-service page (no login required) |
🔗 Provider Channel Management
| Feature | Description |
|:--------|:------------|
| 📋 Multi-Tab Config | Manage channels organized by provider type: Gemini, Claude, Codex, Vertex, OpenAI Compatible, Ampcode |
| 🏷️ Channel Naming | Each channel can have a custom name, notes, proxy URL, custom headers, and model alias mappings |
| ⏱️ Latency Tracking | Average latency (latency_ms) tracked per channel with visual indicators |
| 🔄 Enable/Disable | Individually toggle channels on/off without deletion |
| 🚫 Model Exclusions | Exclude specific models from a channel (e.g., block expensive models on backup keys) |
| 📊 Channel Stats | Per-channel success/fail counts and model availability displayed on each channel card |
🛡️ Security & Authentication
| Feature | Description | |:--------|:------------| | 🔐 OAuth Support | Native OAuth flows for Gemini, Claude, Codex, Qwen, iFlow, Antigravity, and Kimi, plus device/browser/cookie variants where supported | | 🔒 TLS Handling | Configurable TLS settings for upstream communication | | 🏠 Panel Isolation | Management panel access controlled independently with admin password | | 🛡️ Request Cloaking | Upstream requests are stripped of client-identifying headers for privacy |
🗄️ Data Persistence
| Feature | Description | |:--------|:------------| | 💾 SQLite Storage | All usage data, request logs, and message bodies stored in local SQLite database | | 🔄 Redis Backup | Optional Redis integration for periodic snapshotting and cross-restart metric preservation | | 🗃️ Pluggable Auth/Config Backends | Local files by default, with optional PostgreSQL, Git, or S3-compatible object storage backends for config/auth persistence | | 📦 Config Snapshots | Import/export entire system configuration as JSON for backup and migration |
📸 Management Panel Preview
CliRelay can expose a built-in web control panel at /manage. The server can host bundled SPA assets or fall back to synced management assets from the configured panel repository.
The latest panel walkthrough below covers all 13 core screens now shipped in the management workflow.
| Screen | What operators can do there | | :----- | :-------------------------- | | Dashboard Overview | Review KPIs, health score, system status, resource usage, throughput, and channel latency | | Monitor Center | Analyze model distribution, daily trends, API Key usage share, and time-range summaries | | Request Logs | Filter and inspect requests by time range, key, model, channel, and status | | Request Details | Read formatted prompt/response bodies with Markdown rendering and collapsible blocks | | AI Providers | Manage provider tabs, channel health, model coverage, and CRUD operations | | Auth Files | Inspect stored auth files, rename channels, configure prefixes/proxies, and download credentials | | OAuth Login | Start provider authorization and submit remote callback URLs | | API Keys | Control key quotas, RPM/TPM, allowed models, channel bindings, and shortcuts | | Model Pricing | Maintain quota-cost pricing for input, output, and cache dimensions | | Quota | Review remaining refresh time and quota progress across provider families | | Config | Edit source YAML, search config, and switch runtime/config views | | System | Inspect base URLs, versions, lookup links, and discovered model inventory | | Logs | Stream runtime logs with search, download, clear, and visibility toggles |
