Skip to content

README_EN.md

Latest commit

 

History

History
340 lines (249 loc) · 11.7 KB

README_EN.md

File metadata and controls

340 lines (249 loc) · 11.7 KB

CLIProxyAPI Plus

A lightweight, quota-aware AI coding gateway for Claude Code, Codex, Gemini CLI, Antigravity, Kimi, OpenAI-compatible clients, and more.

License Go Deploy Panel

简体中文 | English

CLIProxyAPI Plus is a community enhanced build of CLIProxyAPI. It keeps the original project's broad provider compatibility and OpenAI-compatible gateway behavior, then adds a more operator-friendly Codex quota workflow:

  • Codex quota cards show plan, balance, 5-hour usage, weekly usage, and reset windows.
  • Auth-file cards show remaining quota directly under health status.
  • Auth-file cards show total, cached, input, and output tokens plus API cost equivalent and estimated total capacity.
  • Auth files can be sorted by Codex weekly quota remaining, high capacity first.
  • Codex accounts can be automatically disabled after usage_limit_reached.
  • Codex accounts can also be stopped early when weekly quota remaining is at or below a configurable threshold such as 3% or 5%.
  • OAuth callback waiting is longer, which is friendlier for real browser login flows on remote servers.

The recommended deployment is still the smallest one: download one binary, run it with systemd, and manage it from the single-file web panel. Docker and source builds remain available for users who prefer them.

Project Layout

This release is published as one repository so users have one place to read docs, download binaries, and fetch the panel asset. The backend remains at the repository root, and the management panel source lives in management-center/.

Path Purpose
/ Go backend, gateway, Management API, binary releases, optional Docker image
management-center/ React management panel, released as a single management.html file

The default panel update source points to this repository's latest Release. You can override it if you host your own build.

remote-management:
  disable-control-panel: false
  disable-auto-update-panel: false
  panel-github-repository: "https://github.com/ztx888/CLIProxyAPI-Plus"

Why This Build

Large account pools are tedious to operate manually. A single exhausted Codex credential can keep getting retried, burn refresh attempts, and hide the accounts that still have useful weekly capacity. CLIProxyAPI Plus makes the quota state visible and actionable:

  • Use high-quota accounts first by sorting on weekly remaining quota.
  • See how many tokens each account has actually carried, how much was cached, the API cost equivalent, and the estimated total capacity.
  • Let low-quota accounts disable themselves before they hit the wall.
  • Keep disabled accounts annotated with expected recovery time.
  • Keep the no-Docker, low-memory binary deployment path clean.

Features

Gateway

  • OpenAI-compatible API surface for common chat and responses clients.
  • Provider routing across Claude, Codex, Gemini, Gemini CLI, Antigravity, Kimi, Vertex, Qwen, OpenAI-compatible upstreams, and more.
  • Multiple credentials per provider with priority, prefix routing, retry, and fallback behavior.
  • Management API for configuration, auth files, OAuth login, quota checks, logs, and model metadata.
  • Optional Redis-compatible usage queue and request logging.

Codex Quota Intelligence

  • Shows plan labels such as Free, Plus, Pro, Team, and Pro Lite where available.
  • Shows Codex balance and approximate local/cloud message capacity when returned by the upstream API.
  • Shows 5-hour and weekly windows with remaining percent, used percent, reset label, and window duration.
  • Shows per-auth remaining quota directly on the auth-file grid.
  • Shows runtime token totals per auth file, with K / M units and cost equivalent / estimated total formatted in USD.
  • Adds Weekly quota left sorting to put high-capacity Codex accounts first.
  • Adds persistent auto-disable when Codex returns usage_limit_reached.
  • Adds early auto-disable threshold by weekly remaining percentage.

Lightweight Operations

  • Single static binary for Linux, macOS, Windows, and FreeBSD on amd64/arm64.
  • No database required for the basic gateway.
  • No Docker required.
  • Single-file management panel served at /management.html.
  • systemd friendly config and writable data directories.

Quick Start: Binary + systemd

This is the recommended VPS deployment.

1. Create directories and user

sudo useradd --system --create-home --home-dir /var/lib/cliproxyapi --shell /usr/sbin/nologin cliproxyapi
sudo install -d -o cliproxyapi -g cliproxyapi /opt/cliproxyapi /etc/cliproxyapi /var/lib/cliproxyapi /var/log/cliproxyapi

2. Download a release

Download the archive that matches your server from GitHub Releases. Linux amd64 is the common VPS target.

export CPA_REPO="ztx888/CLIProxyAPI-Plus"
export CPA_VERSION="v0.1.0"
curl -fL "https://github.com/${CPA_REPO}/releases/download/${CPA_VERSION}/CLIProxyAPI-Plus_${CPA_VERSION}_linux_amd64.tar.gz" -o /tmp/cliproxyapi.tar.gz
sudo tar -xzf /tmp/cliproxyapi.tar.gz -C /opt/cliproxyapi
sudo chmod +x /opt/cliproxyapi/cli-proxy-api

If your release archive name differs, download it from the Releases page and place the cli-proxy-api binary at /opt/cliproxyapi/cli-proxy-api.

3. Create config

sudo cp /opt/cliproxyapi/config.example.yaml /etc/cliproxyapi/config.yaml
sudo chown -R cliproxyapi:cliproxyapi /etc/cliproxyapi /var/lib/cliproxyapi /var/log/cliproxyapi
sudo chmod 750 /etc/cliproxyapi /var/lib/cliproxyapi
sudo chmod 640 /etc/cliproxyapi/config.yaml

Minimum remote-management settings:

port: 8317
allow-remote-management: true

remote-management:
  disable-control-panel: false
  disable-auto-update-panel: false
  panel-github-repository: "https://github.com/ztx888/CLIProxyAPI-Plus"
  secret-key: "change-this-management-key"

quota-exceeded:
  switch-project: true
  switch-preview-model: true
  antigravity-credits: true
  auto-disable-codex-usage-limit: true
  auto-disable-codex-weekly-remaining-threshold: 5

4. Install service

sudo tee /etc/systemd/system/cliproxyapi.service >/dev/null <<'EOF'
[Unit]
Description=CLIProxyAPI Plus
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=cliproxyapi
Group=cliproxyapi
WorkingDirectory=/opt/cliproxyapi
Environment=HOME=/var/lib/cliproxyapi
Environment=WRITABLE_PATH=/var/lib/cliproxyapi
ExecStart=/opt/cliproxyapi/cli-proxy-api -config /etc/cliproxyapi/config.yaml
Restart=always
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=full
ReadWritePaths=/var/lib/cliproxyapi /var/log/cliproxyapi /etc/cliproxyapi
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now cliproxyapi
systemctl status cliproxyapi --no-pager

Open the panel:

http://<server-ip>:8317/management.html

Use your remote-management.secret-key as the management key.

Docker

Docker is optional. It is useful if you already run containerized services.

docker run -d \
  --name cliproxyapi-plus \
  --restart unless-stopped \
  -p 8317:8317 \
  -v "$PWD/config.yaml:/CLIProxyAPI/config.yaml" \
  -v "$PWD/auths:/root/.cli-proxy-api" \
  -v "$PWD/logs:/CLIProxyAPI/logs" \
  ghcr.io/ztx888/cliproxyapi-plus:latest

Or with Compose:

cp config.example.yaml config.yaml
docker compose up -d

For lowest VPS memory overhead, use the binary + systemd path instead.

Build From Source

git clone https://github.com/ztx888/CLIProxyAPI-Plus.git
cd CLIProxyAPI-Plus
go build -ldflags="-s -w" -o bin/cli-proxy-api ./cmd/server
./bin/cli-proxy-api -config config.example.yaml

Run tests:

go test ./...

Management Panel

The panel is served from:

/management.html

The backend stores the downloaded panel at its writable static directory. With the recommended systemd service that is:

/var/lib/cliproxyapi/static/management.html

To pin a custom panel manually:

sudo install -o cliproxyapi -g cliproxyapi -m 0644 management.html /var/lib/cliproxyapi/static/management.html

To allow automatic panel updates from your panel repository:

remote-management:
  disable-auto-update-panel: false
  panel-github-repository: "https://github.com/ztx888/CLIProxyAPI-Plus"

Codex Auto-Disable

Two related settings are available under quota-exceeded:

quota-exceeded:
  auto-disable-codex-usage-limit: true
  auto-disable-codex-weekly-remaining-threshold: 5

Behavior:

  • auto-disable-codex-usage-limit disables a Codex auth file when a real request returns usage_limit_reached.
  • auto-disable-codex-weekly-remaining-threshold disables a Codex auth file during quota inspection when the main weekly remaining quota is at or below that percentage.
  • 0 disables early stopping and keeps only the real usage_limit_reached behavior.
  • Disabled auth files persist to disk and include recovery metadata when available.

Recommended values:

Pool size Suggested threshold
1 to 3 accounts 0 or 3
4 to 20 accounts 3 to 5
Large rotation pool 5 to 10

Token Usage And Cost Equivalent

Codex auth-file cards show:

  • Total tokens, cached tokens, input tokens, and output tokens.
  • Current cost equivalent based on public OpenAI API pricing.
  • Estimated total capacity inferred from current cost equivalent and official weekly used percentage.
  • Compact K / M token units for quick comparison across accounts.

Notes:

  • This only counts real proxied requests that returned usage; it is not a full historical bill.
  • Token totals are persisted in a separate file and are not written into credential JSON files. The default path is WRITABLE_PATH/usage/token_usage_totals.json, falling back to auth-dir/usage/token_usage_totals.json when WRITABLE_PATH is unset.
  • Cost equivalent is an API-pricing-based theoretical value for comparing consumption. Whether Free / Plus / Pro accounts are billed is governed by OpenAI's official billing and plan rules.
  • Estimated total capacity is a trend estimate, not a fixed limit returned by OpenAI; it refines as the sample grows.
  • If a request model does not match the built-in OpenAI price table, the UI marks the amount with +, meaning the number only includes requests with recognized pricing.

Security Notes

Never commit runtime credentials.

The repository intentionally ignores:

  • config.yaml
  • .env
  • auths/
  • logs/
  • static/
  • generated binaries
  • editor and agent metadata

Before publishing your own fork, run:

git status --short
rg -n "sk-|ghp_|github_pat_|AIza|password|secret-key|BEGIN OPENSSH|BEGIN PRIVATE KEY" -S .

Use a strong management key and place the service behind HTTPS if it is exposed to the internet.

Releases

Tags trigger binary releases through GoReleaser:

git tag v0.1.0
git push origin v0.1.0

Release artifacts cover:

  • Linux amd64/arm64
  • macOS amd64/arm64
  • Windows amd64/arm64
  • FreeBSD amd64/arm64

The Docker workflow publishes an optional image to GitHub Container Registry when enabled.

Credits

This project is based on the excellent upstream work in router-for-me/CLIProxyAPI. CLIProxyAPI Plus is an independent community build focused on quota visibility, safer Codex pool operation, and lightweight VPS deployment.

License

MIT. See LICENSE.