解锁Gemini潜能：本地API代理与OpenAI兼容接口解决方案

引言：当Gemini遇上API的桥梁

你是否在使用Google Gemini时遇到这样的困扰？官方API调用额度有限，终端交互不够灵活，无法与现有工具链集成。今天我将介绍一个突破性的解决方案：「GeminiCli2API」。这个开源项目巧妙地将Gemini CLI封装成本地API服务，并提供了OpenAI兼容接口，让您能像使用OpenAI一样使用Gemini的强大能力。

❝

「项目核心价值」：通过命令行工具的身份验证机制，突破官方API限制；提供OpenAI兼容接口，实现无缝集成；完整保留安装指南和操作步骤，确保真实可用。

❞

一、项目核心构成：三大模块协同工作

1. 💎 原生Gemini代理服务 (`gemini-api-server.js`)

「功能定位」：直接对接Google Cloud Code Assist API的本地代理
「核心能力」：
- 自动处理OAuth认证与令牌刷新
- 支持API密钥验证（URL参数或请求头）
- 修复角色规范化问题
- 完整实现listModels、generateContent等端点
- 提供强大的日志记录系统

2. 🔄 OpenAI兼容代理服务 (`openai-api-server.js`)

「功能定位」：在原生服务基础上提供OpenAI标准接口
「突破性创新」：
- 无缝转换OpenAI与Gemini格式
- 完整支持流式传输（streaming）
- 兼容/v1/models和/v1/chat/completions端点
- 支持多种认证方式

3. ⚙️ 核心共享模块 (`gemini-core.js`)

「核心功能」：
- 统一处理认证流程
- 管理API调用
- 处理请求/响应转换
- 实现日志记录

graph TD
    A[用户请求] --> B{请求类型}
    B -->|OpenAI格式| C[openai-api-server.js]
    B -->|原生Gemini格式| D[gemini-api-server.js]
    C --> E[gemini-core.js]
    D --> E
    E --> F[Google Cloud Code Assist API]
    F --> E
    E --> G[响应转换]
    G --> H[用户]

二、为什么选择GeminiCli2API？四大核心优势

✅ 突破官方API限制

利用Gemini CLI账号授权，获得更高请求配额
绕过官方API的严格额度控制
免费享受Gemini的高级模型能力

✅ 无缝兼容OpenAI生态

任何支持OpenAI API的客户端即插即用
现有工具链零成本迁移（如LobeChat、NextChat等）
开发者无需修改现有代码

✅ 增强的控制与可见性

详细日志记录所有提示词（prompts）
支持控制台或文件两种日志输出
实时显示令牌有效期状态

✅ 灵活扩展的架构

清晰模块化设计方便二次开发
可添加统一前置提示词
支持实现响应缓存机制
易于集成内容过滤功能

三、手把手安装指南

环境准备

安装Node.js（版本≥18.0.0）
- 官方下载地址

克隆项目仓库：

git clone https://github.com/your-repo/geminicli2api.git

安装依赖

cd geminicli2api
npm install

❝

此过程会自动安装google-auth-library和uuid等关键依赖

❞

四、快速启动与API调用

启动Gemini原生服务

# 默认启动（监听localhost:3000）
node gemini-api-server.js

# 监听所有网络接口（适合Docker部署）
node gemini-api-server.js 0.0.0.0

# 启用提示词日志（控制台输出）
node gemini-api-server.js --log-prompts console

调用Gemini原生API

# 列出可用模型
curl "http://localhost:3000/v1beta/models?key=123456"

# 带系统提示的请求
curl "http://localhost:3000/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: 123456" \
  -d '{
    "system_instruction": { "parts": [{ "text": "你是一只名叫Neko的猫。" }] },
    "contents": [{ "parts": [{ "text": "你好，你叫什么名字？" }] }]
  }'

启动OpenAI兼容服务

node openai-api-server.js --port 8000 --api-key sk-your-key

调用OpenAI兼容API

# 非流式对话
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [
      {"role": "system", "content": "你是一只名叫Neko的猫。"},
      {"role": "user", "content": "你好，你叫什么名字？"}
    ]
  }'

# 流式对话（实时响应）
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "写一首关于宇宙的五行短诗"}
    ],
    "stream": true
  }'

五、认证流程详解（首次使用）

「复制授权链接」：启动服务时终端会输出Google授权URL
「浏览器授权」：在任何设备的浏览器中打开URL完成登录
「粘贴重定向URL」：授权后粘贴浏览器中的localhost地址到终端
「凭证自动存储」：
- Windows：C:\Users\USERNAME\.gemini\oauth_creds.json
- macOS/Linux：~/.gemini/oauth_creds.json

❝

令牌会在过期前自动刷新，确保服务不间断运行

❞

六、进阶应用场景

1. 🔌 无缝集成现有AI客户端

将LobeChat的API端点指向http://localhost:8000/v1
在NextChat配置中使用您的sk-your-key
VS Code插件直接连接本地Gemini服务

2. 🔍 构建私有提示词库

# 记录所有提示词到文件
node openai-api-server.js --log-prompts file

生成日志示例：

[2025-07-21T14:30:15Z] SYSTEM: 你是一位资深Python开发者
[2025-07-21T14:30:17Z] USER: 如何优化这段排序算法？

3. 🛠️ 二次开发扩展

在gemini-core.js中可添加：

// 统一添加系统提示词
const defaultSystemPrompt = {
  parts: [{text: "所有响应使用Markdown格式，保持专业但口语化"}]
};

// 简单缓存机制
const responseCache = new Map();

function checkCache(prompt) {
  return responseCache.get(prompt);
}

七、技术实现细节

认证流程优化

sequenceDiagram
    participant User
    participant Server
    participant GoogleAuth
    User->>Server: 启动服务
    Server->>GoogleAuth: 生成授权URL
    GoogleAuth-->>Server: 返回URL
    Server-->>User: 显示授权链接
    User->>GoogleAuth: 浏览器访问URL
    GoogleAuth-->>User: 返回重定向URL
    User->>Server: 粘贴重定向URL
    Server->>GoogleAuth: 交换令牌
    GoogleAuth-->>Server: 返回访问令牌
    Server->>User: 认证成功提示

请求处理流程

接收客户端请求
验证API密钥（头部或URL参数）
转换OpenAI格式到Gemini格式（如需要）
添加缺失的角色标记
处理系统提示词（systemInstruction）
发送到Google API
转换并返回响应

八、常见问题解答（FAQ）

❓ 这个项目合法吗？

项目使用官方Gemini CLI的认证机制，完全遵循Google API服务条款，通过正规OAuth流程获取访问权限。

❓ 支持多模态（图片/音频）吗？

当前版本专注于文本交互，多模态支持已在开发计划中（标记为TODO）。

❓ 如何确保API密钥安全？

可通过环境变量传递敏感信息
使用--api-key参数避免密钥硬编码
日志系统会自动过滤密钥信息

❓ 最大支持多少并发请求？

项目基于Node.js原生HTTP模块，性能取决于：

本地硬件资源
网络带宽
Google API的速率限制
建议生产环境配合负载均衡使用

❓ 为什么需要OpenAI兼容层？

许多优秀AI工具（如Chatbot UI、LangChain等）默认支持OpenAI API标准。兼容层使这些工具无需修改即可接入Gemini。

九、结语：释放Gemini的全部潜能

GeminiCli2API解决了三个关键痛点：「突破API调用限制」、「实现生态兼容」、「提供企业级控制能力」。无论是个人开发者探索AI可能性，还是企业需要构建可审计的AI工作流，这个项目都提供了可靠的技术基础。

❝

项目遵循GPL v3开源协议，特别鸣谢Google Gemini CLI团队的开创性工作。我们站在巨人的肩膀上，努力让AI技术更加开放可用。

❞

「下一步行动建议」：

克隆仓库体验基础功能
尝试接入您常用的AI客户端
基于业务需求进行二次开发
参与社区贡献代码或反馈问题

突破官方限制！GeminiCli2API打造OpenAI兼容的本地API代理终极解决方案