CLIProxyAPI（一）：入门——把 CLI 订阅变成标准 API

这是 CLIProxyAPI 系列教程的第一篇。

系列目录

1. （一）入门——把 CLI 订阅变成标准 API（本文）
2. （二）多账号轮询与配额策略
3. （三）接入主流 AI 编程工具
4. （四）生产部署——Nginx、TLS 与安全加固
5. （五）Antigravity——用 Google 订阅解锁 Claude Opus 4.8
6. （六）结合 new-api 打造多用户 API 网关
7. （七）自动化运维——配额监控与告警
8. （八）cpa_keeper 与 cpa_cost——用量追踪与成本分析工具

什么是 CLIProxyAPI

Claude Code、Gemini CLI、OpenAI Codex 这类 CLI 工具用的是 OAuth 登录——登录你的订阅账号，在配额范围内免费调用模型，不消耗 API Credits。但它们只能在自家 CLI 里用，不能接入 Cursor、Cline 这些第三方工具。

CLIProxyAPI 做的事情：把 OAuth 登录态包装成标准 OpenAI/Claude/Gemini API，任何支持自定义 API 地址的客户端都可以指向它，白嫖订阅配额。

核心优势：

• 一份订阅，多个工具共用；多个账号，自动轮询
• 支持 Claude、Gemini、Codex、Grok、Qwen、Kimi 等多个来源
• 主程序 ~10MB，内存占用 <15MB，轻量到可以跑在 1GB VPS 上
• 开源 MIT，GitHub 36K+ Stars

安装

Linux（推荐：一键脚本）

curl -fsSL https://raw.githubusercontent.com/router-for-me/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash

脚本自动下载最新版二进制、创建 systemd 服务、配置开机自启。安装完成后：

# 查看服务状态
systemctl --user status cliproxyapi

# 配置文件位置
~/.cli-proxy-api/config.yaml

也可以手动下载：

# 从 GitHub Releases 下载（替换为最新版本号和架构）
wget https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/CLIProxyAPI_linux_amd64.tar.gz
tar -xzf CLIProxyAPI_linux_amd64.tar.gz
cd CLIProxyAPI_linux_amd64
cp config.example.yaml config.yaml
./cli-proxy-api

Arch Linux：

yay -S cli-proxy-api-bin
systemctl --user enable --now cli-proxy-api

macOS

brew install cliproxyapi
brew services start cliproxyapi
# 配置文件：$(brew --prefix)/etc/cliproxyapi.conf

Windows

新手推荐 EasyCLI——官方 Tauri GUI，带系统托盘，自动下载并管理 CLIProxyAPI，省去命令行配置。

或者直接从 GitHub Releases 下载 CLIProxyAPI_windows_amd64.zip 手动运行。

Docker

# docker-compose.yml
services:
  cliproxyapi:
    image: eceasy/cli-proxy-api:latest
    restart: unless-stopped
    ports:
      - "8317:8317"
      - "8085:8085"    # Gemini OAuth 回调
      - "54545:54545"  # Claude OAuth 回调
      - "1455:1455"    # Codex OAuth 回调
    volumes:
      - ./config.yaml:/CLIProxyAPI/config.yaml
      - ./auth:/root/.cli-proxy-api

docker compose up -d

基础配置

安装后先编辑 config.yaml，最少只需改两个地方：

# config.yaml 最简配置
port: 8317

# 客户端连接时用的密钥（自己设，随机字符串即可）
api-keys:
  - "sk-my-secret-key-123"

# OAuth 凭证存储目录
auth-dir: "~/.cli-proxy-api"

# 管理面板密码
remote-management:
  secret-key: "your-panel-password"
  allow-remote: false   # 只允许本机访问管理面板

# 国内服务器必配：出口代理
# proxy-url: "socks5://127.0.0.1:1080"

api-keys 是客户端（Cursor、Cline 等）访问你这个代理时要带的密钥，和上游模型的 API Key 没关系，自己随便设。

改完配置，重启服务：

systemctl --user restart cliproxyapi
# 或直接运行
./cli-proxy-api --config ./config.yaml

登录账号

CLIProxyAPI 支持两种方式接入模型：OAuth 登录（用订阅配额，免费）和 API 密钥（付费按量计费）。入门先看 OAuth。

方式一：千问（最简单，推荐新手开始）

Qwen 和 Kimi 使用设备码流程，不需要本地浏览器，不需要 SSH 隧道，手机扫码就能完成：

./cli-proxy-api --qwen-login
# 终端输出一个验证码和网址
# 用手机或任意浏览器访问该网址，输入验证码
# 完全免费，无需订阅

./cli-proxy-api --kimi-login
# 同上，月之暗面 Kimi 账号

方式二：Claude Code（需要 Claude Pro $20/月）

本地机器（有浏览器）：

./cli-proxy-api --claude-login
# 自动打开浏览器 → Anthropic OAuth 授权页 → 完成授权
# 凭证自动保存到 auth-dir

远程服务器（SSH 无浏览器）：

# 第一步：在服务器上执行，获取 OAuth URL
./cli-proxy-api --claude-login --no-browser

# 第二步：在本地电脑建立 SSH 隧道（端口 54545）
ssh -L 54545:localhost:54545 user@your_server_ip

# 第三步：本地浏览器打开第一步输出的链接完成授权
# 凭证通过隧道传回服务器自动保存

方式三：Gemini CLI（Google One Pro 配额最高）

# 前提：需要 Google 账号，最好有 Google One Pro 订阅
# 并且在 Google Cloud Console 启用了 cloudaicompanion API

./cli-proxy-api --login
# 自动打开浏览器完成 Google OAuth 授权

远程服务器同样用 SSH 隧道，回调端口改为 8085：

ssh -L 8085:localhost:8085 user@your_server_ip
./cli-proxy-api --login --no-browser

方式四：OpenAI Codex（ChatGPT Plus/Pro）

./cli-proxy-api --codex-login
# 回调端口：1455
# 远程 SSH 隧道同理：ssh -L 1455:localhost:1455 user@server

多账号登录

重复执行登录命令，每次在浏览器中切换到不同账号，所有凭证自动进入轮询池：

./cli-proxy-api --claude-login  # 账号 A
./cli-proxy-api --claude-login  # 账号 B，浏览器切换账号
./cli-proxy-api --login         # Gemini 账号 1
./cli-proxy-api --login         # Gemini 账号 2

验证是否正常工作

# 列出可用模型
curl http://localhost:8317/v1/models \
  -H "Authorization: Bearer sk-my-secret-key-123"

# 发送测试请求
curl http://localhost:8317/v1/chat/completions \
  -H "Authorization: Bearer sk-my-secret-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

返回正常 JSON 即代表配置成功。

接入 Claude Code

把 CLIProxyAPI 作为 Claude Code 的后端，相当于用 Claude Code 的交互方式，但流量走你配置的任意模型。

# 方式一：环境变量（临时生效）
export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export ANTHROPIC_AUTH_TOKEN=sk-my-secret-key-123
claude

# 方式二：写入 ~/.claude/settings.json（永久生效）

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-my-secret-key-123",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8317"
  }
}

注意：如果之前用过 Claude Code 自带 OAuth 登录（claude auth），需要先执行 /logout 清除旧 token，否则两套认证会冲突。

管理面板

CLIProxyAPI 自 v6.0.19 起内置了一个基于 React 的 Web 管理界面，无需单独部署，随主程序启动后即可访问。它只调用 /v0/management API，不参与流量代理。

访问地址

http://127.0.0.1:8317/management.html

在线演示版（只读）：https://remote.router-for.me/

登录时填写的密码是 config.yaml 里的 remote-management.secret-key，不是 api-keys。两者职责不同：

config.yaml 管理面板配置详解

remote-management:
  # 是否允许非 localhost 的浏览器访问管理面板
  # false（默认）：只有本机浏览器能访问
  # true：公网/内网都能访问（配合反代使用）
  allow-remote: false

  # 管理密钥。填明文后，启动时自动哈希为 bcrypt 存储。
  # 留空则完全禁用管理 API（所有 /v0/management 路由返回 404）。
  secret-key: "your-strong-password"

  # 是否禁用内置面板路由（/management.html 返回 404）
  # 设为 true 后只保留 Management API，不提供 Web UI
  disable-control-panel: false

  # 禁止面板从 GitHub 自动更新（默认 false）
  # true：只在首次访问时下载一次，之后不自动更新
  # disable-auto-update-panel: false

  # 面板来源的 GitHub 仓库。国内访问 GitHub 慢时，可替换为镜像地址
  panel-github-repository: "https://github.com/router-for-me/Cli-Proxy-API-Management-Center"

密码安全：secret-key 填明文时，CLIProxyAPI 启动会自动 bcrypt 哈希并写回配置文件。多次输错密码会触发 IP 临时封禁（内置暴力破解防护，无需额外配置）。

各功能页面详解

Dashboard（仪表盘）

显示服务连接状态、版本号、构建时间，以及当前可用模型的分组概览。适合快速确认服务是否正常运行。

配置面板（Config）

可视化编辑 config.yaml，支持：

• 表单模式：填写常用字段（port、api-keys、proxy-url 等），无需手写 YAML
• 源码模式：带 YAML 语法高亮和搜索的全文编辑器（基于 CodeMirror）
• 保存前差异预览（diff 视图）

修改配置后点击保存，服务自动热重载，无需手动重启。

AI Providers（提供商）

统一管理各类上游渠道的连接参数：

• Claude / Gemini / Codex / Vertex：配置 base-url、请求头、出口代理、模型别名、排除模型、前缀路由
• OpenAI 兼容提供商：批量管理 API Key，支持从 /v1/models 自动拉取模型列表并导入别名
• Ampcode 集成：配置上游地址/密钥、模型映射表

认证文件（Auth Files）

管理 auth-dir 目录下的 OAuth 凭证文件：

• 上传/下载/删除 JSON 凭证（适合在本地登录后传到服务器）
• 查看单个凭证的可用模型列表
• 配置 OAuth 排除模型（支持 * 通配符，如 gemini-2.5-*）
• 配置 OAuth 模型别名（将 claude-sonnet-4-5 重命名为 cs4.5 等）

OAuth（在线发起登录）

这是管理面板最实用的功能之一：不需要 SSH 到服务器手动执行命令，直接在浏览器里触发 OAuth 登录流程。支持的提供商：

操作流程（以 Claude 为例）：

1. 进入面板 → OAuth 页面 → 选择 Claude
2. 点击「发起登录」，面板调用管理 API 在服务器端启动 OAuth 监听
3. 面板自动轮询状态，待服务器端准备好后，弹出 Google/Anthropic 授权链接
4. 在本地浏览器打开该链接，完成账号授权
5. 面板检测到回调成功，显示「登录完成」，凭证自动写入 auth-dir

远程服务器提示：面板触发登录后，服务器在指定端口等待 OAuth 回调。如果服务器没有公网入站端口（即回调端口 54545/8085 等不可达），仍需在本地建 SSH 隧道（见上文各提供商的远程登录说明）。回调端口只在登录过程中监听，完成后自动关闭。

配额管理（Quota）

查看 Claude、Antigravity、Codex、Gemini CLI 各账号的配额用量和上限，无需手动调用管理 API。

日志（Logs）

• 增量拉取实时日志，可搜索/过滤关键词
• 隐藏管理端流量（减少日志噪音）
• 下载错误日志文件（error-logs-max-files 控制保留数量）

注意：日志页面需要在「配置面板 → 基础设置」里开启「写入日志文件」（logging-to-file: true）后，导航项才会出现。

系统信息（System）

• 版本检查：对比当前版本与最新 GitHub Release
• 模型列表：调用 /v1/models 分组展示所有可用模型（需至少配置一个 api-key）
• 本地认证清理：一键清除当前浏览器 localStorage 里的管理密钥缓存

远程访问管理面板

在 config.yaml 中开启：

remote-management:
  allow-remote: true
  secret-key: "your-strong-password"

然后通过反代对外暴露（以 Caddy 为例）：

cliproxy.k330.com {
    reverse_proxy 127.0.0.1:8317 {
        flush_interval -1
    }
}

访问 https://cliproxy.k330.com/management.html，填入管理密钥即可。

安全建议：

• 管理密钥至少 32 位随机字符，openssl rand -hex 24 生成
• 不要用浏览器密码管理器自动填充到公共设备
• 可在 Caddy/Nginx 对 /v0/management/ 路径额外限制访问 IP

常见问题

Q：登录后调用报 401

区分两种密钥：

• api-keys：你自己设的，客户端带在 Authorization 里，和上游服务商无关
• provider api-key：Anthropic/Google 的官方 API Key，用于付费 API 接入

OAuth 登录方式不需要配置任何上游 API Key，只需要在客户端带上你自己设的 api-keys。

Q：远程服务器无法完成 OAuth，浏览器打不开

使用 --no-browser 参数 + SSH 端口隧道（见上文各提供商的远程登录说明）。

或者在本地电脑完成登录，把 ~/.cli-proxy-api/ 下的凭证文件 scp 到服务器的对应目录。

Q：流式输出卡顿，不是逐字显示

如果套了 Nginx 反代，必须配置：

proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding on;
proxy_read_timeout 300s;

Q：Token 过期需要重新登录

CLIProxyAPI 每 5 分钟自动刷新 Token，正常情况下无感。若刷新失败（账号密码修改、二次验证变动），重新执行对应的 --login 命令即可。

Q：国内服务器访问 Google/Anthropic 超时

在 config.yaml 配置出口代理：

proxy-url: "socks5://user:pass@127.0.0.1:1080"

系列导航

• （一）入门——把 CLI 订阅变成标准 API（本文）
• （二）多账号轮询与配额策略
• （三）接入主流 AI 编程工具
• （四）生产部署——Nginx、TLS 与安全加固
• （五）Antigravity——用 Google 订阅解锁 Claude Opus 4.8
• （六）结合 new-api 打造多用户 API 网关
• （七）自动化运维——配额监控与告警
• （八）cpa_keeper 与 cpa_cost——用量追踪与成本分析工具

实操清单

基于当前服务器实际配置状态（自动扫描 config.yaml、服务状态、凭证目录生成）

安装与服务

• Linux 二进制安装（版本 7.1.45）
• systemd 服务配置（开机自启，运行中）
• Docker Compose 部署方式
• 日志持久化到文件（logging-to-file: true，日志写入 ~/cliproxyapi/logs/main.log）

基础配置

• 端口配置（port: 8317）
• 客户端 API Key 配置（已配置两个密钥）
• 凭证目录配置（auth-dir: ~/.cli-proxy-api）
• 管理面板密码配置（remote-management.secret-key）
• 管理面板远程访问开启（allow-remote: true）
• 反代 + HTTPS 配置（Caddy: cliproxy.k330.com）
• 流式输出配置（Caddy: flush_interval -1，等效于 proxy_buffering off）
• 出口代理配置（proxy-url，服务器如需翻墙访问上游）

账号登录

• Claude Code OAuth 登录（已登录 1 个账号）
• Gemini API Key 配置
• Gemini CLI OAuth 登录（Gemini Studio 账号已登录，auth 文件已生成；enable-gemini-cli-endpoint 暂保持 false，通过 OpenAI 兼容端点访问 Gemini 模型）
• Qwen 账号登录（--qwen-login，免费，无需订阅）
• Kimi 账号登录（--kimi-login）
• Codex / ChatGPT Plus 账号登录（--codex-login）
• 多 Claude 账号配置（当前仅 1 个，可继续 --claude-login 追加）

接入配置

• Claude Code 接入 CLIProxyAPI（~/.claude/settings.json 中配置 ANTHROPIC_BASE_URL）

高级功能

• 轮询策略配置（round-robin）
• 配额超限自动切换（switch-project / switch-preview-model / antigravity-credits）