Gemini CLI 手动配置

大约 7 分钟

Gemini CLI 手动配置

接入结论

接口地址（GOOGLE_GEMINI_BASE_URL）：https://www.yuzhixiaolongxia.com/（末尾有斜杠 /）
认证字段：GEMINI_API_KEY（写入 .env）
令牌分组：Gemini 家族令牌分组
推荐模型 ID：gemini-3.1-pro-preview
模型 ID 查询：模型广场

这篇文档适合谁

适合：会基础命令行、想用 AI 写代码 / 聊天 / 多模态分析的开发者
不适合：完全不会终端的小白——走一键安装包

Gemini CLI 适合做什么

终端里直接跟 AI 对话、写代码、分析问题
长上下文、多模态（看图、看文档）特别能打

前置条件

请先完成环境检查。Node.js ≥ 20 是硬性要求。

极简步骤一览

装好 Gemini CLI（一行 npm install）
在 ~/.gemini/ 下建 .env，粘贴接口地址 + 令牌 + 模型
建 settings.json，告诉它走 API Key 认证
重开终端，跑 gemini 验证

下面是每一步的详细操作。

第一步：安装 Gemini CLI

打开终端，输入：

npm install -g @google/gemini-cli

没有 npm？

说明你还没装 Node.js。先去 https://nodejs.org 下载 LTS 版本，装完再回来。

装完之后验证：

gemini --version

显示了版本号，说明装好了。

第二步：找到配置目录（没有就自己建）

Gemini CLI 的配置文件放在用户主目录下的 .gemini 文件夹里。

Windows

按 Win + R，输入 %USERPROFILE%，回车，打开用户目录（比如 C:\Users\张三）。

.gemini 是隐藏文件夹

资源管理器里默认看不到。要先「查看」→ 勾选「隐藏的项目」才能看见。

在这个目录里找 .gemini 文件夹。没有的话就新建一个（文件夹名 .gemini，前面有个点）。

完整路径长这样：

C:\Users\你的用户名\.gemini\

@tab Mac / Linux

打开终端，输入：

mkdir -p ~/.gemini

Mac 隐藏文件夹

点开头的文件夹在 Finder 里默认也看不到，Cmd + Shift + . 可以切换显示 / 隐藏。

:::

第三步：创建 .env 文件

在 .gemini 目录里新建一个文件，文件名就叫 .env。

特别注意

这个文件名 只有 .env 四个字符，没有其他扩展名。不是 .env.txt，也不是 env.txt。

Windows 用户：创建 .env 的特殊方法

Windows 的记事本不支持直接创建没有扩展名的文件（它会偷偷加 .txt），所以用下面这个办法：

方法一：用命令行创建（推荐，最简单）

打开「命令提示符」，输入（把"你的用户名"换成自己的）：

type nul > C:\Users\你的用户名\.gemini\.env

这条命令会创建一个空的 .env 文件，然后再用记事本打开它填内容。

方法二：用 VS Code 创建

打开 VS Code
菜单「文件」→「打开文件夹」，选中 .gemini 文件夹
左侧点「新建文件」图标，文件名直接输入 .env，回车
VS Code 会问你"这是一个隐藏文件，确定？"，点确定

Mac / Linux 用户

终端里直接跑：

touch ~/.gemini/.env

然后用任意文本编辑器打开它。

第四步：把配置内容填进去

打开 .env 文件，把下面这三行 完整复制粘贴进去：

GOOGLE_GEMINI_BASE_URL=https://www.yuzhixiaolongxia.com/
GEMINI_API_KEY=你的Gemini令牌填这里
GEMINI_MODEL=gemini-3.1-pro-preview

重点：末尾的斜杠 / 不能丢

Gemini CLI 的接口地址 必须以 / 结尾：https://www.yuzhixiaolongxia.com/。这是 Gemini 与其他工具最大的差异——漏了斜杠会导致路径拼接出错。

把 你的Gemini令牌填这里 替换成你的真实令牌。

令牌在哪里找？

新用户不用自己创建

平台为新用户预设了 Gemini 家族令牌分组，登录后到令牌页面直接复制就行。

需要自定义的话，参考：创建令牌教程

必须选对分组

Gemini CLI 只能用 "Gemini 家族令牌分组" 的令牌。Claude / Codex 分组的令牌在这里用不了，会直接 401。

填写注意事项

等号两边不要加空格：不能写成 GEMINI_API_KEY = 你的令牌
令牌不要加引号：直接粘在等号后面，不要写成 "你的令牌"
只填平台令牌：平台只认平台颁发的 sk- 开头令牌
令牌复制时别带多余的空格或换行

粘进去之后保存（Ctrl + S 或 Cmd + S）。

第五步：创建 settings.json 配置文件

有些版本的 Gemini CLI 需要一个额外的 settings.json 来指定认证方式，不然启动时会弹出登录流程。建议直接建好。

在 .gemini 目录里创建 settings.json 文件：

Mac / Linux

touch ~/.gemini/settings.json

Windows

用和创建 .env 一样的方法，在 .gemini 目录里新建 settings.json。

填入以下内容：

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

为什么要这个文件

selectedType: "gemini-api-key" 告诉 Gemini CLI 用 API Key 认证，而不是走账号登录流程。没有这个文件，某些版本会强制你登录。

第六步：重新打开终端，测试一下

必须重开终端

关掉当前的终端窗口，重新打开一个新的。.env 文件是启动时读取的，不重开就不生效。

重开之后输入：

gemini

如果看到 Gemini CLI 的交互界面出来了，配置成功。

成功是什么样子

启动后终端会显示交互界面，类似这样：

Gemini CLI
>

在 > 后面输入问题，比如"你好，介绍一下你自己"，能正常回答就说明配置完全没问题。

失败是什么样子 & 怎么解决

提示 `401 Unauthorized` 或 Gemini CLI 内部弹出授权提示

两种情况，分开处理：

情况一：启动后 Gemini CLI 里弹出 /auth 提示

在 Gemini CLI 的交互界面里，输入：

/auth

按提示填入你的令牌（GEMINI_API_KEY）。这样就能在不退出的情况下重新认证。

情况二：直接报 401 错误

令牌权限不对，或令牌填错了。检查 .env 里的 GEMINI_API_KEY：

确认令牌完整，没截断
确认没有多余的空格或引号
确认用的是 Gemini 家族令牌分组 创建的令牌
还是不行就重新创建一个新令牌再试

提示 `model not found` 或模型找不到

GEMINI_MODEL 字段写错了。对照本页内容检查，确认是 gemini-3.1-pro-preview，没有多余字符。

平台支持模型 ID 智能归一化

常见笔误也能识别，但完整可用模型 ID 还是建议去模型广场查最新。

接口请求路径异常 / 404

最大概率是 GOOGLE_GEMINI_BASE_URL 末尾没有斜杠。检查 .env：

GOOGLE_GEMINI_BASE_URL=https://www.yuzhixiaolongxia.com/

末尾的 / 不能省略。

提示 `gemini: command not found` 或 `'gemini' 不是内部或外部命令`

两种情况：

没装成功：重新跑 npm install -g @google/gemini-cli，看有没有报错
PATH 没加：npm 全局安装目录没在系统 PATH 里。重启电脑 再试，或参考 npm 文档配置 PATH

改完 `.env` 还是没生效

很可能是终端没完全重开，老的环境变量还在缓存里。把所有终端窗口全关掉，重新开一个，再试一次。

常见坑速查（base URL / 模型 ID / 分组）

坑	现象	解决
`GOOGLE_GEMINI_BASE_URL` 末尾丢 `/`	路径拼接错 / 404	末尾必须留 `/`
令牌选错分组	401 Unauthorized	必须用 Gemini 家族令牌分组
Windows 文件变成 `.env.txt`	配置不读取	用 `type nul >` 或 VS Code 创建
等号两边有空格	配置不识别	`GEMINI_API_KEY=xxx`，等号紧贴
令牌加了引号	401	直接粘令牌本体，不加引号
改完没重开终端	配置不生效	完全关掉终端，重新打开
模型 ID 拼错	model not found	去模型广场直接复制

配置完成

Gemini CLI 配置完毕。可以用 gemini 命令启动，跟 AI 聊代码、聊文档、聊图片。

上一步：Codex CLI 手动配置｜回到章节首页：AI 工具接入