CLIProxyAPI：将大模型CLI编程工具转化为免费大模型API接口的本地代理服务

CLIProxyAPI 是一款开源的高效本地 API 代理服务器，其核心理念是打破 CLI（命令行界面）类 AI 编程工具与通用 API 客户端之间的壁垒。它能够将 Gemini CLI、Claude Code、OpenAI Codex、Qwen Code 等热门 CLI 编程助手的原生授权凭证，无缝转化为全面兼容 OpenAI、Anthropic 和 Gemini 标准协议的 API 接口。通过内置的 OAuth 鉴权机制，开发者无需购买高昂的官方 API Key，即可直接利用现有的 CLI 工具操作权限，在 Cursor、Cline、Continue 等第三方 IDE 插件或桌面应用中自由调用底层大模型。此外，CLIProxyAPI 原生支持多账号负载均衡、流式数据输出、函数调用（Function Calling）以及智能模型回退机制，是开发者构建零成本、高可用本地 AI 编程工作流的核心基础设施。

Function List

• 跨协议标准 API 转换: Will Claude Code、OpenAI Codex、Gemini CLI 等 CLI 工具专属的通信协议，实时且无损地转换为市面上兼容性极广的 OpenAI / Anthropic / Gemini 标准 API 端点。
• 基于 OAuth 的免 Key 接入：彻底告别使用传统 API Key 进行调用的方式，通过终端命令行一键唤起 OAuth 网页认证，合法复用大模型厂商下发给 CLI 客户端的长期访问令牌。
• 多账号智能负载均衡：自带 “轮询（Round-Robin）” 与 “优先填满（Fill-First）” 并发调度策略，只需本地登录多个同一平台的账号，系统即可自动分发 API 请求，从根本上解决单账号频次限制（Rate Limit）的痛点。
• 模型别名与回退映射：内置自定义路由规则引擎，允许对冗长的模型名称设置简短别名，且支持在高级模型（如 Opus 级）因网络或额度不可用时，请求自动降级重定向至预设的替代模型。
• 大模型高阶交互能力支持：代理传输层完整还原了 Server-Sent Events (SSE) 流式响应、多模态数据混合识别（文本分析与图像读取透传）以及原生的工具与函数调用（Function Calling）能力。
• 运行时的动态管理接口（Management API）：内置基于 RESTful 架构的本地化控制台端口，支持在程序运行期间动态刷新配置、监控实时账号额度消耗状态及检阅底层请求日志。
• 可复用模块化 Go SDK：软件的核心网络代理与鉴权逻辑被提炼为可独立引用的 Go 语言 SDK，帮助其余开发者将其直接内嵌至自研的 Go 框架项目中进行二次能力扩展。

Using Help

CLIProxyAPI 的系统设计极具“极客精神”，它充当了一个隐形却强大的本地 AI 路由中枢。为了将您本地受限的 Claude Code 或 Gemini CLI 变为无所不能的标准网络 API 接口，请详细阅读本指南，掌握从部署安装到 IDE 集成的全套生产力工作流。

一、 运行环境搭建与安装指南

CLIProxyAPI 采用 Go 语言构建，原生拥有跨平台无依赖的特性。根据您的使用习惯，可通过以下三种方式进行部署：

方式 1：基于 Docker 容器化部署（强烈推荐团队或服务器用户使用）

1. 确保系统内核已安装 Docker 引擎及 Docker Compose 管理插件。
2. 在任意本地工作目录下新建一个名为 docker-compose.yml 的文件，填入如下基础运行模板：将宿主机端口 8317 映射至容器内部，并设定 auth-dir 和配置文件的目录挂载。
3. 请务必确认您挂载的本地目录（如 ./data:/CLIProxyAPI/data）拥有足够的读写权限，这用于持久化存储您未来授权获取的密钥数据。
4. 打开命令行，在同级目录下执行 docker compose up -d 即可在后台无感启动代理服务。

方式 2：下载预编译的二进制可执行程序（推荐轻量化桌面环境操作）

1. 访问 CLIProxyAPI 在 GitHub 官方仓库的 Releases 列表页，根据您的操作系统（Windows / macOS / Linux）与 CPU 芯片架构（amd64 / arm64）下载最新的发行版压缩包。
2. 解压缩下载的文件，您会看到一个独立的主程序文件（例如 cli-proxy-api.exe 或基于 UNIX 的 cli-proxy-api 运行文件）。
3. 无需复杂安装流程，打开系统自带的终端（Terminal 或 Cmd），定位到该文件夹，执行 ./cli-proxy-api，程序即会自动引导生成基础配置文件，并开始监听 8317 Ports.

方式 3：借助第三方社区版桌面端 EasyCLI
如果您完全不习惯使用黑框终端，推荐下载社区贡献的 Tauri 可视化图形客户端 EasyCLI。它封装了所有的启动逻辑，提供直观的按钮供您启停系统、监控请求与配置代理。

二、 核心机制：通过 OAuth 执行账号鉴权授权

将 CLI 工具变现为 API 的基础，在于让代理服务提取这些官方工具的安全令牌（Token）。由于是本地直接请求官方认证，安全性极高。

以获取 Gemini CLI 的调用权限为例：

1. 在代理服务处于运行或可运行的状态下，在终端执行专用登录指令：./cli-proxy-api --login。
2. 控制台随即会打印一串 Google 官方登录验证长链接，并在大部分操作系统下会自动唤起您系统的主力浏览器窗口。
3. 按照普通的登录流程，输入对应的 Google 账户密码并同意授权请求。由于属于 OAuth 2.0 原生标准机制，此操作只在厂商服务器上验证，CLIProxyAPI 仅作凭证捕获，无法知晓您的原始密码。
4. 完成确认后，浏览器会跳转至本地回传页面提示成功。
5. 此时返回终端，你会发现代理服务已在默认存储位置（如 ~/.cli-proxy-api/）自动静默生成了一份 gemini_account1.json，其中就是高价值的可用凭证。对于 Claude Code 等服务，均沿用同等逻辑即可。

三、 性能进阶：多账号负载均衡与 Fallback 路由配置

CLIProxyAPI 不仅仅是一根简单的转发“网线”，其内置的路由器可以成倍提升您的工作效率。打开并在编辑器中查看运行目录下的 config.yaml Configuration file.

1. 打破限流：配置并发多账号（Load Balancing）
假设单个免费账号每分钟只能调用 15 次 API，对于复杂的代码生成远不够用。
操作方法非常简单：重复前述步骤二中的登录指令。每次在浏览器中切换并登录一个新的 Google 或 Anthropic 账户，auth-dir 凭证文件夹内就会多生成一个 JSON 文件。
接下来在 config.yaml 中启用轮询策略：

routing:
strategy: "round-robin"  # 支持轮询或填满模式

代理服务器在接到前端 IDE 发来的连续高频请求时，系统代码会在底层自动读取目录下的全部授权文件，将第一条请求发往账号A、第二条发往账号B，形成无缝轮换。若触发 429 Too Many Requests，它将自动拦截报错并切换账号重试。

2. 防中断保护：建立智能模型映射池（Model Aliasing）
为了防止核心大模型突然宕机影响开发心流，建议配置降级模型机制：

models:
mappings:
"claude-3-opus-20240229": "claude-3-5-sonnet-20241022"
"gemini-ultra": "gemini-2.5-pro"

当前端工具发起对 claude-3-opus 模型的计算申请失败时，底层服务器会静默且快速地把需求转给同一体系下稍快但更稳定的备用模型 sonnet，保障代码输出的持续性。

四、 终极实战：零成本接管 IDE 与第三方应用

服务跑起来后，相当于您已经在本地开启了一家不收费的 AI 云服务供应商。

以在目前爆火的 Cursor 或 Cline 中配置为例：

• Step one: 打开代码编辑器底部的 AI 配置面板，在提供商中选择「OpenAI 兼容平台（Custom Endpoint）」。
• Step two: 将 API 的 Base URL 指向本机的代理地址：http://127.0.0.1:8317/v1（此处注意必须加上 /v1 的版本后缀）。
• Step Three: 在 API Key 输入框内，您可以随便填写任何字母组合(e.g. sk-CLIProxyAPI-test）。原因是本地代理端已经在内部处理了真实的鉴权，对来自于 localhost 的通信通常无视此处的假 Key。
• Step Four: 在可用模型列表中，覆盖或手动输入与之对应的真实 CLI 大模型代号（如 qwen-max 或 claude-3-5-sonnet-20241022）。
  至此，您就可以通过简单的聊天框，让各大平台的旗舰大模型帮您扫描并重构整页的业务代码，真正意义上实现了极客级的 AI 自由！

application scenario

1. AI 编程插件零成本增强体验
   借助该工具拦截并将受限的 CLI AI 指令（如 Claude Code、Gemini CLI）转化打包为通用的 HTTP API 协议。对于使用 Roo Code、Continue、Cursor 等高级 IDE 扩展的独立开发者而言，不仅可以免去高昂的 API 字数消耗费用，还能直接享受大厂的最新前沿模型。
2. 开发组局域网共享算力资源池
   在一个拥有数名成员的初创研发团队中，将各个组员各自拥有的不同厂商的闲置授权文件统一集中导入到部署了 CLIProxyAPI 的内网服务器。开启系统的负载均衡特性后，就相当于构建了一条由团队集资搭建的高并发 “私有专线大模型接口”，规避单个开发者资源枯竭。
3. 跨平台全系模型桌面聚合终端
   终端用户在使用类似 Chatbox、NextChat 等泛用途的聊天图形工具时，直接将大模型后端的网络请求地址重写导向本机的代理端口。这能让原本互不相通、必须在命令行执行的各个 AI 编程组件（包括 Codex、Qwen 等）汇聚于一个对话框中供您随时选择切换。

QA

1. CLIProxyAPI 与市面上那些售卖便宜 API 的中转站有什么根本区别？
   市面上的中转站（Reverse Proxy）一般是在云端倒卖或复用自己充值的 API Key。而 CLIProxyAPI 是一款“纯本地开源工具”，它巧妙提取并复用的是您本人的大模型厂商提供给原生 CLI（命令行）编程工具的后台权限，把这类原本只能通过特定终端命令行才能交互使用的工具，变成能被其他软件直接接入的标准 API 服务，因此本身绝对零成本且保护隐私。
2. 每次想进行代码自动生成，都需要重新在终端里打命令执行登录吗？
   完全不需要。您只需要在初次配置时通过终端进行一次 --login 授权验证。获取到的 Token 会作为持久化的 JSON 文件保存在您的机器硬盘中。这些验证信息有效期极长，后续每次启动服务程序或重启电脑，系统都会自动读取历史配置，实现无感直连。
3. 当我在编程工具中遇到 “429 Rate Limit Exceeded (请求超限)” 报错怎么办？
   由于此类 CLI 工具权限往往依附于个人账号基础配额，报错说明您当前的账号触发了平台的并发检测机制。建议的解决办法是：准备 1-2 个该同平台的其它空闲账号，通过终端再次登录生成新的授权凭据文件。利用代理工具内置的负载均衡（Load Balancing），当主账号遭遇限频时会自动切到子账号执行重试，化解报错。
4. 该代理服务转化的接口，是否支持大段代码生成的实时（Streaming）打字输出？
   百分之百支持。CLIProxyAPI 在协议转换层高度看齐 OpenAI 的架构规范。只要您在调用的客户端应用端设定了开启流式输出，代理程序就会把从官方底层建立连接起产生的每一个增量数据块，以无延迟透传的形式推送至您的编辑器前台，丝毫不会破坏打字机式的视觉展示效果。