1. 项目概述CLIProxyAPI为AI编程工具打通本地代理的桥梁如果你和我一样日常重度依赖Claude Code、Cursor、Windsurf这类AI编程工具但又被官方API高昂的费用、复杂的密钥管理或是某些模型如Claude Code不提供传统API接口所困扰那么你肯定会对今天要聊的这个项目感兴趣。CLIProxyAPI一个名字听起来很技术但功能直击痛点的开源工具。它的核心使命很简单为你手头已有的AI订阅服务如ChatGPT Plus、Claude Pro、Gemini Advanced等创建一个本地的、兼容OpenAI API格式的代理服务器。这意味着什么意味着你可以用你按月付费的Claude Pro账号在Cursor里直接调用Claude-3.5-Sonnet模型来写代码而无需等待Anthropic官方的API开放也无需支付额外的API调用费。同样你的Gemini Advanced订阅、甚至是通过OAuth登录的OpenAI Codex即ChatGPT的编程模式都可以通过这个统一的本地代理被各种原本只认OpenAI API格式的客户端和SDK所使用。这不仅仅是省钱了更是将你手中分散的AI能力整合到了一个统一的、可编程的接口上极大地提升了工作流的灵活性和效率。2. 核心设计思路为什么需要一个“格式转换”代理在深入实操之前我们先拆解一下CLIProxyAPI解决的核心问题这能帮你更好地理解它的价值所在。2.1 市场现状与用户痛点目前主流的AI编程工具如Cursor、Claude Code、Windsurf、Cline等在底层通信上大多遵循或兼容OpenAI的API格式即/v1/chat/completions。这是一个事实上的“行业标准”。然而各大AI服务提供商提供的接入方式却五花八门OpenAI提供标准的API密钥和端点但GPT-4等高级模型API调用成本不菲。Anthropic (Claude)Claude Code作为其编程IDE主要通过OAuth授权使用不直接提供传统API。你想在第三方工具里用Claude模型官方路径几乎堵死。Google (Gemini)Gemini Advanced作为订阅服务其使用也主要绑定在IDE插件或Web界面标准的Gemini API虽然存在但与OpenAI格式不兼容且高级模型如Gemini 2.0 Flash Thinking的API访问可能有延迟或限制。其他服务如Antigravity等新兴服务各有各的接入方式。这就导致了几个典型的痛点成本高昂为每个工具单独购买API额度开销巨大。能力割裂无法在一个工具里灵活切换不同供应商的最优模型。管理复杂需要维护多个平台的API密钥安全性、轮换都是问题。订阅浪费已经为Claude Pro、ChatGPT Plus付了月费却无法在编程工具中直接利用这些订阅的额度。2.2 CLIProxyAPI的解决方案扮演“智能翻译官”CLIProxyAPI的架构思路非常清晰它作为一个本地运行的代理服务器通常跑在localhost:8787扮演了一个“智能翻译官”和“统一网关”的角色。协议转换它接收来自客户端如Cursor的、符合OpenAI API格式的HTTP请求。身份路由根据请求中指定的模型名称如claude-3-5-sonnet或配置的路由规则CLIProxyAPI决定将这个请求转发给哪个上游服务如Claude的OAuth会话、Gemini的API、OpenAI的API等。格式适配在转发前它将OpenAI格式的请求体“翻译”成目标上游服务能理解的格式。例如将OpenAI的messages数组转换成Anthropic Claude所需的特定结构。响应回译收到上游服务的响应后再将其“翻译”回OpenAI的格式返回给最初的客户端。这样一来对于客户端而言它只是在调用一个“标准的OpenAI API”完全无需关心背后是Claude、Gemini还是Codex在提供服务。这个设计巧妙地利用了现有的订阅资源打破了平台壁垒。注意CLIProxyAPI本身不提供任何AI模型或算力。它只是一个代理和转换层。你必须已经拥有相应服务的有效订阅如ChatGPT Plus账号、Claude Pro账号等或API密钥它才能为你工作。2.3 多账户与负载均衡从单点连接到资源池除了基本的格式转换CLIProxyAPI一个更高级的特性是支持多账户负载均衡。比如你可能有多个Google账号都开通了Gemini Advanced或者有多个Claude Pro账号。你可以将这些账号全部配置到CLIProxyAPI中。当配置了多个同一类型的账号后CLIProxyAPI可以以轮询Round-Robin的方式在这些账号间分配请求。这样做有两个巨大好处突破单账号限速单个账号通常有每分钟/每天的请求次数RPM/TPD限制。多账号轮询能有效分散请求避免触发限流。叠加使用额度例如每个Claude Pro账号有固定的消息额度。通过多个账号你实际上获得了数倍的总额度非常适合高强度开发场景。这个功能将CLIProxyAPI从一个简单的“转换器”升级为了一个“智能的AI资源调度器”。3. 环境准备与安装部署详解理解了原理我们开始动手。CLIProxyAPI是一个Go语言编写的项目部署方式非常灵活。这里我将以最常见的本地Docker部署为例因为它最干净、最易于管理也适合绝大多数开发者。当然你也可以通过Go直接运行或使用预编译的二进制文件。3.1 前置条件检查在开始前请确保你的系统满足以下条件操作系统macOS, Linux, 或 Windows (WSL2推荐)。Docker已安装并运行。可以通过在终端运行docker --version来验证。Git用于克隆代码仓库。网络能够正常访问相关AI服务如openai.com,claude.ai,gemini.google.com。如果你的网络环境特殊可能需要进行相应配置。账号准备至少准备好一个你想要接入的AI服务账号如Google账号用于Gemini或Anthropic账号用于Claude。3.2 获取项目代码与配置文件首先我们将项目代码克隆到本地。# 克隆主仓库 git clone https://github.com/router-for-me/CLIProxyAPI.git cd CLIProxyAPI项目根目录下有一个至关重要的文件config.yaml。这是CLIProxyAPI的大脑所有代理规则、账号信息、路由逻辑都在这里定义。我们首先来了解一下它的基本结构。# config.yaml 示例片段 server: port: 8787 # 代理服务器监听的端口 auth: api_keys: - “your-static-api-key-for-clients“ # 客户端连接时使用的密钥可选但建议设置 providers: - name: “claude“ # 提供商名称 type: claude_oauth # 类型Claude OAuth enabled: true config: accounts: - email: “your-emailexample.com“ # session_token 将通过初始化流程获取不直接在此填写明文密码 - name: “gemini“ type: gemini_oauth enabled: true config: accounts: - email: “your-googlegmail.com“ - name: “openai_codex“ type: openai_oauth enabled: true config: accounts: - email: “your-openai-emailexample.com“ routes: - path: “/v1/chat/completions“ # 匹配的请求路径 provider: “*“ # 使用哪个提供商* 表示根据模型名自动路由 model_mapping: # 模型映射规则 “claude-3-5-sonnet“: “claude“ # 当请求模型为claude-3-5-sonnet时使用claude提供商 “gemini-2.0-flash-thinking“: “gemini“ “gpt-4o“: “openai_codex“初始的config.yaml可能比较简单我们需要根据要接入的服务来丰富它。不过CLIProxyAPI提供了一个更友好的方式来初始化配置通过其内置的管理API和交互式流程。3.3 使用Docker Compose一键启动与初始化项目贴心地提供了docker-compose.yml文件这是最推荐的启动方式因为它将应用、配置持久化、日志都打包管理好了。# docker-compose.yml (通常项目已提供检查即可) version: ‘3.8‘ services: cliproxyapi: image: ghcr.io/router-for-me/cliproxyapi:latest container_name: cliproxyapi ports: - “8787:8787“ # 将容器的8787端口映射到宿主机的8787端口 volumes: - ./data:/app/data # 持久化存储配置、会话令牌等数据 - ./logs:/app/logs # 持久化日志 restart: unless-stopped environment: - NODE_ENVproduction启动容器在项目根目录下执行。docker-compose up -d这个命令会拉取最新的CLIProxyAPI镜像并在后台启动容器。现在代理服务器已经在你的localhost:8787上运行了。访问管理界面进行初始化CLIProxyAPI提供了一个基于HTTP的管理API。我们首先通过它来添加账号。打开浏览器或使用curl访问http://localhost:8787/manage或者查看更详细的API文档http://localhost:8787/manage/api通常更实用的方法是使用项目提供的CLI工具或直接调用管理API。例如要启动一个Claude账号的OAuth登录流程你可以调用# 假设管理API的密钥是默认的或者你在config.yaml中配置了auth.api_keys curl -X POST http://localhost:8787/manage/api/v1/providers/claude/accounts \ -H “Authorization: Bearer your-management-api-key“ \ -H “Content-Type: application/json“ \ -d ‘{“action“: “start_oauth“}‘执行后终端会返回一个URL。你需要复制这个URL到浏览器中打开完成Claude或Google、OpenAI的登录授权流程。授权成功后CLIProxyAPI会自动获取并安全地存储session_token或refresh_token。这个令牌是加密后存储在./data目录下的比直接在配置文件中写密码安全得多。实操心得首次配置时建议逐个提供商添加账号。先完成一个如Gemini测试通后再添加下一个。避免多个OAuth流程同时进行导致混乱。另外浏览器的隐私模式无痕窗口有时能避免已有登录状态的干扰。验证代理状态添加完账号后我们可以测试一下代理是否工作。curl http://localhost:8787/v1/models \ -H “Authorization: Bearer your-static-api-key“ \ -H “Content-Type: application/json“如果配置正确你会收到一个JSON响应里面列出了所有已配置提供商支持的模型列表例如claude-3-5-sonnet,gemini-2.0-flash-thinking,gpt-4o等。3.4 配置文件深度解析与调优初始化完成后你的./data目录下会生成运行时的配置文件。理解关键配置项能让你更好地驾驭CLIProxyAPI。server.port修改它可改变代理监听端口。如果8787被占用可以改为其他端口如8790。auth.api_keys这是一个用于控制客户端访问的静态API密钥列表。强烈建议设置一个强密码。客户端如Cursor在连接时需要在请求头中携带Authorization: Bearer your-key。如果留空则代理无需认证即可访问这在本地环境勉强可以但若机器暴露在局域网甚至公网则极其危险。providers这是核心。每个provider的config下可以配置多个accounts。对于OAuth类型accounts里主要就是email令牌是动态管理的。你还可以配置request_timeout: 单个请求的超时时间。max_retries: 请求失败后的重试次数。concurrent_limit: 该提供商同时处理的最大请求数用于控制并发避免被上游限流。routes路由规则决定了请求如何被分发。provider: “*“配合model_mapping是最常用的自动路由模式。你也可以设置更复杂的规则例如基于请求路径或特定头信息路由。logging可以配置日志级别debug,info,warn,error。调试问题时设为debug可以看到详细的请求转发和响应信息但日志量会很大。一个优化后的多账号Gemini配置示例providers: - name: “gemini_pool“ type: gemini_oauth enabled: true config: request_timeout: 120 # 超时时间设为2分钟应对长文本 concurrent_limit: 5 # 每个账号并发限制为5 max_retries: 2 accounts: - email: “dev1gmail.com“ - email: “dev2gmail.com“ - email: “dev3gmail.com“4. 客户端配置实战以Cursor和VS Code为例代理服务器跑起来了接下来就是让我们的开发工具用上它。这里以最流行的两款AI编程工具——Cursor和Visual Studio Code搭配Claude Code或Windsurf插件为例。4.1 配置Cursor使用本地代理Cursor原生支持配置自定义的OpenAI兼容API端点。打开Cursor进入设置Settings。通常可以通过菜单栏Cursor - Settings或快捷键Cmd ,(Mac) /Ctrl ,(Win) 打开。在设置中找到“AI”或“Advanced”相关区域。不同版本可能位置略有不同寻找类似“OpenAI API Base URL”、“Custom API Endpoint”或“AI Provider”的选项。将API URL设置为你的CLIProxyAPI地址http://localhost:8787/v1。注意这里填的是/v1因为OpenAI的标准端点路径是/v1/chat/completionsCLIProxyAPI的/v1路由会处理它。在API Key字段填入你在CLIProxyAPI的config.yaml中设置的auth.api_keys例如your-static-api-key。如果没设置可以留空仅限纯本地环境。在Model下拉菜单中你现在应该能看到CLIProxyAPI返回的模型列表了比如claude-3-5-sonnet、gemini-2.0-flash-thinking。选择一个你配置好的模型。保存设置。测试在Cursor中新建一个文件尝试让AI写一段代码或解释一个函数。观察Cursor界面上的状态指示。你可以在CLIProxyAPI的日志中看到对应的请求和转发记录docker-compose logs -f cliproxyapi4.2 配置VS Code的Claude Code扩展Claude Code扩展默认使用Anthropic的官方服务。我们需要通过设置环境变量或修改扩展配置来指向本地代理。方法一通过环境变量推荐影响范围可控在启动VS Code时设置一个环境变量。具体操作取决于你的操作系统。macOS/Linux在终端中执行。# 设置环境变量并启动VS Code CLAUDE_API_BASE_URL“http://localhost:8787/api/provider/claude/v1“ code .你可以将这个命令别名化或创建一个启动脚本。Windows (PowerShell)$env:CLAUDE_API_BASE_URL“http://localhost:8787/api/provider/claude/v1“ “C:\Path\To\Visual Studio Code\Code.exe“方法二修改VS Code用户设置 (settings.json)有些扩展允许通过配置覆盖端点。打开VS Code的设置 (Ctrl ,)搜索“Claude”看是否有相关的API端点设置。如果没有可以尝试直接编辑settings.json{ “claude.code.apiBaseUrl“: “http://localhost:8787/api/provider/claude/v1“ }注意扩展的配置项名称可能不同需要查阅特定扩展的文档。CLIProxyAPI为Claude提供了专门的路径/api/provider/claude/v1这能确保请求使用Claude原生的消息格式避免不必要的转换损耗。配置认证Claude Code扩展通常期望一个API Key。这里我们需要使用CLIProxyAPI的管理API来生成一个针对Claude provider的临时密钥或者直接使用静态密钥。更常见的做法是CLIProxyAPI的OAuth流程已经处理了认证扩展只需要能连接到代理即可代理会自行处理身份验证。如果扩展强制要求填写API Key可以填写CLIProxyAPI的静态密钥。测试在VS Code中打开一个项目尝试使用Claude Code的指令如/explain。查看CLIProxyAPI日志确认请求是否被正确路由到你的Claude账号。4.3 配置其他工具通用方法对于任何支持“自定义OpenAI API端点”的工具配置方法都大同小异找到API配置在工具设置中寻找类似Base URL、Endpoint、API Host的字段。填写代理地址填入http://localhost:8787/v1对于通用OpenAI兼容或更具体的提供商路径如http://localhost:8787/api/provider/gemini/v1。填写API密钥填入CLIProxyAPI中配置的auth.api_keys。选择模型从工具提供的模型列表中选择CLIProxyAPI支持的模型别名如gpt-4o可能被映射到你的OpenAI Codex。5. 高级特性与运维技巧基础功能用上之后下面这些高级特性和运维技巧能让你用得更加得心应手并有效避免踩坑。5.1 多账户负载均衡与故障转移这是CLIProxyAPI的王牌功能。配置多个同类型账号后负载均衡是自动的。但你需要理解其行为轮询策略默认情况下请求会在可用账户间依次分配。这能平均分配使用量。故障转移如果某个账户的请求失败例如因达到速率限制返回429错误或因会话过期返回401错误CLIProxyAPI会自动尝试列表中的下一个账户。这意味着服务的高可用性。会话保持对于需要上下文连续性的对话多轮聊天CLIProxyAPI会尽量将同一会话的后续请求路由到同一个账户以保持上下文连贯。这是通过请求中的某些标识符来实现的。配置建议为生产环境配置至少2-3个同一服务的账号以确保当一个账号出问题时服务不中断。定期检查./data目录下的会话状态。虽然OAuth令牌会自动刷新但极端情况下可能需要重新授权。5.2 模型映射与别名灵活的路由控制config.yaml中的model_mapping非常强大。你不仅可以做一对一的映射还可以实现更复杂的逻辑备用模型降级当首选模型不可用时自动使用备用模型。routes: - path: “/v1/chat/completions“ provider: “*“ model_mapping: “claude-opus-4.5“: “claude“ # 首选Opus “claude-sonnet-4“: “claude“ # 如果请求Opus但失败可以在客户端或代理逻辑中尝试映射到Sonnet这需要更复杂的错误处理逻辑CLIProxyAPI本身可能需结合健康检查更常见的做法是在客户端如Cursor设置备用模型列表或者利用CLIProxyAPI未来可能增强的健康检查与自动降级功能。统一模型接口你可以为同一个后端模型创建多个别名方便不同客户端调用。model_mapping: “my-fast-coder“: “gemini“ # 客户端使用my-fast-coder实际调用Gemini “my-smart-coder“: “claude“ # 客户端使用my-smart-coder实际调用Claude这样在团队协作中你可以统一分发配置而无需告知每个人背后具体是哪个供应商。5.3 监控、日志与问题排查稳定的服务离不开监控。CLIProxyAPI提供了多种观察其运行状态的方式。日志查看这是最基本也是最重要的排查手段。# 查看实时日志 docker-compose logs -f cliproxyapi # 查看特定时间段的日志 docker-compose logs --since“10m“ cliproxyapi # 将日志输出到文件便于分析 docker-compose logs cliproxyapi proxy.log 21关注日志中的ERROR和WARN级别信息。DEBUG级别日志会打印出详细的请求和响应体有助于分析格式转换问题但注意其中可能包含敏感信息。管理API端点CLIProxyAPI的管理API/manage/api提供了一些查询接口例如GET /manage/api/v1/providers查看所有提供商的状态和账户信息如剩余额度。GET /manage/api/v1/health检查代理服务整体健康状态。 你可以写一个简单的脚本定期调用这些接口监控账户健康。资源监控使用docker stats命令监控容器的CPU、内存使用情况。docker stats cliproxyapi如果发现内存持续增长可能内存泄漏或CPU持续过高请求量过大需要考虑调整配置或升级服务器。5.4 性能调优与安全加固调整超时与重试根据网络状况和上游服务稳定性适当调整request_timeout和max_retries。对于生成长代码的场景超时应设置得长一些如120秒。重试次数不宜过多2-3次为宜避免因持续重试导致雪崩。并发控制利用concurrent_limit防止对单一上游服务发起过多并发请求触发限流。例如为Claude provider设置concurrent_limit: 3。启用API密钥认证再次强调务必在config.yaml中设置auth.api_keys。不要让你的代理在无认证状态下暴露。限制监听地址如果你只在本地使用确保Docker Compose中端口映射是127.0.0.1:8787:8787而不是0.0.0.0:8787:8787。前者只允许本机访问后者允许任何能访问你机器的网络连接访问风险更高。定期更新关注项目GitHub仓库的Release定期拉取新镜像更新以获取性能改进、Bug修复和新功能支持。docker-compose pull docker-compose up -d6. 常见问题与解决方案实录在实际部署和使用中你几乎一定会遇到下面这些问题。这里是我和社区踩过坑后总结的解决方案。6.1 OAuth授权失败或会话频繁过期问题描述在初始化账号或使用过程中出现“Authentication failed”、“Session expired”等错误。排查步骤检查网络确保运行CLIProxyAPI的服务器能够正常访问accounts.google.com,claude.ai,openai.com等OAuth域名。如果使用代理需要在Docker容器内或主机上正确配置网络代理。检查时间同步服务器时间不正确会导致OAuth令牌验证失败。确保服务器时间与网络时间同步使用ntpdate或chronyd。查看详细日志开启debug级别日志查看OAuth流程的具体错误信息。重新授权最直接的方法是通过管理API删除旧账户会话重新启动OAuth流程。令牌可能因上游安全策略而失效。# 删除指定provider的某个账户需要知道account_id可从日志或管理API查询 curl -X DELETE http://localhost:8787/manage/api/v1/providers/claude/accounts/{account_id}6.2 客户端收到“模型不支持”或“未找到”错误问题描述Cursor等客户端在模型列表中看不到预期的模型或选择模型后请求失败。排查步骤检查/v1/models端点首先直接调用代理的模型列表接口看返回中是否包含你想要的模型。curl http://localhost:8787/v1/models -H “Authorization: Bearer your-key“检查model_mapping配置确认config.yaml中的model_mapping是否正确将客户端请求的模型名映射到了已启用的provider。模型名大小写敏感。检查提供商状态通过管理API检查目标provider及其账户是否enabled: true且状态健康。检查路由路径确认客户端请求的URL路径是否与routes中的path匹配。例如客户端调用/v1/chat/completions你的路由就必须有匹配这个path的规则。6.3 请求速度慢或超时问题描述AI响应缓慢或经常出现超时错误。排查步骤区分问题来源在CLIProxyAPI的debug日志中观察请求的各个阶段耗时收到客户端请求 - 转发到上游 - 收到上游响应 - 返回给客户端。这能定位延迟发生在代理层还是上游服务。上游服务问题如果延迟主要在上游响应阶段那可能是Gemini、Claude等服务本身的速度问题或者是你的网络到这些服务的延迟高。可以尝试直接访问这些服务的Web界面感受速度。代理服务器资源检查运行CLIProxyAPI的服务器CPU和内存使用率。如果资源吃紧考虑升级配置。对于Docker可以调整资源限制。调整超时设置适当增加providers.config.request_timeout的值给上游服务更长的响应时间。并发限制检查是否因concurrent_limit设置过低导致请求排队。6.4 如何更新账户配额信息问题描述Claude Pro、Gemini Advanced等都有使用额度限制如何方便地查看还剩多少解决方案CLIProxyAPI的管理API提供了查询接口。你可以定期调用以下端点来获取账户状态信息其中通常包含额度或使用量数据取决于上游服务是否提供。curl http://localhost:8787/manage/api/v1/providers -H “Authorization: Bearer your-management-key“返回的JSON中会包含每个账户的详情。你也可以考虑使用一些基于CLIProxyAPI的第三方仪表盘项目如项目列表中的CLIProxyAPI Dashboard、CPA-XXX Panel它们提供了图形化的配额监控界面。6.5 在服务器或远程机器上部署场景你想在云服务器或家里的NAS上部署CLIProxyAPI然后让局域网内所有设备如公司的台式机、家里的笔记本都能使用。配置要点安全第一必须设置强密码的auth.api_keys。考虑使用HTTPS可以通过在CLIProxyAPI前放置一个Nginx反向代理并配置SSL证书来实现。修改监听地址在config.yaml中可以将server.host设置为0.0.0.0Docker容器内通常已是并在docker-compose.yml中将端口映射到宿主机的某个端口如- “8787:8787“。防火墙确保服务器防火墙开放了8787端口或你自定义的端口。客户端配置在Cursor等客户端中将API Base URL设置为你的服务器IP或域名例如http://your-server-ip:8787/v1。网络考虑确保服务器到上游AI服务的网络畅通且延迟可接受。最后再分享一个我个人的小技巧为不同的项目或工作场景创建不同的config.yaml配置文件。例如一个配置只启用Gemini用于快速代码补全另一个配置启用Claude用于复杂的代码重构和解释。然后通过不同的Docker Compose文件指定不同的配置卷来启动不同的实例监听不同端口。这样可以根据任务需求快速切换更加灵活。