Cloudflare Workers部署Gemini OpenAI网关：统一接口调用AI模型

1. 项目概述在Cloudflare Workers上搭建你的专属Gemini OpenAI网关如果你和我一样既眼馋Google Gemini 2.5系列模型强大的推理能力和超长上下文又习惯了OpenAI API那种简洁统一的调用方式那么你肯定也想过要是能把Gemini变成OpenAI的“样子”来用就好了。今天要聊的这个项目——gemini-cli-openai就完美地解决了这个痛点。它本质上是一个部署在Cloudflare Workers上的反向代理服务能将标准的OpenAI API请求无缝转换成对Google Code Assist API的调用并且全程替你打理好繁琐的OAuth2认证和令牌管理。这意味着什么意味着你手头所有基于OpenAI SDK的工具比如Open WebUI、LiteLLM、Cline甚至是你自己写的脚本现在都能直接“喂”给Gemini模型了。你不再需要为不同的AI服务商维护多套代码逻辑一个统一的OpenAI接口就能通吃。更妙的是它利用了Google官方Gemini CLI的认证流程让你能直接使用Google账户的免费额度在享受Gemini最新模型能力的同时还能获得Cloudflare全球边缘网络带来的低延迟优势。无论你是想快速搭建一个私有AI助手还是想为现有应用无缝集成Gemini的能力这个项目都是一个极佳的起点。2. 核心原理与架构设计拆解2.1 为什么需要这个“翻译层”在深入代码之前我们先得搞清楚为什么不能直接用Gemini的原生API。Google的Gemini API特别是通过Code Assist访问的版本在设计上和OpenAI API存在几个关键差异认证机制不同OpenAI API使用简单的API Key而Google的Code Assist API依赖于OAuth2需要一个包含access_token和refresh_token的凭证文件。手动管理这些令牌的刷新和续期非常麻烦。请求/响应格式不同虽然功能相似但两个API的JSON结构、字段命名、流式响应Server-Sent Events的格式都不完全一致。功能特性映射比如OpenAI的tools函数调用对应Gemini的toolsOpenAI的stream对应Gemini的流式输出但参数和细节需要转换。模型标识符OpenAI客户端期望的模型ID是gpt-3.5-turbo这类格式而我们需要将其映射到gemini-2.5-flash这样的Gemini模型名。gemini-cli-openai这个Worker的核心工作就是优雅地处理这些差异。它接收一个符合OpenAI API规范的HTTP请求然后验证并刷新OAuth2令牌利用KV存储做智能缓存。将请求体“翻译”成Gemini API能理解的格式。将Gemini API的流式或非流式响应再“翻译”回OpenAI API的格式。最后通过Cloudflare的边缘节点将结果返回给客户端。整个过程对客户端是完全透明的客户端以为自己一直在和OpenAI对话。2.2 核心组件交互流程我们可以把整个系统想象成一个高效的国际会议同声传译室客户端与会者用自己熟悉的语言OpenAI API提出问题。Worker传译员与调度中心接收请求Hono框架一个轻量级Web框架负责解析HTTP请求。认证与路由检查API Key如果配置了、解析请求路径如/v1/chat/completions。令牌管理这是关键环节。Worker会先检查Cloudflare KV命名空间中是否存有未过期的access_token。如果有直接使用如果没有或已过期则使用refresh_token向Google的认证服务器申请新的access_token并更新KV缓存。这个机制避免了每次请求都走完整的OAuth流程极大提升了效率。请求转换将OpenAI格式的messages、tools、stream等参数映射并组装成Gemini API所需的GenerateContentRequest。调用上游API使用缓存的或新获取的令牌向https://codeassistant.googleapis.com/v1alpha/models/{model}:generateContent发起请求。响应转换将Gemini返回的数据流或完整响应按照OpenAI的SSEdata: {...}或JSON格式进行重构包括计算prompt_tokens和completion_tokens。返回结果将转换后的数据流或JSON返回给客户端。Cloudflare KV短期记忆库专门用于存储OAuth2令牌对。access_token通常只有1小时有效期而refresh_token有效期很长。Worker利用KV缓存有效的access_token并在其失效时用refresh_token自动更新实现了认证状态的持久化。Google Code Assist API真正的专家执行模型推理返回生成的内容。这个架构的精妙之处在于它将复杂的、状态化的OAuth2认证流程封装成了一个无状态的、简单的API Key或无需认证接口极大地降低了集成的复杂度。3. 从零开始的详细部署与配置指南纸上谈兵终觉浅我们来一步步把这个服务搭起来。我会假设你从零开始并穿插我实际操作中遇到的坑和技巧。3.1 前期准备账号与工具你需要准备好三样东西一个Google账户需要能正常访问Gemini通常是gmail.com结尾的账户。这个账户将用于生成OAuth2凭证和消耗API额度。一个Cloudflare账户前往 Cloudflare官网 注册。确保已启用Workers服务。Cloudflare的免费套餐每天提供10万次请求对于个人和小规模使用完全足够。本地开发环境需要安装Node.js建议18.x或以上版本和npm。首先在终端全局安装Wrangler CLI这是Cloudflare Workers的官方部署工具npm install -g wrangler安装后运行wrangler login按提示在浏览器中登录你的Cloudflare账号完成CLI的授权。3.2 获取核心密钥OAuth2凭证详解这是整个部署过程中最关键、也最容易出错的一步。项目巧妙地利用了Google官方gemini-cli工具来为我们获取合法的OAuth2凭证。操作步骤安装官方Gemini CLInpm install -g google/gemini-cli运行并登录gemini首次运行命令行会显示一个选项列表。使用方向键选择● Login with Google并按回车。此时你的默认浏览器会自动打开Google的OAuth2授权页面。注意请务必使用你打算用于API调用的那个Google账户登录。有时浏览器可能已登录其他账户记得在授权页面上切换或使用正确的账户。授权并找到凭证文件完成浏览器授权后CLI会显示登录成功。此时凭证文件已经以JSON格式保存到了你的本地磁盘。macOS/Linux路径是~/.gemini/oauth_creds.jsonWindows路径是C:\Users\你的用户名\.gemini\oauth_creds.json查看并复制凭证内容用文本编辑器打开这个JSON文件你会看到类似下面的内容{ access_token: ya29.a0AS3H6Nx...很长的一串, refresh_token: 1//09FtpJYpxOd...另一串, scope: https://www.googleapis.com/auth/cloud-platform ..., token_type: Bearer, id_token: eyJhbGciOiJSUzI1NiIs..., expiry_date: 1750927763467 }请完整复制这个JSON对象包括最外层的花括号我们下一步会用到它。实操心得与避坑指南凭证的安全性这个oauth_creds.json文件包含了能访问你Google账户Gemini API权限的密钥。refresh_token尤其重要有了它就可以长期生成新的access_token。切勿将此文件提交到Git等版本控制系统也不要通过不安全的方式分享。“无效授权”错误如果你在后续步骤中遇到401或invalid_grant错误很可能是因为凭证获取有问题。可以尝试删除~/.gemini/目录重新运行gemini命令登录。有时浏览器的缓存或账户切换会导致授权到错误的账户或项目。项目ID问题这个凭证通常绑定了某个Google Cloud项目。Worker脚本会自动从令牌中解析project_id。如果自动解析失败你可能需要在环境变量中手动设置GEMINI_PROJECT_ID这通常发生在使用某些类型的服务账户时。3.3 创建与配置Cloudflare Worker项目接下来我们需要在Cloudflare上创建Worker和它的“记忆库”——KV命名空间。创建KV命名空间KV用于缓存令牌。执行以下命令wrangler kv namespace create GEMINI_CLI_KV命令成功后会返回一个id形如xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。记下这个ID。获取项目代码并配置你可以从GitHub克隆项目或者直接创建一个新目录复制项目的wrangler.toml和src等核心文件。这里假设你克隆了项目。 打开项目根目录下的wrangler.toml文件找到kv_namespaces部分将其替换为你的KV命名空间IDkv_namespaces [ { binding GEMINI_CLI_KV, id 你刚才记下的ID } ]binding是代码中引用这个KV存储的变量名不要修改。3.4 环境变量区分开发与生产环境变量是配置Worker行为的核心。项目区分了本地开发和生产环境。1. 本地开发环境 (.dev.vars)在项目根目录创建一个名为.dev.vars的文件。这个文件仅用于本地测试不会被上传。# 必需将从gemini-cli获取的整个JSON对象粘贴在这里作为一行字符串 GCP_SERVICE_ACCOUNT{access_token:ya29...,refresh_token:1//...,scope:...,token_type:Bearer,id_token:eyJ...,expiry_date:1750927763467} # 可选如果你希望API需要认证才能访问设置一个API密钥。格式建议模仿OpenAI如 sk-开头。 # 如果不设置你的本地测试端点将是公开的任何人拿到地址都能调用。 OPENAI_API_KEYsk-your-secret-key-for-development # 可选启用“伪思考”模式用于测试思考功能的UI展示不实际调用Gemini思考能力 ENABLE_FAKE_THINKINGtrue # 可选内容安全过滤阈值根据你的需求调整 GEMINI_MODERATION_HARASSMENT_THRESHOLDBLOCK_NONE重要提示.dev.vars中的值必须是字符串。即使JSON本身包含引号整个值也要用引号包起来或者确保它是一个正确的JSON字符串。最稳妥的方式就是像我上面写的那样直接把JSON对象粘贴进去。2. 生产环境 (Wrangler Secrets)部署到Cloudflare时需要使用wrangler secret put命令来设置加密的环境变量。# 设置OAuth2凭证 wrangler secret put GCP_SERVICE_ACCOUNT # 粘贴你的JSON字符串然后按CtrlDMac/Linux或CtrlZ然后回车Windows结束输入。 # 设置API密钥可选但生产环境强烈建议设置 wrangler secret put OPENAI_API_KEY # 输入你的密钥例如 sk-123456...然后结束输入。生产环境的所有配置都通过这种方式管理比文件更安全。3.5 部署与测试配置完成后部署就非常简单了。安装依赖npm install本地开发测试强烈推荐npm run dev这会在localhost:8787启动一个本地Worker服务器。你可以立刻用curl或Postman进行测试curl http://localhost:8787/v1/models如果返回了Gemini模型列表恭喜你本地环境跑通了。部署到生产环境npm run deploy部署成功后Wrangler会输出你的Worker域名例如https://gemini-openai.your-username.workers.dev。这个就是你的公开API地址了。部署后第一件事测试认证访问https://你的域名.workers.dev/v1/models。如果你设置了OPENAI_API_KEY需要添加HeaderAuthorization: Bearer sk-your-key。你应该能看到一个包含gemini-2.5-pro等模型的JSON列表。这证明从客户端到Worker再到Google API的整个链路是通的。4. 高级功能解析与实战应用基础服务搭好了我们来挖掘一下它的高级能力这些才是让这个Worker脱颖而出的关键。4.1 思考模式解锁Gemini的推理过程Gemini 2.5系列模型最大的亮点之一是“思考”Thinking能力它允许模型在生成最终答案前先进行一段内部推理。这个Worker完美地将此功能映射到了OpenAI的兼容接口上。两种思考模式伪思考 (Fake Thinking)通过设置环境变量ENABLE_FAKE_THINKINGtrue开启。当请求的模型支持思考时Worker会在真正的模型响应前自动生成一段模拟的推理文本。这纯粹是为了前端UI测试让你能看到“思考”效果并不调用Gemini的真实推理。适合在不想消耗额外推理Token时测试客户端兼容性。真实思考 (Real Thinking)通过设置环境变量ENABLE_REAL_THINKINGtrue开启。这才是调用Gemini原生推理能力的方法。你需要在请求体中通过extra_body或model_params传递include_reasoning: true来触发。如何调用真实思考以Python OpenAI SDK为例from openai import OpenAI client OpenAI(base_url你的Worker地址/v1, api_key你的密钥) response client.chat.completions.create( modelgemini-2.5-pro, # 必须使用支持思考的模型 messages[{role: user, content: 求解鸡兔同笼共有头35个脚94只问鸡兔各几何}], streamTrue, extra_body{ # 关键参数在这里 include_reasoning: True, thinking_budget: 2048 # 可选限制推理过程的最大token数-1表示动态分配 } ) for chunk in response: # 真实思考内容会出现在 delta.reasoning 字段中 if hasattr(chunk.choices[0].delta, reasoning) and chunk.choices[0].delta.reasoning: print(f[模型思考中]: {chunk.choices[0].delta.reasoning}, end) # 最终答案出现在 delta.content 字段中 if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)在流式响应中你会先看到一系列reasoning字段的更新最后才是content字段的答案。这对于展示模型的推理链、构建更可信的AI应用非常有价值。推理强度控制你还可以通过reasoning_effort参数来精细控制推理的深度平衡速度与质量low快速、浅层推理。medium平衡模式默认。high深度、细致的推理耗时更长。 这个参数同样在extra_body中传递。4.2 多模态视觉能力集成Gemini模型原生支持图像理解。这个Worker也完整支持了OpenAI格式的多模态消息输入让你可以轻松进行图像对话。核心要点支持格式Base64编码的数据URL推荐最可靠或公开的图片URL。模型要求确保使用支持视觉的模型如gemini-2.5-flash或gemini-2.5-pro。消息格式遵循OpenAI的content数组格式其中可以混合{type: text, text: ...}和{type: image_url, image_url: {url: ...}}对象。实战示例上传本地图片分析import base64 from openai import OpenAI client OpenAI(base_url你的Worker地址/v1, api_key你的密钥) def analyze_image(image_path): with open(image_path, rb) as img_file: # 将图片转换为Base64字符串并构造成Data URL base64_str base64.b64encode(img_file.read()).decode(utf-8) data_url fdata:image/jpeg;base64,{base64_str} # 根据图片类型改mime type response client.chat.completions.create( modelgemini-2.5-flash, messages[ { role: user, content: [ {type: text, text: 请详细描述这张图片的内容。}, { type: image_url, image_url: { url: data_url, # detail: high # 可选控制图像处理粒度high会消耗更多token } } ] } ], max_tokens500 ) return response.choices[0].message.content # 使用示例 description analyze_image(~/Pictures/my_cat.jpg) print(description)通过这种方式你可以轻松构建图片说明生成器、视觉问答系统等应用。4.3 函数调用与工具使用OpenAI格式的tools函数调用被映射到Gemini的tools。这意味着你现有的基于OpenAI函数调用的代码几乎可以不加修改地运行。配置要点环境变量ENABLE_GEMINI_NATIVE_TOOLStrue是总开关。你还可以通过ENABLE_GOOGLE_SEARCH和ENABLE_URL_CONTEXT等变量控制是否启用特定的原生工具如联网搜索。GEMINI_TOOLS_PRIORITY可以设置当自定义工具和原生工具冲突时优先使用哪一个。一个简单的函数调用示例假设我们想让AI帮我们查询天气我们定义了一个工具。// 使用fetch API调用 const response await fetch(https://你的Worker地址/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer sk-your-key }, body: JSON.stringify({ model: gemini-2.5-pro, messages: [{ role: user, content: 波士顿现在的天气怎么样 }], tools: [{ // 定义工具 type: function, function: { name: get_current_weather, description: 获取指定城市的当前天气, parameters: { type: object, properties: { location: { type: string, description: 城市名例如San Francisco, CA }, unit: { type: string, enum: [celsius, fahrenheit], description: 温度单位 } }, required: [location] } } }], tool_choice: auto // 让模型决定是否调用工具 }) }); const result await response.json(); const message result.choices[0].message; if (message.tool_calls) { // 模型决定调用工具 const toolCall message.tool_calls[0]; console.log(模型想调用函数${toolCall.function.name}); console.log(参数${toolCall.function.arguments}); // 是一个JSON字符串 // 在这里你的后端需要根据函数名和参数执行实际逻辑如调用天气API // 然后将执行结果作为新的 assistant message 携带 tool_call_id 发回给模型让它生成最终回答。 }Worker会处理OpenAI工具格式到Gemini工具格式的转换你只需要关心如何定义工具和处理工具的执行结果。5. 主流生态集成实战案例这个Worker最大的优势就是“开箱即用”的兼容性。我们来看看如何将它接入几个流行的AI工具栈。5.1 与Open WebUI无缝整合Open WebUI 是一个可自托管的ChatGPT风格UI。将其后端指向我们的Worker非常简单。在Open WebUI的管理界面进入设置 (Settings) - 模型 (Models)。点击添加模型 (Add Model)或连接现有模型提供商。在模型提供商中选择OpenAI。填写配置模型名称可以自定义如My-Gemini-2.5-Pro。API密钥填写你在Worker中设置的OPENAI_API_KEY如果设置了的话。基础URL填写你的Worker地址务必以/v1结尾例如https://gemini-openai.your-username.workers.dev/v1。模型这里填写你想在UI中显示的模型ID例如gemini-2.5-pro。Open WebUI会通过/v1/models端点拉取实际可用的模型列表但这里填写的名字会作为UI中的显示名称。保存后你就可以在聊天界面中选择这个模型像使用GPT一样与Gemini对话了。图片上传、聊天历史等功能全部可用。5.2 配置ClineVS Code AI助手Cline 是一个专注于代码的VS Code AI助手扩展。让它使用Gemini能获得更好的代码生成和推理能力。在VS Code中安装Cline扩展。打开VS Code设置 (Ctrl,)搜索cline。找到Cline: Api Provider选择OpenAI。配置以下设置Cline: Base Url设置为你的Worker地址同样以/v1结尾。Cline: Api Key设置为你的OPENAI_API_KEY。Cline: Model设置为gemini-2.5-pro或gemini-2.5-flash。对于代码任务pro版本在复杂推理上表现更好。现在在VS Code中选中代码右键使用Cline或者用快捷键召唤它它就会调用你部署的Gemini Worker来提供代码解释、生成、重构等建议。5.3 使用LiteLLM进行统一代理LiteLLM 是一个强大的LLM调用抽象层。通过它你可以用一套代码调用数十种不同的模型。我们的Worker可以作为一个“自定义的OpenAI兼容端点”接入LiteLLM。配置示例import litellm from litellm import completion # 告诉LiteLLM使用我们的自定义端点 litellm.api_base https://你的Worker地址/v1 litellm.api_key sk-your-key # 可选如果Worker设置了认证 # 现在你可以用LiteLLM的统一接口调用Gemini了 response completion( modelgemini-2.5-flash, # LiteLLM会将这个模型名原样传递给Worker messages[{role: user, content: Hello}], streamTrue ) for chunk in response: print(chunk.choices[0].delta.content or , end)关于思考模式的特别优化如果你启用了STREAM_THINKING_AS_CONTENTtrueWorker会将推理过程以thinking.../thinking标签的形式混在普通内容流中输出类似DeepSeek R1的风格。这种格式与LiteLLM和一些下游工具如某些前端UI的兼容性更好因为它们可能不处理标准的reasoning字段。6. 运维、监控与故障排查服务跑起来之后稳定的运维和快速的问题定位同样重要。6.1 关键环境变量详解除了基础的认证变量以下这些变量能帮你微调服务行为变量名作用推荐设置ENABLE_AUTO_MODEL_SWITCHING当遇到速率限制429错误时自动从pro模型降级到flash模型。true。这能有效提高服务的可用性避免因临时配额不足而完全失败。GEMINI_MODERATION_*_THRESHOLD内容安全过滤。设置对骚扰、仇恨言论、色情、危险内容的拦截严格度。根据你的应用场景调整。BLOCK_NONE不拦截到BLOCK_ONLY_HIGH仅拦截高风险不等。对于开放应用建议至少设为BLOCK_SOME。INCLUDE_GROUNDING_METADATA当使用联网搜索等工具时是否在流式响应中包含原始的引用元数据。默认false。如果你需要精确知道模型回答引用了哪个网页的哪段内容可以设为true但会增加响应体积。ALLOW_REQUEST_TOOL_CONTROL是否允许单个API请求中的参数覆盖全局的工具开关设置。通常设为true以便更灵活地控制每次对话。6.2 内置调试端点Worker提供了几个有用的调试端点帮助你排查问题GET /v1/debug/cache查看当前KV中缓存的令牌信息。如果返回null或过期的expiry_date说明令牌缓存失效或刷新机制有问题。POST /v1/token-test专门测试OAuth2令牌的有效性不涉及模型调用。这是诊断认证问题的第一步。POST /v1/test完整的端到端测试会尝试调用一次Gemini API。你可以直接用curl调用它们# 检查缓存 curl -H Authorization: Bearer sk-your-key https://你的Worker地址/v1/debug/cache # 测试令牌 curl -X POST -H Authorization: Bearer sk-your-key https://你的Worker地址/v1/token-test6.3 常见问题与解决方案实录在我部署和使用的过程中遇到了不少典型问题这里汇总一下问题一部署后访问/v1/models返回401 Unauthorized。排查步骤确认你是否在环境变量或Secrets中设置了OPENAI_API_KEY。如果设置了你的请求必须携带Authorization: Bearer 你的key请求头。如果没设置Key却返回401检查Worker代码是否最新早期版本可能有默认认证逻辑。使用/v1/token-test端点看是否是OAuth2凭证 (GCP_SERVICE_ACCOUNT) 本身无效。问题二请求长时间无响应最终超时或返回5xx错误。可能原因令牌刷新失败这是最常见的原因。Google的refresh_token可能因长时间未使用、授权被撤销或原始OAuth客户端问题而失效。Gemini API配额用尽或服务暂时不可用。解决方案调用/v1/debug/cache查看令牌状态。如果expiry_date已过很久说明刷新失败。重新获取凭证最根本的解决方法是回到第一步重新运行gemini-cli登录获取全新的oauth_creds.json然后更新你的GCP_SERVICE_ACCOUNT环境变量或Secret。检查Cloudflare Workers的日志在Dashboard的Workers详情页看是否有详细的错误信息。问题三流式响应 (streamtrue) 时客户端收不到数据或连接过早关闭。排查步骤首先用curl或最简单的脚本测试排除客户端库的问题。检查Worker日志看是否在转发Gemini流时出错。注意Gemini API本身可能有响应延迟特别是在开启思考模式或处理复杂任务时。确保你的客户端设置了合理的超时时间如60秒以上。问题四提示“Project ID not found”或类似错误。解决方案在环境变量中显式设置GEMINI_PROJECT_ID。这个ID可以从你的Google Cloud控制台获取或者有时会包含在oauth_creds.json的scope字段中形如https://www.googleapis.com/auth/cloud-platform/projects/your-project-id。保持服务健康的建议定期检查可以设置一个简单的cron job每周调用一次/v1/models来“唤醒”服务确保令牌刷新机制正常运行。监控用量关注Cloudflare Workers的请求次数和Gemini API的用量如果Google Cloud项目有配额的化避免意外超额。版本更新关注项目GitHub仓库的更新及时获取Bug修复和新功能支持。这个gemini-cli-openaiWorker项目将一个复杂的企业级API网关问题通过巧妙的架构和Cloudflare的无服务器平台简化成了一个几乎可以一键部署的解决方案。它不仅仅是一个“翻译器”更是一个配备了智能令牌管理、故障降级、多模态支持的生产就绪组件。无论你是想快速体验Gemini 2.5的强大能力还是为现有产品寻找一个稳定、兼容的AI后端它都提供了一个极其优雅的路径。