CLIProxyAPI Plus

面向 AI 编程工具的轻量级智能网关：支持 Claude Code、Codex、Gemini CLI、Antigravity、Kimi、OpenAI 兼容客户端等。

简体中文 | English

CLIProxyAPI Plus 是基于 CLIProxyAPI 的社区增强版。它保留原项目的多供应商代理能力、OpenAI 兼容接口、管理 API 与轻量部署方式，同时针对 Codex 多账号池增加了更适合日常运营的配额能力。

核心增强：

• Codex 配额卡片显示套餐、余额、5 小时额度、周额度和恢复窗口。
• 认证文件卡片在健康状态下方直接显示剩余配额。
• 认证文件配额下方显示总 Token、缓存 Token、输入 Token、输出 Token 和按 OpenAI 标价折算的预估美元花费。
• 认证文件列表支持按 Codex 周额度剩余排序，高额度账号排前面。
• Codex 返回 usage_limit_reached 后可自动持久停用该认证文件。
• Codex 周额度低于指定阈值时可提前停用，例如剩余 3% 或 5% 即停止使用。
• OAuth 登录等待时间更长，远程 VPS 浏览器登录更友好。

推荐部署方式仍然是最省资源的方式：下载一个二进制文件，用 systemd 跑起来，然后通过单文件管理面板操作。Docker 和源码构建仍然保留，方便不同用户选择。

项目结构

Plus 版按一个仓库发布，用户只需要关注一个项目：根目录是后端，management-center/ 是管理面板源码。Release 会同时提供多平台二进制和 management.html。

路径	作用
/	Go 后端、网关、Management API、二进制 release、可选 Docker 镜像
management-center/	React 管理面板，release 为单文件 management.html

默认面板更新源会指向本仓库的最新 Release。如果你发布自己的面板，也可以改成自己的仓库：

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

为什么需要 Plus 版

Codex 多账号池最麻烦的不是能不能跑，而是能不能清楚知道哪个账号还剩多少额度，以及低额度账号是否会继续被请求命中。CLIProxyAPI Plus 解决的是运营体验：

• 高额度账号一眼可见，并且能排序靠前。
• 每个账号实际跑过多少 Token、缓存命中多少、理论 API 成本多少，可以直接在卡片里看到。
• 低额度账号可以在达到阈值后自动停用。
• 真正触发 usage_limit_reached 的账号可以自动持久停用。
• 已停用账号会尽量显示预计恢复时间。
• 保持二进制部署方式，不强依赖 Docker，不引入额外数据库。

功能概览

网关能力

• 提供 OpenAI 兼容接口，适配常见 Chat Completions / Responses 客户端。
• 支持 Claude、Codex、Gemini、Gemini CLI、Antigravity、Kimi、Vertex、Qwen、OpenAI 兼容上游等。
• 多认证文件池，支持优先级、前缀路由、重试、回退和自动刷新。
• Management API 支持配置、认证文件、OAuth 登录、额度检测、日志、模型信息等。
• 可选请求日志、Redis 兼容使用队列和运行状态统计。

Codex 配额增强

• 显示 Free、Plus、Pro、Team、Pro Lite 等套餐信息。
• 显示 Codex 余额和本地/云端可用次数估算。
• 显示 5 小时和周额度窗口，包括剩余百分比、已用百分比、恢复时间和窗口长度。
• 认证文件卡片直接展示剩余额度，不必进入详情页。
• 认证文件卡片展示运行期 Token 明细，Token 数使用 K / M 缩写，预估花费使用美元格式。
• 新增“周限额剩余”排序，高额度账号排在前面。
• 新增 usage_limit_reached 后自动停用。
• 新增按周额度剩余百分比提前停用。

轻量部署

• 单二进制运行，适合小 VPS。
• 基础网关不依赖数据库。
• 不需要 Docker。
• 管理面板是单文件 HTML，通过 /management.html 访问。
• 适合 systemd 托管，运行目录清晰，可控可迁移。

快速开始：二进制 + systemd

这是推荐的小 VPS 部署方式。

1. 创建用户和目录

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. 下载 release

在 GitHub Releases 下载对应系统架构的压缩包。普通 Linux VPS 通常是 linux_amd64。

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

如果实际 release 文件名不同，以 Releases 页面为准，只要最终把 cli-proxy-api 放到：

/opt/cliproxyapi/cli-proxy-api

3. 创建配置

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

最小远程管理配置示例：

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. 安装 systemd 服务

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

打开管理面板：

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

管理密钥就是配置里的 remote-management.secret-key。

Docker 部署

Docker 不是必须的。如果你本来就在用容器，可以这样跑：

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

或使用 Compose：

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

如果你的小 VPS 内存很紧张，优先使用二进制 + systemd。

源码构建

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

运行测试：

go test ./...

管理面板

访问路径：

/management.html

后端会把面板下载到可写静态目录。按推荐 systemd 部署时路径是：

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

如果你想手动固定一个面板文件：

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

如果希望自动从你的面板仓库更新：

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

Codex 自动停用

相关配置：

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

行为说明：

• auto-disable-codex-usage-limit：真实请求返回 usage_limit_reached 后自动停用该 Codex 认证文件。
• auto-disable-codex-weekly-remaining-threshold：管理面板读取配额时，如果主周额度剩余小于等于该百分比，就提前停用。
• 设置为 0 表示关闭提前停用，只保留真实达到周限后的自动停用。
• 停用状态会写回认证文件，并尽量记录预计恢复时间。

建议值：

账号池规模	建议阈值
1 到 3 个账号	0 或 3
4 到 20 个账号	3 到 5
大规模轮换池	5 到 10

Token 统计与预估花费

Codex 认证文件卡片会在配额条下方显示：

• 总 Token、缓存 Token、输入 Token、输出 Token。
• 按 OpenAI API 公开标价折算的预估美元花费。
• Token 数会自动显示为 K / M，方便快速比较账号使用情况。

注意事项：

• 这部分是运行期内存统计，只统计 CPA 代理后收到的真实请求 usage，不是完整历史账单。
• 服务重启后统计会清零；旧请求不会从日志或认证文件里补算。
• 预估花费是 API 标价下的理论成本，用于横向比较账号消耗；Free / Plus / Pro 账号是否真实扣费，以 OpenAI 官方账单和套餐规则为准。
• 如果请求模型没有匹配到内置 OpenAI 价格表，页面会用 + 标记，表示金额只包含已识别价格的请求。

安全与脱敏

不要提交运行时凭据。

仓库默认忽略：

• config.yaml
• .env
• auths/
• logs/
• static/
• 生成的二进制文件
• 编辑器和 AI Agent 本地元数据

发布前建议扫描：

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

如果管理面板暴露到公网，请使用强管理密钥，并放在 HTTPS 反代后面。

Release

打 tag 会触发 GoReleaser 构建多平台二进制：

git tag v0.1.0
git push origin v0.1.0

Release 包含：

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

Docker workflow 可选发布到 GitHub Container Registry。

致谢

本项目基于 router-for-me/CLIProxyAPI 的优秀工作。CLIProxyAPI Plus 是独立社区增强版，重点改进 Codex 配额可视化、账号池自动停用和轻量 VPS 部署体验。

License

MIT。见 LICENSE。