MuxLLM
开始使用

Client Guide · Gemini

Gemini CLI

使用 Gemini API Key 认证和 Gemini 原生协议连接 MuxLLM。只选择模型广场明确显示 gemini 标签的模型。

开始配置核对模型标签

Scope & Evidence

自定义根地址只适用于 Gemini API Key 路线

GOOGLE_GEMINI_BASE_URL 是 Gemini CLI 当前官方支持的 Gemini API 根地址覆盖变量，并且只在 gemini-api-key 认证模式下生效。本教程不使用 Google 登录、Vertex AI、Cloud Shell 或 Code Assist 端点。

等级本页状态含义
E1运行态公开信息已核对目标模型必须带 gemini 标签，原生根地址为 https://api.muxllm.com。
E2Gemini CLI 官方文档已核对安装包、API Key 认证、根地址变量、用户配置路径与 model.name 已复核。
E3本批未执行没有启动 Gemini CLI 或使用真实 Key 调用 MuxLLM。

最后核验日期：2026-07-18。若客户端版本没有读取该变量，应先升级并对照当前官方配置参考，不能通过改写系统 DNS 或不明代理绕过。

Install

选择一种官方安装方式

  1. 确认本机 Node.js 版本满足 Gemini CLI 当前官方要求。
  2. 临时体验可使用 npx；长期使用可安装稳定版。不要同时保留多个来源的旧版本。
  3. 安装后执行 gemini --version，并记录 command -v gemini 返回的实际路径。
  4. 已有配置时，先备份 ~/.gemini/settings.json 与 ~/.gemini/.env。
无需全局安装
npx @google/gemini-cli
安装稳定版
npm install -g @google/gemini-cli@latest
gemini --version
发布通道官方还提供 preview 与 nightly 通道，但它们可能包含尚未完全验证的改动。用于 MuxLLM 接入时优先稳定版，升级后重新做最小请求验证。

Credential & Model

创建独立 Key，并筛选 gemini 标签

  1. 在 MuxLLM 控制台创建仅供 Gemini CLI 使用的独立 Key，设置合理额度和过期时间。
  2. 在模型广场复制一个带 gemini 标签的精确模型 ID。
  3. 不要因为模型名称含 Gemini、Banana 或厂商名就推断它支持 Gemini 原生协议。
  4. 本页示例只使用 YOUR_API_KEY 与 MODEL_NAME；执行时在本地替换，不在截图或日志中展示真实值。
模型动态性模型清单、上下文、分组和价格会变化。本页不固定默认模型，执行时始终以模型广场的精确 ID 与 gemini 标签为准。

Session Setup

先在当前终端临时配置

临时变量便于回滚。根地址只写站点域名，不手工追加 /v1beta 或具体方法路径；Gemini CLI 与 SDK 会根据请求拼接原生路径。

macOS / Linux Shell
export GEMINI_API_KEY="YOUR_API_KEY"
export GOOGLE_GEMINI_BASE_URL="https://api.muxllm.com"

gemini
Windows PowerShell
$env:GEMINI_API_KEY="YOUR_API_KEY"
$env:GOOGLE_GEMINI_BASE_URL="https://api.muxllm.com"

gemini
认证选择首次启动若出现认证选择，使用 Gemini API Key 路线。Google 登录或 Vertex AI 使用其他端点与凭证，不会按本教程读取 MuxLLM Key。

Persistent Setup

模型写入 settings，密钥留在秘密环境

Gemini CLI 用户级设置位于 ~/.gemini/settings.json。模型可持久化到 model.name；凭证优先由系统秘密管理器或安全环境注入。

~/.gemini/settings.json
{
  "model": {
    "name": "MODEL_NAME"
  }
}
~/.gemini/.env（占位示例）
GEMINI_API_KEY="YOUR_API_KEY"
GOOGLE_GEMINI_BASE_URL="https://api.muxllm.com"
  1. 修改前备份两个文件，确保 JSON 可解析且没有重复键。
  2. ~/.gemini/.env 必须仅当前用户可读，不得放进项目或云同步目录。
  3. 如果系统已有更高优先级的同名变量，先清理冲突再重新启动 CLI。
  4. 不要设置 GOOGLE_VERTEX_BASE_URL；那是 Vertex AI 路线，与本教程无关。

Acceptance

确认最终请求走 Gemini 原生路径

  1. 01本地版本

    gemini --version 返回预期稳定版，执行路径唯一。

  2. 02模型与认证

    界面显示 MODEL_NAME，认证方式为 Gemini API Key。

  3. 03短文本请求

    发送最短文本，不启用工具、文件修改、MCP 或长上下文。

  4. 04控制台核对

    确认请求进入独立 Key；最终路径应属于 /v1beta/models/... 原生路线。

E3 尚未执行短文本请求会消耗额度。本批文档工作没有运行 Gemini CLI，也没有验证真实模型输出。

Rollback

恢复设置并清理变量

  1. 退出 Gemini CLI，恢复 settings.json 与 .env 的执行前备份。
  2. 若只增加了 model.name，可精确删除该字段，避免覆盖其他已有设置。
  3. 清理当前终端的 GEMINI_API_KEY 和 GOOGLE_GEMINI_BASE_URL，并从持久环境删除相同行。
  4. 不再使用时停用独立 Key；切回 Google 登录或 Vertex AI 前，按官方认证文档清理冲突变量。
macOS / Linux 清理当前会话
unset GEMINI_API_KEY
unset GOOGLE_GEMINI_BASE_URL

Troubleshooting

401、404、429 与认证模式冲突

现象优先检查处理顺序
401 / 403Key 无效、认证模式不是 Gemini API Key、旧 Google 凭证覆盖退出 CLI → 清理冲突认证 → 重新注入独立 Key → 检查 Key 状态。
404根地址附加了 /v1 或 /v1beta，或模型没有 gemini 标签根地址恢复为域名 → 从模型广场重新复制 ID。
429余额、Key 额度、渠道并发或上游限速停止连续重试，查看错误详情与控制台用量，按建议等待。
变量被忽略客户端过旧、认证模式错误、系统和 .env 存在冲突值核对版本 → 查看变量优先级 → 在新终端使用最小配置复测。
model not foundmodel.name 拼写、分组权限或原生协议不匹配删除别名和厂商前缀，使用模型广场精确 MODEL_NAME。

Security

把 CLI 工具权限与 API 凭证分开

  • 独立 Key 使用最小额度和有效期，不与浏览器应用、服务端或其他 CLI 共用。
  • 用户级 .env 设置仅当前用户可读；项目目录中的 .env 不应保存本 Key。
  • 初次验证关闭不必要的工具和自动批准，先确认文本协议、模型和计费。
  • 不要把提示词、文件内容、Key、完整请求或个人路径放进公开日志。
  • 疑似泄露时先停用 Key；仅删除本地文件不能撤销已复制的凭证。

Next Guide

继续查看 OpenClaw

OpenClaw 通过自定义 Provider 接入，当前仅提供可执行候选配置，并明确保留未实测状态。

下一篇：OpenClaw上一篇：Codex