https://github.com/lansespirit/clipal
Minimal LLM API reverse proxy for Claude Code, Codex CLI & Gemini CLI — YAML routing, hot reload, and automatic provider failover. 极简 LLM API 反向代理：面向 Claude Code / Codex CLI / Gemini CLI，支持 YAML 配置、多上游优先级与自动故障转移。
https://github.com/lansespirit/clipal
api-gateway api-proxy claude-code codex gemini gemini-cli llm proxy-server reverse-proxy
Last synced: 11 days ago
JSON representation
Minimal LLM API reverse proxy for Claude Code, Codex CLI & Gemini CLI — YAML routing, hot reload, and automatic provider failover. 极简 LLM API 反向代理：面向 Claude Code / Codex CLI / Gemini CLI，支持 YAML 配置、多上游优先级与自动故障转移。
- Host: GitHub
- URL: https://github.com/lansespirit/clipal
- Owner: lansespirit
- Created: 2025-12-22T05:17:05.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T14:51:59.000Z (15 days ago)
- Last Synced: 2026-04-03T01:42:44.657Z (14 days ago)
- Topics: api-gateway, api-proxy, claude-code, codex, gemini, gemini-cli, llm, proxy-server, reverse-proxy
- Language: Go
- Homepage:
- Size: 12.3 MB
- Stars: 70
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# Clipal
---
**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 code below to join the Clipal WeChat group and discuss usage, setup, and feedback with other users.
## ✨ 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 **Claude Code, Codex CLI, OpenCode, Gemini CLI, Continue, Aider**, and **Goose**.
- 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.
### 🎛️ **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.
### ⚡ **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:** Claude Code, Codex CLI, OpenCode, Gemini CLI, Continue, Aider, Goose
- **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:
```text
Please help me install and start Clipal. Project: https://github.com/lansespirit/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/lansespirit/Clipal/releases
- Getting Started: https://github.com/lansespirit/Clipal/blob/main/docs/en/getting-started.md
- Web UI: https://github.com/lansespirit/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
Download the standalone binary for your OS from [Releases](https://github.com/lansespirit/Clipal/releases) and put it on your `PATH`.
Latest stable release: [GitHub Releases latest](https://github.com/lansespirit/Clipal/releases/latest)
```bash
chmod +x clipal*
./clipal* --version
```
### 2. Initialize Configurations
```bash
mkdir -p ~/.clipal
cp examples/config.yaml ~/.clipal/config.yaml
cp examples/claude.yaml ~/.clipal/claude.yaml
cp examples/openai.yaml ~/.clipal/openai.yaml
cp examples/gemini.yaml ~/.clipal/gemini.yaml
```
*Edit the generated `~/.clipal/*.yaml` files to add your API keys.*
### 3. Run & Manage
Start Clipal in the foreground:
```bash
clipal
```
Or install it as a background service:
```bash
clipal service install
clipal service start
```
### 4. 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.
---
## 📖 Complete Documentation
Dive deeper into what Clipal can do:
- 🚀 [Getting Started](docs/en/getting-started.md)
- 🔌 [Client Setup Guide](docs/en/client-setup.md)
- ⚙️ [Config Reference](docs/en/config-reference.md)
- 🖥️ [Web UI Guide](docs/en/web-ui.md)
- 🔀 [Routing & Failover Magic](docs/en/routing-and-failover.md)
- 🛠️ [Services, Status, and Updates](docs/en/services.md)
- 📚 [Docs Home](docs/en/README.md) & [Release Notes](release-notes/)
## 🔒 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.
## 📄 License
MIT
## 🙏 Thanks
Thanks to the [linux.do](https://linux.do/) community for its support.
