15分钟部署Cloudflare Worker，让OpenAI生态无缝调用Gemini 2.5模型

1. 项目概述与核心价值如果你和我一样既想用上 Google 最新最强的 Gemini 2.5 Pro/Flash 模型又不想被 OpenAI 的 API 格式和生态绑死那这个项目绝对值得你花上十分钟了解一下。GewoonJaap/gemini-cli-openai 本质上是一个部署在 Cloudflare Workers 上的“翻译官”它能把标准的 OpenAI API 请求无缝转换成对 Google Code Assist API 的调用并且帮你自动处理好最麻烦的 OAuth2 认证和令牌管理。这意味着什么意味着你手头所有那些为 OpenAI 设计的工具——无论是 VS Code 里的 Cline 助手、开源的 Open WebUI 聊天界面还是你项目里用到的 OpenAI SDK——现在都能直接对接 Google 的 Gemini 系列模型了。你不需要改一行客户端代码只需要把 API 的 Base URL 指向你部署的这个 Worker 地址就行。对于开发者来说这极大地降低了接入成本对于普通用户这意味着你可以用自己习惯的客户端免费或低成本地体验到 Gemini 2.5 系列模型强大的推理和视觉能力。这个项目的核心价值在于“兼容”和“简化”。它没有重新发明轮子而是巧妙地利用 Cloudflare Workers 的边缘计算能力和 Google 官方 Gemini CLI 的认证流程搭建了一座高效的桥梁。我实测下来从克隆代码到部署完成整个过程不到 15 分钟之后就能在各种场景下稳定调用 Gemini 了。下面我就结合自己的部署和使用经验把这个项目的里里外外、从原理到避坑给你彻底讲明白。2. 核心原理与架构拆解2.1 为什么需要这个“翻译层”OpenAI 的 API 设计已经成为事实上的行业标准无数客户端、库和工具都围绕其接口规范构建。而 Google 的 Gemini API尽管功能强大但其原生接口无论是 Vertex AI 还是 Code Assist API在请求格式、响应流、函数调用等方面都与 OpenAI 存在差异。直接让现有生态迁移成本太高。这个 Worker 项目所做的就是实现了一个完整的协议适配器。它监听标准 OpenAI 格式的/v1/chat/completions等端点然后将接收到的messages数组、stream参数、tools定义等按照 Gemini API 的规范进行映射和转换。例如OpenAI 的system角色消息在这里会被巧妙地转换成 Gemini 能理解的提示词前缀OpenAI 格式的function_call也会被转换成 Gemini 的functionCall结构。更重要的是认证部分。Google 的 Code Assist API 通常使用 OAuth2 流程需要管理 access_token 和 refresh_token。这个 Worker 内置了一套智能的令牌缓存机制利用 Cloudflare 的 KV 存储来持久化令牌自动处理刷新对客户端完全透明。你只需要在初始化时提供一次通过官方 Gemini CLI 获取的凭证后续所有繁琐的认证工作都由 Worker 在后台完成。2.2 技术栈与工作流剖析项目基于 Hono 框架构建这是一个专为边缘环境如 Cloudflare Workers设计的高性能 Web 框架。选择 Hono 而非更常见的 Express主要是出于对边缘函数环境的深度优化其轻量级和快速的路由匹配在 Workers 的受限环境中表现更佳。整个请求的生命周期如下请求接收与验证Worker 接收到一个 HTTP POST 请求到/v1/chat/completions。它首先会检查是否配置了OPENAI_API_KEY如果配置了则验证请求头中的Authorization: Bearer key是否匹配。令牌获取与刷新Worker 会尝试从绑定的 Cloudflare KV 命名空间GEMINI_CLI_KV中读取缓存的 Google OAuth2 access_token。如果缓存不存在或已过期则使用环境变量GCP_SERVICE_ACCOUNT中存储的 refresh_token 向 Google 认证服务器申请新的 access_token并将新令牌更新到 KV 缓存中。这个过程对用户完全无感。请求格式转换将 OpenAI 格式的请求体进行解析和转换。这包括角色映射user,assistant,system- Gemini 对应的消息角色。内容处理支持多模态内容文本、图片 URL 或 base64 图片数据。参数映射如temperature,max_tokens等通用参数。工具调用转换将 OpenAI 的tools数组转换为 Gemini 的tools声明。调用 Gemini API使用获取到的有效 access_token向 Google 的 Code Assist API 发起请求。这里使用的是https://codeassistant.googleapis.com/v1alpha/models/{model}:streamGenerateContent端点以支持流式响应。响应流式转换与回传将 Gemini API 返回的 Server-Sent Events (SSE) 流进行实时解析并按照 OpenAI 的流式响应格式data: {...}重新封装然后逐块发送回客户端。这保证了客户端如 ChatGPT 界面或 OpenAI SDK能够以熟悉的方式处理流式输出。高级功能处理在此过程中还会根据环境变量处理一些高级功能例如“思考模式”Thinking。如果开启了ENABLE_REAL_THINKING并且用户请求中包含了include_reasoning: trueWorker 会特别处理 Gemini 返回的“推理”内容块将其放入 OpenAI 响应格式的reasoning字段中或者根据STREAM_THINKING_AS_CONTENT设置将其包装在thinking标签内作为普通内容流式输出。实操心得理解 KV 的作用Cloudflare KV 在这里不是可选项而是必需品。因为 Cloudflare Workers 是无状态的每次请求都可能被路由到不同的实例。如果没有 KV 来持久化存储刷新后的 access_token那么每个新实例都需要重新走一遍完整的 OAuth2 刷新流程这会带来严重的延迟和潜在的速率限制问题。KV 充当了一个共享的、低延迟的令牌缓存是保证性能的关键。3. 从零开始的完整部署指南3.1 前期准备与环境检查在开始敲命令之前确保你的环境已经就绪。你需要三样东西一个 Google 账号这个账号需要能够正常访问 Gemini 的相关服务如 Gemini Advanced 或 Google AI Studio。通常一个普通的个人 Google 账号即可。一个 Cloudflare 账号前往 Cloudflare 官网 注册。你需要启用 Workers 服务。好消息是Cloudflare 提供了免费的每日请求额度对于个人和小规模使用完全足够。Node.js 和 npm确保你的本地开发环境安装了 Node.js建议 LTS 版本和 npm。这是运行 Wrangler CLICloudflare 的官方部署工具和项目脚本的基础。打开你的终端先检查一下基础环境node --version # 应输出 v18.0.0 或更高 npm --version # 应输出 8.x 或更高如果版本过低建议使用nvm(Node Version Manager) 来安装和管理 Node.js 版本。接下来安装 Cloudflare 的官方命令行工具 Wranglernpm install -g wrangler安装完成后运行wrangler --version确认安装成功然后登录你的 Cloudflare 账号wrangler login这个命令会打开浏览器引导你授权 Wrangler 访问你的 Cloudflare 账户。3.2 获取核心凭证Google OAuth2 令牌这是整个部署过程中最关键、也最容易出错的一步。项目依赖于通过 Google 官方 Gemini CLI 获取的 OAuth2 凭证。不要尝试手动去 Google Cloud Console 创建服务账号或 OAuth 客户端那样获取的凭证格式和权限与 Code Assist API 所需的不匹配。步骤一安装官方 Gemini CLInpm install -g google/gemini-cli步骤二运行 CLI 并登录直接在终端输入gemini第一次运行它会提示你进行认证。选择● Login with Google选项。此时你的默认浏览器会自动打开一个 Google 的登录授权页面。使用你准备好的 Google 账号登录并授予必要的权限。步骤三定位凭证文件授权成功后Gemini CLI 会在你的用户目录下生成一个配置文件其中就包含了我们需要的 OAuth2 令牌。根据你的操作系统文件路径如下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 对象的内容从第一个{到最后一个}。稍后我们会把它整个设置为环境变量。避坑指南凭证文件找不到或内容不对文件不存在确保你成功运行了gemini命令并完成了浏览器登录流程。有时 CLI 可能不会在首次运行时立即创建文件尝试在 CLI 里输入一个问题并等待回答然后再检查目录。内容只有access_token如果文件里只有access_token而没有refresh_token说明认证流程可能不完整。refresh_token是长期有效的关键没有它令牌过期后就无法自动刷新。解决方法是删除~/.gemini/目录重新运行gemini并登录确保勾选了所有请求的权限范围。权限不足错误后续部署后如果出现 403 错误可能是你的 Google 账号没有访问 Gemini API 的权限。尝试在浏览器中访问 https://makersuite.google.com/app/apikey 如果能正常进入并看到 API 密钥页面说明账号是没问题的。3.3 部署 Worker 到 Cloudflare步骤一获取项目代码git clone https://github.com/GewoonJaap/gemini-cli-openai.git cd gemini-cli-openai npm install步骤二创建 KV 命名空间KV (Key-Value) 存储是 Cloudflare 提供的全球分布式低延迟存储用于缓存我们的 OAuth2 令牌。wrangler kv namespace create GEMINI_CLI_KV执行成功后命令行会返回一个长的 ID格式如xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。记下这个 ID。步骤三配置wrangler.toml用编辑器打开项目根目录下的wrangler.toml文件。找到kv_namespaces部分将其替换为你的 KV 命名空间 IDkv_namespaces [ { binding GEMINI_CLI_KV, id 这里填入你刚才记下的ID } ]binding的名字GEMINI_CLI_KV是代码里引用这个存储的变量名不要修改。步骤四配置环境变量在项目根目录下创建一个名为.dev.vars的文件注意开头有个点。这个文件用于本地开发时的环境变量。将你从oauth_creds.json里复制的完整 JSON 粘贴进去并设置一个可选的 API 密钥# .dev.vars GCP_SERVICE_ACCOUNT{access_token:ya29...,refresh_token:1//...,scope:...,token_type:Bearer,id_token:eyJ...,expiry_date:1750927763467} # 可选设置一个 API 密钥来保护你的端点如果不设置你的 Worker 将对互联网公开 OPENAI_API_KEYsk-你自己生成的一串随机密钥OPENAI_API_KEY的值你可以随意设置比如用openssl rand -hex 32生成一个 64 位的随机字符串前面加上sk-前缀以符合 OpenAI 的格式习惯。步骤五部署到生产环境首先将敏感的环境变量设置为 Cloudflare Worker 的“秘密”这样它们就不会出现在代码仓库中# 设置 OAuth2 凭证 wrangler secret put GCP_SERVICE_ACCOUNT # 粘贴你的完整 JSON 字符串然后按 CtrlD (Mac/Linux) 或 CtrlZ (Windows) 结束输入 # 设置 API 密钥如果之前配置了 wrangler secret put OPENAI_API_KEY # 输入你的密钥如 sk-abc123...然后按结束输入快捷键现在运行部署命令npm run deployWrangler 会打包你的代码并将其推送到 Cloudflare 的边缘网络。部署成功后你会看到类似这样的输出➜ gemini-cli-openai git:(main) ✗ npm run deploy ... Uploaded gemini-cli-openai (2.34 sec) Published gemini-cli-openai (0.57 sec) https://gemini-cli-openai.你的子域名.workers.dev这个https://gemini-cli-openai.你的子域名.workers.dev就是你的 API 端点地址。记下它。3.4 验证部署与初步测试部署完成后强烈建议先进行简单的连通性测试确保一切就绪。测试一列出可用模型使用curl命令调用/v1/models端点这不需要OPENAI_API_KEY如果你没设置的话curl https://gemini-cli-openai.你的子域名.workers.dev/v1/models如果返回一个包含gemini-2.5-pro等模型的 JSON 列表说明 Worker 基础服务是正常的。测试二发送一个简单的聊天请求curl -X POST https://gemini-cli-openai.你的子域名.workers.dev/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gemini-2.5-flash, messages: [ {role: user, content: Hello, say something short.} ] }如果返回了正常的 JSON 响应恭喜你部署成功了如果遇到 401/403 错误请跳转到后面的“故障排查”章节。4. 高级功能配置与实战应用4.1 思考模式Thinking的深度解析与配置Gemini 2.5 系列模型最大的亮点之一就是其“思考”能力。这个 Worker 项目提供了两种方式来利用这个能力你需要根据你的使用场景来选择。1. 真实思考模式这是最强大的模式直接调用 Gemini 模型内部的推理链条。要启用它你需要设置环境变量# 在 .dev.vars (开发) 或通过 wrangler secret put (生产) 设置 ENABLE_REAL_THINKINGtrue启用后在发送请求时需要在请求体中加入include_reasoning: true参数。你还可以通过thinking_budget参数来控制模型用于“思考”的令牌预算。-1: 默认由模型动态分配。0: 禁用思考。正整数如1024限制思考过程使用的最大令牌数。使用示例 (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: 解方程: x^2 - 5x 6 0}], extra_body{ # 注意OpenAI Python SDK 使用 extra_body 传递非标准参数 include_reasoning: True, thinking_budget: 2048 }, streamTrue ) for chunk in response: # 真实思考内容会出现在 reasoning 字段 if hasattr(chunk.choices[0].delta, reasoning) and chunk.choices[0].delta.reasoning: print(f[模型思考中] {chunk.choices[0].delta.reasoning}, end) # 最终答案出现在 content 字段 if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end)在这种模式下思考过程和最终答案是分开流式传输的reasoning字段专门承载模型的内部推理。2. 伪思考模式与 DeepSeek R1 风格流有些客户端或工具比如一些集成了 DeepSeek R1 模型的开源前端可能无法正确解析reasoning字段。为此项目提供了另一种兼容方案。首先设置环境变量ENABLE_FAKE_THINKINGtrue STREAM_THINKING_AS_CONTENTtrueENABLE_FAKE_THINKING会让模型在回答前先“假装”生成一段思考文字实际上是由 Worker 模拟的。而STREAM_THINKING_AS_CONTENTtrue是关键它会把思考内容无论是真实的还是模拟的包装在thinking和/thinking标签内作为普通的content流式输出。这种模式的优势在于兼容性极佳。像 LiteLLM 这样的代理层或者一些定制的前端可以直接把thinking.../thinking之间的内容渲染为思考过程把之后的内容渲染为最终答案用户体验非常连贯。项目还做了优化/thinking结束标签只会在真正的 LLM 响应开始时才发送避免了思考结束和回答开始之间的尴尬停顿。4.2 模型自动降级与工具调用集成自动模型降级Gemini 2.5 Pro 模型虽然强大但可能有速率限制。如果你在请求gemini-2.5-pro时遇到 429请求过多或 503 错误可以启用自动降级功能。ENABLE_AUTO_MODEL_SWITCHINGtrue启用后Worker 在遇到上述错误时会自动将请求重试到gemini-2.5-flash模型并在响应中插入一条通知信息。这保证了服务的可用性对于非关键任务或需要快速响应的场景非常有用。原生工具调用项目支持将 OpenAI 格式的工具函数定义映射到 Gemini 的原生函数调用。这需要通过环境变量开启ENABLE_GEMINI_NATIVE_TOOLStrue # 还可以开启具体的工具如谷歌搜索 ENABLE_GOOGLE_SEARCHtrue ENABLE_URL_CONTEXTtrue开启后你可以在请求中按照 OpenAI 的格式定义tools模型就能在需要时“调用”这些工具。你还可以通过GEMINI_TOOLS_PRIORITY环境变量来控制当 Gemini 原生工具和你自定义的工具冲突时优先使用哪一个。4.3 与现有生态的无缝集成这是本项目最实用的部分。下面以几个最常用的工具为例集成 Open WebUI打开 Open WebUI 的设置 - 模型供应商。点击 “Add new provider”选择 “OpenAI”。在 “API Base URL” 中填入你的 Worker 地址如https://gemini-cli-openai.你的子域名.workers.dev/v1。在 “API Key” 中填入你在OPENAI_API_KEY中设置的密钥如果设置了的话。保存后回到模型页面点击 “Discover models”Open WebUI 会自动从你的/v1/models端点拉取可用的模型列表gemini-2.5-pro, gemini-2.5-flash 等。选择模型现在你就可以在漂亮的 Open WebUI 界面里直接和 Gemini 对话了支持流式输出、图片上传视觉、历史记录等所有功能。集成 VS Code Cline 插件在 VS Code 中安装 Cline 插件。打开 VS Code 设置 (JSON 模式)添加或修改以下配置{ cline.apiBaseUrl: https://gemini-cli-openai.你的子域名.workers.dev/v1, cline.apiKey: sk-你的密钥, cline.model: gemini-2.5-flash, // 或 gemini-2.5-pro cline.apiProvider: openai }重启 VS Code现在 Cline 就会使用你部署的 Gemini Worker 来提供代码补全和建议了。集成 LiteLLM 代理 LiteLLM 是一个强大的 LLM 调用统一层。在你的 LiteLLM 配置或代码中import litellm litellm.api_base https://gemini-cli-openai.你的子域名.workers.dev/v1 litellm.api_key sk-你的密钥 # 现在你可以用 litellm.completion 统一调用 Gemini 了 response litellm.completion( modelgemini-2.5-pro, messages[...], streamTrue )特别提示如果你启用了STREAM_THINKING_AS_CONTENTtrue来获得 DeepSeek R1 风格的思考流LiteLLM 能很好地处理这种格式并将其传递给下游的应用。5. 常见问题排查与性能优化5.1 部署与认证问题问题部署后访问返回 401 Unauthorized 或 403 Forbidden。检查 OAuth2 凭证这是最常见的问题。运行wrangler secret list确认GCP_SERVICE_ACCOUNT已设置。然后通过 Worker 的调试端点检查令牌状态curl https://你的worker地址/v1/debug/cache如果返回null或错误信息说明 KV 缓存未正确写入或凭证无效。尝试重新执行wrangler secret put GCP_SERVICE_ACCOUNT并确保粘贴的是完整的、正确的 JSON 字符串没有多余的空格或换行。检查 KV 绑定确认wrangler.toml中的kv_namespaces的id是否正确。你可以运行wrangler kv namespace list来查看你账户下所有的 KV 命名空间及其 ID。检查 Google 账号权限确保你用来登录 Gemini CLI 的 Google 账号确实有权限访问 Gemini API。可以尝试在浏览器中直接用该账号访问 Google AI Studio 看是否能正常使用。问题请求速度慢首次响应延迟高。冷启动与令牌缓存Cloudflare Workers 在长时间无请求后会有“冷启动”。如果你的 KV 缓存中的令牌也已过期Worker 需要先刷新令牌再处理请求这会导致首次请求较慢可能 2-3 秒。后续请求会直接使用缓存的有效令牌速度很快通常 500ms。这是正常现象。你可以设置一个简单的定时任务如每分钟调用一次/v1/models来保持 Worker 实例和令牌的“温暖”。5.2 功能使用问题问题开启了ENABLE_REAL_THINKING但请求中没有收到reasoning字段。检查请求参数确保你在请求体中明确传递了include_reasoning: true。注意在 Python OpenAI SDK 中这个非标准参数需要放在extra_body字典里。检查模型支持确认你使用的模型是支持思考的如gemini-2.5-pro或gemini-2.5-flash。早期的 Gemini 1.5 模型可能不支持。检查环境变量通过wrangler secret list确认ENABLE_REAL_THINKING已正确设置为true包括引号。问题图片上传视觉功能不工作。检查模型确保你使用的模型支持视觉如gemini-2.5-flash或gemini-2.5-pro。检查图片格式Base64 编码的图片数据 URL 格式必须正确data:image/jpeg;base64,你的base64编码。确保data:后的 MIME 类型如image/jpeg,image/png与实际图片格式匹配并且 base64 部分没有换行符。使用 URL 替代如果 base64 有问题可以尝试先将图片上传到一个可公开访问的图床然后在请求中使用图片 URL。注意某些 URL 可能被 Google 服务器屏蔽。问题流式响应streamtrue时客户端收不到数据或连接中断。检查 SSE 实现确保你的客户端能正确处理 Server-Sent Events。流式响应以data: {...}的格式发送最后以data: [DONE]结束。一些简单的 HTTP 库可能不会自动处理这种格式。检查 Cloudflare 超时设置Cloudflare Workers 默认有执行时间限制如 30 秒。对于非常长的对话或复杂的思考任务模型响应时间可能超时。虽然这个 Worker 本身是流式转发但如果 Gemini API 端响应太慢也可能导致问题。对于长文本生成可以考虑适当降低max_tokens。5.3 性能与成本优化建议选择合适的模型gemini-2.5-flash在绝大多数任务上响应速度远快于gemini-2.5-pro且成本如果涉及计费更低。仅在需要深度推理、复杂代码生成或极高准确度的任务时使用 Pro 模型。善用自动降级开启ENABLE_AUTO_MODEL_SWITCHINGtrue。这样当 Pro 模型遇到限流时可以自动无缝切换到 Flash 模型保证服务连续性。管理思考预算如果启用了真实思考为thinking_budget设置一个合理的值如 1024 或 2048而不是使用默认的-1动态分配。这可以防止模型在简单问题上进行过度的、消耗令牌的“内心戏”从而加快响应速度并节省令牌。监控用量与缓存定期检查你的 Worker 的请求次数和 KV 存储的读取次数。Cloudflare 免费套餐有每日限额。确保你的OPENAI_API_KEY足够复杂避免被他人滥用。KV 缓存能有效减少对 Google 认证服务器的调用既快又省。本地开发与测试在大量测试或开发时使用npm run dev在本地运行 Worker。这不会消耗 Cloudflare 的请求额度并且可以开启详细的日志输出方便调试。部署并熟练使用这个工具后你会发现它就像在你的现有 AI 工作流中打开了一扇新的大门。原本封闭的 OpenAI 生态现在可以自由地接入 Google 最前沿的模型能力。无论是用于代码辅助、内容创作、学术研究还是日常问答多一个强大且免费或低成本的选择总是一件好事。最关键的是整个过程完全掌握在你自己的手中数据经由你部署的 Worker 中转在隐私和可控性上也多了一份保障。如果在使用中遇到任何本文未覆盖的奇怪问题不妨去项目的 GitHub 仓库翻翻 Issues或者自己动手研究一下代码毕竟开源项目的魅力就在于此。