最近更新：2025年11月27日 03:19

Gemini CLI 完整配置指南

API Key 获取与保存

访问 https://www.i-coding.shop/console/token,进入 令牌管理。
点击 添加令牌,打开创建弹窗。
在弹窗中配置:名称、分组(可选)、过期时间(推荐永不过期)、额度限制、可用模型等。
点击提交后系统生成新令牌,请 立即复制 并妥善保存。关闭弹窗后将无法再次查看完整 Key。
该令牌即 Gemini CLI 所需的 API Key,可在列表页随时删除或重新生成。

建议将 API Key 保存在密码管理器(如 1Password、Bitwarden)中,并在 .gitignore 中忽略任何包含 Key 的配置文件。

环境变量与 Base URL

Base URL:https://www.i-coding.shop

必填环境变量:

GEMINI_API_KEY=<你的令牌>
GOOGLE_GEMINI_BASE_URL=https://www.i-coding.shop

可选环境变量:
- GEMINI_API_KEY_HEADER:自定义 API Key 请求头名称(默认为 x-goog-api-key)
- GEMINI_API_ENDPOINT:完整的 API 端点地址(可替代 BASE_URL)

Gemini CLI 支持从环境变量、.env 文件、~/.gemini/settings.json 等多层读取配置,优先级为:命令行参数 > 环境变量 > 项目配置 > 用户配置 > 系统默认值。

注意: CLI 至少需要在用户目录 ~/.gemini(macOS/Linux) 或 %USERPROFILE%\.gemini\(Windows) 中同时存在 .env 与 settings.json,否则认证无法生效。

macOS/Linux 配置流程

Linux 用户可完全套用以下步骤,如使用 bash 仅需替换配置文件路径。

1. 安装 Gemini CLI

方式一:npm 全局安装(推荐)

# 确认 Node.js 版本 >= 18(推荐 20+)
node --version
npm --version

# 全局安装
npm install -g @google/gemini-cli

方式二:npx 直接运行(无需安装)

# 每次运行时自动下载最新版本
npx @google/gemini-cli

验证安装

gemini --version

2. 配置 API Key 与 Base URL

临时设置(当前终端有效)

export GEMINI_API_KEY="你的令牌"
export GOOGLE_GEMINI_BASE_URL="https://www.i-coding.shop"
gemini

关闭终端后变量会消失,适合快速测试。

永久设置(推荐)

zsh(macOS 默认 shell)

# 编辑配置文件
nano ~/.zshrc

# 在文件末尾添加
export GEMINI_API_KEY="你的令牌"
export GOOGLE_GEMINI_BASE_URL="https://www.i-coding.shop"

# 重新加载配置
source ~/.zshrc

bash

echo "export GEMINI_API_KEY='你的令牌'" >> ~/.bash_profile
echo "export GOOGLE_GEMINI_BASE_URL='https://www.i-coding.shop'" >> ~/.bash_profile
source ~/.bash_profile

使用 .env 文件(系统级,推荐)

# 在用户目录创建 ~/.gemini/.env
mkdir -p ~/.gemini
cat > ~/.gemini/.env << EOF
GEMINI_API_KEY=你的令牌
GOOGLE_GEMINI_BASE_URL=https://www.i-coding.shop
EOF

.env 与 settings.json 必须位于同一目录(即 ~/.gemini) 才能被 CLI 识别,不要放在项目路径。

3. 配置核心认证文件 (必需)

为了启用 Gemini CLI 并确保认证生效,必须在用户目录 ~/.gemini 中创建 settings.json 文件,并与 .env 保持同一目录。

# 确保 ~/.gemini 目录存在
mkdir -p ~/.gemini

# 创建 settings.json 配置文件
cat > ~/.gemini/settings.json << EOF
{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}
EOF

macOS/Linux 环境需要 ~/.gemini/.env 与 ~/.gemini/settings.json 同时存在,否则 Gemini CLI 无法加载认证配置。

4. 验证与诊断

# 检查环境变量
echo $GEMINI_API_KEY
echo $GOOGLE_GEMINI_BASE_URL

# 启动交互式界面
gemini

# 测试 API 连接
gemini "Hello, test connection"

若命令返回 AI 响应,说明配置成功。

Windows 配置流程

Windows 完整安装教程

1. 安装 Node.js

方法一:使用官方安装包(推荐)

打开 https://nodejs.org
下载 LTS 版本的 Windows Installer(.msi)
运行安装包并使用默认选项完成安装
安装程序会自动把 Node.js 与 npm 写入 PATH

方法二:使用包管理器

Winget(Windows 11/10 自带)
```
winget install OpenJS.NodeJS.LTS
```
Chocolatey
```
choco install nodejs-lts
```
Scoop
```
scoop install nodejs-lts
```

验证安装

node --version
npm --version

建议坚持使用 LTS 版本以获得最佳稳定性。如遇 PATH 未刷新,请重新打开 CMD/PowerShell。

2. 全局安装 Gemini CLI

打开 CMD 或 PowerShell,执行:

npm install -g @google/gemini-cli
gemini --version     # 可选:确认命令可用

3. 配置 Gemini CLI

重要提示: GEMINI_API_KEY 必须替换为你在 https://www.i-coding.shop/console/token 中创建的 Gemini CLI 专用分组令牌。

3.1 创建 `.gemini` 目录

配置路径:%USERPROFILE%\.gemini\

可在文件资源管理器或 PowerShell 中创建:

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini"

3.2 创建 `.env` 文件

在 %USERPROFILE%\.gemini\ 中创建 .env,写入:

GOOGLE_GEMINI_BASE_URL=https://www.i-coding.shop
GEMINI_API_KEY=粘贴为Gemini CLI专用分组令牌key
GEMINI_MODEL=gemini-3-pro-preview

请确保 .env 与 settings.json 同时保存在 %USERPROFILE%\.gemini\ 目录下,否则 CLI 无法读取配置。

3.3 创建 `settings.json`(必需)

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

将该 JSON 保存为 %USERPROFILE%\.gemini\settings.json,确保与 .env 同目录并在修改后重启 Gemini CLI。

4. 启动 Gemini CLI

gemini

启动后即可使用以下能力:

超大 1M tokens 上下文窗口
Agent Mode 自动规划任务
内置 Google Search,可实时联网

若首次运行失败,请检查 .env 与 settings.json 是否已创建、API Key 是否填写正确,并重新打开终端。

常用命令

gemini --version              # 查看版本
gemini --help                 # 显示帮助信息
gemini                        # 启动交互式界面
gemini "prompt"               # 单次执行提示词
gemini --model gemini-2.5-pro "prompt"  # 指定模型
gemini --no-interactive "prompt"        # 非交互模式

# 交互模式内命令
!                             # 切换到 shell 模式(再次输入退出)
Ctrl+f                        # 聚焦到终端(用于交互式命令)
Ctrl+c                        # 取消当前操作
Ctrl+d 或 exit                # 退出 CLI
ESC                           # 退出 shell 模式

交互式功能

代码生成与调试:直接输入需求,AI 会生成代码或帮助调试
文件分析:可以读取和分析项目文件
Shell 命令执行:在交互模式中执行系统命令
实时编辑器支持:可以在 CLI 中使用 vim、nano 等编辑器
上下文保持:会话中的对话历史会被保留

常见问题

npm 安装后找不到 gemini 命令？: 确认 npm 全局 bin 目录已加入 PATH。可运行 npm config get prefix 查看路径，再将 <prefix>/bin 添加到 PATH。

API Key 设置正确仍提示认证失败？

echo $GEMINI_API_KEY 是否有值
GOOGLE_GEMINI_BASE_URL 是否为 https://www.i-coding.shop
i-Coding 令牌是否过期或被删除
.gemini/settings.json 是否已包含 ide.enabled: true
重启终端后再试

如何切换不同的 AI 模型？

使用 --model 参数，例如：

gemini --model gemini-2.5-pro "你的提示词"

交互模式下如何执行 shell 命令？: 在消息框输入 ! 进入 shell 模式，执行完命令后再次输入 ! 或按 ESC 退出。

如何在项目中使用不同配置？: 在项目根目录创建 .gemini/settings.json 即可覆盖全局设置，但系统目录 ~/.gemini 或 %USERPROFILE%\.gemini\ 中的 .env 与 settings.json 仍是必需的。

API Key 泄露怎么办？: 立即登录 i-Coding 控制台删除泄露令牌并重新生成，同时更新所有环境变量和配置文件。

如何查看当前使用的配置？: Gemini CLI 启动时会展示加载的配置路径；请检查 ~/.gemini/settings.json（或 %USERPROFILE%\.gemini\settings.json）以及项目目录下的 .gemini/settings.json。

支持哪些 Gemini 模型？: 通过 i-Coding 网关可访问所有 Gemini 系列模型（如 Gemini 2.5 Pro、Gemini 3 等）。具体列表可在模型广场查看。