RuntokenDocs
English打开控制台

Gemini CLI

第 1 版 · 更新于 2026-11-12 · 阅读约 3 分钟

通过 Runtoken 接入 Gemini CLI。

准备工作#

开始前，请准备：

  • 可运行的 Gemini CLI，使用 gemini --version 查看版本；安装方法见官方说明。
  • Runtoken 平台 API Key。
  • 使用原生 Gemini v1beta 接口的准确模型 ID。

连接配置#

在单独的终端中设置以下值。

变量或选项配置值作用
GOOGLE_GEMINI_BASE_URLhttps://api.runtoken.netGemini API 的基础域名，不附加 /v1 或模型路径。
GEMINI_API_KEYYOUR_PLATFORM_KEYAPI Key 鉴权模式使用的平台 Key。
GOOGLE_GENAI_API_VERSIONv1beta指定网关的原生 API 版本。
--modelYOUR_MODEL_ID指定平台模型目录中的准确 ID。

SDK 会在基础域名后拼接版本和模型方法。这与其他客户端使用的 OpenAI 风格 /v1 地址不同。

设置凭据并启动#

在小型测试项目中执行以下命令。它们设置当前终端环境，不会把 Key 写入项目文件。

bash
export GOOGLE_GEMINI_BASE_URL="https://api.runtoken.net"
export GOOGLE_GENAI_API_VERSION="v1beta"
export GEMINI_API_KEY="YOUR_PLATFORM_KEY"
gemini --model "YOUR_MODEL_ID"

将 YOUR_PLATFORM_KEY 替换为平台 Key，YOUR_MODEL_ID 替换为使用 Gemini 协议的准确模型 ID。真实 Key 不应出现在共享文件或截图中，包含它的终端命令也可能保留在历史记录里。

出现鉴权选择时，选择 Use Gemini API key。如果已使用其他模式，通过 /auth 切换到 API Key 路径。凭据或地址意外变化时，检查已有 .env 文件和管理配置，不要为了排查网关请求而删除已有 Google 账号登录信息。

检查连接与文件任务#

发送简短消息，在 Runtoken 中查找对应请求记录，核对模型与时间。收到回答本身不能证明 API Key 网关配置已经生效。

随后在测试项目中尝试以下任务。

检查文件创建与后续修改text
创建 greeting.py，定义 greet(name)，返回 "Hello, " 与 name 拼接后的字符串。
重新读取文件，不安装依赖，也不访问网络。

检查并批准必要的文件操作。在同一会话继续要求：名字为空时返回 "Hello, friend"。阅读实际文件，确认工具结果返回后能够继续完成任务。

能力与限制#

使用明确的平台模型 ID，不要假设 CLI 的自动选模能够映射到你的模型目录。辅助请求可能使用与主对话不同的模型或 API 方法。

功能接入要求
流式对话原生生成请求与 SSE 响应兼容。
文件与命令工具模型支持工具调用，且客户端允许对应操作。
token 计数、上下文压缩与辅助模型支持实际调用的方法和模型。
文件资源、显式缓存和托管搜索平台另行支持，修改基础地址不会自动提供这些能力。

Runtoken 不会将 OpenAI 模型转换成原生 Gemini 模型。遇到请求被拒绝时，不要随意更换 API 版本或工具选项。

排查问题#

结合请求方法与错误响应，定位失败环节。

现象检查方向
仍使用 Google 账号发起请求通过 /auth 核对所选鉴权模式。
401 或 Key 被拒绝核对平台 Key、鉴权模式与继承环境，不打印完整 Key。
404检查基础域名、v1beta、实际请求方法与准确模型 ID。
主对话成功，其他请求失败识别是否调用了辅助模型、token 计数方法或工具。
429按平台返回的限额与重置说明处理。

恢复配置与后续阅读#

关闭测试终端即可清除本次环境设置。如果修改了已保存的鉴权选择，通过 /auth 恢复原有模式，只还原本次变更的设置。

接口说明见 Gemini v1beta，客户端说明见官方鉴权指南与配置参考。

这篇文档有帮助吗？