1. 项目概述从“客户端专属”到“开放API”的桥梁最近在折腾AI应用开发的朋友估计都遇到过同一个头疼的问题看中了某个大模型的能力比如Google的Gemini Pro或者Anthropic的Claude Opus结果发现官方要么不提供公开API要么API调用成本高昂要么就是有严格的速率限制。更常见的情况是一些强大的模型功能只被封装在官方的桌面或命令行客户端里比如Gemini CLI、Codex、Grok CLI我们开发者想在自己的项目里调用简直是“看得见摸不着”。这就是AIClient2API简称A2诞生的背景。简单来说它是一个“协议转换器”和“统一网关”。它的核心使命就是把那些原本只能在特定客户端里使用的、免费的AI模型服务通过技术手段“代理”出来封装成标准的、OpenAI兼容的API接口。这意味着你熟悉的那些基于OpenAI API的工具比如NextChat、Cherry-Studio、LobeChat甚至是你自己写的脚本现在都能通过这个本地服务免费或低成本地调用Gemini、Claude Opus、Grok、Codex等模型了。我花了几天时间深度部署和测试了这个项目它远不止是一个简单的“转发代理”。它内置了账号池管理、智能故障转移、多协议互转OpenAI/Claude/Gemini、甚至包括绕过某些服务TLS指纹检测的Sidecar。对于个人开发者、小团队或者仅仅是AI爱好者来说这相当于一下子拥有了一个功能强大且成本可控的“本地AI模型聚合平台”。接下来我就结合自己的实操经验带你从零开始在5分钟内搞定部署和基础接入并深入拆解它的高级玩法和避坑指南。2. 核心设计思路与架构拆解在开始动手之前理解AIClient2API是怎么工作的能帮你更好地使用它并在出问题时快速定位。它的设计非常巧妙核心思路可以概括为“伪装、转换与调度”。2.1 核心工作原理OAuth代理与协议适配项目之所以能调用那些“客户端专属”的模型关键在于利用了这些客户端与后端服务通信时使用的OAuth 2.0授权流程。例如当你使用Gemini CLI时它会引导你完成一次Google账号登录获取一个访问令牌Access Token后续所有请求都携带这个令牌。A2项目模拟了这个过程它提供了一个Web界面引导你完成同样的OAuth登录并将获取到的令牌安全地存储在本地。之后所有发往A2服务的API请求都会被它用这个令牌“伪装”成来自官方客户端的请求转发给真正的模型服务提供商。但这还不够因为不同模型服务商的API协议各不相同。OpenAI有它自己的/v1/chat/completions格式Anthropic Claude用的是/v1/messagesGoogle Gemini又是另一套。所以A2的第二个核心组件是协议转换器。它内部实现了OpenAI、Claude、Gemini三大协议之间的智能互转。当你以OpenAI的格式发送一个聊天请求到A2时如果后端目标是GeminiA2会自动将请求体转换成Gemini能理解的格式收到Gemini的响应后再转换回OpenAI的格式返回给你。对你而言你始终在用一套统一的API背后的复杂性完全被屏蔽了。2.2 模块化架构策略模式与适配器模式的应用从代码架构上看项目采用了经典的策略模式和适配器模式这使得它非常易于扩展。每一个模型提供商如gemini-cli-oauth、claude-kiro-oauth都被实现为一个独立的“策略”或“适配器”。每个适配器负责三件事身份认证管理处理该提供商特有的OAuth流程或API Key验证。协议转换将标准化的内部请求格式转换为该提供商原生的API调用。响应处理将原生响应转换回标准格式。这种设计的好处是当需要支持一个新的“客户端专属”模型时开发者基本上只需要实现一个新的适配器注册到系统中即可核心的路由、调度、池化管理逻辑完全复用。2.3 高可用性设计账号池与智能降级免费服务通常有严格的速率限制Rate Limit。单个账号很容易触发“429 Too Many Requests”错误。A2引入了**提供商池Provider Pool**的概念。你可以为同一个服务比如Gemini配置多个账号即多个OAuth令牌。A2会将这些账号放入一个池中并以轮询Round Robin或更智能的方式调度请求从而将负载分散到多个账号上显著提升整体可用性和请求配额。更厉害的是它的**跨类型故障转移Fallback**机制。假设你主要使用gemini-cli-oauth通过Gemini CLI获取的免费令牌当这个池子里的所有账号都因为配额用尽或被标记为不健康时A2可以自动将请求“降级”转发到另一个配置好的、协议兼容的提供商类型比如gemini-antigravity另一个Google内部接口。这就像为你的API服务上了双保险极大地保证了服务的连续性。3. 5分钟快速部署与初体验理论讲完我们进入实战。最快上手的方式是使用Docker这能避免复杂的本地环境依赖。3.1 使用Docker一键部署推荐确保你的系统已经安装了Docker和Docker Compose。然后只需要一条命令docker run -d \ -p 3000:3000 \ -p 8085:8085 -p 8086:8086 -p 1455:1455 -p 56121:56121 -p 19876-19880:19876-19880 \ --restartalways \ -v $(pwd)/configs:/app/configs \ -v $(pwd)/plugins:/app/src/plugins-user \ --name aiclient2api \ justlikemaki/aiclient-2-api命令参数解读-p 3000:3000将容器的3000端口映射到主机这是Web管理界面的端口。-p 8085:8085 ...映射一系列端口这些是不同提供商OAuth授权回调所需的端口。务必确保这些端口在主机上未被占用。-v $(pwd)/configs:/app/configs将当前目录下的configs文件夹挂载到容器内用于持久化保存所有配置文件、授权令牌。这是最关键的一步否则容器重启后配置会丢失。-v $(pwd)/plugins:/app/src/plugins-user挂载用户自定义插件目录可选。--restartalways设置容器总是自动重启保证服务长期运行。--name aiclient2api给容器起个名字方便管理。执行命令后Docker会自动从Docker Hub拉取镜像并启动。用docker ps检查容器状态看到aiclient2api容器正在运行就成功了。3.2 访问Web管理控制台打开浏览器访问http://你的服务器IP:3000本地部署就是http://localhost:3000。你会看到一个登录界面默认密码是admin123。强烈建议登录后第一件事就是在控制台里修改这个默认密码。登录后的控制台非常直观左侧是导航栏主要功能包括仪表盘系统概览和快速开始指南。配置管理核心区域在这里配置各个模型提供商的参数。提供商池查看和管理已配置的账号池状态。配置文件直接管理存储在configs目录下的各种OAuth凭据文件。实时日志查看系统日志和API请求日志调试神器。3.3 配置第一个模型提供商以Gemini为例我们以配置免费的Gemini Pro为例演示如何通过Web UI完成授权。在控制台左侧点击“配置管理”。页面中会列出所有支持的提供商。找到“Gemini CLI OAuth”卡片。你会看到需要填写Project ID。这个ID需要从Google AI Studio获取。访问 Google AI Studio 用你的Google账号登录。在页面中你应该能看到一个项目或者创建一个新项目。项目ID通常格式为your-project-123456。将这个ID填入Web UI的Project ID字段。点击卡片右上角的“生成授权”按钮。系统会弹出一个对话框并提供一个链接。点击“在浏览器中打开”。浏览器会跳转到Google的OAuth授权页面。选择你用来登录Google AI Studio的同一个Google账号并授予必要的权限。授权成功后页面会显示“授权成功”然后自动关闭。此时回到A2的Web UI你会发现Gemini CLI OAuth卡片的状态可能变成了“已配置”或类似提示并且在下方的“配置文件”页面里应该能看到新生成的oauth_creds.json文件。至此Gemini Pro模型的接入就完成了。整个过程不需要你手动复制粘贴任何令牌全部由Web UI自动化完成体验非常流畅。3.4 进行第一次API调用服务跑起来了Gemini也配好了现在来试试它是否工作。打开你的终端或使用Postman等工具我们用一个最简单的cURL命令来测试OpenAI兼容接口curl http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer your-api-key-here \ -d { model: gemini-2.0-flash-exp, messages: [ {role: user, content: 你好请用中文简单介绍一下你自己。} ], stream: false }注意几个关键点端口请求发往3000端口这是A2服务的主端口。端点路径/v1/chat/completions这是标准的OpenAI聊天补全端点。A2完美兼容这个格式。Authorization头这里的Bearer your-api-key-here需要替换。在A2的Web UI“配置管理”页面顶部有一个“API密钥”的配置项。你可以设置一个自定义的API密钥或者如果你图省事在开发测试时可以直接填写Bearer sk-any-string-you-likeA2默认配置下会接受任何非空的Bearer令牌。生产环境务必设置一个复杂的密钥model参数这里填的是gemini-2.0-flash-exp。这个模型名称需要与提供商支持的模型列表对应。你可以在Web UI的提供商配置附近看到支持的模型列表或者查阅项目文档。如果一切正常你会收到一个JSON格式的响应其中choices[0].message.content字段就是Gemini模型的回复。恭喜你你已经成功通过AIClient2API调用了免费的Gemini模型4. 核心功能深度解析与配置实战基础接入只是开始A2的强大之处在于其丰富的可配置性和企业级功能。下面我们深入几个核心模块。4.1 多协议路由与智能转换A2支持通过不同的URL路径来路由到不同的后端提供商并自动处理协议转换。这是它实现“统一接口”的关键。路由规则示例http://localhost:3000/v1/chat/completions这是默认的OpenAI兼容端点。请求到达后A2会根据你在“配置管理”中设置的默认提供商或者根据请求头、参数中的特定信息来决定将请求转发给哪个后端如Gemini、Claude via Kiro等并完成协议转换。http://localhost:3000/claude-kiro-oauth/v1/messages这是Claude原生协议端点。如果你直接向这个路径发送Claude格式的请求A2会将其直接转发给Kiro服务一个提供Claude模型访问的第三方而不经过OpenAI协议转换。这通常延迟更低。http://localhost:3000/gemini-cli-oauth/v1/chat/completions这是指定使用Gemini CLI提供商来处理OpenAI格式请求。实操心得对于大多数集成OpenAI SDK的应用如NextChat你只需要配置Base URL为http://localhost:3000/v1即可/chat/completions部分由SDK自动追加。但有些客户端如某些版本的Cherry-Studio可能会在Base URL后重复追加路径导致404错误。排查此类问题时第一件事就是打开A2的“实时日志”查看客户端实际发起的请求URL是什么确保路径正确。4.2 账号池Provider Pool配置与管理单个免费账号的配额非常有限。要稳定使用配置账号池是必须的。准备账号池配置文件在挂载的configs目录下参考provider_pools.json.example如果不存在可以从项目GitHub仓库下载创建一个provider_pools.json文件。配置文件结构文件是一个JSON对象键是提供商类型值是该类型下的账号数组。{ gemini-cli-oauth: [ { uuid: gemini-account-1, credentialsPath: /app/configs/gemini/oauth_creds_account1.json, checkHealth: true }, { uuid: gemini-account-2, credentialsPath: /app/configs/gemini/oauth_creds_account2.json, checkHealth: true } ], claude-kiro-oauth: [ { uuid: kiro-account-1, credentialsPath: /app/configs/kiro/kiro-auth-token-account1.json } ] }uuid账号的唯一标识自定义即可。credentialsPath该账号对应的OAuth凭据文件在容器内的绝对路径。注意Docker容器内路径是/app/configs/...对应你挂载的本地configs目录。checkHealth是否对此账号启用健康检查。启用账号池在Web UI的“配置管理”页面找到“高级设置”或直接在configs/config.json中设置PROVIDER_POOLS_FILE_PATH为/app/configs/provider_pools.json。生效与监控重启A2服务Docker容器后进入Web UI的“提供商池”页面。你应该能看到配置的账号以卡片形式列出并有“健康”、“不健康”、“禁用”等状态。系统会定期自动进行健康检查不健康的账号会被暂时跳过。注意事项收集多个账号的OAuth凭据需要你手动为每个Google账号或其他服务账号重复进行Web UI的“生成授权”流程并妥善保存不同的oauth_creds.json文件。建议按账号建立子目录分类存放。4.3 高级配置详解代理、Fallback与TLS绕过4.3.1 代理配置如果你的网络环境无法直接访问某些服务如Google需要配置代理。统一代理在Web UI“配置管理”的“代理设置”区域填入你的代理服务器地址例如http://127.0.0.1:7890或socks5://127.0.0.1:10808然后勾选需要走代理的提供商如gemini-cli-oauth。这种方式下所有选中提供商的请求都会通过该代理发出。提供商自带代理端点有些第三方中转服务已经提供了代理好的API端点。你可以在对应提供商的配置区域直接修改其Base URL。例如将OPENAI_BASE_URL改为https://your-proxy.com/v1。这种方式优先级更高且可能更稳定。4.3.2 跨类型故障转移Fallback这个功能在configs/config.json中配置用于定义当某个类型的提供商全部不可用时可以降级到哪些其他类型。{ providerFallbackChain: { gemini-cli-oauth: [gemini-antigravity, openai-custom], claude-kiro-oauth: [claude-custom] } }这段配置的意思是当gemini-cli-oauth类型的所有账号都不可用时系统会按顺序尝试gemini-antigravity如果还不行再尝试openai-custom。这要求目标类型必须支持当前请求的模型协议兼容。4.3.3 TLS Sidecar绕过Cloudflare 403一些服务如Grok会检测客户端的TLS指纹JA3/JA4如果不是来自主流浏览器直接返回403 Forbidden。A2内置了一个用Go编写的TLS Sidecar来模拟浏览器指纹。本地部署启用步骤安装Go环境确保系统已安装Go 1.20。编译Sidecar在A2项目根目录如果你是从源码运行或解压后的目录中执行cd tls-sidecar go build -o tls-sidecarWindows用户会生成tls-sidecar.exe。启用配置在Web UI“配置管理”中找到TLS Sidecar相关选项并开启或直接在config.json中设置{ TLS_SIDECAR_ENABLED: true, TLS_SIDECAR_PORT: 9090 }Docker用户官方镜像justlikemaki/aiclient-2-api已经预编译了Sidecar二进制文件你只需要在配置中开启TLS_SIDECAR_ENABLED: true即可无需手动编译。开启后针对Grok等服务的请求会自动通过这个Sidecar代理发出从而绕过TLS指纹检测。5. 集成到现有应用与工具A2最大的价值在于它能无缝集成到现有生态中。因为它提供了OpenAI兼容的API所以任何支持自定义OpenAI API Base URL的工具理论上都能使用。5.1 与ChatGPT WebUI类工具集成NextChat, LobeChat以NextChat为例部署或打开你的NextChat。进入设置Settings- 模型提供商Model Provider。添加一个自定义的OpenAI兼容提供商。在API Key字段填写你在A2中设置的API密钥或在测试时任意字符串。在Endpoint字段填写你的A2服务地址例如http://localhost:3000/v1。注意末尾的/v1必不可少。在模型列表中添加A2支持的模型例如gemini-2.0-flash-exp并选择刚才创建的自定义提供商。保存后你就可以在NextChat的聊天界面中选择Gemini模型进行对话了。5.2 与编程SDK集成OpenAI Python Library在Python项目中使用几乎和调用原生OpenAI API一样简单from openai import OpenAI # 将base_url指向你的A2服务 client OpenAI( api_keyyour-a2-api-key, # 填写A2配置的API密钥 base_urlhttp://localhost:3000/v1 # 指向A2 ) # 像调用OpenAI一样发起请求 response client.chat.completions.create( modelgemini-2.0-flash-exp, # 指定A2后端的模型 messages[ {role: user, content: 请用Python写一个快速排序函数。} ], streamFalse, ) print(response.choices[0].message.content)5.3 作为LangChain或LlamaIndex的Model Provider对于更复杂的AI应用框架A2可以作为底层模型提供商接入。LangChain示例from langchain_openai import ChatOpenAI from langchain.schema import HumanMessage llm ChatOpenAI( openai_api_keyany-string, # LangChain可能需要一个非空的key openai_api_basehttp://localhost:3000/v1, model_namegemini-2.0-flash-exp, temperature0.7, ) response llm.invoke([HumanMessage(content你好)]) print(response.content)实操心得在集成过程中最常见的错误是404 Not Found和401 Unauthorized。404几乎都是因为Endpoint路径不对确保是http://your-host:3000/v1而不是http://your-host:3000/v1/chat/completionsSDK会自己加。401则检查API密钥配置在A2的Web UI中确认密钥验证是否开启。6. 常见问题排查与实战经验分享即使按照指南操作也难免会遇到问题。下面是我在实战中遇到的一些典型问题及解决方案。6.1 OAuth授权失败或无限循环问题点击“生成授权”后浏览器页面白屏、报错或授权成功后页面不关闭。排查检查端口确保Docker命令映射了所有OAuth回调端口8085, 8086, 1455, 56121, 19876-19880并且主机上这些端口没有被其他程序占用。检查网络确保你的服务器或本地机器能够正常访问Google、xAI等授权域名。如果网络受限需要在A2中先配置代理。使用无痕模式浏览器的扩展插件有时会干扰OAuth流程尝试在无痕窗口中完成授权。查看日志在A2的Web UI“实时日志”中过滤oauth关键词查看详细的错误信息。6.2 请求返回429速率限制错误问题频繁请求后开始收到429 Too Many Requests。解决方案配置账号池这是根本解决方法。为同一个服务添加多个账号利用轮询分散请求。启用冷却机制在config.json中设置RATE_LIMIT_COOLDOWN_ENABLED: true和RATE_LIMIT_COOLDOWN_MS: 60000例如1分钟。当某个账号触发限流后它会自动退出活跃池一段时间之后自动恢复。配置Fallback如前所述配置providerFallbackChain当一个类型的账号全部限流后自动切换到备用类型。降低请求频率在客户端代码中增加请求间隔。6.3 请求返回403 Forbidden错误特别是Grok问题调用Grok模型时直接返回403。解决方案首要检查TLS Sidecar确认TLS_SIDECAR_ENABLED已设置为true。对于本地部署确认tls-sidecar二进制文件已成功编译并位于正确路径。查看“实时日志”中是否有Sidecar启动失败的错误。检查Cookie/SSO令牌如果使用Grok WebCookie方式确保从浏览器获取的sso令牌是最新且有效的并且GROK_USER_AGENT配置与获取Cookie时使用的浏览器一致。检查账号状态在“提供商池”页面确认Grok对应的节点状态是健康的。有时服务端会临时屏蔽健康检查会将其标记为不健康系统会自动跳过。6.4 Docker容器启动失败或不断重启问题docker run或docker-compose up后容器状态一直是Restarting。排查查看日志运行docker logs aiclient2api查看具体的错误输出。检查挂载目录权限确保运行Docker命令的用户对当前目录下的configs文件夹有读写权限。可以尝试执行chmod 755 configs。检查端口冲突用netstat -tulpn | grep :3000Linux或lsof -i :3000Mac检查端口是否被占用。检查镜像版本尝试拉取最新镜像docker pull justlikemaki/aiclient-2-api:latest。6.5 流式输出Streaming中断或不完整问题当设置stream: true时响应经常中途断开。解决方案检查网络稳定性流式响应对网络稳定性要求较高尤其是通过代理时。调整客户端超时增加客户端的读超时Read Timeout设置给服务器更长的响应时间。检查代理配置如果你使用了代理确保代理服务器支持并正确转发了HTTP/1.1的分块传输编码Chunked Transfer Encoding。查看服务端日志在A2的“实时日志”中查看是否有错误抛出可能是某个提供商账号突然失效导致流中断。6.6 模型列表为空或无法选择问题在NextChat等客户端中模型下拉列表为空。排查检查端点路径确认客户端配置的Endpoint是http://localhost:3000/v1并且客户端支持通过/v1/models接口拉取模型列表。A2提供了这个接口。手动测试接口用cURL直接调用curl http://localhost:3000/v1/models -H Authorization: Bearer sk-xxx看是否能返回模型列表JSON。检查提供商配置确保至少有一个提供商如Gemini已正确配置且状态健康。不健康的提供商不会提供模型。经过这一系列的配置、集成和问题排查你应该已经能够熟练地驾驭AIClient2API将它作为一个稳定、多功能的AI模型网关来使用了。它的价值在于将碎片化的、受限的免费AI能力整合成了一个统一、可靠、可编程的接口极大地降低了个人和小团队进行AI应用创新的门槛。最后再分享一个小心得定期关注项目的GitHub仓库更新作者会频繁添加对新模型和新客户端的支持并修复已知问题保持更新能让你的“AI网关”始终拥有最前沿的能力。