Models Hub
接入 Agent 工具

Gemini CLI 接入 Models Hub:一键配置与手动设置

用 Models Hub CLI 一条命令配置 Gemini CLI,或手动编辑 settings.json 与 .env 接入 Google Gemini 系列模型,附验证步骤与常见报错排查。

编辑此页

Gemini CLI 是 Google 官方的终端 AI 编码助手。把它的鉴权方式切到 API Key 并指向 Models Hub 后,gemini 里的对话与代码修改都会用 Models Hub 的额度调用你指定的模型。本文只讲接入,不讲 Gemini CLI 本身的用法。

三样东西

接入只需要:Models Hub 的 API Key、接入地址 https://modelsok.com、一个模型名。推荐先用一键配置,30 秒完成。

准备

  • 已安装 Gemini CLI。没装的话按 官方安装说明 运行 npm install -g @google/gemini-cli,装完 gemini --version 能出版本号即可。
  • 一个 Models Hub API Key。在控制台的 令牌页 创建,令牌所在分组要能访问你打算用的模型。

推荐模型

Gemini CLI 走的是 Gemini 原生协议,推荐使用 Models Hub 上的 Gemini 系列模型:

用途模型名定价实时状态
日常编码首选gemini-3.1-pro-preview查看价格可用率与延迟
更快更省,适合小改动与批量任务gemini-3.5-flash查看价格可用率与延迟
稳定版,追求可预期行为时用gemini-3.1-pro查看价格可用率与延迟

模型名以 模型定价页 为准,新模型上线后名字会变。如果你想在 Gemini CLI 里改用 Claude 或 GPT 系列模型,把 GEMINI_MODEL 换成定价页上的对应名称即可尝试,Models Hub 网关是否会做协议转换以你的实测结果为准。

方式一:一键配置(推荐)

Models Hub CLI 会把 API Key、接入地址和默认模型写入 ~/.gemini/settings.json 与 ~/.gemini/.env。

macOS / Linux:

curl -fsSL https://modelsok.com/cli/install.sh | sh

Windows(PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://modelsok.com/cli/install.ps1 | iex"

装好后运行 models,在交互菜单里选择 Gemini CLI,按提示粘贴 API Key、选模型即可;也可以用 models configure --target gemini --api-key <你的_API_KEY> --yes 免交互配置。默认模型是 gemini-3.1-pro-preview,想换成其它模型可以在交互时选,或用 --gemini-model 指定。完整用法见 CLI 一键配置。

方式二:手动配置

编辑或新建 ~/.gemini/settings.json,启用 API Key 鉴权:

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  },
  "model": {
    "name": "gemini-3.1-pro-preview"
  }
}

再编辑或新建 ~/.gemini/.env:

GEMINI_API_KEY=你的 Models Hub API Key
GEMINI_MODEL=gemini-3.1-pro-preview
GOOGLE_GEMINI_BASE_URL=https://modelsok.com
变量/字段作用
security.auth.selectedType鉴权方式,gemini-api-key 表示用 API Key 而不是 Google 账号登录
GEMINI_API_KEY你的 Models Hub API Key
GEMINI_MODEL默认模型名
GOOGLE_GEMINI_BASE_URL接入地址,不要加 /v1

以当前版本行为为准

GOOGLE_GEMINI_BASE_URL 最初是社区用来把 Gemini CLI 指向自定义端点的做法,官方文档没有为「API Key + 自定义地址」这个组合单独成文,不同版本行为可能有差异。改完先按下面的验证步骤确认真的接通了。

验证

重新打开终端,在任意项目目录运行 gemini,输入一句话,例如「用一句话介绍当前目录」。能正常回复即接通。再打开 Models Hub 控制台的 用量日志,几秒内会出现一条对应模型名的请求。

常见报错

现象原因处理
401 / 鉴权失败Key 写错、多了空格,或令牌已被禁用到 令牌页 重新复制;一键配置的话重新运行一次 models
改了配置没生效读到的不是当前用户目录下的文件,或终端没重开确认 ~/.gemini/settings.json 与 ~/.gemini/.env 路径正确,重开终端
model not found / 无可用渠道模型名拼错,或令牌所在分组没有该模型对照 定价页 核对名字
请求还是打到了 Google 官方地址selectedType 没设成 gemini-api-key,或走了 OAuth 登录态检查 settings.json 的 security.auth.selectedType
429触发限流,通常是并发过高稍后重试;持续出现联系客服提额

更多排查见 故障排查。

常见问题

计费方式? 按请求实际消耗的输入与输出 token 计费,价格在各模型的定价页,用量日志里能看到每一条请求的明细。

和直接用 Google 官方账号有什么区别? 配置后 Gemini CLI 的所有请求都会走 Models Hub 接入点,不再消耗 Google 账号的免费额度或订阅;你不需要 Google AI Studio 账号。

怎么切换模型? 重新运行 models configure --target gemini --api-key <你的_API_KEY> --gemini-model <model-id> --yes,或手动修改 .env 里的 GEMINI_MODEL 和 settings.json 中的 model.name。

相关

Codex CLI 接入 Models Hub:一键配置与 config.toml

用 Models Hub CLI 一条命令配置 Codex CLI,或手动编辑 ~/.codex/config.toml 添加自定义模型供应商,附验证步骤与常见报错排查。

Copilot CLI 接入 Models Hub:BYOK 环境变量配置

用 BYOK 环境变量把 GitHub Copilot CLI 指向 Models Hub,推荐 anthropic 协议类型避免推理模型报错,附验证步骤与常见报错排查。

本页目录

准备推荐模型方式一:一键配置(推荐)方式二:手动配置验证常见报错常见问题相关