← Voltar aos guias

Gemini CLI 接入统一中转：从环境变量到排错实战

先理解 Gemini CLI 与中转的关系

Gemini CLI 是在终端中调用 Gemini 模型的工具，适合代码问答、文件分析和自动化任务。所谓“通过统一中转”，并不是简单把任意 API 地址填进去，而是让 CLI 将请求发送到一个兼容 Gemini Developer API 协议的端点，再由中转服务完成鉴权、计费和模型路由。这样做的价值是集中管理密钥、观察用量，并为不同工具选择更合适的模型渠道。

配置前要确认中转商明确支持 Gemini 协议、generateContent 请求和流式输出，并确认其支持的模型名。OpenAI 兼容接口与 Gemini 原生接口不是同一协议：一个仅标注“OpenAI SDK 兼容”的地址，通常不能直接作为 Gemini CLI 的端点使用。

准备密钥与端点

先在支持 Gemini 协议的中转控制台创建 API Key，记录基础地址、是否需要包含 v1beta 路径，以及可用模型列表。不要把密钥写进项目代码、提交到 Git，或放进共享的 shell 历史记录。团队项目应使用本机环境变量、密钥管理工具或 CI 的 Secret 功能保存凭据。

在 macOS 或 Linux 终端中，可先临时设置变量：export GEMINI_API_KEY="你的中转密钥"；export GOOGLE_GEMINI_BASE_URL="https://relay.example.com"。部分服务要求基础地址带有 v1beta，部分服务会自行补齐版本路径，应以中转商文档为准。要长期生效，可将这两项写入 ~/.zshrc 或 ~/.bashrc，再执行 source ~/.zshrc。

Windows PowerShell 可使用：$env:GEMINI_API_KEY="你的中转密钥"；$env:GOOGLE_GEMINI_BASE_URL="https://relay.example.com"。这是当前窗口临时配置；需要长期使用时，应在系统环境变量中新增对应项，并重新打开终端。

启动与验证请求

安装并更新 Gemini CLI 后，在同一个终端启动 gemini。首次运行时，选择 API Key 认证方式，避免同时混用 Google 登录、Vertex AI 和中转密钥。随后用 gemini -p "用一句话说明当前目录的用途" 发起一个小请求。若中转支持指定模型，再按其文档设置模型名称，例如 gemini-2.5-flash 或 gemini-2.5-pro；不要猜测模型 ID。

验证时建议先使用短提示词，再尝试读取一个非敏感的小文件。这样可以分别确认网络连接、鉴权、模型路由和工具权限。成功后，再把 CLI 接入日常开发流程，例如让它解释报错、生成测试思路或总结变更内容。

三个常见问题

• 401 或 403：通常是密钥无效、终端未重新加载环境变量，或中转要求的鉴权格式与 CLI 不兼容。先在新终端检查变量是否存在，再核对控制台中的密钥状态。
• 404 或模型不存在：优先检查基础地址是否错误地重复或遗漏了 v1beta，其次核对模型名是否被该中转支持。
• 429、超时或流式中断：查看账户余额、并发限制和服务状态；将复杂任务拆成更小请求，并确认中转确实支持 Gemini 的流式响应。

把 Gemini 与其他 CLI 放进同一套成本体系

统一管理不代表所有工具必须走同一个协议。Gemini CLI 应使用明确兼容 Gemini 的端点；而 Claude Code、Codex 和基于 OpenAI SDK 的应用，则可使用对应的兼容中转。59API 的 API 基础地址为 https://api.59api.com，面向 Claude Opus、Sonnet、Haiku、Fable 与 GPT 模型提供按量付费访问，并兼容 Claude Code、Codex 和 OpenAI SDK。它采用官方质量模型，适合把代码代理和应用调用的成本集中管理。

在接入 Gemini 前，请先向服务商确认 Gemini 协议支持范围；在 Claude 或 GPT 开发工作流中，则可注册 59API 创建测试密钥，以较低门槛验证统一中转的计费和调用体验。这样既能避免协议不匹配，也能根据任务类型选择合适模型。

Preços · Docs