Clipal
Your Ultimate Local LLM API Gateway & Manager
English | 中文
Clipal is the local LLM API proxy built for developer productivity. If you use AI coding tools like Claude Code, Continue, Aider, or Cherry Studio, Clipal acts as your intelligent traffic controller. It consolidates multiple model providers, handles automatic failover, manages API keys, and offers a beautiful Web UI—so you can focus on coding, not configuring.
Join the WeChat Group
Scan the QR codes below to join the Clipal WeChat group or contact the author.
WeChat Group
|
Author WeChat
|
✨ Why Clipal?
🚀 One-Click CLI Takeover
No more hunting for hidden config files. With a single click in the Web UI, Clipal can automatically take over the configurations for 18 clients, including Claude Code, Codex CLI, OpenCode, Antigravity CLI, Pi, Qwen Code, Kimi Code, Copilot CLI, Grok Build and DeepSeek Harness. See the complete takeover catalog and limits.
- It configures the local base URL for you.
- It backs up your original settings.
- It provides a safe rollback whenever you want.
🛡️ Bulletproof Failover & Multi-Key Rotation
Tired of hitting rate limits or empty balances mid-generation?
- Multi-Key Pool: Configure multiple
.api_keys for a single provider. Clipal rotates them automatically and retries locally before giving up.
- Priority Failover: Fall back to secondary models or providers instantly with out-of-the-box circuit breaking and quota management.
- OAuth Upstreams: Authorize Codex, Claude, and Antigravity-backed Google accounts from the Web UI. They participate in the same ordering, pinning, enable/disable, and failover flow as API-key providers, and Clipal refreshes access tokens automatically when a refresh token is available. Antigravity OAuth supports Gemini-compatible text, streaming, token counting, model listing, and Gemini image models through
generateContent; Imagen/Veo predict* endpoints remain on Google AI Studio API-key or Vertex routes. Claude and Codex OAuth requests use Agent SDK-compatible wrapping by default for ordinary clients, with required transport fields handled by Clipal. Explicit request fields such as tools, thinking/reasoning, and output controls take precedence over Clipal defaults when supported by the target model.
OAuth account request preferences default to US / America/New_York when adding an account, with editable country/timezone and default/user provenance. Imports preserve settings; unverified legacy regions require confirmation. Standard HTTP/HTTPS/SOCKS5 proxy interfaces retain domains; inherited routing reads environment and OS proxy settings without software discovery or network changes. Automatic DNS delegates target resolution to standard proxies; routes without a proxy try Cloudflare → Google DoH first, then the system hostname route on lookup or connection failure. Public DoH through a proxy is an opt-in, non-blocking reference diagnostic. See Web UI.
🎛️ Beautiful Local Web UI
Manage your AI workflows visually. Add, edit, enable, or disable providers, pin a specific model, and manage global settings with a modern dashboard. All changes are hot-reloaded—no restarts required.
Usage costs prefer upstream-reported values and otherwise use an offline, embedded snapshot of PAIArtCom/model-specs. Model prices are matched exactly, including cache and long-context tiers; catalog updates never retroactively reprice stored history. See Usage Cost Calculation.
Provider management |
CLI takeover |
Settings |
Status dashboard |
⚡ Frictionless Background Service
Clipal runs as a single, cross-platform binary on macOS, Linux, and Windows.
Type clipal service install and clipal service start to keep it running silently in the background forever. Use clipal status or clipal restart for quick management.
🔌 Supported Clients
Clipal standardizes client ingress entirely on a single local route: http://127.0.0.1:3333/clipal.
It natively supports the request flavors of:
- Anthropic / Claude
- OpenAI / Codex
- Google Gemini
Popular Supported Tools:
- AI Coding Assistants: 18 CLI integrations, with explicit configuration and rollback boundaries
- Desktop Chat Clients: Cherry Studio, Kelivo, Chatbox, ChatWise (via OpenAI compatibility)
⚡ Quick Start
Let Your AI Install It
If you use a terminal-capable AI such as Claude Code or Codex CLI, you can send it the prompt below:
Please help me install and start Clipal. Project: https://github.com/PAIArtCom/Clipal
Please detect my current OS and architecture, check the project's Releases and docs, and complete the download, installation, and startup for me. Then confirm that I can open the Web UI successfully. Use these official links when needed:
- Releases: https://github.com/PAIArtCom/Clipal/releases
- Getting Started: https://github.com/PAIArtCom/Clipal/blob/main/docs/en/getting-started.md
- Web UI: https://github.com/PAIArtCom/Clipal/blob/main/docs/en/web-ui.md
After that, guide me through using the Web UI to enable CLI takeover and add my first provider.
1. Install Clipal
The fastest way is npm:
npm install -g clipal
clipal --version
If you use npm 12 or newer, no extra flags are needed: current Clipal npm packages use platform-specific optional dependencies instead of install scripts. If your npm configuration skips optional dependencies, use npm install -g clipal --include=optional.
Older Clipal npm versions used a postinstall download. If you are installing one of those versions with npm 12+, use npm install -g clipal --allow-scripts=clipal.
Prefer not to use npm? Install the standalone binary with the official script:
curl -fsSL https://clipal.paiart.com/install.sh | sh
On Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://clipal.paiart.com/install.ps1 | iex"
The installer detects your platform, downloads the matching release asset, verifies it against checksums.txt, and installs to ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\clipal). Set CLIPAL_INSTALL_DIR to choose another directory, or CLIPAL_VERSION to pin a release.
For a mirror, set CLIPAL_DOWNLOAD_BASE_URL; preview the Unix install with --dry-run before downloading.
You can also download the right build from Releases and put it on your PATH.
Latest stable release: GitHub Releases latest
chmod +x clipal*
./clipal* --version
2. Run & Manage
Start Clipal in the foreground:
clipal
Or install it as a background service:
clipal service install
clipal service start
3. Open the Web UI
Visit http://127.0.0.1:3333/ in your browser to manage providers and apply CLI Takeover for your favorite tools. You can add providers directly in the Web UI; no manual config-file bootstrap is required.
📖 Complete Documentation
Dive deeper into what Clipal can do:
🔒 Security & Privacy
- Clipal is fully local. The proxy listens on
127.0.0.1:3333 by default.
- The Web UI is strictly locked to localhost—even if the proxy listens externally, the management UI rejects non-loopback requests.
- Your upstream API keys are stored only on your machine and transparently injected into requests.
- OAuth credentials are stored only on your machine under
~/.clipal/oauth/, separate from YAML provider files.
📄 License
MIT
🙏 Thanks
Thanks to the linux.do community for its support.
评论